b2dUnlockImage

Uploads modified pixels to GPU (CPU->GPU copy, required after lock, frees CPU buffer). Takes imageHandle (locked image handle from b2dLockImage, positive integer, must have isLocked=true). Returns nothing. Uploads CPU buffer to GPU (b2dUploadPixelData helper with upload buffer and resource barriers), frees CPU buffer (delete[] img.cpuPixelBuffer, deallocates temporary memory), clears isLocked flag (sets img.isLocked=false, img.cpuPixelBuffer=nullptr), makes changes visible (GPU texture updated with modified pixels from SetPixel calls). Use to complete lock/unlock cycle (required after b2dLockImage), apply pixel modifications (upload SetPixel changes to GPU texture), free memory (deallocate temporary CPU buffer), or finalize image processing (effects, filters, procedural generation). Lock/Unlock workflow: b2dLockImage downloads texture (GPU->CPU, allocates buffer), GetPixel/SetPixel fast CPU operations (no GPU overhead, direct buffer access), b2dUnlockImage uploads changes (CPU->GPU, frees buffer), texture ready for rendering (modified pixels visible in subsequent draws). Use cases: (1) Complete read-write workflow (b2dLockImage(img): modify pixels with SetPixel: b2dUnlockImage(img) apply changes), (2) Complete read-only workflow (b2dLockImage(img): analyze with GetPixel: b2dUnlockImage(img) no changes but cleanup), (3) Image filter application (lock: For each pixel: compute new color: SetPixel: unlock apply filter), (4) Procedural texture generation (lock RT: generate pattern with SetPixel: unlock make visible), (5) Collision baking (lock: compute collision map: SetPixel flags: unlock prepare collision texture). Common patterns: modify = b2dLockImage(img): modify: b2dUnlockImage(img) full cycle; read-only = b2dLockImage(img): read: b2dUnlockImage(img) still required for cleanup. GPU operations: upload buffer (creates D3D12_HEAP_TYPE_UPLOAD intermediate buffer), subresource update (UpdateSubresources copies CPU data to upload buffer then GPU texture), resource barriers (transitions texture PIXEL_SHADER_RESOURCE -> COPY_DEST -> PIXEL_SHADER_RESOURCE), GPU sync (WaitForFence blocks until upload completes, synchronous operation). Upload process: transition to COPY_DEST (barrier prepares texture for writing), copy data (upload buffer -> GPU texture via CopyTextureRegion), transition back (barrier returns texture to PIXEL_SHADER_RESOURCE for rendering), execute and wait (command list executed with fence wait, ensures upload complete). Memory cleanup: delete[] cpuPixelBuffer (frees temporary RGBA buffer widthxheightx4 bytes), set to nullptr (clears pointer, prevents dangling reference), isLocked=false (marks image as unlocked, allows future b2dLockImage calls). Performance: upload cost high (full texture CPU->GPU copy, ~1-10ms depending on size), synchronous (blocks CPU waiting for GPU upload, creates CPU-GPU bubble), amortized (many SetPixel operations uploaded in one batch, efficient vs per-pixel GPU updates), memory freed (temporary buffer deallocated, RAM returned to system). When to use: ALWAYS after b2dLockImage (required to free buffer, even if no modifications made), after pixel modifications (apply SetPixel changes to visible texture), after read-only operations (cleanup even if only GetPixel used, not SetPixel). Validation: prints error if invalid handle (imageHandle not found in g_images map, returns early), prints error if not locked (img.isLocked=false or cpuPixelBuffer=nullptr, cannot unlock non-locked image), prints error if upload fails (b2dUploadPixelData returns false, GPU operation failed but buffer still freed). Error handling: buffer freed regardless (even on upload failure, CPU buffer deallocated to prevent leak), isLocked cleared (image marked as unlocked even on failure), safe to retry (can b2dLockImage again after failed unlock, starts fresh download). Related: b2dLockImage downloads texture (required before this function, creates CPU buffer uploaded by this function), b2dSetPixel modifies pixels (changes CPU buffer, uploaded by this function), b2dGetPixelR/G/B/A read pixels (access CPU buffer, cleanup requires this function), b2dDrawImage renders texture (displays uploaded changes after unlock), b2dFreeImage releases image (automatically unlocks if locked before freeing).