tecs.gfx#

Entity components that describe a rendered scene.

Transform2D places an entity, graphics components describe its appearance, and Renderable2D admits it to rendering. Transform2D, Tint, and Renderable2D form the minimum drawable set:

local player <const> = world:spawn(
    tecs.Transform2D(120, 80, 0, 1, 0, 32, 32),
    app.renderer.sprites:sprite("player.png"),
    tecs.gfx.Tint(1.0, 1.0, 1.0, 1.0),
    tecs.gfx.Renderable2D()
)

local tint <const> = world:getMut(player, tecs.gfx.Tint)
tint.a = 0.5

Sprite selects an image region. Material selects fragment coverage and lighting. Clip selects a target-pixel clip region. PointLight2D, Occluder2D, and DropShadow2D describe deferred lighting and shadows.

The 3D mesh contract is separate from the sprite lane. tecs.Transform3D, Mesh, Bounds3D, MeshMaterial, optional MeshSkin, optional MeshMorph, Tint, and Renderable3D describe an opaque mesh for the optional mesh domain. PointLight3D and SpotLight3D enter the optional tiled local-light lane. Their pose comes from tecs.Transform3D. Material remains the compiled 2D shader identity; mesh material data has its own persisted name and resident slot.

Transform2D remains at tecs.Transform2D because physics, hierarchy, sequencing, and graphics share it. Other render components live under tecs.gfx.

Use world:getMut for authored changes. A direct cdata write through world:get must call world:markComponentDirty, or rendering keeps the old value. batchSpawn skips FFI defaults, so its callback must initialize every field.

PreviousTransform2D stores the pose before the current fixed step. The renderer interpolates it toward Transform2D for presentation without changing simulation state.

A camera maps world coordinates to one viewport.

The camera stores the view center in world units, zoom, and rotation. Callers write these fields directly:

local camera <const> = app.renderer.sprites.camera
camera.x = player.x
camera.y = player.y
camera.zoom = 2
camera.rotation = 0

Position names the center rather than a corner. The default view starts at the world origin. World Y and screen Y both increase downward.

Coordinate conversion#

Each conversion takes the viewport dimensions because one camera can serve targets of different sizes:

local worldX <const>, worldY <const> = camera:toWorld(
    mouseX, mouseY, width, height
)

local screenX <const>, screenY <const> = camera:toScreen(
    worldX, worldY, width, height
)

Use the same dimensions for conversion and rendering. toWorld, toScreen, and matrix then share one mapping, and points round-trip. viewBounds returns a conservative axis-aligned world rectangle when the camera rotates.

matrix reuses the camera's sixteen-float array, and viewBounds reuses its four-element table. Copy either result before retaining it across another call.

A perspective camera maps a right-handed 3D world to one viewport.

World +X points right, +Y points up, and the default camera looks along -Z. The camera orientation is a quaternion in (x, y, z, w) order that turns camera-local coordinates into world coordinates. Position and orientation are caller-writable fields:

local camera <const> = tecs.gfx.newCamera3D({
    x = 0,
    y = 2,
    z = 6,
    verticalFov = math.rad(60),
})
camera.rotationY = math.sin(math.rad(15) * 0.5)
camera.rotationW = math.cos(math.rad(15) * 0.5)

matrix writes a column-major world-to-clip matrix with depth in [0, 1], and inverseMatrix writes its clip-to-world inverse. matrices writes both from one camera calculation for code that needs the pair. Each result uses a separate camera-owned sixteen-float array and remains valid until that same result is written again.

A view draws one or both rendering domains into a rectangle of the frame.

Views are entities. Spawn a View component to replace the renderer's synthesized full-frame view, then assign a 2D camera, a 3D camera, or both:

world:spawn(tecs.gfx.View.new({
    camera3D = tecs.gfx.newCamera3D({x = 0, y = 3, z = 8}),
    x = 0,
    y = 0,
    width = 0.5,
    height = 1,
    order = 0,
}))

Viewport coordinates are fractions of the frame. Views draw in ascending order; equal orders use entity id. A view with both cameras composes meshes then sprites through the normal shared renderer order. A view with only a 2D camera is the direct way to place a full-frame UI above an earlier 3D view.

The renderer must be created with maxViews large enough for the explicit views. Omitting maxViews preserves the original single-view resources and pass sequence.

Coordinates rendering domains and owns frame-wide GPU work.

An application owns one renderer. The renderer owns the deferred graph, presentation targets, capture, and staging-slot rotation. sprites is the 2D domain and meshes is the 3D domain. Each owns its own extraction, residency, instance buffers, and backend. A domain disabled at creation is neither loaded nor allocated.

This division is the 3D extension seam. A mesh domain can be prepared beside the sprite domain and contribute its own pass bodies without either domain branching per entity on what kind of renderer it belongs to.

The public domain values expose cameras, residency operations, extension points, and statistics. Renderer-only lifecycle methods and the extractor, packet, and backend handles stay behind separately typed internal references.

When both domains contribute transparent work, meshes draw first and sprites draw second. Their camera spaces have no universal cross-domain depth order, so the fixed order makes sprites deterministic overlays while each domain retains its own back-to-front sort.

Setting maxViews enables ordered View entities. The renderer extracts and uploads each enabled domain once, then reculls, shades, and immediately composites each view through shared GPU work buffers. Omitting maxViews keeps the original full-frame path and allocates no multi-camera intermediate.

Shaped text as entities in the rendered world.

A Text names a font and string. Transform2D places its top-left corner, Tint colors every glyph, and Clip clips it like any other drawable.

world:addPlugin(tecs.gfx.textPlugin({
    renderer = app.renderer,
}))

world:spawn(
    tecs.Transform2D(24, 24),
    tecs.gfx.Tint(0.92, 0.96, 1.0, 1.0),
    tecs.gfx.Text.new({
        text = "tecs\n1200 entities",
        font = tecs.gfx.newTTF({
            source = "fonts/JetBrainsMono-ExtraBold.ttf",
        }),
        size = 28,
        align = "center",
    })
)

Write text fields through world:getMut. A direct world:get write leaves the column clean and the displayed glyphs unchanged.

Fonts and layout#

newTTF reads source font bytes off the main thread and returns the opened font. It transparently suspends when called by a system. SDLttf and HarfBuzz shape and lay out UTF-8. Tecs asks SDLttf for glyph images lazily, caches each glyph once per renderer, and keeps its own one-instance-per-glyph producer.

The default "sdf" raster scales without regenerating glyphs. Choose a loaded size near the largest ordinary on-screen size. A fixed-size UI may instead load an "alpha" raster at exactly its displayed size. Alpha glyphs retain the font rasterizer's small-size fitting and automatically snap their origin on a screen-space layer when they are unrotated and unscaled.

Text supports explicit newlines and left, center, or right alignment. It does not wrap to a width, anchor outside the top-left corner, or style individual glyphs. The glyph material draws text unlit through the forward-blended lane so its distance-field edge retains partial coverage.

