Mesh Reference - Primitive Types

<title>Mesh Reference - Primitive Types</title>

<warning>This page is work in progress</warning>

# Mesh Library References

These pages seek to provide helpful insight into the usage of the <page>Mesh</page> library and its functions.

The pages in this series are:
* **Primitive Types**

# Terms and Definitions

## What is a Primitive?

Definitionally, a Primitive is the simple shapes that any model (or "Mesh") is built from.  
Practically, a Primitive is a grouping of one or more vertices that the rendering system interprets together in order to draw a simple shape onto the currently active <page text="Render Target">render_rendertargets</page>.

As an example, the most common Primitive types are triangles (3 vertices), and quads (4 vertices).

## Vertex Winding

When defining a Primitive, the order of its vertices is very important for ensuring it draws as expected.  The rendering system does not perform **any** meaningful validation of the Primitive's information and instead simply draws whatever data it is provided.  Because of this, it is important to provide vertices in the order that the rendering system is expecting.

There are two ways of ordering verticies (Called "Windings"): **Clockwise** and **Counter-Clockwise** (or Anti-Clockwise, if preferred.)  

*Fun fact: They're called "Windings" because putting lines between vertices is conceptually similar to ***winding*** a rope or wire around a spool!*

<upload src="b2b4c/8dc9548bb80c0ee.png" size="176662" name="VertexWindings.png" />

## Culling

To save on unnecessary draw operations, the rendering system only draws Primitives (or "faces") that are facing generally towards the camera.  
The way that the rendering system determines which faces to draw and which faces not to draw is based on the vertex winding of the face in question.

If a face is wound counter-clockwise relative to the camera, it is assumed to be a "**front**" face (which is drawn), and if it is instead wound clockwise relative to the camera, it is considered a "**back**" face (Which is *not* drawn.)

This type of culling is often called "**back face culling**" and it is the major reason why vertex order is important when creating Meshes.

In rare cases, it may be necessary to temporarily override the normal winding order by using <page>render.CullMode</page> immediately before and after the rendering operation.

# Types of Primitive

## Points

The <page text="Points Primitive">Enums/MATERIAL#MATERIAL_POINTS</page> type (Also called a "Point List") interprets each of the Mesh's vertices as a standalone point in space.  
When rendered, each of these points appears as a single pixel.

<image src="b2b4c/8dcf911b5bddc93.png" size="11319" name="PrimitivePoints.png" />

<warning>
	The Point Primitive type is currently broken and will not produce any visual effect when rendered.

	It is included here for completeness.
</warning>

## Lines

The <page text="Lines Primitive">Enums/MATERIAL#MATERIAL_LINES</page> type (Also called a "Line List") interprets the Mesh's vertices in pairs of 2 where each pair of vertices represents the start and end points for a line.

Because each line requires a start and end point, the total number of vertices **must** be evenly divisible by 2.

<image src="b2b4c/8dcf915b28645be.png" size="12356" name="PrimitiveLines.png" />

<warning>
	The Lines Primitive type is currently broken and will not produce any visual effect when rendered.

	It is included here for completeness.
</warning>

## Triangles

As the names suggests, <page text="Triangle Primitives ">Enums/MATERIAL#MATERIAL_TRIANGLES</page> (Also called a "Triangle List") groups every 3 of the Mesh's vertices together and draws a textured triangle between them.

Because each triangle requires exactly 3 points, the Mesh's total vertex count must be a multiple of 3.

The direction the resulting triangle faces is determined by the current <page>render.CullMode</page> as well as the order that the vertices were added to the Mesh.

<image src="b2b4c/8dcf9b89dc6a6d5.png" size="39598" name="PrimitiveTriangles.png" />

## Triangle Strips

<page text="Triangle Strip Primitives">Enums/MATERIAL#MATERIAL_TRIANGLE_STRIP</page> are a convenience feature to make it easier to create sequences of  triangles that each share an edge with the previous triangle in the sequence.  

The first triangle in the sequence is created using the first 3 vertices added to the Mesh.  All subsequent triangles are created using just 1 additional vertex in addition to the final 2 vertices of the previous triangle in the sequence.

This method uses fewer total vertices than would be required to create them using the Triangles Primitive type, which makes it more performant than creating those same triangles individually.

### Example

<image src="b2b4c/8dcf9b9ee201c4e.png" size="22819" name="PrimitiveTriangleStrips.png" />

## Line Strips

The <page text="Line Strip Primitive">Enums/MATERIAL#MATERIAL_LINE_STRIP</page> type defines a sequence of lines that are each connected to the previous line in the sequence.

The first line in the sequence is defined by the first 2 vertices in the Mesh and each additional vertex defines a new segment of the line starting at the previous line's end point.

<warning>
	The Line Strip Primitive type is currently broken and will not produce any visual effect when rendered.

	It is included here for completeness.
</warning>

## Line Loops

A Mesh using the <page text="Line Loop Primitive">Enums/MATERIAL#MATERIAL_LINE_LOOP</page> behaves identically to the Line Strip Primitive with the notable addition of a final line connecting the first and last vertices in the sequence.

<warning>
	The Line Loop Primitive type is currently broken and will not produce any visual effect when rendered.

	It is included here for completeness.
</warning>

## Polygons

<page text="Polygon Primitives">Enums/MATERIAL#MATERIAL_POLYGON</page>

## Quads

<page text="Quad Primitives">Enums/MATERIAL#MATERIAL_QUADS</page>

Mesh Reference - Primitive Types

Account Management

Special Pages

Wiki List

Garry's Mod Wiki