b2dCopyImage

Creates deep copy of image (GPU->CPU->GPU, fully independent duplicate). Takes imageHandle (source image handle from b2dLoadImage/b2dLoadAnimImage, positive integer). Returns new image handle (positive integer for copy, 0 on failure). Performs deep copy (reads GPU texture to CPU, creates new GPU texture, uploads data), fully independent (new texture resource, new SRV, separate map entry), preserves all properties (width, height, frameWidth/Height/Count, pixel data). Use to create modifiable copies (copy image before pixel manipulation), duplicate sprites (multiple instances with independent modifications), or backup images (save original before editing). Copy process: creates readback buffer (GPU->CPU copy with D3D12_HEAP_TYPE_READBACK), downloads texture (CopyTextureRegion from GPU to readback buffer, transitions states, WaitForFence), reads pixel data (Map readback buffer, copy to CPU array with row pitch handling), creates new texture (same dimensions and format as source), uploads data (new upload buffer, UpdateSubresources, transitions to shader resource state), creates new entry (new handle, new SRV in descriptor heap, independent from source). Use cases: (1) Duplicate sprite (copy = b2dCopyImage(sprite): independent instance for modification), (2) Backup (original = b2dCopyImage(image): preserve before editing), (3) Multiple versions (bright = b2dCopyImage(img): create tinted/modified versions), (4) Template (template = b2dLoadImage("base.png"): copies = b2dCopyImage(template) for instances). Common patterns: copy = newImg = b2dCopyImage(srcImg): If newImg = 0 Then Print "Failed". Deep copy behavior: fully independent (changes to copy don't affect source, vice versa), separate GPU resources (new ID3D12Resource, separate VRAM allocation), same pixel data (exact duplicate of source at time of copy), separate handle (new handle from g_nextImageHandle++). Performance: copy cost expensive (GPU->CPU download + CPU->GPU upload, ~5-50ms depending on size 256x256 fast, 2048x2048 slow), GPU synchronization (WaitForFence blocks until copy complete, not async), row pitch handling (accounts for GPU texture padding, copies row-by-row), avoid frequent copying (expensive operation, copy at load time not every frame). Properties preserved: dimensions (width, height same as source), frame data (frameWidth, frameHeight, frameCount copied for animation sheets), handle position (handleX, handleY if set, for pivot points), pixel data (exact RGBA values copied). Validation: returns 0 if source handle invalid (not found in g_images map), returns 0 if source texture null (corrupted entry or already freed), returns 0 if GPU allocation failed (out of VRAM or resources). Related: b2dLoadImage loads image (creates original image to copy), b2dFreeImage frees image (copy and source must be freed separately), b2dGetImageWidth queries width (copy has same width as source), b2dGetImageHeight queries height (copy has same height as source).