Module contents#

Submodules#

Constructors#

Types#

Functions#

Values#

Constructors#

tecs.gfx.newTTF Static#

Loads and opens a source font with SDL_ttf.

File acquisition follows the cooperative asset path. The call suspends its system until SDL_ttf has opened the bytes, selected the raster mode, and verified the requested point size.

function tecs.gfx.newTTF(options: TTFOptions): Font

Arguments#

Returns#

Types#

tecs.gfx.Bounds3D record#

Defines a mesh's local-space bounding sphere.

A sphere stays four floats in extraction and transforms conservatively under non-uniform scale by multiplying radius by the largest absolute scale axis. Asset loading may supply these values, and callers may override them for generated or animated geometry. Read-only. Exposes a local-space mesh bounding sphere. The center uses mesh-local coordinates and radius defaults to one world unit.

record tecs.gfx.Bounds3D is Component
    centerX: number
    centerY: number
    centerZ: number
    radius: number
end

Interfaces#

tecs.gfx.Bounds3D.centerX field#

Caller-writable. Sets the local-space sphere-center x coordinate.

tecs.gfx.Bounds3D.centerX: number

tecs.gfx.Bounds3D.centerY field#

Caller-writable. Sets the local-space sphere-center y coordinate.

tecs.gfx.Bounds3D.centerY: number

tecs.gfx.Bounds3D.centerZ field#

Caller-writable. Sets the local-space sphere-center z coordinate.

tecs.gfx.Bounds3D.centerZ: number

tecs.gfx.Bounds3D.radius field#

Caller-writable. Sets the non-negative local-space sphere radius.

tecs.gfx.Bounds3D.radius: number

tecs.gfx.Camera2D record#

Represents a view onto the world.

Assign every field directly, frame by frame. A renderer copies the values it draws from during extraction, so moving a camera afterwards affects the next frame, not the one in flight.

global record tecs.gfx.Camera2D
    record Options
        x: number
        y: number
        zoom: number
        rotation: number
    end

    x: number
    y: number
    zoom: number
    rotation: number

    newCamera2D: function(options: Camera2DOptions): Camera2D
    matrix: function(self, width: number, height: number): loader.CArray
    toScreen: function(
        self,
        worldX: number,
        worldY: number,
        width: number,
        height: number
    ): number, number
    toWorld: function(
        self,
        screenX: number,
        screenY: number,
        width: number,
        height: number
    ): number, number
    viewBounds: function(self, width: number, height: number): {number}
end

tecs.gfx.Camera2D.Options record#

Names the options accepted by newCamera2D so a game can annotate the table it passes without reaching into this file.

record tecs.gfx.Camera2D.Options
    x: number
    y: number
    zoom: number
    rotation: number
end

tecs.gfx.Camera2D.Options.x field

Caller-writable. Sets the center of the view in world units. Both values default to zero.

tecs.gfx.Camera2D.Options.x: number

tecs.gfx.Camera2D.Options.y field

Caller-writable. Sets the center of the view in world units. Both values default to zero.

tecs.gfx.Camera2D.Options.y: number

tecs.gfx.Camera2D.Options.zoom field

Caller-writable. Sets the zoom and defaults to one. Zero or less divides through in every method here and is not rejected.

tecs.gfx.Camera2D.Options.zoom: number

tecs.gfx.Camera2D.Options.rotation field

Caller-writable. Sets the rotation in radians and defaults to zero.

tecs.gfx.Camera2D.Options.rotation: number

tecs.gfx.Camera2D.x field#

Caller-writable. Sets the horizontal center of the view in world units.

tecs.gfx.Camera2D.x: number

tecs.gfx.Camera2D.y field#

Caller-writable. Sets the vertical center of the view in world units. Increasing y moves the view towards the bottom of the world.

tecs.gfx.Camera2D.y: number

tecs.gfx.Camera2D.zoom field#

Caller-writable. Sets the zoom. Values above one magnify about the center without moving the point under the middle of the window.

tecs.gfx.Camera2D.zoom: number

tecs.gfx.Camera2D.rotation field#

Caller-writable. Sets the rotation in radians. Positive values turn the scene counter-clockwise on screen.

tecs.gfx.Camera2D.rotation: number

tecs.gfx.Camera2D.newCamera2D Static#

Creates a camera. Everything defaults to an unrotated, unzoomed view at the world origin, which a renderer then recenters if the game never moves it.

function tecs.gfx.Camera2D.newCamera2D(
    options: Camera2DOptions
): Camera2D

Arguments

Returns

tecs.gfx.Camera2D:matrix Instance#

Writes the world-to-clip matrix for a viewport of width by height.

Column major, because that is how a GLSL mat4 reads a uniform: the first four floats are the first column, not the first row. Transposing these is a mistake that renders something plausible rather than nothing, which is how it survives review.

function tecs.gfx.Camera2D.matrix(
    self, width: number, height: number
): loader.CArray

Arguments

Returns

tecs.gfx.Camera2D:toScreen Instance#

Converts a world point to screen space.

Exactly the inverse of toWorld at the same width and height, and the same mapping the matrix applies, so a point round-trips.

function tecs.gfx.Camera2D.toScreen(
    self, worldX: number, worldY: number, width: number, height: number
): number, number

Arguments

Returns

tecs.gfx.Camera2D:toWorld Instance#

Converts a screen point to world space.

The inverse of what the matrix does, written out rather than inverted, so the Y flip appears once here in the same place it appears above.

function tecs.gfx.Camera2D.toWorld(
    self,
    screenX: number,
    screenY: number,
    width: number,
    height: number
): number, number

Arguments

Returns

tecs.gfx.Camera2D:viewBounds Instance#

Returns the world-space rectangle this camera can see as minX, minY, maxX, and maxY.

When rotated, an axis-aligned box encloses the view's corners, so culling keeps a little more than it must. Keeping too much costs a few instances; keeping too little drops geometry that should have drawn, which is why the error goes this way.

function tecs.gfx.Camera2D.viewBounds(
    self, width: number, height: number
): {number}

Arguments

Returns

tecs.gfx.Camera3D record#

Represents one perspective view into a right-handed 3D world.

global record tecs.gfx.Camera3D
    record Options
        x: number
        y: number
        z: number
        rotationX: number
        rotationY: number
        rotationZ: number
        rotationW: number
        verticalFov: number
        near: number
        far: number
    end

    x: number
    y: number
    z: number
    rotationX: number
    rotationY: number
    rotationZ: number
    rotationW: number
    verticalFov: number
    near: number
    far: number

    newCamera3D: function(options: Camera3DOptions): Camera3D
    inverseMatrix: function(
        self, width: number, height: number
    ): loader.CArray
    matrices: function(
        self, width: number, height: number
    ): loader.CArray, loader.CArray
    matrix: function(self, width: number, height: number): loader.CArray
end

tecs.gfx.Camera3D.Options record#

Names the options accepted by newCamera3D.

