Sdk buffer api documentation

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

Namespace: dmBuffer
Include: #include <dmsdk/dlib/buffer.h>
TYPES
dmBuffer::HBuffer HBuffer type definition
ENUMS
Result result enumeration
ValueType valueType enumeration
STRUCTS
struct dmBuffer::StreamDeclaration StreamDeclaration struct
FUNCTIONS
dmBuffer::Result dmBuffer::Copy(dmBuffer::HBuffer* dst_buffer_handle, dmBuffer::HBuffer* src_buffer_handle) copy a Buffer
dmBuffer::Result dmBuffer::Create(uint32_t count, const dmBuffer::StreamDeclaration* streams_decl, uint8_t streams_decl_count, dmBuffer::HBuffer* out_buffer) create Buffer
void dmBuffer::Destroy(dmBuffer::HBuffer buffer) destroy Buffer.
dmBuffer::Result dmBuffer::GetBytes(dmBuffer::HBuffer buffer, void** out_bytes, uint32_t* out_size) get buffer as a byte array.
dmBuffer::Result dmBuffer::GetContentVersion(dmBuffer::HBuffer type, uint32_t* version) Gets the current update number
dmBuffer::Result dmBuffer::GetCount(dmBuffer::HBuffer buffer, uint32_t* count) get buffer count.
void dmBuffer::GetMetaData(dmBuffer::HBuffer hbuffer, dmhash_t name_hash, void** data, uint32_t count, dmBuffer::ValueType type) retrieve a metadata entry
const char* dmBuffer::GetResultString(dmBuffer::Result result) result to string
uint32_t dmBuffer::GetSizeForValueType(dmBuffer::ValueType type) get size of a value type
dmBuffer::Result dmBuffer::GetStream(dmBuffer::HBuffer buffer, dmhash_t stream_name, void** stream, uint32_t* count, uint32_t* components, uint32_t* stride) get stream from buffer.
dmBuffer::Result dmBuffer::GetStreamType(dmBuffer::HBuffer buffer, dmhash_t stream_name, dmBuffer::ValueType* type, uint32_t* components) get stream type and type count
const char* dmBuffer::GetValueTypeString(dmBuffer::ValueType result) value type to string
bool dmBuffer::IsBufferValid(dmBuffer::HBuffer buffer) check buffer handle
dmBuffer::Result dmBuffer::SetMetaData(dmBuffer::HBuffer hbuffer, dmhash_t name_hash, void* data, uint32_t count, dmBuffer::ValueType type) set a metadata entry
dmBuffer::Result dmBuffer::UpdateContentVersion(dmBuffer::HBuffer type) Update the internal frame counter.
void dmBuffer::ValidateBuffer(dmBuffer::HBuffer buffer) validate buffer.

Functions

dmBuffer::Copy

dmBuffer::Result dmBuffer::Copy(dmBuffer::HBuffer* dst_buffer_handle, dmBuffer::HBuffer* src_buffer_handle)

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

PARAMETERS

dmBuffer::HBuffer* dst_buffer_handle Pointer to HBuffer from where to copy buffer data.
dmBuffer::HBuffer* src_buffer_handle Pointer to HBuffer where to copy the buffer data.

RETURNS

dmBuffer::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::Create

dmBuffer::Result dmBuffer::Create(uint32_t count, const dmBuffer::StreamDeclaration* streams_decl, uint8_t streams_decl_count, dmBuffer::HBuffer* out_buffer)

Creates a new HBuffer with a number of different streams.

PARAMETERS

uint32_t count The number of "structs" the buffer should hold (e.g. vertex count)
const dmBuffer::StreamDeclaration* streams_decl Array of stream declarations
uint8_t streams_decl_count Number of stream declarations inside the decl array (max 256)
dmBuffer::HBuffer* out_buffer Pointer to HBuffer where to store the newly allocated buffer

RETURNS

dmBuffer::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::Destroy

void dmBuffer::Destroy(dmBuffer::HBuffer buffer)

Destroys a HBuffer and it's streams.

PARAMETERS

dmBuffer::HBuffer 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::GetBytes

dmBuffer::Result dmBuffer::GetBytes(dmBuffer::HBuffer buffer, void** out_bytes, uint32_t* out_size)

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

PARAMETERS

dmBuffer::HBuffer buffer buffer handle.
void** out_bytes Pointer to void* where to store the bytes
uint32_t* out_size Pointer to uint32_t where to store the array size

RETURNS

dmBuffer::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::GetContentVersion

dmBuffer::Result dmBuffer::GetContentVersion(dmBuffer::HBuffer type, uint32_t* version)

Gets the current update number

PARAMETERS

dmBuffer::HBuffer type The value type
uint32_t* version The current version number

RETURNS

