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, Tint, and Renderable3D describe an opaque mesh for the optional mesh domain. 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]. It reuses one sixteen-float array, so copy the result before retaining it across another call on the same camera.

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.

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.

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",
        }).value,
        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 a Future. 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#

Constructors#

tecs.gfx.newTTF Static#

Starts loading and opening a source font with SDL_ttf.

The file read happens on the asset worker. The future settles only after SDL_ttf has opened the bytes, selected the raster mode, and verified the requested point size.

function tecs.gfx.newTTF(options: TTFOptions): Future<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
    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: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.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.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: SpriteDomain.Options | boolean
        meshes: MeshDomain.Options
    end

    record SpriteDomain
        record Options
            capacity: integer
            cell: integer
            layers: integer
            reserveRuns: boolean
            partialRewrites: boolean
            packImages: boolean
        end

        record InstanceProducer
            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 ClipRegion
            x: number
            y: number
            width: number
            height: number
        end

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

        camera: Camera2D
        capacity: integer
        count: integer
        dropped: integer
        rewritten: 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

    record MeshDomain
        record Options
            capacity: integer
            vertexCapacity: integer
            indexCapacity: integer
            materialCapacity: integer
            textureWidth: integer
            textureHeight: integer
            textureLayers: integer
            packTextures: boolean
            transparency: boolean
        end

        record MaterialOptions
            name: string
            model: integer
            alphaMode: integer
            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 RegisteredPrimitive
            transform: ecs.Transform3D
            mesh: components.Mesh
            bounds: components.Bounds3D
            material: components.MeshMaterial
        end

        MATERIAL_METALLIC_ROUGHNESS: integer
        MATERIAL_UNLIT: integer
        ALPHA_OPAQUE: integer
        ALPHA_MASK: integer
        ALPHA_BLEND: integer
        camera: Camera3D
        capacity: integer
        vertexCapacity: integer
        indexCapacity: integer
        count: integer
        dropped: integer
        rewritten: integer
        meshCount: integer
        vertexCount: integer
        indexCount: integer
        materialCount: integer
        textureCount: integer
        transparency: boolean
        vertices: Buffer
        indices: Buffer
        instances: Buffer
        materials: Buffer

        material: function(self, name: string): components.MeshMaterial
        mesh: function(
            self, name: string
        ): components.Mesh, components.Bounds3D
        registerMaterial: function(
            self, options: MeshMaterialOptions
        ): components.MeshMaterial
        registerMesh: function(
            self, mesh: assets.Mesh
        ): components.Mesh, components.Bounds3D
        registerModel: function(
            self, model: assets.Model
        ): {RegisteredPrimitive}
        registerTexture: function(self, image: assets.Image): integer
    end

    record MeshOptions
        capacity: integer
        vertexCapacity: integer
        indexCapacity: integer
        materialCapacity: integer
        textureWidth: integer
        textureHeight: integer
        textureLayers: integer
        packTextures: boolean
        transparency: boolean
    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: SpriteDomain.Options | boolean
    meshes: MeshDomain.Options
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: SpriteDomain.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: MeshDomain.Options

tecs.gfx.Renderer.SpriteDomain record#

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

    record InstanceProducer
        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 ClipRegion
        x: number
        y: number
        width: number
        height: number
    end

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

    camera: Camera2D
    capacity: integer
    count: integer
    dropped: integer
    rewritten: 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

tecs.gfx.Renderer.SpriteDomain.Options record

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

tecs.gfx.Renderer.SpriteDomain.Options.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.SpriteDomain.Options.capacity: integer

tecs.gfx.Renderer.SpriteDomain.Options.cell field

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

tecs.gfx.Renderer.SpriteDomain.Options.cell: integer

tecs.gfx.Renderer.SpriteDomain.Options.layers field

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

tecs.gfx.Renderer.SpriteDomain.Options.layers: integer

tecs.gfx.Renderer.SpriteDomain.Options.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.SpriteDomain.Options.reserveRuns: boolean

tecs.gfx.Renderer.SpriteDomain.Options.partialRewrites field

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

tecs.gfx.Renderer.SpriteDomain.Options.partialRewrites: boolean

tecs.gfx.Renderer.SpriteDomain.Options.packImages field

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

tecs.gfx.Renderer.SpriteDomain.Options.packImages: boolean

