b2dGetImageHandleX

Queries horizontal handle offset (returns stored handleX pivot coordinate). Takes imageHandle (image handle from b2dLoadImage or b2dLoadAnimImage, positive integer). Returns handleX (horizontal offset in pixels, integer, 0 if invalid). Reads image.handleX from g_images map (value set by b2dSetImageHandle or b2dSetImageMidHandle). Use to query pivot point (read current handle position), save/restore state (store handle before modifying), or debug positioning (verify handle coordinates). Return behavior: returns handleX if valid (integer pixel offset from left edge, may be 0 if explicitly set or default), returns 0 if invalid (handle not found in g_images map), default is 0 (if never set via b2dSetImageHandle/MidHandle, handleX starts at 0). Use cases: (1) Save/restore handle (oldX=b2dGetImageHandleX(img): modify: b2dSetImageHandle(img, oldX, oldY)), (2) Query center handle (If b2dGetImageHandleX(img)=width/2 Then centered), (3) Relative handle (newX=b2dGetImageHandleX(img)+offset: adjust handle), (4) Debug handle (Print "Handle: "+b2dGetImageHandleX(img)+","+b2dGetImageHandleY(img)), (5) Conditional drawing (If b2dGetImageHandleX(img)>0 Then custom handle set). Common patterns: query = x = b2dGetImageHandleX(img): read X offset; pair = x = b2dGetImageHandleX(img): y = b2dGetImageHandleY(img) query both. Handle coordinates: x coordinate (horizontal offset from left edge, 0=left, increases rightward), pixel units (integer pixels), valid range (typically 0 to image width, but negatives and beyond width accepted), persistent (remains until b2dSetImageHandle called or image freed). Return value interpretation: 0 may mean (default handle never set, explicitly set to 0 via b2dSetImageHandle(img,0,y), invalid handle returns 0), positive value (handle offset rightward from left edge), negative value (handle offset leftward, may be set explicitly). Typical values: 0 (default top-left handle, left edge alignment), width/2 (center handle via b2dSetImageMidHandle, center alignment), width (right edge handle, right alignment), custom (weapon mount point, foot position, etc). Performance: query cost zero (map lookup and integer read, trivial CPU operation), safe to call every frame (no GPU cost, read-only operation), no allocation (returns stored value directly). Validation: returns 0 if invalid (handle not found in g_images map, safe fallback), no error message (silently returns 0 for invalid handles), safe to query any handle (valid or not, always returns integer). Related: b2dGetImageHandleY queries handleY (returns vertical offset, pair with this function), b2dSetImageHandle sets handle (stores handleX/Y values queried by this function), b2dSetImageMidHandle sets center handle (sets handleX to width/2), b2dGetImageWidth queries width (used with handleX for center calculation), b2dDrawImage draws with handle (uses handleX as pivot point).