# IMAGE A static image rendered on a scene. Supports positioning, opacity, clipping, runtime file loading, and collision monitoring against other objects. ## Fields ### FILENAME ``` STRING FILENAME ``` Name of the `.IMG` file with the image. Read at variable initialisation; can also be overwritten at runtime via [`LOAD`](#load). ### MONITORCOLLISION ``` BOOL MONITORCOLLISION ``` Whether the image participates in collision detection with other objects. Modified through [`MONITORCOLLISION`](#monitorcollision-1) and [`REMOVEMONITORCOLLISION`](#removemonitorcollision). ### MONITORCOLLISIONALPHA ``` BOOL MONITORCOLLISIONALPHA ``` Whether collision detection takes the image's alpha channel into account — collisions do not occur on fully transparent pixels. ### PRIORITY ``` INTEGER PRIORITY ``` Rendering priority (`Z`) relative to other scene objects. ### VISIBLE ``` BOOL VISIBLE ``` Image visibility. Modified through [`SHOW`](#show) and [`HIDE`](#hide). ## Methods ### GETALPHA ``` INTEGER GETALPHA(INTEGER posX, INTEGER posY) ``` Returns the alpha-channel value of the pixel at the given coordinates (in the `0–255` scale, where `255` is fully opaque). **Parameters** - `posX` — pixel X coordinate. - `posY` — pixel Y coordinate. **Returns**: the pixel's alpha value. **Examples** ``` IMGLEVEL^GETALPHA(VARX, VARY); IMGALPHA^GETALPHA(EXPMASKX, EXPMASKY); ``` ### GETCENTERX ``` INTEGER GETCENTERX() ``` Returns the X coordinate of the centre of the image's bounding rectangle. **Returns**: centre X. ### GETCENTERY ``` INTEGER GETCENTERY() ``` Returns the Y coordinate of the centre of the image's bounding rectangle. **Returns**: centre Y. ### GETHEIGHT ``` INTEGER GETHEIGHT() ``` Returns the image's height in pixels. **Returns**: image height. **Examples** ``` IMGLINA^GETHEIGHT(); ``` ### GETPIXEL ``` INTEGER GETPIXEL(INTEGER posX, INTEGER posY) ``` Returns the pixel value at the given coordinates as an integer encoded per the image's colour depth: RGB565 for 16-bit images, RGB555 for 15-bit images. **Parameters** - `posX` — pixel X coordinate. - `posY` — pixel Y coordinate. **Returns**: the encoded pixel colour value. **Examples** ``` IMGMASK^GETPIXEL(IKONNEWX, IKONNEWY); ``` ### GETPOSITIONX ``` INTEGER GETPOSITIONX() ``` Returns the X coordinate of the image's top-left corner. **Returns**: position X. ### GETPOSITIONY ``` INTEGER GETPOSITIONY() ``` Returns the Y coordinate of the image's top-left corner. **Returns**: position Y. ### GETWIDTH ``` INTEGER GETWIDTH() ``` Returns the image's width in pixels. **Returns**: image width. **Examples** ``` IMGPASEK^GETWIDTH(); ``` ### HIDE ``` void HIDE() ``` Hides the image (sets [`VISIBLE`](#visible) to `FALSE`). **Examples** ``` G_IMGPAGE^HIDE(); ``` ### INVALIDATE ``` void INVALIDATE() ``` Applies the pending opacity value previously set with [`SETOPACITY`](#setopacity). Without `INVALIDATE`, the opacity change does not become visible. **Examples** ``` G_IMGPAGE^INVALIDATE(); ``` ### ISAT ``` BOOL ISAT(INTEGER posX, INTEGER posY) ``` Checks whether the point at the given coordinates lies inside the image's bounding rectangle. **Parameters** - `posX` — point X coordinate. - `posY` — point Y coordinate. **Returns**: [`BOOL`](BOOL.md) — `TRUE` if the point is inside the image's rectangle. ### LOAD ``` void LOAD(STRING path) ``` Loads an image from a file, replacing the previous contents. After loading, the image is automatically shown ([`VISIBLE`](#visible) is set to `TRUE`). **Parameters** - `path` — `.IMG` file path in the game's VFS. **Examples** ``` G_IMGPAGE^LOAD("$COMMON\PAGE.IMG"); IMGTLO^LOAD(VARSTEMP0); IMGSCR^LOAD(["$COMMON\SAVE_BD\BD_SCR"+VARIACTIVESLOT+".IMG"]); ``` ### MERGEALPHA ``` void MERGEALPHA(INTEGER posX, INTEGER posY, STRING maskName) ``` Binds an alpha mask sourced from another image to this image. The mask is positioned at `(posX, posY)` and modifies the resulting transparency of the current image in the overlapping area. **Parameters** - `posX` — mask X position. - `posY` — mask Y position. - `maskName` — name of the `IMAGE` variable whose alpha channel will be used as the mask. **Examples** ``` IMGDARK^MERGEALPHA([ANNPLAYER0^GETCENTERX()-75], [ANNPLAYER0^GETCENTERY()-75], "IMGKOLKO"); IMG_WODA^MERGEALPHA(800, VARI_Y, "IMG_LIGHT"); ``` ### MONITORCOLLISION {#monitorcollision-1} ``` void MONITORCOLLISION() ``` Enables collision monitoring between this image and other objects. After the call, the [`MONITORCOLLISION`](#monitorcollision) field is `TRUE` and the image is registered with the collision-detection mechanism. ### MONITORCOLLISIONALPHA {#monitorcollisionalpha-1} ``` void MONITORCOLLISIONALPHA() ``` Enables alpha-channel awareness in collision detection. After the call, the [`MONITORCOLLISIONALPHA`](#monitorcollisionalpha) field is `TRUE`. ### MOVE ``` void MOVE(INTEGER offsetX, INTEGER offsetY) ``` Moves the image by the given offsets relative to its current position. **Parameters** - `offsetX` — X offset. - `offsetY` — Y offset. **Examples** ``` IMGBKGA^MOVE(0, 800); IMGLINA^MOVE(0, IMOVDY); IMRECT^MOVE(IGSX, 0); ``` ### REMOVEMONITORCOLLISION ``` void REMOVEMONITORCOLLISION() ``` Disables collision monitoring previously enabled by [`MONITORCOLLISION`](#monitorcollision-1). ### REMOVEMONITORCOLLISIONALPHA ``` void REMOVEMONITORCOLLISIONALPHA() ``` Disables alpha-channel awareness in collision detection, previously enabled by [`MONITORCOLLISIONALPHA`](#monitorcollisionalpha-1). ### SETCLIPPING ``` void SETCLIPPING(INTEGER xLeft, INTEGER yBottom, INTEGER xRight, INTEGER yTop) ``` Restricts the image's drawing area to the rectangle defined by the given edges. Pixels outside the rectangle are not drawn. **Parameters** - `xLeft, yBottom, xRight, yTop` — coordinates of the clipping rectangle. **Examples** ``` G_IMGPAGE^SETCLIPPING(0, 0, G_IPAGE, 600); ``` ### SETOPACITY ``` void SETOPACITY(INTEGER opacity) ``` Sets the pending opacity value in the `0–255` scale (`0` — fully transparent, `255` — fully opaque). Out-of-range values are clamped. **The change does not become visible until [`INVALIDATE`](#invalidate) is called.** **Parameters** - `opacity` — alpha-channel value (`0–255`). **Examples** ``` AIDEMMEDIA^SETOPACITY(VARNR); IMGBRIDGE^SETOPACITY(200); ``` ### SETPOSITION ``` void SETPOSITION(INTEGER posX, INTEGER posY) ``` Sets the absolute position of the image's top-left corner. **Parameters** - `posX` — X coordinate. - `posY` — Y coordinate. **Examples** ``` IMGENERGIA^SETPOSITION([795-VARENERGIA], 78); IMGKOLKO^SETPOSITION(-500, -500); IMGNAKLADKA^SETPOSITION(VARIPOSX, 0); ``` ### SETPRIORITY ``` void SETPRIORITY(INTEGER priority) ``` Sets the image's rendering priority. **Parameters** - `priority` — the new value of the [`PRIORITY`](#priority) field. **Examples** ``` G_IMGPAGE^SETPRIORITY(3000); AIDEMMEDIA^SETPRIORITY(3); ``` ### SHOW ``` void SHOW() ``` Shows the image (sets [`VISIBLE`](#visible) to `TRUE`). **Examples** ``` G_IMGPAGE^SHOW(); REX^SHOW(); ``` ## Signals ### ONCLICK Fired when the image is clicked. ### ONFOCUSON Fired when the cursor moves onto the image. ### ONFOCUSOFF Fired when the cursor moves off the image. ### ONINIT Fired when the object is initialised.