version 2.8 - GameMakerDiscord/custom-sprite-framework GitHub Wiki
Table of Contents
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
Groups
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 onto the group using image_stream or image_cache functions.
- image_group_create(name)
- image_group_destroy(group)
- image_group_clear(group)
- image_group_exists(group)
- image_group_find_image(group,identifier)
image_group_create(name)
| Argument | Description |
|---|---|
| name | The name of the group |
Returns: String or -1
Description
Creates an image group that you can add data to using image_load_ functions or image_cache_ functions.
Returns the group name if successful, else -1.
Example
txg_menu = image_group_create( "menu" );
image_load_start( txg_menu , 1024 , 1024 , 1 );
image_load_add( "button_play" , working_directory + "button_play.png" , 3 , 0 , 0 );
image_load_add( "button_settings" , working_directory + "button_settings.png" , 3 , 0 , 0 );
image_load_add( "button_exit" , working_directory + "button_exit.png" , 3 , 0 , 0 );
image_load_finish();
img_play = image_load_get( "button_play" );
img_settings = image_load_get( "button_settings" );
img_exit = image_load_get( "button_exit" );
image_group_destroy(name)
| Argument | Description |
|---|---|
| name | The name of the group |
Returns: Boolean
Description
Deletes the group and frees all of the memory from the data that the group allocated.
Returns false if the group didn’t exist.
Example
if( mouse_check_button_pressed( mb_left ) ){
image_group_destroy( "game" );
room_goto( rm_menu );
}
image_group_clear(name)
| Argument | Description |
|---|---|
| name | The name of the group |
Returns: Boolean
Description
Clears the group and frees the memory allocated by image info and textures.
Returns false if the group didn’t exist, else true.
Example
if( files_changed ){
image_group_clear( "menu" );
txg_menu = image_group_create( "menu" );
image_load_start( txg_menu , 1024 , 1024 , 1 );
image_load_add( "button_play" , working_directory + "button_play.png" , 3 , 0 , 0 );
image_load_add( "button_settings" , working_directory + "button_settings.png" , 3 , 0 , 0 );
image_load_add( "button_exit" , working_directory + "button_exit.png" , 3 , 0 , 0 );
image_load_finish();
img_play = image_load_get( "button_play" );
img_settings = image_load_get( "button_settings" );
img_exit = image_load_get( "button_exit" );
}
image_group_exists(name)
| Argument | Description |
|---|---|
| name | The name of the group |
Returns: Boolean
Description
Returns whether the group exists or not (true,false)
Example
if( !image_group_exists("menu" ) ){
txg_menu = image_group_create( "menu" );
image_load_start( txg_menu , 1024 , 1024 , 1 );
image_load_add( "button_play" , working_directory + "button_play.png" , 3 , 0 , 0 );
image_load_add( "button_settings" , working_directory + "button_settings.png" , 3 , 0 , 0 );
image_load_add( "button_exit" , working_directory + "button_exit.png" , 3 , 0 , 0 );
image_load_finish();
img_play = image_load_get( "button_play" );
img_settings = image_load_get( "button_settings" );
img_exit = image_load_get( "button_exit" );
}
image_group_find_image(group, identifier)
| Argument | Description |
|---|---|
| group | The name of the group |
| identifier | The sprite identifier that was applied to the sprite using image_load_add or image_load_add_3d |
Returns: image or -1
Description
Returns the image that has the identifier, if no image is found, it returns -1.
Example
var _cache = image_cache_load( working_directory + "main.ic" );
image_cache_unpack( "main" , _cache );
image_cache_delete( _cache );
img_coin = image_group_find_image( "main" , "player" );
img_stuff = image_group_find_image( "main" , "baddie" );
img_random = image_group_find_image( "main" , "wall" );
Stream
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_3d and image_stream_finish, example code:
image_group_create( "main" );
image_stream_start( "main" , 256 , 256 , 1 );
image_stream_add( "main" , "player" , "player.png" , 4 , 8 , 8 );
image_stream_add( "main" , "baddie" , "baddie.png" , 4 , 8 , 8 );
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 only the internet, you need to use the “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_group_create( "main" );
image_stream_start( "main" , 256 , 256 , 1 );
image_stream_add( "main" , "player" , "http://mysite.com/player.png" , 4 , 8 , 8 );
image_stream_add( "main" , "baddie" , "baddie.png" , 4 , 8 , 8 );
image_stream_add( "main" , "floor" , "http://mysite.com/floor.png" , 1 , 0 , 0 );
IMAGE LOADED EVENT
image_stream_receive( "main" );
STEP EVENT
// Finishing the image stream 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’s safe when you only download images and don’t add them 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)
- image_stream_add(group,identifier,fname,subimg,xorig,yorig)
- image_stream_add_3d(group,identifier,fname,subimg,xorig,yorig)
- image_stream_receive(group)
- image_stream_is_received(group)
- image_stream_is_active(group)
- image_stream_finish(group)
- image_stream_finish_clamp(group) – when storing sprites on texpages, it removes the empty edges. Origins are fixed accordingly.
- image_stream_progress(group)
image_stream_start(group,tex_page_width,tex_page_height,sep)
| Argument | Description |
|---|---|
| group | The name of the group |
| 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. |
Returns: N/A
Description
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.
Example
image_group_create( "main" );
image_stream_start( "main" , 256 , 256 , 0 );
image_stream_add_3d( "main" , "baddie" , "http://mysite.com/baddie.png" , 4 , 8 , 16 );
image_stream_add( "main" , "wall" , "wall.png" , 1 , 14 , 20 );
image_stream_add( "main" , "player" , "http://mysite.com/player.png" , 15 , 8 , 16 );
image_stream_add(group,identifier,fname,subimg,xorig,yorig)
| Argument | Description |
|---|---|
| group | The name of the group |
| identifier | A key that will later be used to find the image again. |
| fname | File location of the image |
| subimg | Number of subimages |
| xorig | X position of the origin in the image. |
| yorig | Y position of the origin in the image. |
Returns: N/A
Description
Used to add the image into a stream for loading, the images will be loaded in using image_load_finish
Example
image_group_create( "main" );
image_stream_start( "main" , 256 , 256 , 0 );
image_stream_add_3d( "main" , "baddie" , "http://mysite.com/baddie.png" , 4 , 8 , 16 );
image_stream_add( "main" , "wall" , "wall.png" , 1 , 14 , 20 );
image_stream_add( "main" , "player" , "http://mysite.com/player.png" , 15 , 8 , 16 );
image_stream_add_3d(group,identifier,fname,subimg,xorig,yorig)
| Argument | Description |
|---|---|
| group | The name of the group |
| identifier | A key that will later be used to find the image again. |
| fname | File location of the image |
| subimg | Number of subimages |
| xorig | X position of the origin in the image. |
| yorig | Y position of the origin in the image. |
Returns: N/A
Description
Used to add the image into a stream for loading, the images will be loaded in using image_load_finish
NOTE: This will set the image to have a separate texture page for all of its subimages which should only be used for 3D or cases when you need to get the texture of the image.
Example
image_group_create( "main" );
image_stream_start( "main" , 256 , 256 , 0 );
image_stream_add_3d( "main" , "baddie" , " baddie.png" , 4 , 8 , 16 );
image_stream_add( "main" , "wall" , "wall.png" , 1 , 14 , 20 );
image_stream_finish( "main" );
img_baddie = image_group_find_image( "main" , "baddie" );
img_wall = image_group_find_image( "main" , "wall" );
image_stream_receive(group)
| Argument | Description |
|---|---|
| group | The name of the group |
Returns: N/A
Description
Used in the “Image loaded” event. This will check if the images have loaded, if the loading fails, the image will be requested again so make sure that the image exists on the url.
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.
Example
image_stream_receive( "main" );
if( image_stream_is_received( "main" ) and image_stream_is_active( "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_stream_is_received(group)
| Argument | Description |
|---|---|
| group | The name of the group |
Returns: Boolean
Description
Returns whether the image stream has finished or not. This function only works on active streams, use image_stream_is_active to make sure that the stream of the group is active.
Example
image_stream_receive( "main" );
if( image_stream_is_received( "main" ) and image_stream_is_active( "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_stream_is_active(group)
| Argument | Description |
|---|---|
| group | The name of the group |
Returns: Boolean
Description
Returns whether the image stream for the group specified has been started and is active or not.
Example
image_stream_receive( "main" );
if( image_stream_is_received( "main" ) and image_stream_is_active( "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_stream_finish(group)
| Argument | Description |
|---|---|
| group | The name of the group |
Returns: N/A
Description
Sorts all of the loaded images onto texturepages and makes them ready for usage. This will only work if the image stream has finished loading the images, to check whether they are loaded image_stream_is_received. if you are only loading images from the computer then you don’t need to use image_stream_is_received.
Example
image_stream_receive( "main" );
if( image_stream_is_received( "main" ) and image_stream_is_active( "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_stream_progress(group)
| Argument | Description |
|---|---|
| group | The name of the group |
Returns: Real, value from 0-1
Description
Returns a value from 0-1 that shows how much of the group has been loaded. The larger the number the more has been loaded, 1 means that everything has been loaded and 0 means that nothing has been loaded.
Example
image_stream_receive( "main" );
percentage_loaded = image_stream_progress( "main" ) * 100;
Cache
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 );
- image_cache_create(group)
- image_cache_save(cache,fname)
- image_cache_load(fname)
- image_cache_unpack(group,cache)
- image_cache_delete(cache)
image_cache_create(group)
| Argument | Description |
|---|---|
| group | The name of the group |
Returns: buffer/cache
Description
Generates a cache out of the image group, the cache itself is a buffer so you can use it in networking or any other buffer specific functions.
The cache can be saved to improve the image group loading speeds.
Example
// Create Event
txg_game = image_group_create( "game" );
image_load_start( txg_game , 1024 , 1024 , 1 );
image_load_add_3d( "tex_grass" , working_directory + "tex_grass.png" , 1 , 0 , 0 );
image_load_add_3d( "tex_dirt " , working_directory + "tex_dirt.png" , 1 , 0 , 0 );
image_load_add_3d( "tex_stone" , working_directory + "tex_stone.png" , 1 , 0 , 0 );
image_load_finish();
img_grass = image_load_get( "tex_grass " );
img_dirt = image_load_get( "tex_dirt" );
img_stone = image_load_get( "tex_stone" );
var _cache = image_cache_create( txg_game );
image_cache_save( _cache , working_directory + "game.ic" );
image_cache_delete( _cache );
image_cache_save(cache,fname)
| Argument | Description |
|---|---|
| cache | The cache created using image_cache_create or image_cache_load |
| fname | The name to save the file as |
Returns: Boolean
Description
Saves the cache as the specified file. You can load the cache in again using image_cache_load.
Example
// Create Event
txg_game = image_group_create( "game" );
image_load_start( txg_game , 1024 , 1024 , 1 );
image_load_add_3d( "tex_grass" , working_directory + "tex_grass.png" , 1 , 0 , 0 );
image_load_add_3d( "tex_dirt " , working_directory + "tex_dirt.png" , 1 , 0 , 0 );
image_load_add_3d( "tex_stone" , working_directory + "tex_stone.png" , 1 , 0 , 0 );
image_load_finish();
img_grass = image_load_get( "tex_grass " );
img_dirt = image_load_get( "tex_dirt" );
img_stone = image_load_get( "tex_stone" );
var _cache = image_cache_create( txg_game );
image_cache_save( _cache , working_directory + "game.ic" );
image_cache_delete( _cache );
image_cache_load(fname)
| Argument | Description |
|---|---|
| fname | The path of the file to be loaded |
Returns: buffer/cache or -1
Description
Loads the cache in from the specified file and makes sure that it is a cache file and its version is supported.
Example
var _cache = image_cache_load( working_directory + "game.ic" );
image_cache_unpack( "game" , _cache );
image_cache_delete( _cache );
img_baddie = image_group_find_image("game" , "baddie" );
img_player = image_group_find_image("game" , "player" );
image_cache_unpack(group,cache)
| Argument | Description |
|---|---|
| fname | The path of the file to be loaded |
Returns: Boolean
Description
Extracts the cache content into the group, if the group does not exist it will be created, if it does, it will be overwritten. This is faster than using the image_stream functions. Returns whether it unpacked or not, if not then no data has been overwritten and the group has not been created if it does not exist.
Example
var _cache = image_cache_load( working_directory + "game.ic" );
image_cache_unpack( "game" , _cache );
image_cache_delete( _cache );
img_baddie = image_group_find_image("game" , "baddie" );
img_player = image_group_find_image("game" , "player" );
image_cache_delete(cache)
| Argument | Description |
|---|---|
| cache | The cache created using image_cache_create or image_cache_load |
Returns: N/A
Description
Deletes the cache from the memory.
Example
var _cache = image_cache_load( working_directory + "game.ic" );
image_cache_unpack( "game" , _cache );
image_cache_delete( _cache );
img_baddie = image_group_find_image("game" , "baddie" );
img_player = image_group_find_image("game" , "player" );
Handling
- 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_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.
image_()
| Argument | Description |
|---|---|
| xxx | xxx |
Returns:
Description
Example
Drawing
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)
Misc
- 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.