---
title: 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)."
category: geometry
categoryLabel: Geometry
---

import { Code, Tabs, TabItem, Aside } from "@astrojs/starlight/components";

## 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

<Tabs>

<TabItem label="Rust">
<Code
code={`
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]);
`}
lang="rust"
/>

</TabItem>

<TabItem label="JavaScript">
<Code
code={`
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]);
`}
lang="js"
/>

</TabItem>

<TabItem label="Python">
<Code
code={`
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])
`}
lang="python"
/>

</TabItem>

<TabItem label="Swift">
<Aside type="caution" title="Work in progress">Swift bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Swift placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

<TabItem label="Kotlin">
<Aside type="caution" title="Work in progress">Kotlin/Android bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Kotlin placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

</Tabs>


## Methods


---

### Mesh::new

Create an empty mesh.

#### Example

<Tabs>

<TabItem label="Rust">
<Code
code={`
use fragmentcolor::mesh::Mesh;
let m = Mesh::new();
_ = m;
`}
lang="rust" meta="collapse={3-3}"
/>

</TabItem>

<TabItem label="JavaScript">
<Code
code={`
import { Mesh } from "fragmentcolor";
const m = new Mesh();
`}
lang="js"
/>

</TabItem>

<TabItem label="Python">
<Code
code={`
from fragmentcolor import Mesh
m = Mesh()
`}
lang="python"
/>

</TabItem>

<TabItem label="Swift">
<Aside type="caution" title="Work in progress">Swift bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Swift placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

<TabItem label="Kotlin">
<Aside type="caution" title="Work in progress">Kotlin/Android bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Kotlin placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

</Tabs>


---

### Mesh::from_vertices

Create a mesh from an iterator of Vertex values.

#### Example

<Tabs>

<TabItem label="Rust">
<Code
code={`
use fragmentcolor::Mesh;

let mesh = Mesh::from_vertices([
    [0.0, 0.0],
    [1.0, 0.0],
    [0.0, 1.0],
]);
`}
lang="rust"
/>

</TabItem>

<TabItem label="JavaScript">
<Code
code={`
import { Mesh } from "fragmentcolor";

const mesh = Mesh.fromVertices([
    [0.0, 0.0],
    [1.0, 0.0],
    [0.0, 1.0],
]);
`}
lang="js"
/>

</TabItem>

<TabItem label="Python">
<Code
code={`
from fragmentcolor import Mesh

mesh = Mesh.from_vertices([
    [0.0, 0.0],
    [1.0, 0.0],
    [0.0, 1.0],
])
`}
lang="python"
/>

</TabItem>

<TabItem label="Swift">
<Aside type="caution" title="Work in progress">Swift bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Swift placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

<TabItem label="Kotlin">
<Aside type="caution" title="Work in progress">Kotlin/Android bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Kotlin placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

</Tabs>


---

### Mesh::add_vertex

Add a single vertex to the mesh.

#### Example

<Tabs>

<TabItem label="Rust">
<Code
code={`
use fragmentcolor::mesh::{Mesh};
let mut m = Mesh::new();
m.add_vertex([0.0, 0.0]);
`}
lang="rust"
/>

</TabItem>

<TabItem label="JavaScript">
<Code
code={`
import { Mesh } from "fragmentcolor";
const m = new Mesh();
m.addVertex([0.0, 0.0]);
`}
lang="js"
/>

</TabItem>

<TabItem label="Python">
<Code
code={`
from fragmentcolor import Mesh
m = Mesh()
m.add_vertex([0.0, 0.0])
`}
lang="python"
/>

</TabItem>

<TabItem label="Swift">
<Aside type="caution" title="Work in progress">Swift bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Swift placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

<TabItem label="Kotlin">
<Aside type="caution" title="Work in progress">Kotlin/Android bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Kotlin placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

</Tabs>


---

### Mesh::add_vertices

Add many vertices to the mesh.

#### Example

<Tabs>

<TabItem label="Rust">
<Code
code={`
use fragmentcolor::mesh::Mesh;
let mut m = Mesh::new();
m.add_vertices([
  [0.0, 0.0],
  [1.0, 0.0],
]);
`}
lang="rust"
/>

</TabItem>

<TabItem label="JavaScript">
<Code
code={`
import { Mesh } from "fragmentcolor";
const m = new Mesh();
m.addVertices([
  [0.0, 0.0],
  [1.0, 0.0],
]);
`}
lang="js"
/>

</TabItem>

<TabItem label="Python">
<Code
code={`
from fragmentcolor import Mesh
m = Mesh()
m.add_vertices([
  [0.0, 0.0],
  [1.0, 0.0],
])
`}
lang="python"
/>

</TabItem>

<TabItem label="Swift">
<Aside type="caution" title="Work in progress">Swift bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Swift placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

<TabItem label="Kotlin">
<Aside type="caution" title="Work in progress">Kotlin/Android bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Kotlin placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

</Tabs>


---

### Mesh::add_instance

