Blitz3D+ Command Reference

ImageXHandle ( image )

Parameters

image - handle of the image to query

Description

Returns the x position of an image's handle, measured from the left edge of the image.

The handle is the point inside the picture that lines up with the x,y you pass to DrawImage. It is 0 on a freshly loaded image unless AutoMidHandle was on, and it changes when you call MidHandle or HandleImage.

Reading it back is useful when you need to reason about the image in screen space but do not control where the handle was set - converting a sprite's draw position into a top-left corner for your own bounding box, lining a shadow up under a character, or nudging one sprite to a fixed offset from another whatever handle either of them uses. Use ImageYHandle for the other axis.

All frames of an animated image share one handle, so there is no frame parameter.

Note the double meaning of "handle" in these pages: here it is a position inside the image, while the value you pass in is the number that identifies the image itself.

See also: ImageYHandle, HandleImage, MidHandle, AutoMidHandle, ImageWidth.

Example

; ImageXHandle Example
; --------------------

Graphics 640,480,0,2
SetBuffer BackBuffer()

player=LoadImage("media/player.bmp")   ; a 32x36 ship sprite
mode=0

While Not KeyDown(1)

    Cls

    ; Space cycles the handle: top-left, centre, bottom-right
    If KeyHit(57) Then mode=(mode+1) Mod 3
    If mode=0 Then HandleImage player,0,0
    If mode=1 Then MidHandle player
    If mode=2 Then HandleImage player,32,36

    ; A crosshair marks the draw point; the handle decides the offset
    x=MouseX()
    y=MouseY()
    DrawImage player,x,y
    Color 255,255,0
    Line x-10,y,x+10,y
    Line x,y-10,x,y+10

    Text 0,0,"Move mouse   Space: change the handle   Esc: exit"
    ; ImageXHandle reads back the handle position set above
    Text 0,20,"ImageXHandle(player)="+ImageXHandle(player)+"   ImageYHandle(player)="+ImageYHandle(player)

    Flip

Wend

End

Index