Self and View #macros

There is a big list of macros defined in raptor that help when it comes to positioning (especially with camera movements), active viewports, and different sprite offsets, scales, etc.

They are grouped in three major sections: VIEW macros, SELF macros and CAM macros (for the camera).

Let's take a closer look at each of those groups.

CAMERA macros

Macro Name	Description	Code
CAM	The active camera	view_camera[CAM_INDEX]
CAM_WIDTH	The active camera's view width	camera_get_view_width(CAM)
CAM_HEIGHT	The active camera's view height	camera_get_view_height(CAM)
CAM_CENTER_X	Horizontal Camera center	(CAM_LEFT_EDGE + CAM_WIDTH / 2)
CAM_CENTER_Y	Vertical Camera center	(CAM_TOP_EDGE + CAM_HEIGHT / 2)
CAM_LEFT_EDGE	Left edge of camera's view	camera_get_view_x(CAM)
CAM_TOP_EDGE	Top edge of camera's view	camera_get_view_y(CAM)
CAM_RIGHT_EDGE	Right edge of camera's view	(CAM_LEFT_EDGE + CAM_WIDTH - 1)
CAM_BOTTOM_EDGE	Bottom edge of camera's view	(CAM_TOP_EDGE + CAM_HEIGHT - 1)
CAM_ASPECT_RATIO	Camera view dimension ratio	(CAM_WIDTH / CAM_HEIGHT)

VIEW macros

These macros deliver UI coordinates

Macro Name	Description	Code
UI_VIEW_WIDTH	The width (in pixels) of the UI layer	display_get_gui_width()
UI_VIEW_HEIGHT	The height (in pixels) of the UI layer	display_get_gui_height()
UI_VIEW_CENTER_X	Horizontal center point of the UI	(UI_VIEW_WIDTH / 2)
UI_VIEW_CENTER_Y	Vertital center point of the UI	(UI_VIEW_HEIGHT / 2)
UI_VIEW_ASPECT_RATIO	The view dimension ratio	(UI_VIEW_WIDTH / UI_VIEW_HEIGHT)
UI_SCALE	UI scale factor	min(display_get_gui_width()/VIEW_WIDTH, display_get_gui_height()/VIEW_HEIGHT)

These macros deliver world (room-) coordinates

Macro Name	Description	Code
VIEW_WIDTH	The width of the active viewport	view_wport[VIEWPORT_INDEX]
VIEW_HEIGHT	The height of the active viewport	view_hport[VIEWPORT_INDEX]
VIEW_TOP_EDGE	The upper edge of the active viewport	view_yport[VIEWPORT_INDEX]
VIEW_LEFT_EDGE	The left edge of the active viewport	view_xport[VIEWPORT_INDEX]
VIEW_RIGHT_EDGE	The right edge of the active viewport	(VIEW_LEFT_EDGE + UI_VIEW_WIDTH)
VIEW_BOTTOM_EDGE	The bottom edge of the active viewport	(VIEW_TOP_EDGE + UI_VIEW_HEIGHT)
VIEW_CENTER_X	The horizontal center of the active viewport	(VIEW_LEFT_EDGE + VIEW_WIDTH / 2)
VIEW_CENTER_Y	The vertical center of the active viewport	(VIEW_TOP_EDGE + VIEW_HEIGHT / 2)
VIEW_ASPECT_RATIO	The viewports' dimension ratio	(VIEW_WIDTH / VIEW_HEIGHT)

SELF macros

These can be used inside objects (self must be an object instance).
NOTE: All SELF macros respect the sprite x/y offset and deliver ready-to-use values!

