Mesh

Description

High-level geometry container. A Mesh owns a list of vertices and optional instances. Internally it deduplicates vertices and always draws indexed and instanced (instance_count defaults to 1 when none are provided).

Vertex layouts are managed by the Shader. At render time, inputs declared in your shader’s vertex function (annotated with @location(N)) are derived from the source and matched by name and type to Mesh properties across both streams (instance first, then vertex).

Mapping is driven by shader reflection; there are no special-case names or reserved locations. The renderer matches attributes by explicit location if provided (instance first, then vertex), and otherwise by name.

If a required input cannot be found or its type does not match, rendering returns an error indicating the missing attribute or mismatch.

Example

Rust

use fragmentcolor::mesh::{Mesh, Vertex, VertexValue};

let mut mesh = Mesh::new();
mesh.add_vertex([0.0, 0.5, 0.0]);
mesh.add_vertex([-0.5, -0.5, 0.0]);
mesh.add_vertex([0.5, -0.5, 0.0]);

JavaScript

import { Mesh, Vertex } from "fragmentcolor";

const mesh = new Mesh();
mesh.addVertex([0.0, 0.5, 0.0]);
mesh.addVertex([-0.5, -0.5, 0.0]);
mesh.addVertex([0.5, -0.5, 0.0]);

Python

from fragmentcolor import Mesh, Vertex

mesh = Mesh()
mesh.add_vertex([0.0, 0.5, 0.0])
mesh.add_vertex([-0.5, -0.5, 0.0])
mesh.add_vertex([0.5, -0.5, 0.0])

Swift

import FragmentColor

let mesh = Mesh()
try mesh.addVertex([0.0, 0.5, 0.0])
try mesh.addVertex([-0.5, -0.5, 0.0])
try mesh.addVertex([0.5, -0.5, 0.0])

Kotlin

import org.fragmentcolor.*

val mesh = Mesh()
mesh.addVertex(Vertex(listOf(0.0f, 0.5f, 0.0f)))
mesh.addVertex(Vertex(listOf(-0.5f, -0.5f, 0.0f)))
mesh.addVertex(Vertex(listOf(0.5f, -0.5f, 0.0f)))

Methods

---

Mesh::new

Create an empty mesh. Add vertices with add_vertex (or add_vertices) and instances with add_instance, then attach the mesh to a shader to draw it.

Example

Rust

use fragmentcolor::mesh::Mesh;
let m = Mesh::new();
1 collapsed line
_ = m;

JavaScript

import { Mesh } from "fragmentcolor";
const m = new Mesh();

Python

from fragmentcolor import Mesh
m = Mesh()

Swift

import FragmentColor
let m = Mesh()

Kotlin

import org.fragmentcolor.*
val m = Mesh()

---

Mesh::from_vertices

Create a mesh from an iterator of Vertex values.

Example

Rust

use fragmentcolor::Mesh;

let mesh = Mesh::from_vertices([
  [0.0, 0.0],
  [1.0, 0.0],
  [0.0, 1.0],
]);

JavaScript

import { Mesh } from "fragmentcolor";

const mesh = Mesh.fromVertices([ [0.0, 0.0], [1.0, 0.0], [0.0, 1.0], ]);

Python

from fragmentcolor import Mesh

mesh = Mesh.from_vertices([
  [0.0, 0.0],
  [1.0, 0.0],
  [0.0, 1.0],
])

Swift

import FragmentColor

let mesh = try Mesh.fromVertices([
  [0.0, 0.0],
  [1.0, 0.0],
  [0.0, 1.0],
])

Kotlin

import org.fragmentcolor.*

val mesh = Mesh.fromVertices(listOf(Vertex(listOf(0.0f, 0.0f)), Vertex(listOf(1.0f, 0.0f)), Vertex(listOf(0.0f, 1.0f))))

---

Mesh::add_vertex

Append a single vertex to the mesh. Pass an array literal for the position ([x, y] or [x, y, z]); for vertices that carry uv, color, or other per-vertex attributes, build a Vertex first and pass it in.

Example

Rust

use fragmentcolor::mesh::{Mesh};
let mut m = Mesh::new();
m.add_vertex([0.0, 0.0]);

JavaScript

import { Mesh } from "fragmentcolor";
const m = new Mesh();
m.addVertex([0.0, 0.0]);

Python

from fragmentcolor import Mesh
m = Mesh()
m.add_vertex([0.0, 0.0])

