This function creates a new buffer and returns it.
The function allocates a portion of memory for the buffer, which can then be used to store different types of data (specified when you write to the buffer using the buffer_write, buffer_poke or buffer_fill function).
The following constants can be used to define the buffer type:
| Buffer Type Constant | |
|---|---|
| Constant | Description |
| buffer_fixed | A buffer of fixed size. |
| buffer_grow | A buffer that will "grow" dynamically as data is added |
| buffer_wrap | A buffer where the data will "wrap". When the data being added reaches the limit of the buffer size, the overwrite will be placed back at the start of the buffer, and further writing will continue from that point. |
| buffer_fast | A special "stripped" buffer that is extremely fast to read/write to. Can only be used with buffer_u8 data types, and must be 1 byte aligned. |
Apart from the buffer type, you will also have to set the byte alignment for the buffer. This value will vary depending on the data that you wish to store in the buffer, and in most cases a value of 1 is perfectly fine. However, be aware that for some operations a specific alignment is essential, and an incorrect alignment may cause errors (for further details on alignment see Buffers). The following is a general guide to show which values are most appropriate for each data type (when in doubt, use an alignment of 1):
NOTE Byte alignment can be very important as the wrong choice may adversely affect performance.
IMPORTANT You cannot create buffers that are 2 Gibibytes (2,147,483,648 bytes) or larger.
NOTE It's important that you remove any dynamically created resources like this from memory when you no longer need them to prevent memory leaks, so when you are finished with the buffer that you have created you should free it up again using buffer_delete.
buffer_create(size, type, alignment)
| Argument | Type | Description |
|---|---|---|
| size | Real | The size (in bytes) of the buffer. |
| type | Buffer Type Constant | The type of buffer to create (see the constants list above). |
| alignment | Real | The byte alignment for the buffer |
player_buffer = buffer_create(16384, buffer_fixed, 2);
The above code allocates 16384 bytes of memory to a buffer and returns the buffer, storing the reference to it in the variable player_buffer for future use. The buffer is aligned to a two byte boundary.