record tecs.gfx.Camera3D.Options
    x: number
    y: number
    z: number
    rotationX: number
    rotationY: number
    rotationZ: number
    rotationW: number
    verticalFov: number
    near: number
    far: number
end

tecs.gfx.Camera3D.Options.x field

Caller-writable. Sets the world-space x coordinate and defaults to zero.

tecs.gfx.Camera3D.Options.x: number

tecs.gfx.Camera3D.Options.y field

Caller-writable. Sets the world-space y coordinate and defaults to zero.

tecs.gfx.Camera3D.Options.y: number

tecs.gfx.Camera3D.Options.z field

Caller-writable. Sets the world-space z coordinate and defaults to zero.

tecs.gfx.Camera3D.Options.z: number

tecs.gfx.Camera3D.Options.rotationX field

Caller-writable. Sets the orientation quaternion x component and defaults to zero.

tecs.gfx.Camera3D.Options.rotationX: number

tecs.gfx.Camera3D.Options.rotationY field

Caller-writable. Sets the orientation quaternion y component and defaults to zero.

tecs.gfx.Camera3D.Options.rotationY: number

tecs.gfx.Camera3D.Options.rotationZ field

Caller-writable. Sets the orientation quaternion z component and defaults to zero.

tecs.gfx.Camera3D.Options.rotationZ: number

tecs.gfx.Camera3D.Options.rotationW field

Caller-writable. Sets the orientation quaternion scalar component and defaults to one.

tecs.gfx.Camera3D.Options.rotationW: number

tecs.gfx.Camera3D.Options.verticalFov field

Caller-writable. Sets the vertical field of view in radians and defaults to pi divided by three.

tecs.gfx.Camera3D.Options.verticalFov: number

tecs.gfx.Camera3D.Options.near field

Caller-writable. Sets the positive near-plane distance and defaults to 0.1 world units.

tecs.gfx.Camera3D.Options.near: number

tecs.gfx.Camera3D.Options.far field

Caller-writable. Sets the far-plane distance and defaults to 1000 world units.

tecs.gfx.Camera3D.Options.far: number

tecs.gfx.Camera3D.x field#

Caller-writable. Sets the world-space x coordinate.

tecs.gfx.Camera3D.x: number

tecs.gfx.Camera3D.y field#

Caller-writable. Sets the world-space y coordinate.

tecs.gfx.Camera3D.y: number

tecs.gfx.Camera3D.z field#

Caller-writable. Sets the world-space z coordinate.

tecs.gfx.Camera3D.z: number

tecs.gfx.Camera3D.rotationX field#

Caller-writable. Sets the local-to-world orientation quaternion x component.

tecs.gfx.Camera3D.rotationX: number

tecs.gfx.Camera3D.rotationY field#

Caller-writable. Sets the local-to-world orientation quaternion y component.

tecs.gfx.Camera3D.rotationY: number

tecs.gfx.Camera3D.rotationZ field#

Caller-writable. Sets the local-to-world orientation quaternion z component.

tecs.gfx.Camera3D.rotationZ: number

tecs.gfx.Camera3D.rotationW field#

Caller-writable. Sets the local-to-world orientation quaternion scalar component.

tecs.gfx.Camera3D.rotationW: number

tecs.gfx.Camera3D.verticalFov field#

Caller-writable. Sets the vertical field of view in radians between zero and pi.

tecs.gfx.Camera3D.verticalFov: number

tecs.gfx.Camera3D.near field#

Caller-writable. Sets the positive near-plane distance.

tecs.gfx.Camera3D.near: number

tecs.gfx.Camera3D.far field#

Caller-writable. Sets the far-plane distance, which must exceed near.

tecs.gfx.Camera3D.far: number

tecs.gfx.Camera3D.newCamera3D Static#

Creates a perspective camera.

function tecs.gfx.Camera3D.newCamera3D(
    options: Camera3DOptions
): Camera3D

Arguments

Returns

tecs.gfx.Camera3D:inverseMatrix Instance#

Writes the column-major clip-to-world matrix for a viewport.

This is the exact inverse of matrix at the same dimensions. Clip x and y range from negative one to one, clip z ranges from zero to one, and the caller divides the resulting xyz by w.

function tecs.gfx.Camera3D.inverseMatrix(
    self, width: number, height: number
): loader.CArray

Arguments

Returns

tecs.gfx.Camera3D:matrices Instance#

Writes the world-to-clip matrix and its clip-to-world inverse.

This method normalizes the camera quaternion and derives the projection once, then writes both arrays. Use it when both matrices describe the same view.

function tecs.gfx.Camera3D.matrices(
    self, width: number, height: number
): loader.CArray, loader.CArray

Arguments

Returns

tecs.gfx.Camera3D:matrix Instance#

Writes the column-major world-to-clip matrix for a viewport.

The method normalizes the camera quaternion while calculating the view, without modifying the caller's fields. Clip depth maps near to zero and far to one.

function tecs.gfx.Camera3D.matrix(
    self, width: number, height: number
): loader.CArray

Arguments

Returns

tecs.gfx.Clip record#

Restricts a renderable's fragments to a clip region.

A component rather than a field on something every renderable has, because presence is the opt-in and absence is the common case. Archetypes without this column skip clipping, and their fragments never read the region table.

The index names a rectangle set with renderer.sprites:setClipRegion. Zero, which is the default, means no clipping. Nesting is the caller's: a region is one rectangle, so a panel inside a panel is set up as the intersection of the two rather than as two regions an instance sits in at once. Read-only. Exposes the clip component, which keeps a renderable's fragments inside one rectangle. index names a region set with renderer.sprites:setClipRegion, and 0, the default, means no clipping. A region is a single rectangle, so the caller intersects nested regions.

record tecs.gfx.Clip is Component
    index: number
end

Interfaces#

tecs.gfx.Clip.index field#

Caller-writable. Selects a clip region configured with renderer.sprites:setClipRegion. Zero disables clipping.

tecs.gfx.Clip.index: number

tecs.gfx.DropShadow2D record#

Casts a stretched copy of the entity along the ground, away from light.

This darkens everything a light left, including ambient light, which Occluder2D cannot do. It blocks no light in return: a crowd of light-blocking silhouettes merges under the mask into one flat mat of darkness, so the thing that wants a contact shadow is exactly the thing that must not be an occluder. An entity carrying both is an occluder, because dropping that half would silently unblock a light.

The nearest few lights by weight throw the copy. Adding a distant light does not move an established shadow. Read-only. Exposes the drop-shadow component, which darkens the ground away from each nearby light, including ambient light, without blocking light. height is 0 to 1 and controls the copy's travel under the same interpretation as Occluder2D.height.

record tecs.gfx.DropShadow2D is Component
    height: number
end

Interfaces#

tecs.gfx.DropShadow2D.height field#

Caller-writable. Sets how far lights throw the shadow, from zero to one of the world's configured shadow height.

tecs.gfx.DropShadow2D.height: number