tecs.gfx.Renderer.SpriteDomain.InstanceProducer 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.SpriteDomain.InstanceProducer
    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.SpriteDomain.InstanceProducer.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.SpriteDomain.InstanceProducer.destroy: function(InstanceProducer) | nil

tecs.gfx.Renderer.SpriteDomain.InstanceProducer: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.SpriteDomain.InstanceProducer.blended(
    self
): integer

Arguments

Returns

tecs.gfx.Renderer.SpriteDomain.InstanceProducer: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.SpriteDomain.InstanceProducer.casting(
    self
): integer

Arguments

Returns

tecs.gfx.Renderer.SpriteDomain.InstanceProducer:count Instance

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

function tecs.gfx.Renderer.SpriteDomain.InstanceProducer.count(
    self
): integer

Arguments

Returns

tecs.gfx.Renderer.SpriteDomain.InstanceProducer: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.SpriteDomain.InstanceProducer.takeDirty(
    self
): {integer}

Arguments

Returns

tecs.gfx.Renderer.SpriteDomain.InstanceProducer: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.SpriteDomain.InstanceProducer.write(
    self, loader.CArray, loader.CArray, integer, integer, integer
)

Arguments

Returns

None.

tecs.gfx.Renderer.SpriteDomain.ClipRegion 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.SpriteDomain.ClipRegion
    x: number
    y: number
    width: number
    height: number
end

tecs.gfx.Renderer.SpriteDomain.ClipRegion.x field

Caller-writable. Sets the left edge in target pixels.

tecs.gfx.Renderer.SpriteDomain.ClipRegion.x: number

tecs.gfx.Renderer.SpriteDomain.ClipRegion.y field

Caller-writable. Sets the top edge in target pixels.

tecs.gfx.Renderer.SpriteDomain.ClipRegion.y: number

tecs.gfx.Renderer.SpriteDomain.ClipRegion.width field

Caller-writable. Sets the width in target pixels.

tecs.gfx.Renderer.SpriteDomain.ClipRegion.width: number

tecs.gfx.Renderer.SpriteDomain.ClipRegion.height field

Caller-writable. Sets the height in target pixels.

tecs.gfx.Renderer.SpriteDomain.ClipRegion.height: number

tecs.gfx.Renderer.SpriteDomain.ComputeStage record

Something that writes instances with compute before the cull runs.

The pool a particle emitter draws from is the caller this exists for. Its contents outlive the frame, so it is not written through staging the way an archetype run is, and what it writes has to land before the mark pass reads the bounds beside it. A stage is recorded on the frame's command buffer between the staging flush and the cull, and SDL orders all three because each declares what it writes.

record tecs.gfx.Renderer.SpriteDomain.ComputeStage
    active: function(self): boolean
    destroy: function(self)
    record: function(self, Frame, Buffer, Buffer)
end

tecs.gfx.Renderer.SpriteDomain.ComputeStage:active Instance

Whether this stage has anything to record this frame.

Asked every frame rather than derived from a dirty bit, because the thing this exists for dirties nothing: an emitter's whole field moves every frame while the world holding it reports no change at all. There is no bit to read, so the stage has to publish the answer.

function tecs.gfx.Renderer.SpriteDomain.ComputeStage.active(
    self
): boolean

Arguments

Returns

tecs.gfx.Renderer.SpriteDomain.ComputeStage:destroy Instance

Releases what the stage owns, called when the backend is destroyed.

A stage's buffers and pipelines are built on the backend's device, so they cannot outlive it and nothing else is holding them: a world that installed a stage and then dropped its renderer would leak every one of them otherwise. Must be safe to call more than once.

function tecs.gfx.Renderer.SpriteDomain.ComputeStage.destroy(self)

Arguments

Returns

None.

tecs.gfx.Renderer.SpriteDomain.ComputeStage:record Instance

Records its dispatches onto frame's command buffer.

The instance and bounds buffers are handed over rather than reached for, because writing them is the whole point of being here and a stage that had to find them would be a stage that could find something else.

function tecs.gfx.Renderer.SpriteDomain.ComputeStage.record(
    self, Frame, Buffer, Buffer
)

Arguments

Returns

None.

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.count field

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

tecs.gfx.Renderer.SpriteDomain.count: integer

tecs.gfx.Renderer.SpriteDomain.dropped field

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

tecs.gfx.Renderer.SpriteDomain.dropped: integer

tecs.gfx.Renderer.SpriteDomain.rewritten field

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

