Buffer API documentation

Version: stable

FUNCTION
buffer.copy_buffer() copies one buffer to another
buffer.copy_stream() copies data from one stream to another
buffer.create() creates a new buffer
buffer.get_bytes() gets data from a stream
buffer.get_metadata() retrieve a metadata entry from a buffer
buffer.get_stream() gets a stream from a buffer
buffer.set_metadata() set a metadata entry on a buffer
CONSTANT
buffer.VALUE_TYPE_FLOAT32 float32
buffer.VALUE_TYPE_INT16 int16
buffer.VALUE_TYPE_INT32 int32
buffer.VALUE_TYPE_INT64 int64
buffer.VALUE_TYPE_INT8 int8
buffer.VALUE_TYPE_UINT16 uint16
buffer.VALUE_TYPE_UINT32 uint32
buffer.VALUE_TYPE_UINT64 uint64
buffer.VALUE_TYPE_UINT8 uint8

Functions

buffer.copy_buffer()

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

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 buffer the destination buffer
dstoffset number the offset to start copying data to
src buffer the source data buffer
srcoffset number the offset to start copying data from
count number 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.copy_stream()

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

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 bufferstream the destination stream
dstoffset number the offset to start copying data to (measured in value type)
src bufferstream the source data stream
srcoffset number the offset to start copying data from (measured in value type)
count number 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.create()

buffer.create(element_count,declaration)

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 number The number of elements the buffer should hold
declaration table A table where each entry (table) describes a stream
  • hash | string name: The name of the stream
  • constant type: The data type of the stream
  • number count: The number of values each element should hold

RETURNS

buffer 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_bytes()

buffer.get_bytes(buffer,stream_name)

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

PARAMETERS

buffer buffer the source buffer
stream_name hash the name of the stream

RETURNS

data string the buffer data as a Lua string

buffer.get_metadata()

buffer.get_metadata(buf,metadata_name)

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

PARAMETERS

buf buffer the buffer to get the metadata from
metadata_name hash, string name of the metadata entry

RETURNS

values table, nil table of metadata values or nil if the entry does not exist
value_type constant, nil 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

buffer.get_stream()

buffer.get_stream(buffer,stream_name)

Get a specified stream from a buffer.

PARAMETERS

buffer buffer the buffer to get the stream from
stream_name hash, string the stream name

RETURNS

stream bufferstream the data stream

buffer.set_metadata()

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

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 buffer the buffer to set the metadata on
metadata_name hash, string name of the metadata entry
values table actual metadata, an array of numeric values
value_type constant 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)

Constants

buffer.VALUE_TYPE_FLOAT32

Float, single precision, 4 bytes


buffer.VALUE_TYPE_INT16

Signed integer, 2 bytes


buffer.VALUE_TYPE_INT32

Signed integer, 4 bytes


buffer.VALUE_TYPE_INT64

Signed integer, 8 bytes


buffer.VALUE_TYPE_INT8

Signed integer, 1 byte


buffer.VALUE_TYPE_UINT16

Unsigned integer, 2 bytes


buffer.VALUE_TYPE_UINT32

Unsigned integer, 4 bytes


buffer.VALUE_TYPE_UINT64

Unsigned integer, 8 bytes


buffer.VALUE_TYPE_UINT8

Unsigned integer, 1 byte