Makes an image from a rectangle of another image (a sprite sheet), sharing its texture.
2D Overlay
Parameters & Returns
Parameters
imageHandleInt
xInt
yInt
widthInt
heightInt
Returns
Int
Quick Summary
Makes an image from a rectangle of another image (a sprite sheet), sharing its texture.
Technical Exegesis...
Returns a new image handle that is the width x height rectangle at x,y of imageHandle, in pixels of that image. Use it to cut sprites out of one sprite sheet (atlas) of any layout, without drawing and grabbing them.
Nothing is copied: the sub-image uses the sheet's texture and just remembers its rectangle, so it costs no extra video memory and no upload.
Returns a new image handle that is the width x height rectangle at x,y of imageHandle, in pixels of that image. Use it to cut sprites out of one sprite sheet (atlas) of any layout, without drawing and grabbing them.
Nothing is copied: the sub-image uses the sheet's texture and just remembers its rectangle, so it costs no extra video memory and no upload. Draws of different sub-images of the same sheet that come one after another share one draw call, so a whole scene of sprites from one sheet can be a handful of draw calls (desktop and web).
A sub-image is an ordinary image to everything else. b2dGetImageWidth / b2dGetImageHeight give the rectangle's size. It has its own handle point (starting at 0,0) and its own b2dSetImageSmooth setting (starting as the sheet's). Every draw - b2dDrawImage, rotated, scaled, tinted, b2dDrawImageEx with a shader, b2dDrawImageQuad / QuadUV / the depth quads (their 0..1 u,v run across the rectangle), b2dDrawImage9Slice, tilemaps - shows only the rectangle. Pixel collisions and b2dGetPixel use the rectangle's pixels, with coordinates relative to the sub-image. b2dCopyImage of a sub-image makes an independent image of just the rectangle. A sub-image of a sub-image is a rectangle of the same sheet.
Writing pixels (b2dLockImage / b2dSetPixel / b2dUnlockImage, b2dSetImagePixels) into a sub-image writes into the shared sheet, so the sheet and its other sub-images change too (on the PlayStation a sub-image is read-only). A sub-image can't be a render target.
Freeing a sub-image frees only its handle. The sheet can be freed before its sub-images: the texture stays until the last image using it is freed.
Returns 0 if imageHandle doesn't exist, width or height is less than 1, or the rectangle isn't fully inside the image. On the web the sheet may still be loading: you get a handle straight away, and a rectangle that turns out not to fit is reported in the browser console and never draws. Palette (indexed) images can't be used as a sheet on DX12 and the web yet (returns 0).
Tip: a sheet loaded with b2dLoadImage has mipmaps on desktop, so a sub-image drawn much smaller than its size can pick up colour from its neighbours, and a smoothed sub-image scaled up can show half a pixel of the next cell at its edge. Leave a transparent gap of a pixel or two between sprites in the sheet, or use b2dSetImageSmooth(sub, False) for pixel art.
Example
Example.bam
Global sheet:Int = b2dLoadImage("Media/sprites.png")
; cut sprites out of the sheet - any size, anywhereGlobal player:Int = b2dCreateSubImage(sheet, 0, 0, 32, 48)
Global coin:Int = b2dCreateSubImage(sheet, 32, 0, 16, 16)
b2dSetImageMidHandle(player)
b2dDrawImage(player, 400, 300)
b2dDrawImage(coin, 100, 100)