Home
This documentation is for the version 2.9.
Version 2.9 comes with a major update. Backup your project before updating. The internal algorithms and the outer scripts have been changed and may potentially cause unintended behaviour - if you find a bug, please report it either on the marketplace or github. Read the changes carefully and update your implementations accordingly. I'm also planning to update this to GMS2 once I grab a license in the end of August.
- image_stream_add scripts now require a float between 0.0-1.0 for their origin arguments instead of ints. 1.0 is the width/height of the image to be loaded. This change makes sure that there are no resolution specific limitations by requiring to know the size of the sprite beforehand
- Added image_save_sheet(ind, fname, row_count) to save images as sheets instead of strips
- Added image_stream_add_files - creates a single image from subimages saved as multiple files (coin_0.png, coin_1.png etc). The path specified must not contain the file type or the number.
- Added image_stream_add_sheet - adds an image from a sheet rather than a strip. Requires row and column counts. Shows a warning in case the image size doesn't divide with the row/column counts properly.
- Image_stream_add_ scripts and image_stream_receive now make sure that the added image is not larger than the texturepage's size.
- Added bbox support to images. Image streams will now automatically calculate the smallest possible collision box of an added image using Game Maker's built in functionality.
- Added image_get_bbox_left, _bbox_top, _bbox_right, _bbox_bottom and image_set_bbox
- Added clamp and removeback booleans to image_stream_start arguments. Clamp cuts the stored image on a texturepage to the bare minimum, getting rid of all the excess transparent sides. Removeback indicates whether to make all pixels with the background colour (left-bottom pixel) transparent.
- Added image_stream_stop(group) - if the stream is active it will be stopped and all its data cleared from memory.
- Added image_group_flush(group) - removes the given groups' texturepages from video memory. Read the documentation of background_flush for reference.
- Added image_group_prefetch(group) - Places the given groups' texturepages into texture memory. Read the documentation of background_prefetch for reference.
- Removed image_stream_finish_clamp. Use image_stream_start(..., ..., ..., ..., clamp, removeback) instead Made stream debug messages more informative
Internal:
- Reorganised majority of the code.
- Localised the texturepage clamping functionality to image_stream_add scripts.
- Added 4 internal scripts starting with '__is' to shorten common code in different scripts.
- Separated image streaming into three types: strip, sheet and list. Each type is handled separately in the stream scripts.
- Added enum __IS_STREAM_IMAGE to handle image specific stream data.
- Added enums __ISG_IMG and __ISG_SUBIMG to make image data handling safer and easier to read. All scripts have been updated accordingly.
- Updated the image format to store bbox data.
- Updated the cache format from 1.0 to 1.1. The new format also stores bbox values. Image_cache_unpack supports both 1.0 and 1.1 versions, but sets the bbox data to the image size when loading 1.0 caches.
- Removed "loading_3d" list from image stream. 3D images are now just handled as a __IS.TYPE_3D type in the regular "loading" list
Groups – groups to handle memory management and texture pages
Stream – Image loading
Cache – pack image groups into cache for storage and faster loading speed
Handling – functions to get or set individual image data
Drawing – functions for drawing the images
Misc – other functions
Image groups are used for storing the texturepages and image data. Image groups allow easier memory management and makes it easier to organise things. You can load images into the group using image_stream or image_cache functions.
- image_group_create(name) - creates an empty image group. Returns -1 if a group with the name already exists.
- image_group_destroy(name) - stops the stream if its running, clears the group and removes it and all its data from memory. Returns true on success and false if no such group exists.
- image_group_clear(name) - stops the stream if its running, clears the group. Returns true on success and false if no such group exists.
- image_group_exists(name) - returns whether a group with the specified name exists.
- image_group_find_image(name, identifier) - Returns the ID of an image with the specified identifier if it exists, otherwise it returns -1.
- image_group_flush(name) - removes the given groups' texturepages from video memory. Read the documentation of background_flush for reference.
- image_group_prefetch(name) - Places the given groups' texturepages into texture memory. Read the documentation of background_prefetch for reference.
| Argument | Description |
|---|---|
| name | The name of the group |
| identifier | The sprite identifier that was applied to the sprite using image_stream_add_... |
txg_menu = image_group_create( "menu" );
image_stream_start( txg_menu, 1024, 1024, 1, false, true );
image_stream_add( "button_play", working_directory + "button_play.png", 3, 0.5, 0.5 );
image_stream_add_sheet( "button_settings", working_directory + "button_settings.png", 3, 2, 0.5, 0.5 );
image_stream_add_files( "button_exit", working_directory + "button_exit", 3, 0.5, 0.5 );
image_stream_finish( txg_menu );
img_play = image_group_find_image( "button_play" );
img_settings = image_group_find_image( "button_settings" );
img_exit = image_group_find_image( "button_exit" );Image streams are used for loading images into the image system either from the computer or the internet. Image streams allow you to load images into multiple groups at the same time. If you are loading images only from the computer then you only need to use image_stream_start, image_stream_add, image_stream_add_files, image_stream_add_sheet, image_stream_add_3d and image_stream_finish, example code:
image_system_init();
image_group_create( "main" );
image_stream_start( "main", 256, 256, 1, true, true );
image_stream_add( "main", "player", "player.png", 4, 0.5, 1.0 );
image_stream_add( "main", "baddie", "baddie.png", 4, 0.5, 1.0 );
image_stream_add( "main", "floor", "floor.png", 1, 0, 0 );
image_stream_finish( "main" );
img_player = image_group_find_image( "main", "player" );
img_baddie = image_group_find_image( "main", "baddie" );
img_floor = image_group_find_image( "main", "floor" );But if you are loading images from the computer and the internet, or just the internet, you need to use the async “Image loaded” event in order to load them. To make sure that all of the image have arrived, and rerequest them if needed, you have to use image_stream_receive and image_stream_is_received. Example code:
CREATE EVENT
image_system_init();
image_group_create( "main" );
image_stream_start( "main", 256, 256, 1, true, true );
image_stream_add( "main", "player", "player.png", 4, 0.5, 1.0 );
image_stream_add( "main", "baddie", "baddie.png", 4, 0.5, 1.0 );
image_stream_add( "main", "floor", "floor.png", 1, 0.0, 0.0 );IMAGE LOADED EVENT
image_stream_receive( "main" );STEP EVENT
// image_stream_finish() is not safe to add to the image loaded event
// because image loaded event gets triggered ONLY when an image arrives from
// the internet. It may work in case you're only downloading images and not adding any from the computer.
if( image_stream_is_active( "main" ) ){
if( image_stream_is_received( "main" ) ){
image_stream_finish( "main" );
img_player = image_group_find_image( "main", "player" );
img_baddie = image_group_find_image( "main", "baddie" );
img_floor = image_group_find_image( "main", "floor" );
}
}- image_stream_start(group,tex_page_width,tex_page_height,tex_offset, clamp, removeback)
- image_stream_finish(group)
- image_stream_add(group,identifier,fname,subimg,xorig,yorig)
- image_stream_add_files(group,identifier,basename,xorig,yorig)
- image_stream_add_sheet(group,identifier,fname,hor_count,ver_count,xorig,yorig)
- image_stream_add_3d(group,identifier,fname,subimg,xorig,yorig)
- image_stream_receive(group)
Misc
- image_stream_is_active(group) - returns true if a stream has been started with image_stream_start
- image_stream_is_received(group) - returns true if the stream has finished. Only used when also receiving images from the internet. Requires image_stream_receive to work.
- image_stream_progress(group) - Returns the progress of the stream as a value between 0-1. Requires image_stream_receive to work.
- image_stream_stop(group) - Stops the stream and clears all the data loaded so far.
| Argument | Description |
|---|---|
| tex_page_width | Width of the texture pages in the group |
| tex_page_height | Height of the texture pages in the group |
| sep | Distance between different images on the texture page. |
| clamp | Minimises sizes of subimages on texturepages |
| removeback | Indicates whether to make all pixels with the background colour (left-bottom pixel) transparent. |
Returns: true on success, false on failure
Starts the image loading stream, you can add images onto the stream and load them either instantly or using the Image Loaded event for images from the internet. Use image_stream_finish to finish loading them.
The clamp option calculates the minimal visible size of each subimage on a texturepage. Image origin is fixed accordingly.
| Argument | Description |
|---|---|
| identifier | A key that will later be used to find the image again. |
| fname | File path or url of the image |
| subimg | Number of subimages |
| xorig | Sprite origin as an UV value. 0.0 - left, 1.0 - right side of a subimage |
| yorig | Sprite origin as an UV value. 0.0 - top, 1.0 - bottom side of a subimage |
Returns: Returns false on failure, true on success
Adds an image strip to the stream to be loaded. The fname can either be an url or a path on the device. Sandboxing rules apply.
| Argument | Description |
|---|---|
| identifier | A key that will later be used to find the image again. |
| fname | File path or url of the image |
| hor_count | Number of subimages in each row |
| ver_count | Number of subimages in each column |
| xorig | Sprite origin as an UV value. 0.0 - left, 1.0 - right side of a subimage |
| yorig | Sprite origin as an UV value. 0.0 - top, 1.0 - bottom side of a subimage |
Returns: Returns false on failure, true on success
Adds an image sheet to the stream to be loaded. The fname can either be an url or a path on the device. Sandboxing rules apply. This also outputs a warning into the console in case the size of the image doesn't divide by hor_count and ver_count properly.
| Argument | Description |
|---|---|
| identifier | A key that will later be used to find the image again. |
| basename | Sprite filepath without the specified format or subimage |
| xorig | Sprite origin as an UV value. 0.0 - left, 1.0 - right side of a subimage |
| yorig | Sprite origin as an UV value. 0.0 - top, 1.0 - bottom side of a subimage |
Returns: Returns false on failure, true on success
Adds an image to the stream to be loaded. The basename reffers to the path of the subimages including its general name without the trailing subimage number or file format.
This script supports .png, .jpg, .jpeg and .gif formats as do all other stream_add scripts. In case the basename is "coin" then the stream will look for files that start with "coin" and are followed by "_number" and any supported file format. In case there is a file called "coin_0_strip_0.png" or "coin_strip_0.png" then those will be ignored. Only "coin_0.png", "coin_1.jpg", "coin_2.gif" would be added to this image.
| Argument | Description |
|---|---|
| identifier | A key that will later be used to find the image again. |
| fname | File path or url of theimage |
| subimg | Number of subimages |
| xorig | Sprite origin as an UV value. 0.0 - left, 1.0 - right side of a subimage |
| yorig | Sprite origin as an UV value. 0.0 - top, 1.0 - bottom side of a subimage |
Returns: Returns false on failure, true on success
Adds an image to the stream to be loaded. The fname can either be an url or a path on the device. Sandboxing rules apply.
NOTE: This will set the image to have a separate texture for all of its subimages which should only be used for 3D or cases when you need to use the full texture of an image.
| Argument | Description |
|---|---|
| group | The name of the group |
Returns: Returns false in case it is used otuside an async event, true otherwise.
Used in the “Image loaded” event. This will receive the images that belong to the group. In case a load has failed, it will be rerequested until it is received, hence you should make sure that all the links work beforehand.
NOTE: This function MUST be used if you load images from the internet, image_stream_progress and image_stream_is_received will not work properly without this.
| Argument | Description |
|---|---|
| group | The name of the group |
Returns: N/A
Sorts all of the loaded images onto texturepages and makes them ready for usage. In case you are loading images from the internet, this will only work if the image stream has finished loading the images. Use image_stream_is_received to check whether they are loaded and image_stream_receive to receive them.
if( image_stream_is_active( "main" ) ){
if( image_stream_is_received( "main" ) ){
image_stream_finish( "main" );
globalvar img_coin, img_player;
img_coin = image_group_find_image( "main", "coin" );
img_player = image_group_find_image( "main", "player" );
}
}Image cache can be used to store image groups into caches that can be saved as a single file or sent via networking functions, caches are stored in buffers. Loading images from an image cache will also drastically increase the loading speed in most cases. Code examples:
Saving a group as an image cache.
var _cache = image_cache_create( "main" );
image_cache_save( _cache, working_directory + "main.ic" );
image_cache_delete( _cache );Loading the group from the image cache.
txg_main = image_group_create( "main" );
var _cache = image_cache_load( working_directory + "main.ic" );
image_cache_unpack( "main", _cache );
image_cache_delete( _cache );Each image cache that has been saved also has a version attached to it. Image_cache_load also supports loading older cache versions. The current cache version is 1.1.
- image_cache_create(group)
- image_cache_save(cache,fname)
- image_cache_load(fname)
- image_cache_unpack(group,cache)
- image_cache_delete(cache)
- image_get_number(ind) - Returns the number of subimages of the image.
- image_get_identifier(ind) - Returns the identifier of the image.
if( image_get_identifier( image ) == "coin" ){
score += 4;
instance_destroy();
}- image_get_width(ind) - Returns the width of the image.
- image_get_height(ind) - Returns the height of the image.
- image_get_xoffset(ind) - Returns the xoffset of the image.
- image_get_yoffset(ind) - Returns the yoffset of the image.
- image_get_bbox_left(ind) - Returns the relative position of the left of the sprite bounding box. This value is given as a relative value based on the upper left corner (0,0).
- image_get_bbox_top(ind) - Returns the relative position of the top of the sprite bounding box. This value is given as a relative value based on the upper left corner (0,0).
- image_get_bbox_right(ind) - Returns the relative position of the right of the sprite bounding box. This value is given as a relative value based on the upper left corner (0,0).
- image_get_bbox_bottom(ind) - Returns the relative position of the bottom of the sprite bounding box. This value is given as a relative value based on the upper left corner (0,0).
- image_set_bbox(ind,left,top,right,bottom) - Sets the image boundign box to the specified values.
- image_get_uvs(ind,subimg)
Returns an array with UV coords for the image subimg on the texture page, [0] = left, [1] = top, [2] = right and [3] = bottom.
var _uv = image_get_uvs( image );
sh_params = shader_get_uniform( sh_outline, "UV" );
shader_set( sh_outline );
shader_set_uniform_f_array(sh_params, _uv );
draw_image( image, 0, x, y );
shader_reset();- image_exists(ind) - Returns whether the image exists or not.
- image_set_offset(ind,xoff,yoff) - Changes the image origin to the specified x and y.
- image_get_texturepage(ind,subimg) - Returns the background ID on which the image is on and which is used as a texturepage.
- image_get_texture(ind,subimg)
Returns a special pointer for the image texture. This value can then be used in other draw functions, particularly in general 3D and some of the 2D primitive functions, as well as the Shader functions.
NOTE: This returns the whole texture of the specific subimages texturegroup due to GM limitations, it will only return the texture of the specific subimage if the image was added using image_stream_add_3d. You can use image_get_uvs to find the coordinates of the subimage on the texture.
var _tex;
_tex = image_get_texture( img_wall, 0 );
draw_primitive_begin_texture( pr_trianglestrip, _tex );
draw_vertex_texture( 0, 0, 0, 0 );
draw_vertex_texture( 480, 0, 1, 0 ); draw_vertex_texture( 480, 640, 1, 1 );
draw_vertex_texture( 0, 640, 0, 1 );
draw_primitive_end();- image_save(ind,subimg,fname) - Saves the specific subimage(frame) of the image as a .png format image file.
- image_save_strip(ind,fname) - Saves the image as a .png format image file.
All of the drawing functions are the equivelant of the GM draw_sprite drawing functions. Unless specified differently, use the equivelant Game Maker's documentation on sprite functions.
- draw_image(ind,subimg,x,y)
- draw_image_ext(ind,subimg,x,y,xscale,yscale,rot,colour,alpha)
- draw_image_general(ind,subimg,left,top,width,height,x,y,xscale,yscale,rot,c1,c2,c3,c4,alpha)
- draw_image_part(ind,subimg,left,top,width,height,x,y)
- draw_image_part_ext(ind,subimg,left,top,width,height,x,y,xscale,yscale,colour,alpha)
- draw_image_pos(ind,subimg,x1,y1,x2,y2,x3,y3,x4,y4,alpha) - This works a bit differently than GM built in draw_sprite_pos function, this will draw the entire image including the invisible areas, GM's built in function will only draw the areas with alpha > 0
- draw_image_stretched(ind,subimg,x,y,w,h)
- draw_image_stretched_ext(ind,subimg,x,y,w,h,colour,alpha)
- draw_image_tiled(ind,subimg,x,y)
- draw_image_tiled_ext(ind,subimg,x,y,xscale,yscale,colour,alpha)
- draw_image_tiled_area(image,subimg,x1,y1,x2,y2) - Draws the image tiled from point x1,y1 to x2,y2.
| Argument | Description |
|---|---|
| image | The index of the image |
| subimg | the frame/subimage of the image |
| x1 | the x starting coordinate of the tiled area |
| y1 | the y starting coordinate of the tiled area |
| x2 | the x ending coordinate of the tiled area |
| y2 | the y ending coordinate of the tiled area |
- draw_image_tiled_area_ext(image,subimg,x1,y1,x2,y2,xscale,yscale,colour,alpha)
| Argument | Description |
|---|---|
| image | The index of the image |
| subimg | the frame/subimage of the image |
| x1 | the x starting coordinate of the tiled area |
| y1 | the y starting coordinate of the tiled area |
| x2 | the x ending coordinate of the tiled area |
| y2 | the y ending coordinate of the tiled area |
| xscale | the horizontal scale of the image (1=default,2=2 times larger) |
| yscale | the vertical scale of the image (1=default,2=2 times larger) |
| colour | the colour of the image |
| alpha | the alpha/opacity of the image |
- draw_image_pos_ext(image,subimg,x1,y1,x2,y2,x3,y3,x4,y4,rot,col,alpha)
- draw_image_pos_general(image,subimg,x1,y1,x2,y2,x3,y3,x4,y4,rot,c1,c2,c3,c4,alpha)
- image_system_init() - Initialises the image system, the extension calls this automatically. Only call this if you use scripts or want to manually reinitialise the image system.
- image_system_cleanup() - Removes all of the image system data from memory.