tecs.gfx.Font record#

Represents a loaded font named by Text.

record tecs.gfx.Font
    name: string
    source: string
    size: number
    raster: FontRaster
end

tecs.gfx.Font.name field#

Read-only. Reports the caller-selected identity that snapshots store.

tecs.gfx.Font.name: string

tecs.gfx.Font.source field#

Read-only. Reports the source path passed to newTTF.

tecs.gfx.Font.source: string

tecs.gfx.Font.size field#

Read-only. Reports the point size at which SDL_ttf rasterizes glyphs.

tecs.gfx.Font.size: number

tecs.gfx.Font.raster field#

Read-only. Reports whether glyph images contain a scalable distance field or direct alpha coverage.

tecs.gfx.Font.raster: FontRaster

tecs.gfx.FontRaster enum#

Selects a font's glyph raster representation.

enum tecs.gfx.FontRaster
    "alpha"
    "sdf"
end

tecs.gfx.Material record#

Selects the material that shades renderable geometry.

Absent means the default 2D material. It samples the sprite image array and covers the whole quad, so an entity with neither a Sprite nor a Material still draws. Present selects one of the compiled shader materials found under materials/.

Use materials.id(name) instead of writing an id. Sorted material names determine ids, so adding a file may renumber them. Snapshots therefore store only the material name.

Meshes use MeshMaterial, whose resident PBR data is independent from this compiled 2D shader identity. Read-only. Exposes the compiled 2D shader material component. Absent selects the default material. Take id from materials.id(name) rather than writing a number because sorted material names determine ids and may move when a file appears. Meshes use MeshMaterial.

record tecs.gfx.Material is Component
    id: number
    param: number
end

Interfaces#

tecs.gfx.Material.id field#

Caller-writable. Selects a material by the id returned from materials.id.

tecs.gfx.Material.id: number

tecs.gfx.Material.param field#

Caller-writable. Passes a value from zero to one to the material. The material's business; the rounded rectangle reads it as a corner radius.

tecs.gfx.Material.param: number

tecs.gfx.Mesh record#

Selects immutable geometry for the 3D mesh domain.

asset is the process-local index returned by meshId. slot is engine-owned residency state and starts negative so a mesh domain can resolve it once. Snapshots store only the normalized asset name. Read-only. Exposes the mesh-reference component. asset is a process-local meshId and zero means no mesh. slot is engine-owned residency state and a negative value means unresolved.

record tecs.gfx.Mesh is Component
    asset: number
    slot: number
end

Interfaces#

tecs.gfx.Mesh.asset field#

Caller-writable. Selects geometry by its meshId index. Zero selects no mesh.

tecs.gfx.Mesh.asset: number

tecs.gfx.Mesh.slot field#

Engine-owned. Stores the mesh domain's residency slot. Set it negative when changing asset; otherwise ordinary game code should ignore it.

tecs.gfx.Mesh.slot: number

tecs.gfx.MeshMaterial record#

Selects resident PBR data for the 3D mesh domain.

A compiled 2D Material and a loaded glTF material are different compatibility surfaces. asset therefore names a mesh material independently, while slot is engine-owned device residency. Zero in both fields selects the neutral built-in material. Read-only. Exposes the 3D material-reference component. asset is a process-local meshMaterialId; slot is engine-owned residency, and zero selects the neutral built-in material.

record tecs.gfx.MeshMaterial is Component
    asset: number
    slot: number
end

Interfaces#

tecs.gfx.MeshMaterial.asset field#

Caller-writable. Selects material data by its meshMaterialId index. Zero selects the neutral built-in material.

tecs.gfx.MeshMaterial.asset: number

tecs.gfx.MeshMaterial.slot field#

Engine-owned. Stores the mesh domain's resident material slot. Set it negative when changing asset; otherwise game code should ignore it.

tecs.gfx.MeshMaterial.slot: number

tecs.gfx.MeshMorph record#

Selects one resident morph-weight vector for GPU mesh deformation.

asset is the stable name's process-local identity. slot is the first weight in domain residency and starts negative so extraction can resolve it once. The component is optional; a morphed mesh without it uses its undeformed base geometry. Read-only. Exposes the optional morph-weight component. asset is a process-local meshMorphId; slot is engine-owned residency, and a negative value means unresolved.

record tecs.gfx.MeshMorph is Component
    asset: number
    slot: number
end

Interfaces#

tecs.gfx.MeshMorph.asset field#

Caller-writable. Selects weights by their meshMorphId index. Zero selects no morph weights.

tecs.gfx.MeshMorph.asset: number

tecs.gfx.MeshMorph.slot field#

Engine-owned. Stores the first resident weight. Set it negative when changing asset; otherwise ordinary game code should ignore it.

tecs.gfx.MeshMorph.slot: number

tecs.gfx.MeshSkin record#

Selects one resident joint palette for GPU mesh skinning.

asset is the stable name's process-local identity. slot is the first joint matrix in domain residency and starts negative so extraction can resolve it once. The component is optional; a mesh without it remains rigid even when its domain enables skinning. Read-only. Exposes the optional joint-palette component. asset is a process-local meshSkinId; slot is engine-owned residency, and a negative value means unresolved.

record tecs.gfx.MeshSkin is Component
    asset: number
    slot: number
end

Interfaces#

tecs.gfx.MeshSkin.asset field#

Caller-writable. Selects a palette by its meshSkinId index. Zero selects no palette.

tecs.gfx.MeshSkin.asset: number

tecs.gfx.MeshSkin.slot field#

Engine-owned. Stores the first resident joint matrix. Set it negative when changing asset; otherwise ordinary game code should ignore it.

tecs.gfx.MeshSkin.slot: number

tecs.gfx.ModelOwner interface#

global interface tecs.gfx.ModelOwner
    path: string
    animations: {assets.ModelAnimation}
    animationCount: integer

    animationIndex: function(self, name: string): integer
end

tecs.gfx.ModelOwner.path field#

Read-only. Contains the source asset path.

tecs.gfx.ModelOwner.path: string

tecs.gfx.ModelOwner.animations field#

Read-only. Contains decoded clips in file order.

tecs.gfx.ModelOwner.animations: {assets.ModelAnimation}

tecs.gfx.ModelOwner.animationCount field#

Read-only. Reports the number of decoded clips.

tecs.gfx.ModelOwner.animationCount: integer

tecs.gfx.ModelOwner:animationIndex Instance#

Returns a clip's one-based index.

function tecs.gfx.ModelOwner.animationIndex(self, name: string): integer

Arguments

Returns

tecs.gfx.Occluder2D record#

Blocks light from reaching what lies behind the entity.

The renderer adds the silhouette to the occluder mask every light samples, so one entity blocks every light at the cost of one drawing of itself rather than one per light. It blocks each light's contribution, not ambient light. DropShadow2D handles ambient darkening.

