b2dSaveImage

Saves image to PNG file (reads GPU texture, writes to disk, synchronous operation). Takes imageHandle (image handle from b2dLoadImage, b2dCreateRenderTarget, or b2dGrabImage, positive integer), filePath (output file path, string, .png extension). Returns 1 on success, returns 0 on failure (invalid handle, GPU read error, or file write error). Creates readback buffer (GPU->CPU copy via D3D12_HEAP_TYPE_READBACK), copies texture to CPU (GPU CopyTextureRegion to readback buffer with resource barriers), maps and extracts pixels (copies rows accounting for pitch alignment), writes PNG file (uses stbi_write_png with RGBA 4-channel format). Use to save screenshots (capture and save render target contents), export textures (save procedurally generated or modified images), debug rendering (save intermediate results to disk), or create assets (bake dynamic textures to files). Image types supported: loaded images (from b2dLoadImage, regular texture files), render targets (from b2dCreateRenderTarget, offscreen rendering results), grabbed images (from b2dGrabImage, captured regions), copied images (from b2dCopyImage, duplicated textures). Use cases: (1) Screenshot (rt=b2dCreateRenderTarget: draw scene: b2dFlush(): b2dSaveImage(rt,\"screenshot.png\") save frame), (2) Procedural texture (draw shapes: b2dFlush(): grabbed=b2dGrabImage(0,0,w,h): b2dSaveImage(grabbed,\"texture.png\") bake to file), (3) Debug output (b2dSaveImage(texture,\"debug.png\") inspect texture contents), (4) Asset export (b2dSaveImage(dynamicImg,\"generated.png\") save runtime-generated asset), (5) RT capture series (For i=0 To 10: draw frame: b2dFlush(): b2dSaveImage(rt,\"frame\"+i+\".png\") save animation frames). Common patterns: save RT = b2dSetRenderTarget(rt): draw: b2dFlush(): b2dSaveImage(rt,\"output.png\") render and save; save loaded = img=b2dLoadImage(\"input.png\"): modify: b2dSaveImage(img,\"modified.png\") load, modify, save. GPU operations: readback buffer (creates temporary CPU-readable buffer, D3D12_HEAP_TYPE_READBACK heap type), resource barriers (transitions RT from RENDER_TARGET or PIXEL_SHADER_RESOURCE to COPY_SOURCE if needed), texture copy (GPU CopyTextureRegion full texture to readback buffer), map buffer (CPU maps readback buffer to access pixel data), extract with pitch (copies row-by-row accounting for D3D12 row pitch alignment, layout.Footprint.RowPitch). Resource state handling: RT detection (if img.isRenderTarget, handles state transitions), state tracking (uses img.hasBeenUsedAsTexture to determine current state RENDER_TARGET or PIXEL_SHADER_RESOURCE), transition to COPY_SOURCE (barrier inserted for RT textures), transition back (restores original state after copy), regular images (no transition needed, already in PIXEL_SHADER_RESOURCE). PNG format: RGBA 4-channel (stbi_write_png with channels=4, full alpha support), 8-bit per channel (R8G8B8A8 format, 0-255 values), row pitch (output stride = width x 4, packed RGBA no padding), lossless compression (PNG format, no quality loss). Performance: cost high (GPU->CPU copy + file I/O, ~10-100ms depending on image size and disk speed), synchronous (blocks CPU waiting for GPU copy and file write, creates bubble), memory allocation (temporary readback buffer = image size with pitch, brief allocation), disk I/O (file write speed varies by storage device, SSD fast ~50MB/s, HDD slow ~20MB/s). Validation: returns 0 if invalid handle (imageHandle not found in g_images map), returns 0 if GPU operations fail (readback buffer creation, texture copy, or command execution fails), returns 0 if file write fails (stbi_write_png returns 0, disk full, invalid path, no permissions), all failures silent (no error message to user, returns 0 on any failure). File path handling: overwrites existing (if file exists, overwritten without warning), creates directories (user responsible for creating parent directories, function doesn't create folders), path format (uses OS path separators, forward slash / or backslash \\ depending on platform), extension not enforced (function writes PNG regardless of extension, recommend .png extension for clarity). Related: b2dGrabImage captures from RT (creates image that can be saved by this function), b2dCreateRenderTarget creates RT (RT contents can be saved by this function), b2dLoadImage loads image (loaded images can be modified and re-saved by this function), b2dCopyImage copies image (copied images can be saved by this function), b2dFlush completes rendering (call before saving RT to ensure contents finished).