Buffer

Constructors

`syz_createBufferFromFile`

SYZ_CAPI syz_ErrorCode syz_createBufferFromFile(syz_Handle *out, const char *path, void *userdata, syz_UserdataFreeCallback *userdata_free_callback);

Create a buffer from a file using an UTF-8 encoded path.

`syz_createBufferFromStreamParams`

SYZ_CAPI syz_ErrorCode syz_createBufferFromStreamParams(syz_Handle *out, const char *protocol, const char *path, void *param, void *userdata, syz_UserdataFreeCallback *userdata_free_callback);

Create a buffer from stream parameters. See decoding for information on streams.

This call will decode the stream in the calling thread, returning errors as necessary. Synthizer will eventually offer a BufferCache which supports background decoding and caching, but for the moment the responsibility of background decoding is placed on the calling program.

`syz_createBufferFromEncodedData`

SYZ_CAPI syz_ErrorCode syz_createBufferFromEncodedData(syz_Handle *out, unsigned long long data_len, const char *data, void *userdata, syz_UserdataFreeCallback *userdata_free_callback);

Create a buffer from encoded audio data in ram, for example an ogg file read from disk. This will also work with mmapped pointers. As with all other decoding, Synthizer will autodetect the type from the data. The pointer must live for the duration of the call.

`syz_createBufferFromFloatArray`

SYZ_CAPI syz_ErrorCode syz_createBufferFromFloatArray(syz_Handle *out, unsigned int sr, unsigned int channels, unsigned long long frames, const float *data, void *userdata, syz_UserdataFreeCallback *userdata_free_callback);

Create a buffer from an array of float data generated by the application. The array must be channels * frames elements.

`syz_createBufferFromStreamHandle`

SYZ_CAPI syz_ErrorCode syz_createBufferFromStreamHandle(syz_Handle *out, syz_Handle stream, void *userdata, syz_UserdataFreeCallback *userdata_free_callback);

Create a buffer from a stream handle. Usually used with custom streams. Decodes in the calling thread. The lifetime of the stream's underlying asset need only be as long as this call.

`syz_ufferGetSizeInBytes`

SYZ_CAPI syz_ErrorCode syz_bufferGetSizeInBytes(unsigned long long *size, syz_Handle buffer);

Get the approximate size of this buffer's in-memory representation in bytes.

Properties

None.

Functions

Getters

SYZ_CAPI syz_ErrorCode syz_bufferGetChannels(unsigned int *out, syz_Handle buffer);
SYZ_CAPI syz_ErrorCode syz_bufferGetLengthInSamples(unsigned int *out, syz_Handle buffer);
SYZ_CAPI syz_ErrorCode syz_bufferGetLengthInSeconds(double *out, syz_Handle buffer);

The self-explanatory getters. These aren't properties because they can't be written and they shouldn't participate in the property infrastructure.

Remarks

Buffers hold audio data, as a collection of contiguous chunks. Data is resampled to the Synthizer samplerate and converted to 16-bit PCM.

Buffers are one of the few Synthizer objects that don't require a context. They may be used freely with any object requiring a buffer, from any thread. In order to facilitate this, buffers are immutable after creation.

The approximate memory usage of a buffer in bytes is 2 * channels * duration_in_seconds * 44100. Loading large assets into buffers is not recommended. For things such as music tracks, use StreamingGenerators. Note that on 32-bit architectures, some operating systems only allow a 2 gigabyte address space. Synthizer avoids allocating buffers as contiguous arrays in part to allow efficient use of 32-bit address spaces, but this only goes so far. If on a 32-bit architecture, expect to run out of memory from Synthizer's perspective well before decoding 2 Gigabytes of buffers simultaneously due to the inability to find consecutive free pages.

The Synthizer Manual