Coverage is the silhouette, so a circle, a rounded box or a glyph casts the shape it draws with no threshold of its own to set. A translucent entity casts nothing: it is drawn forward over the composited image and never reaches the G-buffer, so a hard silhouette of it would be a lie. Read-only. Exposes the occluder component, which blocks every light with the entity's shape. height is 0 to 1 of the world height Deferred.shadowHeight sets, so 1 is a full wall and 0 blocks nothing. This component requires renderer shadows.

record tecs.gfx.Occluder2D is Component
    height: number
end

Interfaces#

tecs.gfx.Occluder2D.height field#

Caller-writable. Sets the occluder height from zero to one of the world's configured shadow height.

tecs.gfx.Occluder2D.height: number

tecs.gfx.PointLight2D record#

Represents a light resolved by the deferred lighting pass. Read-only. Exposes the point-light component resolved by deferred lighting and positioned by the entity's Transform2D. height is above the surface plane and at 0 the light contributes nothing at all; radius is its reach in world units; r, g, b and intensity default to white at 1.

record tecs.gfx.PointLight2D is Component
    height: number
    radius: number
    r: number
    g: number
    b: number
    intensity: number
end

Interfaces#

tecs.gfx.PointLight2D.height field#

Caller-writable. Sets the height above the surface plane. At zero, the Lambert term vanishes and the light contributes nothing.

tecs.gfx.PointLight2D.height: number

tecs.gfx.PointLight2D.radius field#

Caller-writable. Sets the light's reach in world units.

tecs.gfx.PointLight2D.radius: number

tecs.gfx.PointLight2D.r field#

Caller-writable. Sets the red channel from zero to one.

tecs.gfx.PointLight2D.r: number

tecs.gfx.PointLight2D.g field#

Caller-writable. Sets the green channel from zero to one.

tecs.gfx.PointLight2D.g: number

tecs.gfx.PointLight2D.b field#

Caller-writable. Sets the blue channel from zero to one.

tecs.gfx.PointLight2D.b: number

tecs.gfx.PointLight2D.intensity field#

Caller-writable. Scales the light's contribution.

tecs.gfx.PointLight2D.intensity: number

tecs.gfx.PointLight3D record#

Represents an omnidirectional light in the 3D mesh domain. Read-only. Exposes an omnidirectional mesh light positioned by the entity's tecs.Transform3D. The mesh domain must enable lights.

record tecs.gfx.PointLight3D is Component
    radius: number
    r: number
    g: number
    b: number
    intensity: number
    flags: integer
end

Interfaces#

tecs.gfx.PointLight3D.radius field#

Caller-writable. Sets the light's positive reach in world units.

tecs.gfx.PointLight3D.radius: number

tecs.gfx.PointLight3D.r field#

Caller-writable. Sets non-negative red radiance.

tecs.gfx.PointLight3D.r: number

tecs.gfx.PointLight3D.g field#

Caller-writable. Sets non-negative green radiance.

tecs.gfx.PointLight3D.g: number

tecs.gfx.PointLight3D.b field#

Caller-writable. Sets non-negative blue radiance.

tecs.gfx.PointLight3D.b: number

tecs.gfx.PointLight3D.intensity field#

Caller-writable. Scales the light's non-negative radiance.

tecs.gfx.PointLight3D.intensity: number

tecs.gfx.PointLight3D.flags field#

Caller-writable. Combines LIGHT_* integer constants. Zero, the default, keeps the light out of the optional local-shadow atlas.

tecs.gfx.PointLight3D.flags: integer

tecs.gfx.PreviousTransform2D record#

Stores the transform as it stood before the current fixed step.

Presence is the opt-in: an entity carrying it is drawn somewhere between this and its current transform, according to how far through the step the frame falls. Simulation advances in fixed jumps and frames arrive whenever the display asks for one, so without this an entity moved by physics steps visibly rather than moving.

Only the fields that move continuously are here. Scale and layer change by assignment rather than by integration, and a half-applied assignment is not a value anything asked for. Read-only. Exposes the transform component used for frame interpolation. Presence is the opt-in to interpolation: an entity carrying it is drawn between this and its current transform, so physics does not step visibly. Carries x, y and rotation (radians) only, because scale and layer change by assignment rather than by integration.

record tecs.gfx.PreviousTransform2D is Component
    x: number
    y: number
    rotation: number
end

Interfaces#

tecs.gfx.PreviousTransform2D.x field#

Engine-owned. Stores the previous horizontal position for frame interpolation. Ordinary game code should ignore this field.

tecs.gfx.PreviousTransform2D.x: number

tecs.gfx.PreviousTransform2D.y field#

Engine-owned. Stores the previous vertical position for frame interpolation. Ordinary game code should ignore this field.

tecs.gfx.PreviousTransform2D.y: number

tecs.gfx.PreviousTransform2D.rotation field#

Engine-owned. Stores the previous rotation in radians for frame interpolation. Ordinary game code should ignore this field.

tecs.gfx.PreviousTransform2D.rotation: number

tecs.gfx.Renderable2D record#

Marks an entity as contributing geometry. Without it, a Transform2D represents only a position. Read-only. Exposes the renderable tag, which marks an entity as contributing geometry. The tag costs a column of nothing; without it a Transform2D is only a position, which is what most entities in a world are.

record tecs.gfx.Renderable2D is Component
end

Interfaces#

tecs.gfx.Renderable3D record#

Marks an entity as contributing geometry to the 3D mesh domain. Without it, a tecs.Transform3D and Mesh describe state but enter no render query. Read-only. Exposes the tag that admits an entity carrying tecs.Transform3D, Mesh, and Bounds3D to the mesh domain.

record tecs.gfx.Renderable3D is Component
end

Interfaces#

tecs.gfx.Renderer record#

