Buffer

Functions for manipulating buffers and streams

buffer.VALUE_TYPE_UINT8

uint8

Unsigned integer, 1 byte


buffer.VALUE_TYPE_UINT16

uint16

Unsigned integer, 2 bytes


buffer.VALUE_TYPE_UINT32

uint32

Unsigned integer, 4 bytes


buffer.VALUE_TYPE_UINT64

uint64

Unsigned integer, 8 bytes


buffer.VALUE_TYPE_INT8

int8

Signed integer, 1 byte


buffer.VALUE_TYPE_INT16

int16

Signed integer, 2 bytes


buffer.VALUE_TYPE_INT32

int32

Signed integer, 4 bytes


buffer.VALUE_TYPE_INT64

int64

Signed integer, 8 bytes


buffer.VALUE_TYPE_FLOAT32

float32

Float, single precision, 4 bytes


buffer.create(element_count, declaration)

creates a new buffer

Create a new data buffer containing a specified set of streams. A data buffer can contain one or more streams with typed data. This is useful for managing compound data, for instance a vertex buffer could contain separate streams for vertex position, color, normal etc.

PARAMETERS

element_count - The number of elements the buffer should hold

declaration - A table where each entry (table) describes a stream

RETURN

buffer - the new buffer

EXAMPLES

How to create and initialize a buffer

function init(self)
  local size = 128
  self.image = buffer.create( size * size, { {name=hash("rgb"), type=buffer.VALUE_TYPE_UINT8, count=3 } })
  self.imagestream = buffer.get_stream(self.image, hash("rgb"))

  for y=0,self.height-1 do
     for x=0,self.width-1 do
         local index = y * self.width * 3 + x * 3 + 1
         self.imagestream[index + 0] = self.r
         self.imagestream[index + 1] = self.g
         self.imagestream[index + 2] = self.b
     end
  end


buffer.get_stream(buffer, stream_name)

gets a stream from a buffer

Get a specified stream from a buffer.

PARAMETERS

buffer - the buffer to get the stream from

stream_name - the stream name

RETURN

stream - the data stream


buffer.copy_stream(dst, dstoffset, src, srcoffset, count)

copies data from one stream to another

Copy a specified amount of data from one stream to another. The value type and size must match between source and destination streams. The source and destination streams can be the same.

PARAMETERS

dst - the destination stream

dstoffset - the offset to start copying data to (measured in value type)

src - the source data stream

srcoffset - the offset to start copying data from (measured in value type)

count - the number of values to copy (measured in value type)

EXAMPLES

How to update a texture of a sprite:

-- copy entire stream
local srcstream = buffer.get_stream(srcbuffer, hash("xyz"))
local dststream = buffer.get_stream(dstbuffer, hash("xyz"))
buffer.copy_stream(dststream, 0, srcstream, 0, #srcstream)


buffer.copy_buffer(dst, dstoffset, src, srcoffset, count)

copies one buffer to another

Copy all data streams from one buffer to another, element wise. Each of the source streams must have a matching stream in the destination buffer. The streams must match in both type and size. The source and destination buffer can be the same.

PARAMETERS

dst - the destination buffer

dstoffset - the offset to start copying data to

src - the source data buffer

srcoffset - the offset to start copying data from

count - the number of elements to copy

EXAMPLES

How to copy elements (e.g. vertices) from one buffer to another

-- copy entire buffer
buffer.copy_buffer(dstbuffer, 0, srcbuffer, 0, #srcbuffer)

-- copy last 10 elements to the front of another buffer
buffer.copy_buffer(dstbuffer, 0, srcbuffer, #srcbuffer - 10, 10)


buffer.get_bytes(buffer, stream_name)

gets data from a stream

Get a copy of all the bytes from a specified stream as a Lua string.

PARAMETERS

buffer - the source buffer

stream_name - the name of the stream

RETURN

data - the buffer data as a Lua string


buffer.set_metadata(buf, metadata_name, values, value_type)

set a metadata entry on a buffer

Creates or updates a metadata array entry on a buffer. The value type and count given when updating the entry should match those used when first creating it.

PARAMETERS

buf - the buffer to set the metadata on

metadata_name - name of the metadata entry

values - actual metadata, an array of numeric values

value_type - type of values when stored

EXAMPLES

How to set a metadata entry on a buffer

-- create a new metadata entry with three floats
buffer.set_metadata(buf, hash("somefloats"), {1.5, 3.2, 7.9}, buffer.VALUE_TYPE_FLOAT32)
-- ...
-- update to a new set of values
buffer.set_metadata(buf, hash("somefloats"), {-2.5, 10.0, 32.2}, buffer.VALUE_TYPE_FLOAT32)


buffer.get_metadata(buf, metadata_name)

retrieve a metadata entry from a buffer

Get a named metadata entry from a buffer along with its type.

PARAMETERS

buf - the buffer to get the metadata from

metadata_name - name of the metadata entry

RETURN

values - table of metadata values or nil if the entry does not exist

value_type - numeric type of values or nil

EXAMPLES

How to get a metadata entry from a buffer

-- retrieve a metadata entry named "somefloats" and its nomeric type
local values, type = buffer.get_metadata(buf, hash("somefloats"))
if metadata then print(#metadata.." values in 'somefloats'") end