Add a single instance (any Vertex can be converted into an instance).

#### Example

<Tabs>

<TabItem label="Rust">
<Code
code={`
use fragmentcolor::mesh::{Mesh, Vertex};
let mut m = Mesh::new();
let v = Vertex::new([0.0, 0.0]);
m.add_instance(v);
`}
lang="rust"
/>

</TabItem>

<TabItem label="JavaScript">
<Code
code={`
import { Mesh, Vertex } from "fragmentcolor";
const m = new Mesh();
const v = new Vertex([0.0, 0.0]);
m.addInstance(v);
`}
lang="js"
/>

</TabItem>

<TabItem label="Python">
<Code
code={`
from fragmentcolor import Mesh, Vertex
m = Mesh()
v = Vertex([0.0, 0.0])
m.add_instance(v)
`}
lang="python"
/>

</TabItem>

<TabItem label="Swift">
<Aside type="caution" title="Work in progress">Swift bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Swift placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

<TabItem label="Kotlin">
<Aside type="caution" title="Work in progress">Kotlin/Android bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Kotlin placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

</Tabs>


---

### Mesh::add_instances

Add many instances to the mesh.

#### Example

<Tabs>

<TabItem label="Rust">
<Code
code={`
use fragmentcolor::mesh::{Mesh, Vertex};
let mut m = Mesh::new();
m.add_instances([
  Vertex::new([0.0, 0.0]),
  Vertex::new([1.0, 1.0]),
]);
`}
lang="rust"
/>

</TabItem>

<TabItem label="JavaScript">
<Code
code={`
import { Mesh, Vertex } from "fragmentcolor";
const m = new Mesh();
m.addInstances([
  Vertex.new([0.0, 0.0]),
  Vertex.new([1.0, 1.0]),
]);
`}
lang="js"
/>

</TabItem>

<TabItem label="Python">
<Code
code={`
from fragmentcolor import Mesh, Vertex
m = Mesh()
m.add_instances([
  Vertex([0.0, 0.0]),
  Vertex([1.0, 1.0]),
])
`}
lang="python"
/>

</TabItem>

<TabItem label="Swift">
<Aside type="caution" title="Work in progress">Swift bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Swift placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

<TabItem label="Kotlin">
<Aside type="caution" title="Work in progress">Kotlin/Android bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Kotlin placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

</Tabs>


---

### Mesh::clear_instances

Remove all instances from a mesh (render defaults to 1 instance).

#### Example

<Tabs>

<TabItem label="Rust">
<Code
code={`
use fragmentcolor::mesh::Mesh;
let mut m = Mesh::new();
m.clear_instances();
`}
lang="rust"
/>

</TabItem>

<TabItem label="JavaScript">
<Code
code={`
import { Mesh } from "fragmentcolor";
const m = new Mesh();
m.clearInstances();
`}
lang="js"
/>

</TabItem>

<TabItem label="Python">
<Code
code={`
from fragmentcolor import Mesh
m = Mesh()
m.clear_instances()
`}
lang="python"
/>

</TabItem>

<TabItem label="Swift">
<Aside type="caution" title="Work in progress">Swift bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Swift placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

<TabItem label="Kotlin">
<Aside type="caution" title="Work in progress">Kotlin/Android bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Kotlin placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

</Tabs>


---

### 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).

#### Example

<Tabs>

<TabItem label="Rust">
<Code
code={`
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
m.set_instance_count(1_000_000);
`}
lang="rust"
/>

</TabItem>

<TabItem label="JavaScript">
<Code
code={`
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
m.setInstanceCount(1_000_000);
`}
lang="js"
/>

</TabItem>

<TabItem label="Python">
<Code
code={`
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
m.set_instance_count(1_000_000)
`}
lang="python"
/>

</TabItem>

<TabItem label="Swift">
<Aside type="caution" title="Work in progress">Swift bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Swift placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

<TabItem label="Kotlin">
<Aside type="caution" title="Work in progress">Kotlin/Android bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Kotlin placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

</Tabs>


---

### Mesh::clear_instance_count

Remove all instances from a mesh (render defaults to 1 instance).

#### Example

<Tabs>

<TabItem label="Rust">
<Code
code={`
use fragmentcolor::mesh::Mesh;
let mut m = Mesh::new();
m.clear_instance_count();
`}
lang="rust"
/>

</TabItem>

<TabItem label="JavaScript">
<Code
code={`
import { Mesh } from "fragmentcolor";
const m = new Mesh();
m.clearInstanceCount();
`}
lang="js"
/>

</TabItem>

<TabItem label="Python">
<Code
code={`
from fragmentcolor import Mesh
m = Mesh()
m.clear_instance_count()
`}
lang="python"
/>

</TabItem>

<TabItem label="Swift">
<Aside type="caution" title="Work in progress">Swift bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Swift placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

<TabItem label="Kotlin">
<Aside type="caution" title="Work in progress">Kotlin/Android bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Kotlin placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

</Tabs>
