Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Defold

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): 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 buffer
  • dstoffset: number — the offset to start copying data to
  • src: Opaque<"buffer"> & { length: LuaLengthMethod<number> } — the source data buffer
  • srcoffset: number — the offset to start copying data from
  • count: 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 stream
  • dstoffset: number — the offset to start copying data to (measured in value type)
  • src: Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<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)

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
  end

Parameters

  • element_count: number — The number of elements the buffer should hold
  • declaration: [{ 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

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 buffer
  • stream_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'") end

Parameters

  • buf: Opaque<"buffer"> & { length: LuaLengthMethod<number> } — the buffer to get the metadata from
  • metadata_name: Hash | string — name of the metadata entry

Returns

  • values: number[] | undefined — table of metadata values or nil if the entry does not exist
  • value_type: buffer.ValueType | undefined — numeric type of values or nil

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 from
  • stream_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 on
  • metadata_name: Hash | string — name of the metadata entry
  • values: [number, ...number[]] — actual metadata, an array of numeric values
  • value_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

Types

type buffer.ValueType = typeof buffer.VALUE_TYPE_FLOAT32 | typeof buffer.VALUE_TYPE_INT16 | typeof buffer.VALUE_TYPE_INT32 | typeof buffer.VALUE_TYPE_INT64 | typeof buffer.VALUE_TYPE_INT8 | typeof buffer.VALUE_TYPE_UINT16 | typeof buffer.VALUE_TYPE_UINT32 | typeof buffer.VALUE_TYPE_UINT64 | typeof buffer.VALUE_TYPE_UINT8

On this page

Functionsbuffer.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>): voidConstantsbuffer.VALUE_TYPE_FLOAT32: number & { readonly __brand: "buffer.VALUE_TYPE_FLOAT32" }buffer.VALUE_TYPE_INT16: number & { readonly __brand: "buffer.VALUE_TYPE_INT16" }buffer.VALUE_TYPE_INT32: number & { readonly __brand: "buffer.VALUE_TYPE_INT32" }buffer.VALUE_TYPE_INT64: number & { readonly __brand: "buffer.VALUE_TYPE_INT64" }buffer.VALUE_TYPE_INT8: number & { readonly __brand: "buffer.VALUE_TYPE_INT8" }buffer.VALUE_TYPE_UINT16: number & { readonly __brand: "buffer.VALUE_TYPE_UINT16" }buffer.VALUE_TYPE_UINT32: number & { readonly __brand: "buffer.VALUE_TYPE_UINT32" }buffer.VALUE_TYPE_UINT64: number & { readonly __brand: "buffer.VALUE_TYPE_UINT64" }buffer.VALUE_TYPE_UINT8: number & { readonly __brand: "buffer.VALUE_TYPE_UINT8" }Typestype buffer.ValueType = typeof buffer.VALUE_TYPE_FLOAT32 | typeof buffer.VALUE_TYPE_INT16 | typeof buffer.VALUE_TYPE_INT32 | typeof buffer.VALUE_TYPE_INT64 | typeof buffer.VALUE_TYPE_INT8 | typeof buffer.VALUE_TYPE_UINT16 | typeof buffer.VALUE_TYPE_UINT32 | typeof buffer.VALUE_TYPE_UINT64 | typeof buffer.VALUE_TYPE_UINT8