lubyk logo

Lubyk documentation

four.Buffer

A buffer holds 1D to 4D int/float vectors in a linear lua array. For usage, see new or the SimpleShader example.

TODO INCOMPLETE DOCUMENTATION

Constants

Buffer element type

Defines how the data will be stored on the GPU and how the shader will view the data.

.FLOAT = 1

.DOUBLE = 2

.INT = 3

.UNSIGNED_INT = 4

.BYTE = 5

.UNSIGNED_BYTE = 6

Buffer usage hints

Defines how the data will be updated (hint for renderer).

.UPDATE_NEVER = 1

.UPDATE_SOMETIMES = 2

.UPDATE_OFTEN = 3

Constructor

.new (def)

Create a four.Buffer with parameters defined in def. Possible keys are:

dimthe vectors dimension (defaults to 3).
scalar_typethe vector's element type (defaults to lib.FLOAT).
dataan array of numbers (defaults to {})
normalizetrue if the data should be normalized by the GPU (defaults to false).
updatethe update frequency (defaults to UPDATE_NEVER)
disposableif true, data is disposed by the renderer once uploaded to the GPU (defaults to true).
updatedif true, data will be read again by the renderer. The renderer sets the flag back to false once it read the data.

Usage examples:

Vertex buffer (3 values = xyz).

local vb = four.Buffer { dim = 3,
           scalar_type = four.Buffer.FLOAT }

Color buffer (4 values = rgba)

local cb = four.Buffer { dim = 4,
           scalar_type = four.Buffer.FLOAT }

Index buffer (how values are used is defined in four.Geometry#primitive).

local ib = four.Buffer { dim = 1,
           scalar_type = four.Buffer.UNSIGNED_INT }

:set (def)

:length ()

:scalarLength ()

:disposeBuffer ()

Getters

:getScalar (i)

:get1D (i)

:get2D (i)

:get3D (i)

:get4D (i)

:getV2 (i)

:getV3 (i)

:getV4 (i)

Setters

:setScalar (i, x)

:set1D (i, x)

:set2D (i, x, y)

:set3D (i, x, y, z)

:set4D (i, x, y, z, w)

:setV2 (i, v)

:setV3 (i, v)

:setV4 (i, v)

Append

Note: appending just adds elements at the end of the data, it does not care about buffer dimension.

:push (...)

:push1D (x)

:push2D (x, y)

:push3D (x, y, z)

:push4D (x, y, z, w)

:pushV2 (v)

:pushV3 (v)

:pushV4 (v)

Swapping and deleting

:swap (i,j)

Swap elements i and j.

:delete (i)

Delete element i. Warning: does not preserve the order of elements in the array.

TODO Could greatly optimize by using table.remove (this would also preserve order).

Traversing

:foldScalars (f, acc)

:fold1D (f, acc)

:fold2D (f, acc)

:fold3D (f, acc)

:fold4D (f, acc)

:foldV3 (f, acc)

:foldV4 (f, acc)

Sorting

Sorting methods use custom comparison function cmp(x,y) which should return:

  • -1 if x is smaller than y
  • 0 if x equals y
  • 1 if x is greater than y

:sort (cmp, get)

Sort the elements of the buffer in place using cmp as a comparison function. cmp is given objects returned by optional get function. (defaults depends on self.dim, number for 1, V2 for 2, V3 for 3, V4 for 4)

:sortOrder (cmp, get)

This is like sort except elements of the buffer are kept in place and an array of indexes defining the order is returned.

Data properties

:dimExtents ()

Returns a table of size self.dim containing tables with the minimal and maximal scalar values for each dimension in to form {min = ..., max = ...}.

TODO

BufferTODO INCOMPLETE DOCUMENTATION

#deleteTODO Could greatly optimize by using table.remove (this would also preserve order).