b2dLoadImage

Loads image from file for 2D overlay (PNG/JPG/BMP/TGA via stb_image, returns handle). Takes filePath (image file path, string, relative or absolute). Returns image handle (positive integer, 0 on failure). Loads image using stb_image (supports PNG, JPG, BMP, TGA, GIF, PSD, HDR, PIC, PNM, forced RGBA 4 channels), creates GPU texture (ID3D12Resource, DXGI_FORMAT_R8G8B8A8_UNORM), uploads pixel data (via upload buffer, transitions to PIXEL_SHADER_RESOURCE state), creates SRV (shader resource view in descriptor heap), stores in g_images map (indexed by handle, persistent until freed). Use to load sprites (characters, UI elements, backgrounds), load textures (icons, buttons, overlays), or load animation sheets (sprite sheets for frame animation). Loading process: reads file with stb_image (stbi_load forces 4 channels RGBA, returns pixel data array), creates texture resource (D3D12_RESOURCE_DIMENSION_TEXTURE2D, widthxheight, RGBA8 format), uploads data to GPU (command list with UpdateSubresources, transitions to shader resource state), creates SRV (descriptor in g_2D_srvHeap, used for shader sampling), increments handle (g_nextImageHandle++, unique ID per image). Use cases: (1) Load sprite (img = b2dLoadImage("player.png"): draw character sprite), (2) Load UI (buttonImg = b2dLoadImage("button.png"): draw button), (3) Load background (bg = b2dLoadImage("background.jpg"): draw background layer), (4) Load icon (icon = b2dLoadImage("icon.png"): draw HUD icon), (5) Load texture (tex = b2dLoadImage("tile.png"): tiled texture). Common patterns: load = img = b2dLoadImage("file.png"), If img = 0 Then Print "Failed"; draw = b2dDrawImage(img, x, y). Supported formats: PNG (supports transparency alpha channel, lossless compression), JPG/JPEG (no transparency, lossy compression, good for photos), BMP (no compression, large files, simple format), TGA (supports alpha, uncompressed or RLE), GIF (animated GIF loads first frame only, no animation support), other (PSD, HDR, PIC, PNM also supported by stb_image). RGBA conversion: forces 4 channels (stbi_load with 4 parameter, grayscale->RGBA, RGB->RGBA with full alpha), alpha channel preserved (PNG transparency maintained, white background if no alpha), GPU format R8G8B8A8_UNORM (8 bits per channel, normalized 0-255->0.0-1.0). Texture properties: full image dimensions (widthxheight from file, no resizing or scaling), single mip level (no mipmaps, only base texture level 0), persistent in VRAM (remains in GPU memory until b2dFreeImage called), shared by all draws (multiple b2dDrawImage calls reference same GPU texture). Performance: load cost varies (small 256x256 ~1-5ms, large 2048x2048 ~10-50ms, depends on file size and format), GPU upload synchronous (WaitForFence blocks until upload complete, load not async), recommend load at startup (avoid loading during gameplay, causes frame hitches), batch loading (load multiple images together during load screens). Validation: returns 0 if filepath null (null pointer error), returns 0 if file not found (stbi_load failed, file doesn't exist or unreadable), returns 0 if invalid format (unsupported format or corrupted file), returns 0 if GPU allocation failed (out of VRAM or descriptor heap full), check return value (If img = 0 Then handle error). Image storage: stored in g_images map (std::map<int, OverlayImage>, indexed by handle), OverlayImage structure (width, height, texture ptr, SRV index, frame data for animation), handle persistent (remains valid until b2dFreeImage, don't reuse freed handles). Related: b2dLoadAnimImage loads animation sheet (loads image with frame dimensions, calculates frame count), b2dFreeImage frees image (releases GPU texture and SRV, removes from map), b2dCopyImage copies image (deep copy, creates independent duplicate), b2dGetImageWidth queries width (returns image width in pixels), b2dGetImageHeight queries height (returns image height in pixels), b2dDrawImage draws image (renders image to overlay at position).