b2dLockImage

Downloads texture to CPU buffer (enables fast GetPixel/SetPixel, GPU->CPU copy, must unlock after). Takes imageHandle (image handle from b2dLoadImage, b2dCreateRenderTarget, etc, positive integer). Returns nothing. Downloads texture from GPU (ReadTextureFromGPU helper copies texture to CPU with readback buffer), allocates CPU buffer (img.cpuPixelBuffer = new unsigned char[widthxheightx4] RGBA format), sets isLocked flag (prevents double-locking, enables GetPixel/SetPixel), stores in image structure (persists until b2dUnlockImage called). Use to enable pixel access (required before b2dGetPixelR/G/B/A or b2dSetPixel), batch pixel operations (multiple GetPixel/SetPixel without GPU overhead), analyze image data (collision detection, color sampling, procedural generation), or modify textures (effects, filters, drawing algorithms). Lock/Unlock workflow: lock once (downloads texture GPU->CPU), manipulate pixels (fast CPU-side GetPixel/SetPixel operations), unlock once (uploads modified texture CPU->GPU), avoid multiple locks (each lock downloads full texture, expensive). Use cases: (1) Pixel-perfect collision (b2dLockImage(img1): b2dLockImage(img2): check alpha at overlap: b2dUnlockImage(img1): b2dUnlockImage(img2)), (2) Color analysis (b2dLockImage(img): For y=0 To h: For x=0 To w: r=b2dGetPixelR(img,x,y): process: Next: Next: b2dUnlockImage(img)), (3) Image filter (b2dLockImage(img): For each pixel: modify with b2dSetPixel: b2dUnlockImage(img) upload changes), (4) Procedural texture (create RT: b2dLockImage(rt): draw patterns with b2dSetPixel: b2dUnlockImage(rt) generate content), (5) Texture baking (render to RT: b2dLockImage(rt): read pixels: save data: b2dUnlockImage(rt)). Common patterns: read-only = b2dLockImage(img): read pixels with GetPixel: b2dUnlockImage(img) no upload; read-write = b2dLockImage(img): modify with SetPixel: b2dUnlockImage(img) upload changes. GPU operations: readback buffer (creates D3D12_HEAP_TYPE_READBACK buffer, GPU-accessible for copy), texture copy (CopyTextureRegion from texture to readback buffer with resource barriers), GPU sync (WaitForFence blocks until copy completes, synchronous operation), buffer mapping (maps readback buffer to CPU memory, extracts pixels row-by-row with pitch handling). CPU buffer allocation: RGBA format (4 bytes per pixel, R at offset+0, G at offset+1, B at offset+2, A at offset+3), size calculation (width x height x 4 bytes), row-major layout (pixels stored left-to-right, top-to-bottom, index = (yxwidth+x)x4), memory ownership (image owns buffer, freed during unlock or image free). Lock state: isLocked flag (set to true, prevents double-locking), cpuPixelBuffer pointer (non-null while locked, null when unlocked), persistent until unlock (remains locked until b2dUnlockImage called, spans multiple frames if needed), blocks re-lock (calling b2dLockImage on already-locked image prints error, returns early). Performance: download cost high (full texture GPU->CPU copy, ~1-10ms depending on size 1920x1080 = ~8MB), synchronous (blocks CPU waiting for GPU copy, creates CPU-GPU bubble), memory cost (allocates widthxheightx4 bytes in RAM, temporary buffer until unlock), amortized (one download enables many fast GetPixel/SetPixel operations without GPU overhead). When to use: many pixel operations (reading/writing many pixels, lock once vs GPU round-trip per pixel), pixel analysis (collision, sampling, statistics, procedural checks), image processing (filters, effects, transformations), NOT for single pixel (locking for one pixel wastes performance, direct GPU operations better for single access). Validation: prints error if invalid handle (imageHandle not found in g_images map, returns early), prints error if already locked (img.isLocked=true, prevents double-lock corrupting buffer), returns early if GPU read fails (ReadTextureFromGPU returns empty vector, texture copy failed). Related: b2dUnlockImage uploads changes (required after lock, uploads modified pixels CPU->GPU, frees CPU buffer), b2dGetPixelR/G/B/A read pixel channels (requires lock first, fast CPU buffer access), b2dSetPixel writes pixel (requires lock first, modifies CPU buffer), b2dFreeImage releases image (automatically unlocks if locked, frees CPU buffer).