tecs.gfx.Renderer.SpriteDomain.rewritten: 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

tecs.gfx.Renderer.SpriteClipRegion.x field

Caller-writable. Sets the left edge in target pixels.

tecs.gfx.Renderer.SpriteClipRegion.x: number

tecs.gfx.Renderer.SpriteClipRegion.y field

Caller-writable. Sets the top edge in target pixels.

tecs.gfx.Renderer.SpriteClipRegion.y: number

tecs.gfx.Renderer.SpriteClipRegion.width field

Caller-writable. Sets the width in target pixels.

tecs.gfx.Renderer.SpriteClipRegion.width: number

tecs.gfx.Renderer.SpriteClipRegion.height field

Caller-writable. Sets the height in target pixels.

tecs.gfx.Renderer.SpriteClipRegion.height: number

tecs.gfx.Renderer.SpriteComputeStage record#

Something that writes instances with compute before the cull runs.

The pool a particle emitter draws from is the caller this exists for. Its contents outlive the frame, so it is not written through staging the way an archetype run is, and what it writes has to land before the mark pass reads the bounds beside it. A stage is recorded on the frame's command buffer between the staging flush and the cull, and SDL orders all three because each declares what it writes.

record tecs.gfx.Renderer.SpriteComputeStage
    active: function(self): boolean
    destroy: function(self)
    record: function(self, Frame, Buffer, Buffer)
end

tecs.gfx.Renderer.SpriteComputeStage:active Instance

Whether this stage has anything to record this frame.

Asked every frame rather than derived from a dirty bit, because the thing this exists for dirties nothing: an emitter's whole field moves every frame while the world holding it reports no change at all. There is no bit to read, so the stage has to publish the answer.

function tecs.gfx.Renderer.SpriteComputeStage.active(self): boolean

Arguments

Returns

tecs.gfx.Renderer.SpriteComputeStage:destroy Instance

Releases what the stage owns, called when the backend is destroyed.

A stage's buffers and pipelines are built on the backend's device, so they cannot outlive it and nothing else is holding them: a world that installed a stage and then dropped its renderer would leak every one of them otherwise. Must be safe to call more than once.

function tecs.gfx.Renderer.SpriteComputeStage.destroy(self)

Arguments

Returns

None.

tecs.gfx.Renderer.SpriteComputeStage:record Instance

Records its dispatches onto frame's command buffer.

The instance and bounds buffers are handed over rather than reached for, because writing them is the whole point of being here and a stage that had to find them would be a stage that could find something else.

function tecs.gfx.Renderer.SpriteComputeStage.record(
    self, Frame, Buffer, Buffer
)

Arguments

Returns

None.

tecs.gfx.Renderer.MeshDomain record#

record tecs.gfx.Renderer.MeshDomain
    record Options
        capacity: integer
        vertexCapacity: integer
        indexCapacity: integer
        materialCapacity: integer
        textureWidth: integer
        textureHeight: integer
        textureLayers: integer
        packTextures: boolean
        transparency: boolean
    end

    record MaterialOptions
        name: string
        model: integer
        alphaMode: integer
        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 RegisteredPrimitive
        transform: ecs.Transform3D
        mesh: components.Mesh
        bounds: components.Bounds3D
        material: components.MeshMaterial
    end

    MATERIAL_METALLIC_ROUGHNESS: integer
    MATERIAL_UNLIT: integer
    ALPHA_OPAQUE: integer
    ALPHA_MASK: integer
    ALPHA_BLEND: integer
    camera: Camera3D
    capacity: integer
    vertexCapacity: integer
    indexCapacity: integer
    count: integer
    dropped: integer
    rewritten: integer
    meshCount: integer
    vertexCount: integer
    indexCount: integer
    materialCount: integer
    textureCount: integer
    transparency: boolean
    vertices: Buffer
    indices: Buffer
    instances: Buffer
    materials: Buffer

    material: function(self, name: string): components.MeshMaterial
    mesh: function(
        self, name: string
    ): components.Mesh, components.Bounds3D
    registerMaterial: function(
        self, options: MeshMaterialOptions
    ): components.MeshMaterial
    registerMesh: function(
        self, mesh: assets.Mesh
    ): components.Mesh, components.Bounds3D
    registerModel: function(
        self, model: assets.Model
    ): {RegisteredPrimitive}
    registerTexture: function(self, image: assets.Image): integer
end