b2dGrabImage

Captures rectangle from active render target (returns new image, requires b2dFlush first, RT only not backbuffer). Takes x1 (left edge of capture region in pixels, integer), y1 (top edge of capture region in pixels, integer), x2 (right edge of capture region in pixels, integer, 0=use full width from x1), y2 (bottom edge of capture region in pixels, integer, 0=use full height from y1). Returns new image handle (positive integer, captured region as new image), returns 0 on failure (invalid RT, empty region, or backbuffer capture attempted). Calls b2dFlush internally (ensures pending commands complete before capture), reads from g_2D_currentRenderTarget (must have active custom RT, backbuffer capture not supported in overlay system), creates readback buffer (GPU->CPU copy via D3D12_HEAP_TYPE_READBACK), extracts region (copies specified rectangle from full texture row-by-row with pitch handling), creates new image (uploads captured pixels to new GPU texture, stores in g_images map). Use to capture RT contents (screenshot of render target), extract regions (grab portion of rendered texture), create dynamic textures (capture procedural content), or implement RT effects (feedback loops, trails, echoes). Backbuffer limitation: ONLY captures from render targets (g_2D_currentRenderTarget must be > 0, b2dSetRenderTarget must have been called), returns 0 for backbuffer (if g_2D_currentRenderTarget=0, cannot capture from screen in overlay system), use BBR_GrabImage for backbuffer (3D system function for screen capture, separate from 2D overlay). Use cases: (1) RT screenshot (b2dSetRenderTarget(rt): draw: b2dFlush(): img=b2dGrabImage(0,0,0,0) capture full RT), (2) Region capture (b2dFlush(): img=b2dGrabImage(100,100,300,300) capture 200x200 region), (3) Feedback effect (img=b2dGrabImage(0,0,w,h): b2dSetDefaultRenderTarget(): b2dDrawImage(img,offsetX,offsetY) echo trail), (4) Thumbnail (b2dFlush(): thumb=b2dGrabImage(0,0,rtW,rtH): scale thumb for minimap), (5) Texture baking (draw procedural: b2dFlush(): texture=b2dGrabImage(0,0,0,0) save generated texture). Common patterns: full capture = b2dFlush(): img = b2dGrabImage(0,0,0,0) grab entire RT; region = b2dFlush(): img = b2dGrabImage(x1,y1,x2,y2) grab rectangle. Coordinate system: x1,y1 top-left (origin 0,0 = RT top-left corner), x2,y2 bottom-right (exclusive, x2-x1=width, y2-y1=height), automatic full size (if x2=0 and y2=0, uses full RT dimensions from x1,y1 to end), clamping to bounds (region clamped to RT dimensions, out-of-bounds clamped not error). Region calculation: width = x2 - x1 (horizontal size of capture), height = y2 - y1 (vertical size of capture), clamp negative origins (if x1<0 or y1<0, adjusted to 0 with width/height reduced), clamp overrun (if x1+width > RTwidth, width reduced to fit). Flush requirement: MUST call b2dFlush first (or let b3dRenderWorld execute commands before grabbing), ensures RT complete (pending draws finished, pixels available for capture), internal flush (function calls b2dFlush internally, redundant flush safe but wastes performance). GPU operations: readback buffer (creates temporary CPU-readable buffer, D3D12_HEAP_TYPE_READBACK), texture copy (GPU copies full RT texture to readback buffer, CopyTextureRegion), CPU extraction (maps readback buffer, extracts specified region row-by-row accounting for pitch), new texture creation (uploads captured pixels to new GPU texture DXGI_FORMAT_R8G8B8A8_UNORM), SRV creation (creates shader resource view for new image, stores in g_images map). Resource barriers: transition to COPY_SOURCE (source RT transitioned from RENDER_TARGET or PIXEL_SHADER_RESOURCE to COPY_SOURCE), transition back (source RT transitioned back to original state after copy), state tracking (uses img.hasBeenUsedAsTexture to determine original state). Performance: cost high (GPU->CPU copy + CPU extraction + CPU->GPU upload, ~1-10ms depending on RT size), synchronous (blocks CPU waiting for GPU copy complete, creates bubble), memory allocation (temporary readback buffer + new image allocation, 2x RT size in memory temporarily), prefer infrequent use (expensive operation, not every frame, use for specific capture needs). Validation: returns 0 if not initialized (g_initialized, g_commandListManager, or g_3D_pDevice null), returns 0 if no RT active (g_2D_currentRenderTarget=0, backbuffer not supported), returns 0 if invalid RT (RT handle not found or not isRenderTarget), returns 0 if empty region (width<=0 or height<=0 after clamping), all failures silent (no error message, returns 0). Related: b2dSetRenderTarget activates RT (must call before this function, sets g_2D_currentRenderTarget), b2dFlush completes rendering (must call before capture to ensure RT finished, called internally by this function), b2dCreateRenderTarget creates RT (allocates render target captured by this function), b2dSaveImage saves to file (captured image can be saved to disk with this function), b2dDrawImage draws captured image (display grabbed content), b2dFreeImage releases captured image (deallocate when done).