Buffer API documentation

buffer_data

buffer_data = userdata

A buffer stores one or more named streams of typed values. Create a buffer with buffer.create, or obtain one from APIs such as resource.get_buffer, sys.load_buffer, or image.load. Use buffer.get_stream to access the values in an individual stream.

EXAMPLES

local vertices = buffer.create(3, {
    { name = hash("position"), type = buffer.VALUE_TYPE_FLOAT32, count = 3 }
})

buffer_stream

buffer_stream = userdata

An indexable view of one named stream in a buffer_data. Obtain a stream with buffer.get_stream. Reading or writing the stream accesses the values in its underlying buffer.

EXAMPLES

local vertices = buffer.create(1, {
    { name = hash("position"), type = buffer.VALUE_TYPE_FLOAT32, count = 3 }
})
local positions = buffer.get_stream(vertices, "position")
positions[1] = 10
positions[2] = 20
positions[3] = 0

buffer.VALUE_TYPE

buffer.VALUE_TYPE: integer

Buffer value types

VALUES

buffer.copy_buffer()

buffer.copy_buffer(dst:buffer_data, dstoffset:number, src:buffer_data, srcoffset:number, count:number)

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

EXAMPLES

-- 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:buffer_stream, dstoffset:number, src:buffer_stream, srcoffset:number, count:number)

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

EXAMPLES

-- 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:number, declaration:({ name:hash|string, type:buffer.VALUE_TYPE, count:number })[])→buffer:buffer_data

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

RETURNS

EXAMPLES

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:buffer_data, stream_name:hash)→data:string

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

PARAMETERS

RETURNS

buffer.get_metadata()

buffer.get_metadata(buf:buffer_data, metadata_name:hash|string)→(values:number[]|nil, value_type:buffer.VALUE_TYPE|nil)

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

PARAMETERS

RETURNS

EXAMPLES

-- 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:buffer_data, stream_name:hash|string)→stream:buffer_stream

Get a specified stream from a buffer.

PARAMETERS

RETURNS

buffer.set_metadata()

buffer.set_metadata(buf:buffer_data, metadata_name:hash|string, values:number[], value_type:buffer.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

EXAMPLES

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