Rex-EMoolator-docs/docs/en/reference/CANVAS_OBSERVER.md

CANVAS_OBSERVER

Entry point for canvas operations — the shared rendering area where the engine draws every visible graphic. Provides methods for adding and removing graphics from the screen, looking up the object under a point, setting the background, taking screenshots, and emitting signals on game-window focus changes.

A scene typically has a single CANVAS_OBSERVER instance that scripts treat as a global object.

Methods

ADD

void ADD(STRING varName)
void ADD(STRING varName, INTEGER priority)

Adds an ANIMO or IMAGE variable to the canvas — makes it visible and optionally assigns a render priority (default 1000).

Parameters

• varName — name of the graphics variable.
• priority — (optional) render priority (Z position).

Examples

CANVASOBSERVER^ADD("ANNMKORBA2");
CANVASOBSERVER^ADD("ANNMPRZEGRYZA");

ENABLENOTIFY

void ENABLENOTIFY(BOOL enable)

Enables or disables emission of game-window focus signals (ONWINDOWFOCUSON, ONWINDOWFOCUSOFF).

Parameters

• enable — TRUE enables notifications, FALSE disables them.

Examples

CANVASOBSERVER^ENABLENOTIFY(TRUE);

GETBPP

INTEGER GETBPP()

Returns the canvas colour depth in bits per pixel. The original BlooMoo engine runs in 16 bpp (RGB565) — this method always returns 16.

Returns: INTEGER — colour depth in bits (16).

GETGRAPHICSAT

STRING GETGRAPHICSAT(INTEGER posX, INTEGER posY, BOOL onlyVisible, INTEGER minZ, INTEGER maxZ)
STRING GETGRAPHICSAT(INTEGER posX, INTEGER posY, BOOL onlyVisible, INTEGER minZ, INTEGER maxZ, BOOL ignoreAlpha)

Returns the name of the graphics variable at the point (posX, posY). Only the current scene is searched. The lookup starts from the highest-priority graphic and walks down. Returns "NULL" if no graphic matches.

Parameters

• posX, posY — query point coordinates.
• onlyVisible — if TRUE, only currently visible graphics are considered.
• minZ, maxZ — priority (Z) range restricting the search.
• ignoreAlpha — (optional) if TRUE, only the graphic's rectangle is tested; if FALSE (or omitted), the pixel's alpha channel is checked too.

Returns: STRING — the matched object's name or "NULL".

Examples

CANVASOBSERVER^GETGRAPHICSAT(MOUSE^GETPOSX(),MOUSE^GETPOSY(),TRUE,2998,2998,FALSE);
CANVASOBSERVER^GETGRAPHICSAT(VARICURSORX,VARICURSORY,TRUE,40,40,TRUE);

GETGRAPHICSAT2

STRING GETGRAPHICSAT2(INTEGER posX, INTEGER posY, BOOL onlyVisible, INTEGER minZ, INTEGER maxZ)
STRING GETGRAPHICSAT2(INTEGER posX, INTEGER posY, BOOL onlyVisible, INTEGER minZ, INTEGER maxZ, BOOL ignoreAlpha)

Variant of GETGRAPHICSAT that walks up the container hierarchy (scene → episode → root) instead of searching only the current scene.

MOVEBKG

void MOVEBKG(INTEGER deltaX, INTEGER deltaY)

Moves the background by the given X/Y deltas (relative to its current position).

Parameters

• deltaX, deltaY — translation vector in pixels.

Examples

CANVASOBSERVER^MOVEBKG(0,ARRAYDY^GET(0));
CANVASOBSERVER^MOVEBKG(ISCROLLMOVEX,ISCROLLMOVEY);

PASTE

void PASTE(STRING varName, INTEGER posX, INTEGER posY)

Pastes a snapshot of the current contents of an ANIMO or IMAGE graphic onto the canvas as a static, non-modifiable texture at (posX, posY). The source variable itself is not modified.

Parameters

• varName — name of the graphics variable.
• posX, posY — paste position.

Examples

CANVASOBSERVER^PASTE("ANNBUM",[I1-IPLANPOSX],[I2-IPLANPOSY]);
CANVASOBSERVER^PASTE("IMG1",0,0);

REDRAW

void REDRAW()

In the original engine this marks the canvas as needing repaint. In practice the engine already redraws the whole canvas every frame, so this method behaves as a no-op.

REFRESH

void REFRESH()

Forces a redraw of every IMAGE in the current scene — internally calls INVALIDATE on each.

REMOVE

void REMOVE(STRING varName1, [STRING varName2, ...])

Hides the listed graphics on the canvas (sets their visibility to FALSE). Accepts any number of arguments.

Parameters

• varName1, varName2, … — successive graphics-variable names to hide.

Examples

CANVASOBSERVER^REMOVE("ZLY");
CANVASOBSERVER^REMOVE("ANNAUTOR","ANNAUTOL","ANNAUTORMASK","ANNAUTOLMASK");

SAVE

void SAVE(STRING imgFileName, DOUBLE xScaleFactor, DOUBLE yScaleFactor)
void SAVE(STRING imgFileName, DOUBLE xScaleFactor, DOUBLE yScaleFactor, INTEGER xLeft, INTEGER yTop, INTEGER xRight, INTEGER yBottom)

Saves the current canvas view to an .IMG file. The seven-argument form crops a rectangle from the canvas before scaling.

Parameters

• imgFileName — destination .IMG path.
• xScaleFactor, yScaleFactor — X/Y scaling factors.
• xLeft, yTop, xRight, yBottom — (optional) rectangle to crop before scaling.

Examples

CANVASOBSERVER^SAVE("$COMMON\PAGE.IMG",1,1);
CANVASOBSERVER^SAVE("$COMMON\ZOOM.IMG",2,2,$1,$2,$3,$4);
CANVASOBSERVER^SAVE(["$COMMON\SAVE_BD\BD_SCR"+VARISLOTNO+".IMG"],0.5,0.5);

SETBACKGROUND

void SETBACKGROUND(STRING imageName)

Sets the canvas background. The argument may name an existing IMAGE variable or a path to an .IMG file — in the latter case the engine creates a hidden IMAGE variable backing that file.

Parameters

• imageName — IMAGE variable name or .IMG file path.

Examples

CANVASOBSERVER^SETBACKGROUND(SOBJECT|NAME);
CANVASOBSERVER^SETBACKGROUND("LOGO.IMG");

SETBKGPOS

void SETBKGPOS(INTEGER posX, INTEGER posY)

Sets the absolute X/Y position of the background.

Parameters

• posX, posY — new background position.

Examples

CANVASOBSERVER^SETBKGPOS([VARI_BKGX-VARI_BKGXOFFSET],[VARI_BKGY-VARI_BKGYOFFSET]);
CANVASOBSERVER^SETBKGPOS(VARI_TMPX,0);

Signals

ONINIT

Fired when the object is initialised.

ONWINDOWFOCUSON

Fired when the game window gains focus (e.g. after un-minimising). Emission requires notifications enabled via ENABLENOTIFY.

ONWINDOWFOCUSOFF

Fired when the game window loses focus (e.g. when switched to another application). Emission requires notifications enabled.

ONSIGNAL

Fired when a signal arrives (see Events and signals).