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.

// How to create and initialize a buffer
export default defineScript({
  init(self) {
    const 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 (let y = 0; y < self.height; y++) {
      for (let x = 0; x < self.width; x++) {
        const index = y * self.width * 3 + x * 3;
        self.imagestream[index + 0] = self.r;
        self.imagestream[index + 1] = self.g;
        self.imagestream[index + 2] = self.b;
      }
    }
  },
});

Parameters

• element_count: number — The number of elements the buffer should hold

• declaration: Record<string | number, unknown> — 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: Opaque<"buffer"> — the new buffer

Get a specified stream from a buffer.

Parameters

• buffer: Opaque<"buffer"> — the buffer to get the stream from
• stream_name: Hash | string — the stream name

Returns

• stream: Opaque<"bufferstream"> & { [index: number]: number } — the data stream

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.

// How to update a texture of a sprite:
// copy entire stream
const srcstream = buffer.get_stream(srcbuffer, hash("xyz"));
const dststream = buffer.get_stream(dstbuffer, hash("xyz"));
buffer.copy_stream(dststream, 0, srcstream, 0, srcstream.length);

Parameters

• dst: Opaque<"bufferstream"> & { [index: number]: number } — the destination stream
• dstoffset: number — the offset to start copying data to (measured in value type)
• src: Opaque<"bufferstream"> & { [index: number]: number } — 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)

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.

// How to copy elements (e.g. vertices) from one buffer to another
// copy entire buffer
buffer.copy_buffer(dstbuffer, 0, srcbuffer, 0, srcbuffer.length);

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

Parameters

• dst: Opaque<"buffer"> — the destination buffer
• dstoffset: number — the offset to start copying data to
• src: Opaque<"buffer"> — the source data buffer
• srcoffset: number — the offset to start copying data from
• count: number — the number of elements to copy

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

Parameters

• buffer: Opaque<"buffer"> — the source buffer
• stream_name: Hash — the name of the stream

Returns

• data: string — the buffer data as a Lua string

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.

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

Parameters

• buf: Opaque<"buffer"> — the buffer to set the metadata on
• metadata_name: Hash | string — name of the metadata entry
• values: Record<string | number, unknown> — actual metadata, an array of numeric values
• value_type: Opaque<"constant"> — type of values when stored

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

// How to get a metadata entry from a buffer
// retrieve a metadata entry named "somefloats" and its numeric type
const [values, type] = buffer.get_metadata(buf, hash("somefloats"));
if (values) print(`${values.length} values in 'somefloats'`);

Parameters

• buf: Opaque<"buffer"> — the buffer to get the metadata from
• metadata_name: Hash | string — name of the metadata entry

Returns

• values: Record<string | number, unknown> | nil — table of metadata values or nil if the entry does not exist
• value_type: Opaque<"constant"> | nil — numeric type of values or nil

Unsigned integer, 1 byte

Unsigned integer, 2 bytes

Unsigned integer, 4 bytes

Unsigned integer, 8 bytes

Signed integer, 1 byte

Signed integer, 2 bytes

Signed integer, 4 bytes

Signed integer, 8 bytes

Float, single precision, 4 bytes