b2dSetImageHandle

Sets custom pivot point (handle offset for position, scale, rotation transforms). Takes imageHandle (image handle from b2dLoadImage or b2dLoadAnimImage, positive integer), x (horizontal offset in pixels, integer, 0=left edge), y (vertical offset in pixels, integer, 0=top edge). Returns nothing. Stores handleX/handleY in image structure (persists until changed or image freed), affects all subsequent draws (b2dDrawImage, b2dDrawAnimImage, and Ex versions). Use to set rotation center (rotate around specific point not default top-left), set scaling origin (scale from specific point), or align sprites (position by foot, center, weapon mount point). Handle behavior: default (0,0) top-left (without calling this function, handle at top-left corner), position offset (x,y in draw call specifies where handle point appears, not top-left), rotation center (image rotates around handle point, not top-left), scale origin (image scales from handle point outward). Use cases: (1) Center rotation (b2dSetImageHandle(img, width/2, height/2): rotate around center), (2) Bottom-center for characters (b2dSetImageHandle(player, width/2, height): position by feet), (3) Weapon pivot (b2dSetImageHandle(sword, 5, 50): rotate around grip point), (4) Corner rotation (b2dSetImageHandle(door, 0, height/2): rotate door from hinge), (5) Center-aligned UI (b2dSetImageHandle(button, width/2, height/2): position button by center). Common patterns: center = b2dSetImageHandle(img, w/2, h/2) center pivot; bottom = b2dSetImageHandle(img, w/2, h) align by bottom; reset = b2dSetImageHandle(img, 0, 0) default top-left. Coordinate system: x positive right (0=left edge, width=right edge), y positive down (0=top edge, height=bottom edge), units in pixels (integer pixel offsets from top-left corner). Transform behavior: position offset (drawX,drawY specify where handle appears in screen coordinates), rotation around handle (image rotates around handle point as center), scale from handle (image scales outward from handle point), transform order (scale->rotation->position, handle applied at each step). Animation images: handle applies to each frame (same handle for all frames in animation), coordinates relative to frame (if animation has 64x64 frames, valid range 0-64), single handle for animation (cannot set different handles per frame). Performance: cost zero (simple integer storage, no GPU cost), affects all draws (every b2dDrawImage call uses stored handle until changed), persistent state (remains until b2dSetImageHandle called again or image freed). Validation: ignores if imageHandle invalid (handle not found in g_images map, silently skips), no coordinate validation (negative or out-of-bounds handles accepted, may cause unexpected positioning), safe to call multiple times (overwrites previous handle, last call wins). Related: b2dSetImageMidHandle convenience function (automatically sets handle to image/frame center), b2dGetImageHandleX queries handleX (reads stored X offset), b2dGetImageHandleY queries handleY (reads stored Y offset), b2dDrawImage draws with handle (position, rotation, scale affected by handle), b2dSetRotation sets rotation angle (rotates around handle point), b2dSetScale sets scale factors (scales from handle point).