@spearwolf/vertex-objects

vertex-objects

is a typescript library that allows you to create and render multiple and (optionally) instanced geometries with just a single draw call. such vertex objects are defined by a descriptor — for creation and usage there is a super easy and oddly satisfying to use object-based api.

it's based on the fantastic three.js library which itself is build upon WebGL.

the main features of this library are centered around the definition, creation and life-cycle management of vertex objects, in addition there are some more helpers and classes to ease the texture handling, respectively the loading of texture-atlas definitions.

IMPORTANT: this library is a kind of meta library. there is nothing in this library that three.js doesn't already allow you to do out of the box: however, this library gives you highly specialized tools that allow you to work with complex particle-like and instanced geometries in a super elegant way. a whole bunch of unnecessary boilerplate code is taken away from you and you can concentrate on the creative part of shader development 🚀

Vertex Objects

are like particles or freestyle sprites whose attributes, vertex and fragment shaders are left to you completely freely definable — but the management and organization of the underlying geometry data attribute typed array buffers is taken away from you

examples can be found here:

• animated-billboards
• animated-sprites
• instanced-quads
• crosses
• textured-quads-from-tileset
• textured-quads
• textured-sprites

all (most) of these examples are showing lots of sprites in 3d space with just one webgl draw call!

many of these examples define unusual and quirky properties, but this is intentional and purely for demonstration purposes ;-)

Texture Mapping

those who work with 2D-, 2.5D ~sprites, tiles or billboard particles will quickly realize that an easy way to import spritesheet images and texture-atlas definitions could be very handy. this library provides helpers for importing tilesets via grid-aligned spritesheet images or texture altases from json files (generated by tools such as TexturePacker).

examples can be found here:

• animated-billboards
• animated-sprites
• textured-quads-from-tileset
• textured-sprites

CHEAT SHEET

Vertex Object Descriptors

Describe your vertex objects

{
    vertexCount: 4,
    indices: [0, 1, 2, 0, 2, 3],        // [optional]

    meshCount: 1,                       // for instanced attributes (use instead of vertexCount)
                                        // not yet fully thought through: VertexBufferObject <- capacity <- meshCount > 1 ?
    attributes: {
        position: {                                     // attribute name
            components: ['x', 'y', 'z'],                // either define components ..
            size: 3,                                    // .. or set number of anonymous components

            type: 'float32',                            // [optional] the default type is float32
            normalized: boolean,                        // [optional] default is not

            usage: 'static' | 'dynamic' | 'stream',     // [optional] default is 'static'
            autoTouch: true                             // [optional] if usage == 'static' then default is false otherwise true
         }
    }

    basePrototpe: MyBaseClass.prototype;  // [optional]

    methods: {                            // [optional] also works as mixins
        [methodName]() {}                 // attention: only functions are accepted as methods
    }
}

API Overview

const geometry = new VertexObjectGeometry(descriptor, CAPACITY = 1);

const geometry = new InstancedVertexObjectGeometry(instancedDescriptor, INSTANCED_CAPACITY, baseDescriptor, BASE_CAPACITY = 1);
const geometry = new InstancedVertexObjectGeometry(instancedDescriptor, INSTANCED_CAPACITY, baseBufferGeometry);

const vo = geometry.pool.createVO()  // VertexObjectGeometry

const vo = geometry.basePool.createVO()       // InstancedVertexObjectGeometry
const vo = geometry.instancedPool.createVO()

vo.setPosition([...])
vo.x0_0
vo.x1_0
vo.x3_0
vo.x0_1

vo.copy(vo)

geometry.pool.freeVO(vo)
geometry.basePool.freeVO(vo)
geometry.instancedPool.freeVO(vo)

geometry.touchAttributes('position', 'foo')
geometry.touchBuffers({dynamic: false, stream: true, static: false})
geometry.touch('position', {dynamic: true}, ...)  // yes, you can mix it here if you want

geometry.update()  // automatically called by VertexObjects

Simple Usage

const mesh = new VertexObjects(geometry, material)

mesh.frustumCalled = false  // not needed, but can be very helpful ;)

scene.add(mesh)