# project (Shader Module)

The `project`

shader module is part of the core of deck.gl. It makes it easy to write shaders that support all of deck.gl's projection modes and it supports some advanced rendering techniques such as pixel space rendering etc.

The `project`

module has two extensions:

- project32 shorthand functions for projecting directly from worldspace to clipspace.
- project64 counterpart of
`project32`

that enables 64 bit projections, providing an increase in precision, at the cost of performance.

## Usage

Projects worldspace coordinates to clipspace coordinates.

`// instanced geometry`

in vec3 positions;

// instance attributes

in vec3 instanceCenter;

in float instanceSize;

void main(void) {

vec3 center = project_position(instanceCenter);

vec3 vertex = positions * project_size(instanceSize);

gl_Position = project_common_position_to_clipspace(center + vertex);

}

## getUniforms

The JavaScript uniforms are extracted from both contextual and per-layer props. The following information are used:

`viewport`

`devicePixelRatio`

`coordinateSystem`

`coordinateOrigin`

`modelMatrix`

## GLSL Uniforms

Uniforms are considered private to each shader module. They may change in between patch releases. Always use documented functions instead of accessing module uniforms directly.

The uniforms of the `project`

shader module are prefixed with `project_`

in their names.

## GLSL Functions

The projection module enables you to write vertex shaders that support deck.gl's coordinate systems and projection methods. Using the projection module ensures that you layer will be able accept position coordinates in the various formats supported by deck.gl, such as `[longitude, latitude, altitude]`

or `[metersX, metersY, metersZ]`

. To support the basic features expected of a deck.gl layer, such as various viewport types and coordinate systems, your own shaders should always use the built-in projection functions.

The functions converts positions/vectors between 4 coordinate spaces:

Name | Short Name | Description |
---|---|---|

World space | `world` | The coordinate system defined by the layer, not necessarily linear or uniform. |

Common space | `common` | A normalized intermediate 3D space that deck.gl uses for consistent processing of geometries, guaranteed to be linear and uniform. Therefore, it is safe to add/rotate/scale positions and vectors in this space. |

Screen space | `pixel` | Top-left coordinate system runs from `[0, 0]` to `[viewportWidth, viewportHeight]` (see remarks below). |

Clip space | `clipspace` | Output of the vertex shader. |

More detailed explanation of each coordinate space can be found in the coordinate systems guide.

The GLSL functions of the `project`

shader module uses the following naming convention:

`project_[<source_space>]_<object_type>_[to_<target_space>]`

`source_space`

: the short name of the coordinate space of the input. If not specified, the input is always in the`world`

space.`object_type`

: one of the following`position`

: absolute position of a point`offset`

: the delta between two positions`normal`

: the normal vector of a surface`size`

: the measurement of a geometry. This is different from`offset`

in that`size`

is uniform on all axes (e.g. [x, y, z] in meters in`LNGLAT`

world space) and`offset`

may not be (e.g. [dLon, dLat, dAlt] in degrees, degrees, and meters respectively in`LNGLAT`

world space).

`target_space`

: the short name of the coordinate space of the output. If not specified, the output is always in the`common`

space.

### project_position

`vec2 project_position(vec2 position)`

vec3 project_position(vec3 position)

vec3 project_position(vec3 position, vec3 position64Low)

vec4 project_position(vec4 position)

vec4 project_position(vec4 position, vec3 position64Low)

Converts the coordinates of a point from the world space to the common space. The coordinates are interpreted according to `coordinateSystem`

and `modelMatrix`

is applied.

### project_size

`float project_size(float meters)`

vec2 project_size(vec2 meters)

vec3 project_size(vec3 meters)

vec4 project_size(vec4 meters)

Converts the size of a geometry from the world space (meters if geospatial, and absolute units otherwise) to the common space.

### project_size_to_pixel

`float project_size_to_pixel(float size)`

float project_size_to_pixel(float size, int units)

Converts the size of a geometry from the given units in the world space to the common space. If unspecified, units is meters. The result corresponds to the number of screen pixels when the given size is viewed with a top-down camera.

### project_pixel_size

`float project_pixel_size(float pixels)`

float project_pixel_size(vec2 pixels)

Converts the size of a geometry from the screen space to the common space.

### project_pixel_size_to_clipspace

`vec2 project_pixel_size_to_clipspace(vec2 pixels)`

Converts the size of a geometry from the screen space to the clip space.

### project_normal

`vec3 project_normal(vec3 vector)`

Converts position deltas from the world space to normalized vector in the common space.

### project_common_position_to_clipspace

`vec4 project_common_position_to_clipspace(vec4 position)`

Converts the coordinates of a point from the common space to the clip space, which can be assigned to `gl_Position`

as the "return value" from the vertex shader.

### project_get_orientation_matrix

`mat3 project_get_orientation_matrix(vec3 up)`

Returns a matrix that rotates any vector defined in the default common space to a new orientation, such that `vec3(0, 0, 1)`

is aligned with `up`

. `up`

is a normal in common space.

## Remarks

- For consistent results, the screen space pixels are logical pixels, not device pixels, i.e. functions in the project module multiply
`pixels`

with`project_uDevicePixelRatio`

. - The pixels offsets will be divided by the
`w`

coordinate of`gl_Position`

. This is simply the GPUs standard treatment of any coordinate. This means that there will be more pixels closer to the camera and less pixels further away from the camer. Setting the`focalDistance`

uniform controls this. - To avoid pixel sizes scaling with distance from camera, simply set
`focalDistance`

to 1 and multiply clipspace offset with`gl_Position.w`