global record tecs.gfx.Renderer
    record Options
        ambient: {number}
        shadows: Deferred.ShadowOptions
        sprites: SpriteDomainModule.Options | boolean
        meshes: MeshDomainModule.Options
        bloom: Deferred.BloomOptions
        maxViews: integer
    end

    interface DomainStats
        count: integer
        dropped: integer
        rewritten: integer

        extractSeconds: function(self): number
    end

    interface SpriteDomain is DomainStats
        camera: Camera2D
        capacity: integer
        images: TextureArray
        instances: Buffer

        addComputeStage: function(self, stage: ComputeStage)
        addProducer: function(self, producer: InstanceProducer)
        clearClipRegion: function(self, index: integer)
        regionOf: function(self, path: string): TextureArray.Region
        registerImage: function(self, decoded: assets.Image): components.Sprite, TextureArray.Region
        replaceImage: function(self, decoded: assets.Image): components.Sprite, TextureArray.Region
        reservesRuns: function(self): boolean
        setClipRegion: function(self, index: integer, region: ClipRegion)
        sprite: function(self, name: string, u0: number, v0: number, u1: number, v1: number): components.Sprite
        spriteSize: function(self, sprite: components.Sprite): number, number
    end

    record SpriteOptions
        capacity: integer
        cell: integer
        layers: integer
        reserveRuns: boolean
        partialRewrites: boolean
        packImages: boolean
    end

    record SpriteInstanceProducer
        destroy: function(InstanceProducer) | nil

        blended: function(self): integer
        casting: function(self): integer
        count: function(self): integer
        takeDirty: function(self): {integer}
        write: function(self, loader.CArray, loader.CArray, integer, integer, integer)
    end

    record SpriteClipRegion
        x: number
        y: number
        width: number
        height: number
    end

    record SpriteComputeStage
        active: function(self): boolean
        destroy: function(self)
        record: function(self, Frame, Buffer, Buffer)
    end

    interface MeshDomain is DomainStats
        record Options
            capacity: integer
            vertexCapacity: integer
            indexCapacity: integer
            materialCapacity: integer
            textureWidth: integer
            textureHeight: integer
            textureLayers: integer
            packTextures: boolean
            mipmaps: boolean
            textureFormat: integer
            transparency: boolean
            doubleSided: boolean
            shadows: MeshShadowOptions
            skinning: MeshSkinningOptions
            morphing: MeshMorphingOptions
            lights: MeshLightOptions
            vertexColors: boolean
            fog: MeshFogOptions
            probe: MeshProbeOptions
            environment: MeshEnvironmentOptions
            ssao: Deferred.SSAOOptions
        end

        record MaterialOptions
            name: string
            model: integer
            alphaMode: integer
            doubleSided: boolean
            baseColorTexture: integer
            normalTexture: integer
            metallicRoughnessTexture: integer
            occlusionTexture: integer
            emissiveTexture: integer
            alphaCutoff: number
            baseR: number
            baseG: number
            baseB: number
            baseA: number
            emissiveR: number
            emissiveG: number
            emissiveB: number
            metallic: number
            roughness: number
            normalScale: number
            occlusionStrength: number
        end

        record ShadowOptions is MeshShadowTuning
            scale: number
        end

        interface Shadow
            distance: number
            splitLambda: number
            splitBlend: number
            depthPadding: number
            directionX: number
            directionY: number
            directionZ: number
            r: number
            g: number
            b: number
            intensity: number
            strength: number
            bias: number
            softness: number
        end

        record SkinningOptions
            jointCapacity: integer
        end

        record MorphingOptions
            vertexCapacity: integer
            weightCapacity: integer
        end

        record LightOptions
            capacity: integer
            shadows: MeshLocalShadowOptions
        end

        record LocalShadowOptions
            capacity: integer
            size: integer
            bias: number
            softness: number
        end

        record FogOptions is MeshFogTuning
        end

        interface Fog
            start: number
            finish: number
            r: number
            g: number
            b: number
        end

        record ProbeOptions is MeshProbeTuning
        end

        interface Probe
            positiveX: {number}
            negativeX: {number}
            positiveY: {number}
            negativeY: {number}
            positiveZ: {number}
            negativeZ: {number}
            intensity: number
        end

        record EnvironmentOptions is MeshEnvironmentTuning
            size: integer
        end

        interface Environment
            intensity: number
            skyboxIntensity: number
            rotation: number
        end

        record EnvironmentFaces
            positiveX: assets.Image
            negativeX: assets.Image
            positiveY: assets.Image
            negativeY: assets.Image
            positiveZ: assets.Image
            negativeZ: assets.Image
        end

        type SSAOOptions = Deferred.SSAOOptions
        type SSAO = Deferred.SSAO
        record RegisteredPrimitive
            transform: ecs.Transform3D
            mesh: components.Mesh
            bounds: components.Bounds3D
            material: components.MeshMaterial
            skin: components.MeshSkin
            morph: components.MeshMorph
        end

        record Model3D is ModelOwner
            record Primitive
                transform: ecs.Transform3D
                mesh: components.Mesh
                bounds: components.Bounds3D
                material: components.MeshMaterial
                skin: components.MeshSkin
                morph: components.MeshMorph
            end

            record Instance
                primitives: {Primitive}
                transform: ecs.Transform3D
                animation: integer
                time: number
                speed: number
                loop: boolean
                playing: boolean

                bind: function(self, world: World, primitive: integer, entity: integer)
                play: function(self, animation: string | integer, options: PlayOptions)
                sample: function(self, animation: string | integer, time: number, loop: boolean)
                unbind: function(self, primitive: integer)
                update: function(self, dt: number)
            end

            record PlayOptions
                speed: number
                loop: boolean
                playing: boolean
            end

            animationIndex: function(self, name: string): integer
            newInstance: function(self): Instance
        end

        MATERIAL_METALLIC_ROUGHNESS: integer
        MATERIAL_UNLIT: integer
        MATERIAL_LAMBERT: integer
        ALPHA_OPAQUE: integer
        ALPHA_MASK: integer
        ALPHA_BLEND: integer
        TEXTURE_RGBA8: integer
        TEXTURE_BC3: integer
        camera: Camera3D
        capacity: integer
        vertexCapacity: integer
        indexCapacity: integer
        meshCount: integer
        vertexCount: integer
        indexCount: integer
        materialCount: integer
        textureCount: integer
        jointCount: integer
        morphVertexCount: integer
        morphWeightCount: integer
        transparency: boolean
        doubleSided: boolean
        mipmaps: boolean
        textureFormat: integer
        shadows: boolean
        skinning: boolean
        morphing: boolean
        localLights: boolean
        localShadows: boolean
        localShadowCount: integer
        lightCapacity: integer
        lightCount: integer
        vertexColors: boolean
        fogging: boolean
        probing: boolean
        environmentLighting: boolean
        environmentSize: integer
        environmentReady: boolean
        ssao: Deferred.SSAO
        shadow: MeshShadowTuning
        fog: MeshFogTuning
        probe: MeshProbeTuning
        environment: MeshEnvironmentTuning

        material: function(self, name: string): components.MeshMaterial
        mesh: function(self, name: string): components.Mesh, components.Bounds3D
        registerEnvironment: function(self, faces: MeshEnvironmentFaces)
        registerMaterial: function(self, options: MeshMaterialOptions): components.MeshMaterial
        registerMesh: function(self, mesh: assets.Mesh): components.Mesh, components.Bounds3D
        registerModel: function(self, model: assets.Model): Model3D
        registerMorph: function(self, name: string, weights: {number}): components.MeshMorph
        registerSkin: function(self, name: string, matrices: {number}): components.MeshSkin
        registerTexture: function(self, image: assets.Image): integer
        updateMorph: function(self, morph: components.MeshMorph, weights: {number})
        updateSkin: function(self, skin: components.MeshSkin, matrices: {number})
    end

    record MeshOptions
        capacity: integer
        vertexCapacity: integer
        indexCapacity: integer
        materialCapacity: integer
        textureWidth: integer
        textureHeight: integer
        textureLayers: integer
        packTextures: boolean
        mipmaps: boolean
        textureFormat: integer
        transparency: boolean
        doubleSided: boolean
        shadows: MeshShadowOptions
        skinning: MeshSkinningOptions
        morphing: MeshMorphingOptions
        lights: MeshLightOptions
        vertexColors: boolean
        fog: MeshFogOptions
        probe: MeshProbeOptions
        environment: MeshEnvironmentOptions
        ssao: Deferred.SSAOOptions
    end

    record BloomOptions
        scale: number
        threshold: number
        knee: number
        intensity: number
    end

    sprites: SpriteDomain
    meshes: MeshDomain
    deferred: Deferred

    newRenderer: function(device: loader.CPtr, swapchainFormat: integer, options: RendererOptions): Renderer
    captureTexture: function(self): Texture
    depthSortCollapse: function(self): number
    destroy: function(self)
    device: function(self): loader.CPtr
    extractSeconds: function(self): number
    install: function(self, world: types.World)
    rebuildPipelines: function(self)
    render: function(self, frame: Frame)
    saveScreenshot: function(self, path: string): boolean, string
    screenshot: function(self): string, string
