| Definitions: | Constants for screen properties | |
|---|---|---|
| Name | Value | Description |
| screen_width | 640 | Width of the screen, in pixels |
| screen_height | 360 | Height of the screen, in pixels |
| Definitions: | Values for common colors (with full opacity) | |
|---|---|---|
| Name | Value | Description |
| color_black | FF000000h | Pure black |
| color_white | FFFFFFFFh | Pure white |
| color_gray | FF808080h | 1/2 brightness gray |
| color_darkgray | FF404040h | 1/4 brightness gray |
| color_lightgray | FFC0C0C0h | 3/4 brightness gray |
| color_red | FF0000FFh | Pure red |
| color_green | FF00FF00h | Pure green |
| color_blue | FFFF0000h | Pure blue |
| color_yellow | FF00FFFFh | Yellow (red + green) |
| color_magenta | FFFF00FFh | Magenta (red + blue) |
| color_cyan | FFFFFF00h | Cyan (green + blue) |
| color_orange | FF0080FFh | Orange (red + 1/2 green) |
| color_brown | FF204080h | Brown (1/2 red + 1/4 green + 1/8 blue) |
| Function: | make_gray |
|---|---|
| Prototype: | int make_gray( int brightness ) |
| Description: | Makes a gray color in RGBA format, with the given brightness and full opacity |
| Returns: | |
| int | The resulting color |
| Arguments: | |
| int brightness | Brightness of the gray tone, in range [0-255] |
| Function: | make_color_rgb |
|---|---|
| Prototype: | int make_color_rgb( int r, int g, int b ) |
| Description: | Makes a color in RGBA format, with the requested RGB components and full opacity |
| Returns: | |
| int | The resulting color |
| Arguments: | |
| int r | Red component of the color, in range [0-255] |
| int g | Green component of the color, in range [0-255] |
| int b | Blue component of the color, in range [0-255] |
| Function: | make_color_rgba |
|---|---|
| Prototype: | int make_color_rgba( int r, int g, int b, int a ) |
| Description: | Makes a color in RGBA format, with the requested components |
| Returns: | |
| int | The resulting color |
| Arguments: | |
| int r | Red component of the color, in range [0-255] |
| int g | Green component of the color, in range [0-255] |
| int b | Blue component of the color, in range [0-255] |
| int a | Alpha component of the color, in range [0-255] |
| Function: | get_color_red |
|---|---|
| Prototype: | int get_color_red( int color ) |
| Description: | Returns the red component of a color in RGBA format |
| Returns: | |
| int | The red component, in range [0-255] |
| Arguments: | |
| int color | The input color in RGBA format |
| Function: | get_color_green |
|---|---|
| Prototype: | int get_color_green( int color ) |
| Description: | Returns the green component of a color in RGBA format |
| Returns: | |
| int | The green component, in range [0-255] |
| Arguments: | |
| int color | The input color in RGBA format |
| Function: | get_color_blue |
|---|---|
| Prototype: | int get_color_blue( int color ) |
| Description: | Returns the blue component of a color in RGBA format |
| Returns: | |
| int | The blue component, in range [0-255] |
| Arguments: | |
| int color | The input color in RGBA format |
| Function: | get_color_alpha |
|---|---|
| Prototype: | int get_color_alpha( int color ) |
| Description: | Returns the alpha component of a color in RGBA format |
| Returns: | |
| int | The alpha component, in range [0-255] |
| Arguments: | |
| int color | The input color in RGBA format |
| Function: | select_texture |
|---|---|
| Prototype: | void select_texture( int texture_id ) |
| Description: | Sets the selected texture to the given texture ID. All texture functions will apply to that texture from that moment |
| Arguments: | |
| int texture_id | ID of the texture to select |
| Function: | get_selected_texture |
|---|---|
| Prototype: | int get_selected_texture() |
| Description: | Gets the ID of the currently selected texture |
| Returns: | |
| int | ID of selected texture (from -1 to the last texture ID in the cartridge, if any) |
| Function: | select_region |
|---|---|
| Prototype: | void select_region( int region_id ) |
| Description: | Sets the selected texture region to the given texture ID. All region functions will apply to that region ID from the selected texture |
| Arguments: | |
| int region_id | ID of the texture region to select |
| Function: | get_selected_region |
|---|---|
| Prototype: | int get_selected_region() |
| Description: | Gets the ID of the currently selected texture region |
| Returns: | |
| int | ID of selected texture region (from 0 to 4095) |
| Function: | define_region |
|---|---|
| Prototype: | void define_region( int min_x, int min_y, int max_x, int max_y, int hotspot_x, int hotspot_y ) |
| Description: | Defines the currently selected texture region, as a rectangle within the selected texture. All arguments are given in pixel coordinates within the selected texture |
| Arguments: | |
| int min_x | Left boundary of the region |
| int min_y | Top boundary of the region |
| int max_x | Right boundary of the region |
| int max_y | Bottom boundary of the region |
| int hotspot_x | X coordinate of the hotspot (can be outside the texture) |
| int hotspot_y | Y coordinate of the hotspot (can be outside the texture) |
| Function: | define_region_topleft |
|---|---|
| Prototype: | void define_region_topleft( int min_x, int min_y, int max_x, int max_y ) |
| Description: | Same as define_region, but automatically places the hotspot at the top-left corner |
| Arguments: | |
| int min_x | Left boundary of the region |
| int min_y | Top boundary of the region |
| int max_x | Right boundary of the region |
| int max_y | Bottom boundary of the region |
| Function: | define_region_center |
|---|---|
| Prototype: | void define_region_center( int min_x, int min_y, int max_x, int max_y ) |
| Description: | Same as define_region, but automatically places the hotspot at the center of the rectangle |
| Arguments: | |
| int min_x | Left boundary of the region |
| int min_y | Top boundary of the region |
| int max_x | Right boundary of the region |
| int max_y | Bottom boundary of the region |
| Function: | define_region_matrix |
|---|---|
| Prototype: | void define_region_matrix( int first_id, int first_min_x, int first_min_y, int first_max_x, int first_max_y, int first_hotspot_x, int first_hotspot_y, int elements_x, int elements_y, int gap ) |
| Description: | Defines a set of same-sized regions within the selected texture that are laid out as a rectangular matrix. Consecutive IDs will be defined from left to right, and top to bottom. All regions will have the same relative hotspot position |
| Arguments: | |
| int first_id | ID to use for the first region (top-left region in the matrix) |
| int first_min_x | Left boundary of the first region |
| int first_min_y | Top boundary of the first region |
| int first_max_x | Right boundary of the first region |
| int first_max_y | Bottom boundary of the first region |
| int first_hotspot_x | X coordinate of the first region's hotspot |
| int first_hotspot_y | Y coordinate of the first region's hotspot |
| int elements_x | Number of columns in the region matrix |
| int elements_y | Number of rows in the region matrix |
| int gap | Separation in pixels between adjacent regions |
| Function: | set_region_hotspot |
|---|---|
| Prototype: | void set_region_hotspot( int hotspot_x, int hotspot_y ) |
| Description: | Sets the hotspot for the currently selected texture region |
| Arguments: | |
| int hotspot_x | X coordinate of the hotspot (can be outside the texture) |
| int hotspot_y | Y coordinate of the hotspot (can be outside the texture) |
| Definitions: | Supported color blending modes | |
|---|---|---|
| Name | Value | Description |
| blending_alpha | 20h | Alpha blending: Colors are replaced (neutral). The default mode |
| blending_add | 21h | Addition blending: Colors are added (light effect) |
| blending_subtract | 22h | Subtraction blending: Colors are subtracted (shadow effect) |
| Function: | set_blending_mode |
|---|---|
| Prototype: | void set_blending_mode( int mode ) |
| Description: | Changes the active color blending to the specified mode |
| Arguments: | |
| int mode | One of the possible blending modes defined |
| Function: | get_blending_mode |
|---|---|
| Prototype: | int get_blending_mode() |
| Description: | Obtains the active color blending mode |
| Returns: | |
| int | The currently active blending mode |
| Function: | set_multiply_color |
|---|---|
| Prototype: | void set_multiply_color( int color ) |
| Description: | Sets the multiply color to the given color. Next region drawing commands will be done with the new multiply color |
| Arguments: | |
| int color | The new multiply color |
| Function: | get_multiply_color |
|---|---|
| Prototype: | int get_multiply_color() |
| Description: | Obtains the current multiply color |
| Returns: | |
| int | The current multiply color |
| Function: | set_drawing_point |
|---|---|
| Prototype: | void set_drawing_point( int drawing_x, int drawing_y ) |
| Description: | Sets the drawing point to the given screen coordinates. Next region drawing commands will be placed on the new drawing point |
| Arguments: | |
| int drawing_x | X coordinate of the new drawing point |
| int drawing_y | Y coordinate of the new drawing point |
| Function: | get_drawing_point |
|---|---|
| Prototype: | void get_drawing_point( int* drawing_x, int* drawing_y ) |
| Description: | Obtains the coordinates of the current drawing point |
| Arguments: | |
| int* drawing_x | Pointer to an integer that will receive the X coordinate |
| int* drawing_y | Pointer to an integer that will receive the Y coordinate |
| Function: | set_drawing_scale |
|---|---|
| Prototype: | void set_drawing_scale( float scale_x, float scale_y ) |
| Description: | Sets the drawing scale to the given X and Y factors. Next region drawing commands that enable scaling will use the new factors |
| Arguments: | |
| float scale_x | New scale factor on X. Negative values cause a mirror effect along X |
| float scale_y | New scale factor on Y. Negative values cause a mirror effect along Y |
| Function: | get_drawing_scale |
|---|---|
| Prototype: | void get_drawing_scale( float* scale_x, float* scale_y ) |
| Description: | Obtains the current scale factors on X and Y |
| Arguments: | |
| float* scale_x | Pointer to a float that will receive the X scale factor |
| float* scale_y | Pointer to a float that will receive the Y scale factor |
| Function: | set_drawing_angle |
|---|---|
| Prototype: | void set_drawing_angle( float angle ) |
| Description: | Sets the drawing angle to the new value. Next region drawing commands that enable rotation will use the new angle |
| Arguments: | |
| float angle | The new rotation angle, given in radians. Positive angles rotate clockwise |
| Function: | get_drawing_angle |
|---|---|
| Prototype: | float get_drawing_angle() |
| Description: | Obtains the current drawing angle |
| Returns: | |
| float | The current rotation angle, in radians. Positive angles rotate clockwise |
| Function: | clear_screen |
|---|---|
| Prototype: | void clear_screen( int color ) |
| Description: | Fills the screen with the given color. This command is affected by the active blending mode, but color multiply effect is not applied |
| Arguments: | |
| int color | The color to use |
| Function: | draw_region |
|---|---|
| Prototype: | void draw_region() |
| Description: | Draws the currently selected texture region, at the current drawing position, with scaling and rotation effects disabled |
| Function: | draw_region_at |
|---|---|
| Prototype: | void draw_region_at( int drawing_x, int drawing_y ) |
| Description: | Draws the currently selected texture region, at the specified position on screen, with scaling and rotation effects disabled |
| Arguments: | |
| int drawing_x | X coordinate of the drawing position |
| int drawing_y | Y coordinate of the drawing position |
| Function: | draw_region_zoomed |
|---|---|
| Prototype: | void draw_region_zoomed() |
| Description: | Draws the currently selected texture region, at the current drawing position, with scaling enabled and rotation disabled |
| Function: | draw_region_zoomed_at |
|---|---|
| Prototype: | void draw_region_zoomed_at( int drawing_x, int drawing_y ) |
| Description: | Draws the currently selected texture region, at the specified position on screen, with scaling enabled and rotation disabled |
| Arguments: | |
| int drawing_x | X coordinate of the drawing position |
| int drawing_y | Y coordinate of the drawing position |
| Function: | draw_region_rotated |
|---|---|
| Prototype: | void draw_region_rotated() |
| Description: | Draws the currently selected texture region, at the current drawing position, with rotation enabled and scaling disabled |
| Function: | draw_region_rotated_at |
|---|---|
| Prototype: | void draw_region_rotated_at( int drawing_x, int drawing_y ) |
| Description: | Draws the currently selected texture region, at the specified position on screen, with rotation enabled and scaling disabled |
| Arguments: | |
| int drawing_x | X coordinate of the drawing position |
| int drawing_y | Y coordinate of the drawing position |
| Function: | draw_region_rotozoomed |
|---|---|
| Prototype: | void draw_region_rotozoomed() |
| Description: | Draws the currently selected texture region, at the current drawing position, with scaling and rotation effects enabled |
| Function: | draw_region_rotozoomed_at |
|---|---|
| Prototype: | void draw_region_rotozoomed_at( int drawing_x, int drawing_y ) |
| Description: | Draws the currently selected texture region, at the specified position on screen, with scaling and rotation effects enabled |
| Arguments: | |
| int drawing_x | X coordinate of the drawing position |
| int drawing_y | Y coordinate of the drawing position |
| Definitions: | Sizes for the BIOS font | |
|---|---|---|
| Name | Value | Description |
| bios_character_width | 10 | Width in pixels of BIOS font characters |
| bios_character_height | 20 | Height in pixels of BIOS font characters |
| Function: | print_at |
|---|---|
| Prototype: | void print_at( int drawing_x, int drawing_y, int* text ) |
| Description: | Prints a text string using the BIOS font, at the specified position |
| Arguments: | |
| int drawing_x | X coordinate for text left |
| int drawing_y | Y coordinate for text top |
| int* text | Pointer to the null-terminated string to print |
| Function: | |
|---|---|
| Prototype: | void print( int* text ) |
| Description: | Prints a text string using the BIOS font, at the current drawing position |
| Arguments: | |
| int* text | Pointer to the null-terminated string to print |