Swift

import FragmentColor
let m = Mesh()
try m.addVertex([0.0, 0.0])

Kotlin

import org.fragmentcolor.*
val m = Mesh()
m.addVertex(Vertex(listOf(0.0f, 0.0f)))

---

Mesh::add_vertices

Add many vertices to the mesh.

Example

Rust

use fragmentcolor::mesh::Mesh;
let mut m = Mesh::new();
m.add_vertices([
[0.0, 0.0],
[1.0, 0.0],
]);

JavaScript

import { Mesh } from "fragmentcolor";
const m = new Mesh();
m.addVertices([ [0.0, 0.0], [1.0, 0.0], ]);

Python

from fragmentcolor import Mesh
m = Mesh()
m.add_vertices([
[0.0, 0.0],
[1.0, 0.0],
])

Swift

import FragmentColor
let m = Mesh()
try m.addVertices([
[0.0, 0.0],
[1.0, 0.0],
])

Kotlin

import org.fragmentcolor.*
val m = Mesh()
m.addVertices(listOf(Vertex(listOf(0.0f, 0.0f)), Vertex(listOf(1.0f, 0.0f))))

---

Mesh::add_instance

Add a single per-instance attribute set to the mesh.

An Instance is a bag of named attributes (transform, color, id, …) sent to the shader’s per-instance inputs. It carries no position — the mesh’s vertices are reused for every instance.

Adding an instance also clears any previously set instance count override (see Mesh::set_instance_count).

Example

Rust

use fragmentcolor::mesh::{Mesh, Instance};

let m = Mesh::new();
let offset: [f32; 2] = [0.25, 0.10];
let tint:   [f32; 4] = [1.0, 0.0, 0.0, 1.0];
m.add_instance(Instance::new().set("offset", offset).set("tint", tint));

JavaScript

import { Mesh, Instance } from "fragmentcolor";

const m = new Mesh();
const offset = [0.25, 0.10];
const tint = [1.0, 0.0, 0.0, 1.0];
m.addInstance(Instance.new().set("offset", offset).set("tint", tint));

Python

from fragmentcolor import Mesh, Instance

m = Mesh()
offset = [0.25, 0.10]
tint = [1.0, 0.0, 0.0, 1.0]
m.add_instance(Instance().set("offset", offset).set("tint", tint))

Swift

import FragmentColor

let m = Mesh()
let offset = [0.25, 0.10]
let tint = [1.0, 0.0, 0.0, 1.0]
try m.addInstance(Instance().set("offset", offset).set("tint", tint))

Kotlin

import org.fragmentcolor.*

val m = Mesh()
val offset = listOf(0.25f, 0.10f)
val tint = listOf(1.0f, 0.0f, 0.0f, 1.0f)
m.addInstance(Instance().set("offset", offset).set("tint", tint))

---

Mesh::add_instances

Add many per-instance attribute sets to the mesh in one call.

Each Instance is a bag of named attributes (transform, color, id, …) sent to the shader’s per-instance inputs. Instances carry no position — the mesh’s vertices are reused for every instance.

Adding instances also clears any previously set instance count override (see Mesh::set_instance_count).

Example

Rust

use fragmentcolor::mesh::{Mesh, Instance};

let m = Mesh::new();
let red:   [f32; 4] = [1.0, 0.0, 0.0, 1.0];
let green: [f32; 4] = [0.0, 1.0, 0.0, 1.0];
let blue:  [f32; 4] = [0.0, 0.0, 1.0, 1.0];
m.add_instances([
  Instance::new().set("tint", red),
  Instance::new().set("tint", green),
  Instance::new().set("tint", blue),
]);

JavaScript

import { Mesh, Instance } from "fragmentcolor";

const m = new Mesh();
const red = [1.0, 0.0, 0.0, 1.0];
const green = [0.0, 1.0, 0.0, 1.0];
const blue = [0.0, 0.0, 1.0, 1.0];
m.addInstances([ Instance.new().set("tint", red), Instance.new().set("tint", green), Instance.new().set("tint", blue), ]);

Python

from fragmentcolor import Mesh, Instance

m = Mesh()
red = [1.0, 0.0, 0.0, 1.0]
green = [0.0, 1.0, 0.0, 1.0]
blue = [0.0, 0.0, 1.0, 1.0]
m.add_instances([
  Instance().set("tint", red),
  Instance().set("tint", green),
  Instance().set("tint", blue),
])