end

tecs.gfx.Renderer.Options record#

record tecs.gfx.Renderer.Options
    ambient: {number}
    shadows: Deferred.ShadowOptions
    sprites: SpriteDomainModule.Options | boolean
    meshes: MeshDomainModule.Options
    bloom: Deferred.BloomOptions
    maxViews: integer
end

tecs.gfx.Renderer.Options.ambient field

Caller-writable. Sets ambient red, green, and blue and defaults to white.

tecs.gfx.Renderer.Options.ambient: {number}

tecs.gfx.Renderer.Options.shadows field

Caller-writable. Enables and configures 2D shadows. Nil disables them.

tecs.gfx.Renderer.Options.shadows: Deferred.ShadowOptions

tecs.gfx.Renderer.Options.sprites field

Caller-writable. Configures the 2D sprite rendering domain. False disables it; nil enables it with defaults.

tecs.gfx.Renderer.Options.sprites: SpriteDomainModule.Options | boolean

tecs.gfx.Renderer.Options.meshes field

Caller-writable. Configures and enables the 3D mesh rendering domain. Nil leaves every mesh module and allocation out of this renderer.

tecs.gfx.Renderer.Options.meshes: MeshDomainModule.Options

tecs.gfx.Renderer.Options.bloom field

Caller-writable. Enables and configures optional bloom. Nil omits its targets, pipelines, and passes.

tecs.gfx.Renderer.Options.bloom: Deferred.BloomOptions

tecs.gfx.Renderer.Options.maxViews field

Caller-writable. Enables View entities and sets their fixed ceiling. Omit to retain the original single full-frame camera path. Setting it allocates one forward intermediate shared by every view.

tecs.gfx.Renderer.Options.maxViews: integer

tecs.gfx.Renderer.DomainStats interface#

interface tecs.gfx.Renderer.DomainStats
    count: integer
    dropped: integer
    rewritten: integer

    extractSeconds: function(self): number
end

tecs.gfx.Renderer.DomainStats.count field

Read-only. Reports instances resident after the last extraction.

tecs.gfx.Renderer.DomainStats.count: integer

tecs.gfx.Renderer.DomainStats.dropped field

Read-only. Reports instances the last extraction could not fit.

tecs.gfx.Renderer.DomainStats.dropped: integer

tecs.gfx.Renderer.DomainStats.rewritten field

Read-only. Reports instances rewritten by the last extraction.

tecs.gfx.Renderer.DomainStats.rewritten: integer

tecs.gfx.Renderer.DomainStats:extractSeconds Instance

Returns the seconds consumed by the last extraction.

function tecs.gfx.Renderer.DomainStats.extractSeconds(self): number

Arguments

Returns

tecs.gfx.Renderer.SpriteDomain interface#

interface tecs.gfx.Renderer.SpriteDomain is DomainStats
    camera: Camera2D
    capacity: integer
    images: TextureArray
    instances: Buffer

    addComputeStage: function(self, stage: ComputeStage)
    addProducer: function(self, producer: InstanceProducer)
    clearClipRegion: function(self, index: integer)
    regionOf: function(self, path: string): TextureArray.Region
    registerImage: function(
        self, decoded: assets.Image
    ): components.Sprite, TextureArray.Region
    replaceImage: function(
        self, decoded: assets.Image
    ): components.Sprite, TextureArray.Region
    reservesRuns: function(self): boolean
    setClipRegion: function(self, index: integer, region: ClipRegion)
    sprite: function(
        self,
        name: string,
        u0: number,
        v0: number,
        u1: number,
        v1: number
    ): components.Sprite
    spriteSize: function(
        self, sprite: components.Sprite
    ): number, number
end

Interfaces

tecs.gfx.Renderer.SpriteDomain.camera field

Caller-writable. Controls the 2D view. The first drawable frame centers it on the viewport.

tecs.gfx.Renderer.SpriteDomain.camera: Camera2D

tecs.gfx.Renderer.SpriteDomain.capacity field

Read-only. Reports the instance capacity fixed at creation.

tecs.gfx.Renderer.SpriteDomain.capacity: integer

tecs.gfx.Renderer.SpriteDomain.images field

Read-only. Provides the sprite image array.

tecs.gfx.Renderer.SpriteDomain.images: TextureArray

tecs.gfx.Renderer.SpriteDomain.instances field

Engine-owned. Exposes sprite instances to custom compute stages. Ordinary game code should ignore it.

tecs.gfx.Renderer.SpriteDomain.instances: Buffer

tecs.gfx.Renderer.SpriteDomain:addComputeStage Instance

Adds a compute stage between staging flush and sprite culling.

function tecs.gfx.Renderer.SpriteDomain.addComputeStage(
    self, stage: ComputeStage
)

Arguments

Returns

None.

tecs.gfx.Renderer.SpriteDomain:addProducer Instance

Adds a retained instance producer after archetype instances.

function tecs.gfx.Renderer.SpriteDomain.addProducer(
    self, producer: InstanceProducer
)

Arguments

Returns

None.

tecs.gfx.Renderer.SpriteDomain:clearClipRegion Instance

Stops one clip-region index from clipping.

function tecs.gfx.Renderer.SpriteDomain.clearClipRegion(
    self, index: integer
)

Arguments

Returns

None.

tecs.gfx.Renderer.SpriteDomain:regionOf Instance

Returns the region occupied by a registered image.

function tecs.gfx.Renderer.SpriteDomain.regionOf(
    self, path: string
): TextureArray.Region

Arguments

Returns

tecs.gfx.Renderer.SpriteDomain:registerImage Instance

Uploads a decoded image and returns a sprite selecting the whole image.

The path identifies the image for this domain's lifetime. Re-registering it returns the existing region. The call releases valid decoded pixels.

function tecs.gfx.Renderer.SpriteDomain.registerImage(
    self, decoded: assets.Image
): components.Sprite, TextureArray.Region

Arguments

Returns

