yak2D Coordinate Systems and Rendering Resolution
RenderStage Output
A RenderStage's output is render area size agnostic. This means that a RenderStage's output will fill the entire destination render area, which is either an entire RenderTarget or a rectangular area of one defined by a viewport.
The pixel size of the render area does not matter.
However, if the aspect ratio of the destination render area does not match that of the RenderStage's output, the output will be distorted (stretched or squashed) to fit.
Drawing
During Drawing, DrawRequests are submitted to, and rendered by, a DrawStage. The final position of vertices upon the render area is transformed by the assigned Camera2D.
Each Camera2D has a virtual resolution that defines the boundaries of screen space as well as world space once a camera's zoom, world focus point and rotation are also accounted for.
What this means in practice
A user can choose a virtual resolution and draw everything in relation to these effective screen dimensions, but it can be rendered at a final real resolution chosen simply by the an appropriately sized render area.
Coordinate Systems (spaces)
yak2D uses 3 coordinate systems (or spaces) for 2D rendering:
Screen Space
The coordinate system used when drawing with CoordinateSpace.Screen. Positions are defined in relation to a fixed visible area defined by the camera's virtual resolution.
The origin (0,0) is located in the centre. Positive X-axis runs from left to right, with positive Y-axis running 'upwards' towards the top of the visible area.
Visible positions in screen space are defined by:
and...
where:
- w = virtual resolution width
- h = virtual resolution height
Screen Space Diagram
World Space
The coordinate system used when drawing with CoordinateSpace.World. Positions are defined in relation to an origin. The visible area is defined by the camera's world focus point (position) in relation to the origin, the camera's zoom scalar, rotation and virtual resolution.
World space axis are similar to screen space, in that when unrotated, positive X-axis runs from left to right, with positive Y-axis running 'upwards' towards the top of the visible area.
Therefore, if the camera's world focus point is (0,0), it's zoom is 1.0 and there is no camera rotation, then a position in world space will match a position in screen space.
Window Space
Window space is used when defining viewports and is the coordinate system used for mouse position.
The origin (0,0) of window space is positioned at the top-left corner of the window (or RenderTarget), with positive X-axis running from left to right, and positive Y-axis running 'downwards' towards the bottom of the window (or RenderTarget).
Window space units are absolute pixels.
Valid / visible pixel positions in window space are defined by:
and...
where:
- w = Window or RenderTarget width
- h = Window or RenderTarget height
Window Space Diagram
Viewports
Viewports are used to define rectangular render areas of a RenderTarget.
Viewport position and size are defined in pixel units and use window space coordinates.
Texture Coordinates
yak2D texture coordinates are origin top-left and do not change across any graphics API backends. This is the same as used in Direct3D, Vulkan and Metal APIs, and is the coordinate system as window space.
Note: When writing shaders for a CustomVeldrid RenderStage, the user is responsible for accounting for the backend differences between graphics APIs.
When writing shaders for a CustomShader RenderStage, the vertex shader provided already accounts for the differences in OpenGL texture coordinates. Therefore all shaders can be written assuming origin top-left.
3D Rendering
The MeshRender RenderStage uses a Camera3D to manage the required view and projection matrices used during rendering.
yak2D uses a Right-Handed coordinate system, which does not change across any graphics API backends. This coordinate system is positive-x towards the right, positive-y upwards and positive-z out of the screen, towards the camera.
Note: When writing shaders for a CustomVeldrid RenderStage, the user is responsible for accounting for the backend differences between graphics APIs.
Mouse Input
yak2D provides mouse position as a position on the application window, in window space.
Coordinate System Conversions
To easily convert positions between any of screen space, world space or window space, yak2D provides helper functions.