Creates rectangle image (rasterized texture, returns handle for b2dDrawImage).
Takes width (rectangle width in pixels, positive integer), height (rectangle height in pixels, positive integer), fill (1=filled rectangle, 0=outline only).
Returns image handle (positive integer, use with b2dDrawImage/b2dSetColor/b2dSetScale/b2dSetRotation, etc), returns 0 on failure.
2D Overlay
Parameters & Returns
Parameters
fillInt
heightInt
widthInt
Returns
Int
Quick Summary
Creates rectangle image (rasterized texture, returns handle for b2dDrawImage).
Takes width (rectangle width in pixels, positive integer), height (rectangle height in pixels, positive integer), fill (1=filled rectangle, 0=outline only).
Returns image handle (positive integer, use with b2dDrawImage/b2dSetColor/b2dSetScale/b2dSetRotation, etc), returns 0 on failure.
Technical Exegesis...
Rectangle rasterization: allocates pixel buffer (width*height*4 bytes, RGBA format), fill mode determines rendering (filled=all pixels white alpha 255, outline=only border pixels white alpha 255 with 1-pixel thickness, transparent elsewhere), uploads to GPU (creates D3D12 texture resource, transitions to PIXEL_SHADER_RESOURCE state).
Rectangle rasterization: allocates pixel buffer (width*height*4 bytes, RGBA format), fill mode determines rendering (filled=all pixels white alpha 255, outline=only border pixels white alpha 255 with 1-pixel thickness, transparent elsewhere), uploads to GPU (creates D3D12 texture resource, transitions to PIXEL_SHADER_RESOURCE state).
Fill parameter: fill=1 creates solid rectangle (entire area opaque white, fully filled), fill=0 creates outline (only perimeter pixels opaque white, 1-pixel border thickness, interior transparent), border detection (checks if x==0 or x==width-1 or y==0 or y==height-1 for edge pixels).
Image handle usage: use with b2dDrawImage (b2dDrawImage(rect, x, y) draws at position), use with transforms (b2dSetScale/b2dSetRotation/b2dSetAlpha apply, then b2dDrawImage), use with color (b2dSetColor(r,g,b) tints rectangle before drawing), free when done (b2dFreeImage(rect) releases GPU texture).
Use cases: (1) UI panels (panel=b2dCreateRectangle(400,300,1): b2dSetColor(50,50,50): b2dDrawImage(panel,x,y) dark gray panel), (2) Selection box (outline=b2dCreateRectangle(100,100,0): b2dSetColor(255,255,0): b2dDrawImage(outline,x,y) yellow selection), (3) Health bar (bar=b2dCreateRectangle(200,20,1): b2dSetColor(255,0,0): b2dDrawImage(bar,x,y) red health bar), (4) Button (button=b2dCreateRectangle(150,50,1): apply color and draw for UI button).
Center handle: handleX and handleY set to width/2 and height/2 (center of rectangle), rotation pivot at center (b2dSetRotation rotates around rectangle center, not top-left), position is center (x,y in b2dDrawImage positions rectangle center, not corner).
Performance: texture creation cost (rasterization + GPU upload, one-time ~1-10ms depending on size), reusable (create once, draw many times with b2dDrawImage, no per-frame cost), GPU memory (width*height*4 bytes, e.g. 200x100 = ~78KB), stored until freed (persists in g_images map until b2dFreeImage called).
Validation: returns 0 if width<=0 or height<=0 (invalid dimensions), returns 0 if GPU allocation fails (out of VRAM or device not initialized).
Related: b2dDrawImage draws rectangle (positions and renders rectangle texture), b2dSetColor tints rectangle (applies color multiplier before drawing), b2dSetScale/b2dSetRotation/b2dSetAlpha transform rectangle (applies transforms to rectangle image), b2dFreeImage frees rectangle (releases GPU texture when done), b2dCreateCircle creates circle image (similar function for circles).
Example
Example.bam
; Create a filled red rectangle
rect = b2dCreateRectangle(200, 100, 1)
; Draw it at screen position with color
b2dSetColor(255, 0, 0)
b2dDrawImage(rect, 400, 300)
; Create an outline rectangle
outline = b2dCreateRectangle(150, 150, 0)
b2dSetColor(0, 255, 255)
b2dDrawImage(outline, 600, 300)
; Can also scale and rotate
b2dSetScale(1.5, 1.5)
b2dSetRotation(30.0)
b2dDrawImage(rect, 200, 400)
; Free when done
b2dFreeImage(rect)
b2dFreeImage(outline)