- Select ref document -

SDK Buffer API documentation

version 1.2.147

<dmsdk/dlib/buffer.h>

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

Functions

dmBuffer::Create

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

Creates a new HBuffer with a number of different streams.

Parameters

count

uint32_t The number of "structs" the buffer should hold (e.g. vertex count)

streams_decl

const dmBuffer::StreamDeclaration* Array of stream declarations

streams_decl_count

uint8_t Number of stream declarations inside the decl array (max 256)

out_buffer

dmBuffer::HBuffer* Pointer to HBuffer where to store the newly allocated buffer

count

uint32_t The number of "structs" the buffer should hold (e.g. vertex count)

streams_decl

const dmBuffer::StreamDeclaration* Array of stream declarations

streams_decl_count

uint8_t Number of stream declarations inside the decl array (max 256)

out_buffer

dmBuffer::HBuffer* Pointer to HBuffer where to store the newly allocated buffer

Returns

result

dmBuffer::Result BUFFER_OK if buffer was allocated successfully

result

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

dmBuffer::Destroy(buffer)

Destroys a HBuffer and it's streams.

Parameters

buffer

dmBuffer::HBuffer Buffer handle to the buffer to free

buffer

dmBuffer::HBuffer 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::GetBytes(buffer, out_bytes, out_size)

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

Parameters

buffer

dmBuffer::HBuffer buffer handle.

out_bytes

void** Pointer to void* where to store the bytes

out_size

uint32_t* Pointer to uint32_t where to store the array size

buffer

dmBuffer::HBuffer buffer handle.

out_bytes

void** Pointer to void* where to store the bytes

out_size

uint32_t* Pointer to uint32_t where to store the array size

Returns

result

dmBuffer::Result BUFFER_OK if the buffer was successfully accessed

result

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::GetCount

dmBuffer::GetCount(buffer, count)

Get (struct) count for a buffer.

Parameters

buffer

dmBuffer::HBuffer buffer handle.

count

uint32_t* Pointer to uint32_t where to store the element count

buffer

dmBuffer::HBuffer buffer handle.

count

uint32_t* Pointer to uint32_t where to store the element count

Returns

result

dmBuffer::Result BUFFER_OK if the element count was successfully accessed

result

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::GetResultString

dmBuffer::GetResultString(result)

Converts result to string

Parameters

result

dmBuffer::Result The result

result

dmBuffer::Result The result

Returns

result

const char* The result as a string

result

const char* The result as a string

dmBuffer::GetSizeForValueType

dmBuffer::GetSizeForValueType(type)

Gets the size of a value type

Parameters

type

dmBuffer::ValueType The value type

type

dmBuffer::ValueType The value type

Returns

size

uint32_t The size in bytes

size

uint32_t The size in bytes

dmBuffer::GetStream

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

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

Parameters

buffer

dmBuffer::HBuffer buffer handle.

stream_name

dmhash_t Hash of stream name to get

stream

void** Where to store the stream

count

uint32_t* Where to store the count (e.g. vertex count). May be null.

components

uint32_t* Where to store the number of components (e.g. 3 for a Vector3). May be null.

stride

uint32_t* Where to store the 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))

buffer

dmBuffer::HBuffer buffer handle.

stream_name

dmhash_t Hash of stream name to get

stream

void** Where to store the stream

count

uint32_t* Where to store the count (e.g. vertex count). May be null.

components

uint32_t* Where to store the number of components (e.g. 3 for a Vector3). May be null.

stride

uint32_t* Where to store the 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

result

dmBuffer::Result BUFFER_OK if the stream was successfully accessed

result

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::GetStreamType(buffer, stream_name, type, components)

Gets the stream type

Parameters

buffer

dmBuffer::HBuffer Pointer to a buffer.

stream_name

dmhash_t Hash of stream name to get

type

dmBuffer::ValueType* The value type

components

uint32_t* The number of values (E.g. 3 for a Vector3)

buffer

dmBuffer::HBuffer Pointer to a buffer.

stream_name

dmhash_t Hash of stream name to get

type

dmBuffer::ValueType* The value type

components

uint32_t* The number of values (E.g. 3 for a Vector3)

Returns

result

dmBuffer::Result Returns BUFFER_OK if all went ok

result

dmBuffer::Result Returns BUFFER_OK if all went ok

dmBuffer::GetValueTypeString

dmBuffer::GetValueTypeString(result)

Converts a value type to string

Parameters

result

dmBuffer::ValueType The value type

result

dmBuffer::ValueType The value type

Returns

result

const char* The value type as a string

result

const char* The value type as a string

dmBuffer::IsBufferValid

dmBuffer::IsBufferValid(buffer)

Checks if a handle is still valid

Parameters

buffer

dmBuffer::HBuffer The buffer

buffer

dmBuffer::HBuffer The buffer

Returns

result

bool True if the handle is valid

result

bool True if the handle is valid

dmBuffer::ValidateBuffer

dmBuffer::ValidateBuffer(buffer)

Validate a buffer and it's streams.

Parameters

buffer

dmBuffer::HBuffer Buffer handle to the buffer to validate

buffer

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

Buffer stream declaration structure

Members

m_Name

dmhash_t Hash of stream name

m_Type

dmBuffer::ValueType Stream ValueType type

m_Count

uint8_t Component count of stream type. E.g. 3 for a Vector3

m_Flags

uint32_t Flags for a stream.

m_Reserved

uint32_t Reserved for future use.

m_Name

dmhash_t Hash of stream name

m_Type

dmBuffer::ValueType Stream ValueType type

m_Count

uint8_t Component count of stream type. E.g. 3 for a Vector3

m_Flags

uint32_t Flags for a stream.

m_Reserved

uint32_t Reserved for future use.

Examples

Declare a typical position stream:

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

Typedefs

dmBuffer::HBuffer

typedef struct Buffer* HBuffer;

Enumerations

Result

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

ValueType

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