dmBuffer::Result Returns BUFFER_OK if all went ok

dmBuffer::GetCount

dmBuffer::Result dmBuffer::GetCount(dmBuffer::HBuffer buffer, uint32_t* count)

Get (struct) count for a buffer.

PARAMETERS

dmBuffer::HBuffer buffer buffer handle.
uint32_t* count Pointer to uint32_t where to store the element count

RETURNS

dmBuffer::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::GetMetaData

void dmBuffer::GetMetaData(dmBuffer::HBuffer hbuffer, dmhash_t name_hash, void** data, uint32_t count, dmBuffer::ValueType type)

Retrieve metadata entry information

PARAMETERS

dmBuffer::HBuffer hbuffer A buffer handle
dmhash_t name_hash The entry name as a hash
void** data Gets the internal address of metadata values
uint32_t count Gets the number of metadata values stored
dmBuffer::ValueType type Gets the type of values of the metadata

dmBuffer::GetResultString

const char* dmBuffer::GetResultString(dmBuffer::Result result)

Converts result to string

PARAMETERS

dmBuffer::Result result The result

RETURNS

const char* The result as a string

dmBuffer::GetSizeForValueType

uint32_t dmBuffer::GetSizeForValueType(dmBuffer::ValueType type)

Gets the size of a value type

PARAMETERS

dmBuffer::ValueType type The value type

RETURNS

uint32_t The size in bytes

dmBuffer::GetStream

dmBuffer::Result dmBuffer::GetStream(dmBuffer::HBuffer buffer, dmhash_t stream_name, void** stream, uint32_t* count, uint32_t* components, uint32_t* stride)

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

PARAMETERS

dmBuffer::HBuffer buffer buffer handle.
dmhash_t stream_name Hash of stream name to get
void** stream Where to store the stream
uint32_t* count Where to store the count (e.g. vertex count). May be null.
uint32_t* components Where to store the number of components (e.g. 3 for a Vector3). May be null.
uint32_t* 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))

RETURNS

dmBuffer::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::GetStreamType

dmBuffer::Result dmBuffer::GetStreamType(dmBuffer::HBuffer buffer, dmhash_t stream_name, dmBuffer::ValueType* type, uint32_t* components)

Gets the stream type

PARAMETERS

dmBuffer::HBuffer buffer Pointer to a buffer.
dmhash_t stream_name Hash of stream name to get
dmBuffer::ValueType* type The value type
uint32_t* components The number of values (E.g. 3 for a Vector3)

RETURNS

dmBuffer::Result Returns BUFFER_OK if all went ok

dmBuffer::GetValueTypeString

const char* dmBuffer::GetValueTypeString(dmBuffer::ValueType result)

Converts a value type to string

PARAMETERS

dmBuffer::ValueType result The value type

RETURNS

const char* The value type as a string

dmBuffer::IsBufferValid

bool dmBuffer::IsBufferValid(dmBuffer::HBuffer buffer)

Checks if a handle is still valid

PARAMETERS

dmBuffer::HBuffer buffer The buffer

RETURNS

bool True if the handle is valid

dmBuffer::SetMetaData

dmBuffer::Result dmBuffer::SetMetaData(dmBuffer::HBuffer hbuffer, dmhash_t name_hash, void* data, uint32_t count, dmBuffer::ValueType type)

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

dmBuffer::HBuffer hbuffer A buffer handle
dmhash_t name_hash The entry name as a hash
void* data A pointer to an array of the values
uint32_t count Number of values in the array
dmBuffer::ValueType type The type of the values

RETURNS

dmBuffer::Result RESULT_OK if the metadata entry was successfully stored

dmBuffer::UpdateContentVersion

dmBuffer::Result dmBuffer::UpdateContentVersion(dmBuffer::HBuffer type)

Used to know if a buffer has been updated.

PARAMETERS

dmBuffer::HBuffer type The value type

RETURNS

dmBuffer::Result Returns BUFFER_OK if all went ok

dmBuffer::ValidateBuffer

void dmBuffer::ValidateBuffer(dmBuffer::HBuffer buffer)

Validate a buffer and it's streams.

PARAMETERS

dmBuffer::HBuffer 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
}

Structs

dmBuffer::StreamDeclaration

TYPE

struct dmBuffer::StreamDeclaration

Buffer stream declaration structure

MEMBERS

dmhash_t m_Name Hash of stream name
dmBuffer::ValueType m_Type Stream ValueType type
uint8_t m_Count Component count of stream type. E.g. 3 for a Vector3
uint32_t m_Flags Flags for a stream.
uint32_t m_Reserved Reserved for future use.

Types

dmBuffer::HBuffer

typedef uint32_t HBuffer;

Enums

Result

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

ValueType

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