Buffer

Buffer API for data buffers as the main way to communicate between systems.

dmBuffer::HBuffer

HBuffer type definition

typedef uint32_t HBuffer;


ValueType

valueType enumeration

ValueType enumeration.

MEMBERS

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

result enumeration

Result enumeration.

MEMBERS

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 -


dmBuffer::StreamDeclaration()

StreamDeclaration struct

Buffer stream declaration structure

MEMBERS

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.

EXAMPLES

Declare a typical position stream:

const dmBuffer::StreamDeclaration streams_decl[] = {
    {dmHashString64("position"), dmBuffer::VALUE_TYPE_FLOAT32, 3}
};


dmBuffer::Create(count, streams_decl, streams_decl_count, out_buffer)

create Buffer

Creates a new HBuffer with a number of different streams.

PARAMETERS

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

RETURN

result - BUFFER_OK if buffer was allocated successfully

EXAMPLES

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
}


dmBuffer::Copy(dst_buffer_handle, src_buffer_handle)

copy a Buffer

Copies the data from one buffer to another buffer. The stream declaration needs to be the same in both buffers.

PARAMETERS

dst_buffer_handle - Pointer to HBuffer from where to copy buffer data.

src_buffer_handle - Pointer to HBuffer where to copy the buffer data.

RETURN

result - BUFFER_OK if buffer was copied successfully

EXAMPLES

dmBuffer::Result r = dmBuffer::Copy(buffer_a, buffer_b);

if (r == dmBuffer::RESULT_OK) {
    // success
} else {
    // handle error
}


dmBuffer::Destroy(buffer)

destroy Buffer.

Destroys a HBuffer and it's streams.

PARAMETERS

buffer - Buffer handle to the buffer to free

EXAMPLES

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
}


dmBuffer::IsBufferValid(buffer)

check buffer handle

Checks if a handle is still valid

PARAMETERS

buffer - The buffer

RETURN

result - True if the handle is valid


dmBuffer::ValidateBuffer(buffer)

validate buffer.

Validate a buffer and it's streams.

PARAMETERS

buffer - Buffer handle to the buffer to validate

EXAMPLES

// 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
}


dmBuffer::GetStream(buffer, stream_name, stream, count, components, stride)

get stream from buffer.

Get a stream from a buffer. Output stream is 16 byte aligned.

PARAMETERS

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))

RETURN

result - BUFFER_OK if the stream was successfully accessed

EXAMPLES

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
}


dmBuffer::GetBytes(buffer, out_bytes, out_size)

get buffer as a byte array.

Gets the buffer as a byte array. If the buffer is interleaved (default), a pointer to the whole memory is returned.

PARAMETERS

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

RETURN

result - BUFFER_OK if the buffer was successfully accessed

EXAMPLES

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
}


dmBuffer::GetCount(buffer, count)

get buffer count.

Get (struct) count for a buffer.

PARAMETERS

buffer - buffer handle.

count - Pointer to uint32_t where to store the element count

RETURN

result - BUFFER_OK if the element count was successfully accessed

EXAMPLES

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
}


dmBuffer::GetStreamType(buffer, stream_name, type, components)

get stream type and type count

Gets the stream type

PARAMETERS

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)

RETURN

result - Returns BUFFER_OK if all went ok


dmBuffer::GetSizeForValueType(type)

get size of a value type

Gets the size of a value type

PARAMETERS

type - The value type

RETURN

size - The size in bytes


dmBuffer::GetResultString(result)

result to string

Converts result to string

PARAMETERS

result - The result

RETURN

result - The result as a string


dmBuffer::GetValueTypeString(result)

value type to string

Converts a value type to string

PARAMETERS

result - The value type

RETURN

result - The value type as a string


dmBuffer::GetContentVersion(type, version)

Gets the current update number

Gets the current update number

PARAMETERS

type - The value type

version - The current version number

RETURN

result - Returns BUFFER_OK if all went ok


dmBuffer::UpdateContentVersion(type)

Update the internal frame counter.

Used to know if a buffer has been updated.

PARAMETERS

type - The value type

RETURN

result - Returns BUFFER_OK if all went ok


dmBuffer::SetMetaData(hbuffer, name_hash, data, count, type)

set a metadata entry

Create or update a new metadata entry with a number of values of a specific type. It will allocate space to store these values.

PARAMETERS

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

RETURN

result - RESULT_OK if the metadata entry was successfully stored


dmBuffer::GetMetaData(hbuffer, name_hash, data, count, type)

retrieve a metadata entry

Retrieve metadata entry information

PARAMETERS

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