buffer_save_async

Save part of the contents of a buffer to a file asynchronously.

Syntax:

buffer_save_async(buffer, filename, offset, size);


Argument Description
buffer The index of the buffer to save.
filename The name of the file to save as.
offset The offset within the buffer to save from (in bytes).
size The size of the buffer area to save (in bytes).


Returns: Real


Description

With this function you can save part of the contents of a buffer to a file, ready to be read back into memory using the buffer_load function (or any of the other functions for loading buffers). The "offset" defines the start position within the buffer for saving (in bytes), and the "size" is the size of the buffer area to be saved from that offset onwards (also in bytes). This function works asynchronously, and so the game will continue running while being saved. This function will trigger an Asynchronous Load/Save Event where you can check to ensure that the save has occurred correctly.

Note that you can save out multiple buffers in one by calling this function multiple times between calls to buffer_async_group_begin() and buffer_async_group_end() (see those functions for further information on this).

The function returns a unique ID value which can then be used to check the asynchronous event async_load ID value, as shown in the extended example below. The async_load map in the event will have the following two key/value pairs:

  1. "id": the ID of the async function as returned by the save function.
  2. "status": will return true if the data was saved/loaded correctly, and false otherwise.




Extended Example:

The buffer_save_async() function can be called from any event, and since it is asynchronous the callback can be almost instantaneous or could take several seconds. Calling the function is simple and would look something like this:

saveid = buffer_save_async(buff, "Player_Save.sav", 0, 16384);

The above code saves the contents of the buffer "buff" to the given save file, storing the ID of the function call in the variable "saveid". When the save is complete, the asynchronous Save/Load event will be triggered and you can parse the async_load map for the correct ID of the function, like this:

if ds_map_find_value(async_load, "id") == saveid
   {
   if ds_map_find_value(async_load, "status") == false
      {
      show_debug_message("Save failed!");
      }
   }

The above code will first check the id of the ds_map that has been created, then check the status of the callback, posting a debug message if there has been any issues.


Back: Buffers
Next: buffer_load
© Copyright YoYo Games Ltd. 2015 All Rights Reserved