410 lines
7.2 KiB
Markdown
410 lines
7.2 KiB
Markdown
# 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.
|