Buffer API for data buffers as the main way to communicate between systems.
typedef uint32_t HBuffer;
ValueType enumeration.
dmBuffer::VALUE_TYPE_UINT8 -
dmBuffer::VALUE_TYPE_UINT16 -
dmBuffer::VALUE_TYPE_UINT32 -
dmBuffer::VALUE_TYPE_UINT64 -
dmBuffer::VALUE_TYPE_INT8 -
dmBuffer::VALUE_TYPE_INT16 -
dmBuffer::VALUE_TYPE_INT32 -
dmBuffer::VALUE_TYPE_INT64 -
dmBuffer::VALUE_TYPE_FLOAT32 -
dmBuffer::MAX_VALUE_TYPE_COUNT -
Result enumeration.
dmBuffer::RESULT_OK -
dmBuffer::RESULT_GUARD_INVALID -
dmBuffer::RESULT_ALLOCATION_ERROR -
dmBuffer::RESULT_BUFFER_INVALID -
dmBuffer::RESULT_BUFFER_SIZE_ERROR -
dmBuffer::RESULT_STREAM_SIZE_ERROR -
dmBuffer::RESULT_STREAM_MISSING -
dmBuffer::RESULT_STREAM_TYPE_MISMATCH -
dmBuffer::RESULT_STREAM_COUNT_MISMATCH -
dmBuffer::RESULT_METADATA_INVALID -
dmBuffer::RESULT_METADATA_MISSING -
Buffer stream declaration structure
m_Name - Hash of stream name
m_Type - Stream ValueType type
m_Count - Component count of stream type. E.g. 3 for a Vector3
m_Flags - Flags for a stream.
m_Reserved - Reserved for future use.
Declare a typical position stream:
const dmBuffer::StreamDeclaration streams_decl[] = {
{dmHashString64("position"), dmBuffer::VALUE_TYPE_FLOAT32, 3}
};
Creates a new HBuffer with a number of different streams.
count - The number of "structs" the buffer should hold (e.g. vertex count)
streams_decl - Array of stream declarations
streams_decl_count - Number of stream declarations inside the decl array (max 256)
out_buffer - Pointer to HBuffer where to store the newly allocated buffer
result - BUFFER_OK if buffer was allocated successfully
const dmBuffer::StreamDeclaration streams_decl[] = {
{dmHashString64("position"), dmBuffer::VALUE_TYPE_FLOAT32, 3},
{dmHashString64("texcoord0"), dmBuffer::VALUE_TYPE_UINT16, 2},
{dmHashString64("color"), dmBuffer::VALUE_TYPE_UINT8, 4},
};
dmBuffer::HBuffer buffer = 0x0;
dmBuffer::Result r = dmBuffer::Create(1024, streams_decl, 3, &buffer);
if (r == dmBuffer::RESULT_OK) {
// success
} else {
// handle error
}
Copies the data from one buffer to another buffer. The stream declaration needs to be the same in both buffers.
dst_buffer_handle - Pointer to HBuffer from where to copy buffer data.
src_buffer_handle - Pointer to HBuffer where to copy the buffer data.
result - BUFFER_OK if buffer was copied successfully
dmBuffer::Result r = dmBuffer::Copy(buffer_a, buffer_b);
if (r == dmBuffer::RESULT_OK) {
// success
} else {
// handle error
}
Destroys a HBuffer and it's streams.
buffer - Buffer handle to the buffer to free
const dmBuffer::StreamDeclaration streams_decl[] = {
{dmHashString64("position"), dmBuffer::VALUE_TYPE_FLOAT32, 3},
};
dmBuffer::HBuffer buffer = 0x0;
dmBuffer::Result r = dmBuffer::Create(4, streams_decl, 1, &buffer);
if (r == dmBuffer::RESULT_OK) {
dmBuffer::Destroy(buffer);
} else {
// handle error
}
Checks if a handle is still valid
buffer - The buffer
result - True if the handle is valid
Validate a buffer and it's streams.
buffer - Buffer handle to the buffer to validate
// Pass buffer to third party library that does operations on the buffer or streams.
ThirdPartyLib::PerformOperation(buffer);
r = dmBuffer::ValidateBuffer(buffer);
if (r == dmBuffer::RESULT_OK) {
// buffer and streams are valid
} else {
// the third party lib made the buffer invalid
}
Get a stream from a buffer. Output stream is 16 byte aligned.
buffer - buffer handle.
stream_name - Hash of stream name to get
stream - Where to store the stream
count - Where to store the count (e.g. vertex count). May be null.
components - Where to store the number of components (e.g. 3 for a Vector3). May be null.
stride - Where to store the (struct) stride. The stride can be added to the value pointer. May be null. E.g. for a float array, the stride is (sizeof(Struct) / sizeof(float))
result - BUFFER_OK if the stream was successfully accessed
float* positions = 0x0;
uint32_t size = 0;
uint32_t components = 0;
uint32_t stride = 0;
dmBuffer::Result r = dmBuffer::GetStream(buffer, dmHashString64("position"), (void**)&positions, &count, &components, &stride);
if (r == dmBuffer::RESULT_OK) {
for (int i = 0; i < count; ++i)
{
for (int c = 0; c < components; ++c)
{
positions[c] *= 1.1f;
}
positions += stride;
}
} else {
// handle error
}
Gets the buffer as a byte array. If the buffer is interleaved (default), a pointer to the whole memory is returned.
buffer - buffer handle.
out_bytes - Pointer to void* where to store the bytes
out_size - Pointer to uint32_t where to store the array size
result - BUFFER_OK if the buffer was successfully accessed
uint8_t* bytes = 0x0;
uint32_t size = 0;
dmBuffer::Result r = dmBuffer::GetBytes(buffer, (void**)&bytes, &size);
if (r == dmBuffer::RESULT_OK) {
for (int i = 0; i < size; ++i)
{
stream[i] = (uint8_t)(i & 0xFF);
}
} else {
// handle error
}
Get (struct) count for a buffer.
buffer - buffer handle.
count - Pointer to uint32_t where to store the element count
result - BUFFER_OK if the element count was successfully accessed
uint32_t count = 0;
dmBuffer::Result r = dmBuffer::GetCount(buffer, &count);
if (r == dmBuffer::RESULT_OK) {
printf("buffer %p has %d number of elements", buffer, count);
} else {
// handle error
}
Gets the stream type
buffer - Pointer to a buffer.
stream_name - Hash of stream name to get
type - The value type
components - The number of values (E.g. 3 for a Vector3)
result - Returns BUFFER_OK if all went ok
Gets the size of a value type
type - The value type
size - The size in bytes
Converts result to string
result - The result
result - The result as a string
Converts a value type to string
result - The value type
result - The value type as a string
Gets the current update number
type - The value type
version - The current version number
result - Returns BUFFER_OK if all went ok
Used to know if a buffer has been updated.
type - The value type
result - Returns BUFFER_OK if all went ok
Create or update a new metadata entry with a number of values of a specific type. It will allocate space to store these values.
hbuffer - A buffer handle
name_hash - The entry name as a hash
data - A pointer to an array of the values
count - Number of values in the array
type - The type of the values
result - RESULT_OK if the metadata entry was successfully stored
Retrieve metadata entry information
hbuffer - A buffer handle
name_hash - The entry name as a hash
data - Gets the internal address of metadata values
count - Gets the number of metadata values stored
type - Gets the type of values of the metadata