b2dGetImageHandleY

Queries vertical handle offset (returns stored handleY pivot coordinate). Takes imageHandle (image handle from b2dLoadImage or b2dLoadAnimImage, positive integer). Returns handleY (vertical offset in pixels, integer, 0 if invalid). Reads image.handleY 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 handleY if valid (integer pixel offset from top 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, handleY starts at 0). Use cases: (1) Save/restore handle (oldY=b2dGetImageHandleY(img): modify: b2dSetImageHandle(img, oldX, oldY)), (2) Query center handle (If b2dGetImageHandleY(img)=height/2 Then centered), (3) Relative handle (newY=b2dGetImageHandleY(img)+offset: adjust handle), (4) Debug handle (Print "Handle: "+b2dGetImageHandleX(img)+","+b2dGetImageHandleY(img)), (5) Conditional drawing (If b2dGetImageHandleY(img)=height Then bottom-aligned). Common patterns: query = y = b2dGetImageHandleY(img): read Y offset; pair = x = b2dGetImageHandleX(img): y = b2dGetImageHandleY(img) query both. Handle coordinates: y coordinate (vertical offset from top edge, 0=top, increases downward), pixel units (integer pixels), valid range (typically 0 to image height, but negatives and beyond height 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,x,0), invalid handle returns 0), positive value (handle offset downward from top edge), negative value (handle offset upward, may be set explicitly). Typical values: 0 (default top-left handle, top edge alignment), height/2 (center handle via b2dSetImageMidHandle, center alignment), height (bottom edge handle, bottom alignment for characters standing on ground), custom (head position, weapon mount point, 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: b2dGetImageHandleX queries handleX (returns horizontal offset, pair with this function), b2dSetImageHandle sets handle (stores handleX/Y values queried by this function), b2dSetImageMidHandle sets center handle (sets handleY to height/2), b2dGetImageHeight queries height (used with handleY for center calculation), b2dDrawImage draws with handle (uses handleY as pivot point).