Macro Name	Description	Code
SELF_WIDTH	Own (scaled) width	sprite_width
SELF_HEIGHT	Own (scaled) height	sprite_height
SELF_WIDTH_UNSCALED	Own sprites' original width	sprite_get_width(sprite_index)
SELF_HEIGHT_UNSCALED	Own sprites' original height	sprite_get_height(sprite_index)
SELF_CENTER_X	Own horizontal center	(sprite_width / 2 - sprite_xoffset)
SELF_CENTER_Y	Own vertical center	(sprite_height / 2 - sprite_yoffset)
SELF_CENTER	"x,y" coordinate pair of own center. Neat on function calls that take x,y params	SELF_CENTER_X, SELF_CENTER_Y
SELF_LEFT_EDGE	Own left edge	-sprite_xoffset
SELF_TOP_EDGE	Own top edge	-sprite_yoffset
SELF_RIGHT_EDGE	Own right edge	(sprite_width - 1 - sprite_xoffset)
SELF_BOTTOM_EDGE	Own bottom edge	(sprite_height - 1 - sprite_yoffset)
SELF_ASPECT_RATIO	Own dimension ratio	(SELF_WIDTH / SELF_HEIGHT)
SELF_MOVE_DELTA_X	Moved distance since last frame	(x - xprevious)
SELF_MOVE_DELTA_Y	Moved distance since last frame	(y - yprevious)
SELF_HAVE_MOVED	true/false whether we have moved	(SELF_MOVE_DELTA_X!=0||SELF_MOVE_DELTA_Y!=0)
SELF_VIEW_CENTER_X	Own center point in the room	(x + SELF_CENTER_X)
SELF_VIEW_CENTER_Y	Own center point in the room	(y + SELF_CENTER_Y)
SELF_VIEW_CENTER	"x,y" pair similar to SELF_CENTER	SELF_VIEW_CENTER_X, SELF_VIEW_CENTER_Y
SELF_VIEW_LEFT_EDGE	Own left edge in the room	(x + SELF_LEFT_EDGE)
SELF_VIEW_TOP_EDGE	Own top edge in the room	(y + SELF_TOP_EDGE)
SELF_VIEW_RIGHT_EDGE	Own right edge in the room	(x + SELF_RIGHT_EDGE)
SELF_VIEW_BOTTOM_EDGE	Own bottom edge in the room	(y + SELF_BOTTOM_EDGE)

SELF_UI macros

These can be used inside objects (self must be an object instance).
NOTE: These macros behave identically to the SELF_* macros above, but they deliver their values from the GUI layer coordinates and also take UI_SCALE into account.

Macro Name	Description	Code
SELF_UI_VIEW_CENTER_X	Own center point in the UI	(UI_SCALE * (x + SELF_CENTER_X))
SELF_UI_VIEW_CENTER_Y	Own center point in the UI	(UI_SCALE * (y + SELF_CENTER_Y))
SELF_UI_VIEW_CENTER	"x,y" pair similar to SELF_CENTER	(UI_SCALE * SELF_VIEW_CENTER_X), (UI_SCALE * SELF_VIEW_CENTER_Y)
SELF_UI_VIEW_LEFT_EDGE	Own left edge in the UI	(UI_SCALE * (x + SELF_LEFT_EDGE))
SELF_UI_VIEW_TOP_EDGE	Own top edge in the UI	(UI_SCALE * (y + SELF_TOP_EDGE))
SELF_UI_VIEW_RIGHT_EDGE	Own right edge in the UI	(UI_SCALE * (x + SELF_RIGHT_EDGE))
SELF_UI_VIEW_BOTTOM_EDGE	Own bottom edge in the UI	(UI_SCALE * (y + SELF_BOTTOM_EDGE))

Advanced options for the CAM and VIEW macros

If you looked closely at the code of the macros above, you might have recognized the CAM_INDEX and VIEWPORT_INDEX macros used in some of them, but those are never declared here.
This is because they are not macros -- they are global variables which you can modify.

There are two functions available that help, if you have more than one camera and/or viewport active.
You do not need to remember the old values when switching the camera or the viewport.

macro_camera_viewport_index_switch_to(cam, viewport)

This function activates another camera and/or viewport index. After calling this, all the macros above deliver the values of the now active camera/viewport.
Both parameters are optional and default to 0.

macro_camera_viewport_index_switch_back()

After you are finished with your calculations for another camera/viewport, simply call this function to restore the index values that have been active before.