tecs.gfx.Renderer.SpriteDomain:replaceImage Instance

Uploads a decoded image over the one registered under its path.

The replacement keeps the registered layer and rectangle, so existing sprites keep their identity. Missing pixels, an unknown path, or a size change raises. The call releases valid decoded pixels.

function tecs.gfx.Renderer.SpriteDomain.replaceImage(
    self, decoded: assets.Image
): components.Sprite, TextureArray.Region

Arguments

Returns

tecs.gfx.Renderer.SpriteDomain:reservesRuns Instance

Returns whether archetype runs have room to grow.

function tecs.gfx.Renderer.SpriteDomain.reservesRuns(self): boolean

Arguments

Returns

tecs.gfx.Renderer.SpriteDomain:setClipRegion Instance

Assigns a clipping rectangle in target pixels.

function tecs.gfx.Renderer.SpriteDomain.setClipRegion(
    self, index: integer, region: ClipRegion
)

Arguments

Returns

None.

tecs.gfx.Renderer.SpriteDomain:sprite Instance

Returns a sprite for a registered image.

UVs are fractions of the image. Omitted values select the whole image. An unknown name raises.

function tecs.gfx.Renderer.SpriteDomain.sprite(
    self, name: string, u0: number, v0: number, u1: number, v1: number
): components.Sprite

Arguments

Returns

tecs.gfx.Renderer.SpriteDomain:spriteSize Instance

Returns a sprite's natural size in source-image pixels.

function tecs.gfx.Renderer.SpriteDomain.spriteSize(
    self, sprite: components.Sprite
): number, number

Arguments

Returns

tecs.gfx.Renderer.SpriteOptions record#

record tecs.gfx.Renderer.SpriteOptions
    capacity: integer
    cell: integer
    layers: integer
    reserveRuns: boolean
    partialRewrites: boolean
    packImages: boolean
end

tecs.gfx.Renderer.SpriteOptions.capacity field

Caller-writable. Sets the maximum resident sprite-instance count. Rows beyond this fixed ceiling are dropped instead of growing a buffer under a frame that may still read it.

tecs.gfx.Renderer.SpriteOptions.capacity: integer

tecs.gfx.Renderer.SpriteOptions.cell field

Caller-writable. Sets the image-array cell size in pixels.

tecs.gfx.Renderer.SpriteOptions.cell: integer

tecs.gfx.Renderer.SpriteOptions.layers field

Caller-writable. Sets the image-array layer count.

tecs.gfx.Renderer.SpriteOptions.layers: integer

tecs.gfx.Renderer.SpriteOptions.reserveRuns field

Caller-writable. Gives archetype runs room to grow without moving every later run. Defaults to false, which packs runs end to end.

tecs.gfx.Renderer.SpriteOptions.reserveRuns: boolean

tecs.gfx.Renderer.SpriteOptions.partialRewrites field

Caller-writable. Rewrites only structurally changed rows instead of a whole archetype run. Defaults to false.

tecs.gfx.Renderer.SpriteOptions.partialRewrites: boolean

tecs.gfx.Renderer.SpriteOptions.packImages field

Caller-writable. Packs many images into each array layer. Defaults to false, which gives each image its own layer.

tecs.gfx.Renderer.SpriteOptions.packImages: boolean

tecs.gfx.Renderer.SpriteInstanceProducer record#

Something that draws instances without owning entities.

Text is the reason this exists. A glyph is a textured quad like any other, but making each one an entity puts every glyph in the world into one archetype, so editing one string marks that column dirty and rewrites all of them; and spawning or despawning glyphs moves an archetype's length, which forces the whole scene to be laid out again. A producer sidesteps both: it is laid out as its own run, and it says which parts of that run changed.

It writes the same sixteen floats and four bounds floats every other instance carries, so culling, depth, layers and materials all apply to it without knowing it is not an entity.

record tecs.gfx.Renderer.SpriteInstanceProducer
    destroy: function(InstanceProducer) | nil

    blended: function(self): integer
    casting: function(self): integer
    count: function(self): integer
    takeDirty: function(self): {integer}
    write: function(
        self, loader.CArray, loader.CArray, integer, integer, integer
    )
end

tecs.gfx.Renderer.SpriteInstanceProducer.destroy field

Caller-writable. Releases work the producer owns. The renderer calls this at most once, before releasing the device resources its instances feed. The producer may omit it when it has nothing to release.

tecs.gfx.Renderer.SpriteInstanceProducer.destroy: function(InstanceProducer) | nil

tecs.gfx.Renderer.SpriteInstanceProducer:blended Instance

Instances of its run that may reach the forward pass.

Asked every sync, because the forward lane is skipped entirely on a frame nothing said was blended and a producer whose run holds blended instances would then not be drawn. A producer that never blends answers zero and costs one call.

An upper bound rather than a count, and deliberately: a producer whose instances are written by compute cannot know how many of them a frame actually has. Over-reporting runs a lane that finds less than it was told to expect, which is the safe direction; under-reporting drops the whole lane, which is not.

function tecs.gfx.Renderer.SpriteInstanceProducer.blended(self): integer

Arguments

Returns

tecs.gfx.Renderer.SpriteInstanceProducer:casting Instance

Caller-writable. Reports instances of its run that may reach the shadow lane.

This has the same upper-bound contract as blended: a CPU producer answers exactly, while a compute producer may conservatively report every slot that can carry a caster. Under-reporting would skip the lane and lose shadows; over-reporting only runs an empty compaction.

function tecs.gfx.Renderer.SpriteInstanceProducer.casting(self): integer

Arguments

Returns

tecs.gfx.Renderer.SpriteInstanceProducer:count Instance

Instances to reserve. Changing it moves the layout, so a producer that can avoid changing it should.

function tecs.gfx.Renderer.SpriteInstanceProducer.count(self): integer

Arguments

Returns

tecs.gfx.Renderer.SpriteInstanceProducer:takeDirty Instance

Sub-ranges written since the last sync, as flat one-based inclusive pairs, and cleared by returning them. Empty means nothing changed and the run is skipped.

function tecs.gfx.Renderer.SpriteInstanceProducer.takeDirty(
    self
): {integer}

Arguments

Returns

tecs.gfx.Renderer.SpriteInstanceProducer:write Instance

Writes instances first through last of its run. base is the instance index the run starts at, so instance first is written at base + first - 1.

function tecs.gfx.Renderer.SpriteInstanceProducer.write(
    self, loader.CArray, loader.CArray, integer, integer, integer
)

Arguments

Returns

None.

tecs.gfx.Renderer.SpriteClipRegion record#

A clip rectangle, in target pixels measured from the top left.

Screen space rather than world space, because that is what a fragment is tested in and what a scissor means: a panel occupies a part of the window whether its contents are placed by the camera, in screen pixels, or in virtual coordinates, and one rectangle is right for all three.

record tecs.gfx.Renderer.SpriteClipRegion
    x: number
    y: number
    width: number
    height: number
end