Swift

import FragmentColor

let m = Mesh()
let red = [1.0, 0.0, 0.0, 1.0]
let green = [0.0, 1.0, 0.0, 1.0]
let blue = [0.0, 0.0, 1.0, 1.0]
m.addInstances([
  try Instance().set("tint", red),
  try Instance().set("tint", green),
  try Instance().set("tint", blue),
])

Kotlin

import org.fragmentcolor.*

val m = Mesh()
val red = listOf(1.0f, 0.0f, 0.0f, 1.0f)
val green = listOf(0.0f, 1.0f, 0.0f, 1.0f)
val blue = listOf(0.0f, 0.0f, 1.0f, 1.0f)
m.addInstances(listOf(Instance().set("tint", red), Instance().set("tint", green), Instance().set("tint", blue),))

---

Mesh::clear_instances

Reset the mesh’s instance state to the default (1 draw, no per-instance data).

Specifically, this:

• Drops any per-instance attributes added via add_instance / add_instances.
• Clears any count override previously set with set_instance_count.

After calling, the mesh renders as a single instance unless you populate it again or call set_instance_count.

Example

Rust

use fragmentcolor::mesh::{Mesh, Instance};

let m = Mesh::new();
let red: [f32; 4] = [1.0, 0.0, 0.0, 1.0];
m.add_instance(Instance::new().set("tint", red));
m.clear_instances(); // back to a single uninstanced draw

JavaScript

import { Mesh, Instance } from "fragmentcolor";

const m = new Mesh();
const red = [1.0, 0.0, 0.0, 1.0];
m.addInstance(Instance.new().set("tint", red));
m.clearInstances(); // back to a single uninstanced draw;

Python

from fragmentcolor import Mesh, Instance

m = Mesh()
red = [1.0, 0.0, 0.0, 1.0]
m.add_instance(Instance().set("tint", red))
m.clear_instances(); # back to a single uninstanced draw

Swift

import FragmentColor

let m = Mesh()
let red = [1.0, 0.0, 0.0, 1.0]
try m.addInstance(Instance().set("tint", red))
m.clearInstances(); // back to a single uninstanced draw

Kotlin

import org.fragmentcolor.*

val m = Mesh()
val red = listOf(1.0f, 0.0f, 0.0f, 1.0f)
m.addInstance(Instance().set("tint", red))
m.clearInstances(); // back to a single uninstanced draw

---

Mesh::set_instance_count

Override how many instances to draw without providing per-instance attributes.

Use this when driving instance data from a storage buffer and indexing via @builtin(instance_index) in the vertex shader — common for compute-driven simulations and large particle systems.

The override is automatically cleared if you later call add_instance / add_instances (those carry their own count) or clear_instances.

Example

Rust

use fragmentcolor::mesh::Mesh;
let mut m = Mesh::new();
m.add_vertices([
  [-0.01, -0.01],
  [ 0.01, -0.01],
  [ 0.00,  0.01],
]);
// Draw one million instances, fetching per-particle data from a storage buffer.
m.set_instance_count(1_000_000);

JavaScript

import { Mesh } from "fragmentcolor";
const m = new Mesh();
m.addVertices([ [-0.01, -0.01], [ 0.01, -0.01], [ 0.00,  0.01], ]);
// Draw one million instances, fetching per-particle data from a storage buffer.
m.setInstanceCount(1_000_000);

Python

from fragmentcolor import Mesh
m = Mesh()
m.add_vertices([
  [-0.01, -0.01],
  [ 0.01, -0.01],
  [ 0.00,  0.01],
])
# Draw one million instances, fetching per-particle data from a storage buffer.
m.set_instance_count(1_000_000)

Swift

import FragmentColor
let m = Mesh()
try m.addVertices([
  [-0.01, -0.01],
  [ 0.01, -0.01],
  [ 0.00,  0.01],
])
// Draw one million instances, fetching per-particle data from a storage buffer.
m.setInstanceCount(1_000_000)

Kotlin

import org.fragmentcolor.*
val m = Mesh()
m.addVertices(listOf(Vertex(listOf(-0.01f, -0.01f)), Vertex(listOf(0.01f, -0.01f)), Vertex(listOf(0.00f, 0.01f))))
// Draw one million instances, fetching per-particle data from a storage buffer.
m.setInstanceCount(1_000_000u)