This event is triggered when you load an image into
GameMaker: Studio, as long as you have used a valid URL or
path with the applicable load file function. For example say you
want to load a background image, and only change the current
background to the new one when it has loaded. Well you would have
something like this in a create event or an alarm event (for
example):
back = background_add("http://www.angusgames.com/game/background1.png", 0, 0);
This will now start to load the image into the device or the browser, but it will not block GameMaker: Studio while it waits for the file to be loaded. Instead GameMaker: Studio will keep running as normal until the image is loaded and the call back triggers the Image Loaded event, where a ds_map (more commonly known as a "dictionary") is created and stored in the special variable async_load. The map contains the following information:
- "filename": The complete path to the file you requested.
- "id": The ID of the resource that you have loaded. This will be the same as the variable that you have assigned the resource to.
- "status": Returns a value of less than 0 for an error.
You would then assign the newly loaded image to a background in this event. The above is also true for sprites and sounds, with a ds_map being generated for each of these resources as shown above, and the following code example demonstrates how the returned information would be used in this event:
if ds_map_find_value(async_load, "id") == back
{
if ds_map_find_value(async_load, "status") >=
0
{
background_index[0] = back
}
}
The above code will first check the id of the ds_map that has
been created, then check the status of the callback. If the value
is greater than or equal to 0 (signalling success) the result from
the callback will then be used to set the background index to the
newly loaded image.
NOTE: The variable async_load is only valid
in these events, as the ds_map that is points to is created at the
start of the event, then deleted again at the end, with this
variable being reset to a value of -1.