buffer
Functions for manipulating buffers and streams
Functions
buffer.copy_buffer(dst:Opaque<"buffer"> & { length: LuaLengthMethod<number> }, dstoffset: number, src:Opaque<"buffer"> & { length: LuaLengthMethod<number> }, srcoffset: number, count: number): voidbuffer.copy_stream(dst:Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }, dstoffset: number, src:Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }, srcoffset: number, count: number): voidbuffer.create(element_count: number, declaration: [{ name?: Hash | string; type:buffer.ValueType; count?: number }, ...{ name?: Hash | string; type:buffer.ValueType; count?: number }[]]):Opaque<"buffer"> & { length: LuaLengthMethod<number> }buffer.get_bytes(buffer:Opaque<"buffer"> & { length: LuaLengthMethod<number> }, stream_name?: Hash | string): stringbuffer.get_metadata(buf:Opaque<"buffer"> & { length: LuaLengthMethod<number> }, metadata_name: Hash | string): LuaMultiReturn<[number[] | undefined,buffer.ValueType| undefined]>buffer.get_stream(buffer:Opaque<"buffer"> & { length: LuaLengthMethod<number> }, stream_name: Hash | string):Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }buffer.set_metadata(buf:Opaque<"buffer"> & { length: LuaLengthMethod<number> }, metadata_name: Hash | string, values: [number, ...number[]], value_type: Exclude<buffer.ValueType, typeof buffer.VALUE_TYPE_INT64 | typeof buffer.VALUE_TYPE_UINT64>): void
buffer.copy_buffer(dst: Opaque<"buffer"> & { length: LuaLengthMethod<number> }, dstoffset: number, src: Opaque<"buffer"> & { length: LuaLengthMethod<number> }, srcoffset: number, count: number): void
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
const element_count = 64;
const srcbuffer = resource.get_buffer("/src.bufferc");
const dstbuffer = resource.get_buffer("/dst.bufferc");
// copy entire buffer
buffer.copy_buffer(dstbuffer, 0, srcbuffer, 0, element_count);
// copy last 10 elements to the front of another buffer
buffer.copy_buffer(dstbuffer, 0, srcbuffer, element_count - 10, 10);-- 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)Parameters
dst:Opaque<"buffer"> & { length: LuaLengthMethod<number> }— the destination bufferdstoffset:number— the offset to start copying data tosrc:Opaque<"buffer"> & { length: LuaLengthMethod<number> }— the source data buffersrcoffset:number— the offset to start copying data fromcount:number— the number of elements to copy
buffer.copy_stream(dst: Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }, dstoffset: number, src: Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }, srcoffset: number, count: number): void
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:
const srcbuffer = resource.get_buffer("/src.bufferc");
const dstbuffer = resource.get_buffer("/dst.bufferc");
// 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());-- 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)Parameters
dst:Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }— the destination streamdstoffset:number— the offset to start copying data to (measured in value type)src:Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }— the source data streamsrcoffset:number— the offset to start copying data from (measured in value type)count:number— the number of values to copy (measured in value type)
buffer.create(element_count: number, declaration: [{ name?: Hash | string; type: buffer.ValueType; count?: number }, ...{ name?: Hash | string; type: buffer.ValueType; count?: number }[]]): Opaque<"buffer"> & { length: LuaLengthMethod<number> }
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() {
const size = 128;
const [width, height] = [size, size];
const [r, g, b] = [0xff, 0x80, 0x10];
const image = buffer.create(size * size, [{ name: hash("rgb"), type: buffer.VALUE_TYPE_UINT8, count: 3 }]);
const imagestream = buffer.get_stream(image, hash("rgb"));
for (let y = 0; y < height; y++) {
for (let x = 0; x < width; x++) {
const index = y * width * 3 + x * 3;
imagestream[index + 0] = r;
imagestream[index + 1] = g;
imagestream[index + 2] = b;
}
}
return { image, imagestream };
},
});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
endParameters
element_count:number— The number of elements the buffer should holddeclaration:[{ name?: Hash | string; type: buffer.ValueType; count?: number }, ...{ name?: Hash | string; type: buffer.ValueType; count?: number }[]]— A table where each entry (table) describes a stream- hash | string
name: The name of the stream - buffer.VALUE_TYPE
type: The data type of the stream - number
count: The number of values each element should hold
- hash | string
Returns
buffer:Opaque<"buffer"> & { length: LuaLengthMethod<number> }— the new buffer
buffer.get_bytes(buffer: Opaque<"buffer"> & { length: LuaLengthMethod<number> }, stream_name?: Hash | string): string
Get a copy of all the bytes of the buffer, every stream included, as a Lua string.
Parameters
buffer:Opaque<"buffer"> & { length: LuaLengthMethod<number> }— the source bufferstream_name?:Hash | string— the name of the stream; the engine ignores it and returns every byte of the buffer
Returns
data:string— the buffer data as a Lua string
buffer.get_metadata(buf: Opaque<"buffer"> & { length: LuaLengthMethod<number> }, metadata_name: Hash | string): LuaMultiReturn<[number[] | undefined, buffer.ValueType | undefined]>
Get a named metadata entry from a buffer along with its type.
// How to get a metadata entry from a buffer
const buf = resource.get_buffer("/my.bufferc");
// 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'`);-- 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'") endParameters
buf:Opaque<"buffer"> & { length: LuaLengthMethod<number> }— the buffer to get the metadata frommetadata_name:Hash | string— name of the metadata entry
Returns
values:number[] | undefined— table of metadata values ornilif the entry does not existvalue_type:buffer.ValueType | undefined— numeric type of values ornil
buffer.get_stream(buffer: Opaque<"buffer"> & { length: LuaLengthMethod<number> }, stream_name: Hash | string): Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }
Get a specified stream from a buffer.
Parameters
buffer:Opaque<"buffer"> & { length: LuaLengthMethod<number> }— the buffer to get the stream fromstream_name:Hash | string— the stream name
Returns
stream:Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }— the data stream
buffer.set_metadata(buf: Opaque<"buffer"> & { length: LuaLengthMethod<number> }, metadata_name: Hash | string, values: [number, ...number[]], value_type: Exclude<buffer.ValueType, typeof buffer.VALUE_TYPE_INT64 | typeof buffer.VALUE_TYPE_UINT64>): void
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
const buf = resource.get_buffer("/my.bufferc");
// 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);-- 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"> & { length: LuaLengthMethod<number> }— the buffer to set the metadata onmetadata_name:Hash | string— name of the metadata entryvalues:[number, ...number[]]— actual metadata, an array of numeric valuesvalue_type:Exclude<buffer.ValueType, typeof buffer.VALUE_TYPE_INT64 | typeof buffer.VALUE_TYPE_UINT64>— type of values when stored
Constants
buffer.VALUE_TYPE_FLOAT32: number & { readonly __brand: "buffer.VALUE_TYPE_FLOAT32" }
float32 Float, single precision, 4 bytes
buffer.VALUE_TYPE_INT16: number & { readonly __brand: "buffer.VALUE_TYPE_INT16" }
int16 Signed integer, 2 bytes
buffer.VALUE_TYPE_INT32: number & { readonly __brand: "buffer.VALUE_TYPE_INT32" }
int32 Signed integer, 4 bytes
buffer.VALUE_TYPE_INT64: number & { readonly __brand: "buffer.VALUE_TYPE_INT64" }
int64 Signed integer, 8 bytes
buffer.VALUE_TYPE_INT8: number & { readonly __brand: "buffer.VALUE_TYPE_INT8" }
int8 Signed integer, 1 byte
buffer.VALUE_TYPE_UINT16: number & { readonly __brand: "buffer.VALUE_TYPE_UINT16" }
uint16 Unsigned integer, 2 bytes
buffer.VALUE_TYPE_UINT32: number & { readonly __brand: "buffer.VALUE_TYPE_UINT32" }
uint32 Unsigned integer, 4 bytes
buffer.VALUE_TYPE_UINT64: number & { readonly __brand: "buffer.VALUE_TYPE_UINT64" }
uint64 Unsigned integer, 8 bytes
buffer.VALUE_TYPE_UINT8: number & { readonly __brand: "buffer.VALUE_TYPE_UINT8" }
uint8 Unsigned integer, 1 byte