Image Loaded and Sound Loaded Events

This is the sub event that will be triggered by any resource call-backs received.

These two events are triggered when you load an image or a sound into GameMaker:Studio, as long as you have used a valid URL 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.