b2dSetPixel

Writes RGBA pixel to locked image (requires b2dLockImage first, fast CPU buffer write, clamped 0-255). Takes imageHandle (locked image handle, positive integer, must have isLocked=true), x (horizontal pixel coordinate, integer, 0=left edge), y (vertical pixel coordinate, integer, 0=top edge), r (red channel 0-255, integer, clamped automatically), g (green channel 0-255, integer, clamped automatically), b (blue channel 0-255, integer, clamped automatically), a (alpha channel 0-255, integer, 0=transparent, 255=opaque, clamped automatically). Returns nothing. Writes to CPU buffer (img.cpuPixelBuffer, direct memory access), calculates pixel index (index = (yxwidth+x)x4 row-major RGBA layout), writes RGBA bytes (buffer[index+0]=r, buffer[index+1]=g, buffer[index+2]=b, buffer[index+3]=a), clamps color values (negative->0, >255->255, automatic clamping no error). Use to modify pixels (procedural generation, effects, drawing), apply filters (blur, sharpen, color correction), implement drawing (lines, shapes, text on texture), or create dynamic content (animated textures, runtime-generated images). Lock/Unlock workflow: b2dLockImage downloads texture (GPU->CPU, one-time cost), SetPixel many times (fast CPU buffer writes, no GPU overhead per pixel), b2dUnlockImage uploads changes (CPU->GPU, applies all modifications in batch). Use cases: (1) Procedural texture (b2dLockImage(rt): For y=0 To h: For x=0 To w: r=Sin(x)*128+127: g=Cos(y)*128+127: b=128: b2dSetPixel(rt,x,y,r,g,b,255): Next: Next: b2dUnlockImage(rt) generate pattern), (2) Apply filter (b2dLockImage(img): For each pixel: read neighbors with GetPixel: compute filter: b2dSetPixel result: b2dUnlockImage(img) blur/sharpen), (3) Draw line (b2dLockImage(img): For t=0 To 1 Step 0.01: x=lerp(x1,x2,t): y=lerp(y1,y2,t): b2dSetPixel(img,x,y,255,0,0,255): Next: b2dUnlockImage(img)), (4) Color correction (b2dLockImage(img): For each pixel: r=b2dGetPixelR(img,x,y)*1.2: g=b2dGetPixelG(img,x,y)*1.1: b=b2dGetPixelB(img,x,y): a=b2dGetPixelA(img,x,y): b2dSetPixel(img,x,y,r,g,b,a): b2dUnlockImage(img) adjust brightness), (5) Alpha masking (b2dLockImage(img): For each pixel: If condition Then a=255 Else a=0: b2dSetPixel(img,x,y,r,g,b,a) create mask). Common patterns: set opaque = b2dSetPixel(img,x,y,r,g,b,255) solid color; set transparent = b2dSetPixel(img,x,y,r,g,b,0) invisible pixel; read-modify-write = r=b2dGetPixelR(img,x,y)*scale: b2dSetPixel(img,x,y,r,g,b,a) adjust color. RGBA format: R at offset+0 (red channel first byte), G at offset+1 (green channel second byte), B at offset+2 (blue channel third byte), A at offset+3 (alpha channel fourth byte), 4 bytes per pixel (RGBA tightly packed). Color clamping: r clamped 0-255 (if r<0 then r=0, if r>255 then r=255, automatic no error), g clamped 0-255 (same logic), b clamped 0-255 (same logic), a clamped 0-255 (same logic), safe to pass any integer (out-of-range values adjusted automatically). Coordinate system: origin top-left (0,0 = top-left corner), x rightward (0=left edge, width-1=right edge), y downward (0=top edge, height-1=bottom edge), row-major layout (left-to-right, top-to-bottom). Index calculation: pixel index = (y x width + x) x 4 (offset to pixel's first byte), write 4 bytes (buffer[index+0 through index+3] = R,G,B,A), bounds check (x in 0 to width-1, y in 0 to height-1), out-of-bounds silently ignored (returns early, no write, no error). Upload requirement: changes in CPU buffer only (modifications not visible on GPU until b2dUnlockImage), batch modifications efficient (many SetPixel calls uploaded together in one GPU transfer), visible after unlock (b2dUnlockImage uploads CPU buffer to GPU texture, changes appear in subsequent draws). Performance: write cost zero (direct CPU memory write, 4 sequential byte stores), no GPU overhead (writes to CPU buffer, no GPU round-trips), amortized upload cost (one unlock uploads all SetPixel modifications in batch), efficient for many pixels (thousands of SetPixel calls faster than GPU per-pixel updates). Validation: prints error if not locked (img.isLocked=false or cpuPixelBuffer=nullptr, returns early), returns early if invalid handle (imageHandle not in g_images map), returns early if out-of-bounds (x<0 or x>=width or y<0 or y>=height, silently skips write), no error on clamped colors (color values clamped silently, valid operation). Related: b2dGetPixelR/G/B/A read pixel channels (pair with SetPixel for read-modify-write operations), b2dLockImage enables pixel access (required before this function, downloads texture to CPU), b2dUnlockImage uploads changes (required after SetPixel to make modifications visible, uploads CPU buffer to GPU), b2dDrawImage renders texture (displays modified texture after unlock).