# Coordinate Systems

When dealing with voxels (and math in three-dimensional space in general), it is extremely important to get your coordinate systems and the conversions between them right. Even slightly wrong conversions can (and will) lead to *massive* headaches and horrible debugging sessions.

As such, it is a good idea to do one or more of these:

- Add the coordinate-system being used to every position, rotation and scale value.
- Restrict the mixing of coordinate-systems, by using a type-system that let's you create new types from existing types.
- Document the coordinate-systems of function parameters.

Note that, depending on the software you are using, the concrete definition and usage of coordinate-systems can vary *wildly*...

**Authors Opinion:**
I recommend using a right-handed coordinate-system with Z-up or, if you prefer, Y-up.

- Blender, SketchUp and various Autodesk products use it.
- Z-up, so that a sheet of graph-paper represents the X/Y plane.

Also, keep in mind that the great majority of 2D renderers *and displays* available use a X-right + Y-*down* system, mainly due to western writing systems being oriented that way.

## Terminology

Now then, let's get to the various coordinate systems!

The order in which they are listed is *kinda important*, so try to keep it in mind. ;)

**TODO:**Add descriptive diagrams to all definitions.

### Voxel/Sample Space

The 'inner' coordinate system of an *individual voxel*.

### Object/Local/Chunk Space

The local coordinate system of an individual object, such as an entity or a chunk.

### World/Scene Space

The global coordinate system that is the entire scene. This is where almost all the (gameplay-related) math will occur.

### View/Camera Space

The view of a camera into world space.

### (Homogeneous) Clip Space

The camera space with a perspective- or orthographic-projection applied,
forming a prism/box called the *clip volume*.

- This is the space that we output to in a vertex shader.
- i.e.:
`gl_Position`

is in clip-space.

- i.e.:
- Coordinates are defined to be homogenous here.

### Normalized Device Coordinate(s) Space

The clip space after perspective coordinate division, if applicable.

### Screen/Window/Framebuffer Space

The space where whole-numbered coordinates correspond to pixels on a screen, falling into a range of either...

`[(0,0), (WIDTH-1,HEIGHT-1)]`

`[(1,1), (WIDTH,HEIGHT)]`

## References

- Wikipedia
- Learn OpenGL: Coordinate Systems
- Freya Holmérs Cheat Sheet
- WebGPU Specification
- Setting Up a Proper Projection Matrix for Vulkan
- Homogeneous Coordinates, Clip Space, and NDC | WebGPU
- Why is clip space always referred to as "homogeneous clip space"?
- Explaining Homogeneous Coordinates & Projective Geometry
- When does the transition from clip space to screen coordinates happen?
- Scratchapixel: The Perspective and Orthographic Projection Matrix
- OpenGL Projection Matrix
- Lecture 05: Spatial Transformations (CMU 15-462/662)
- WebGPU: Point Rasterization
- OpenGL
`ARB_clip_control`