Coordinate and Camera System

By default Messenger integrates Elm-regl's camera and virtual coordinate system.

The default virtual canvas size is 1920x1080.

The following is an illustration of the coordinate system:

The coordinate increases on the east and south direction.

Note that this is only virtual coordinates used in Messenger, and the actual canvas size may vary based on screen size.

Camera System

Messenger provides with a Global Camera that could be set in globalData.camera and many Local Cameras that could override the global camera's rule.

A camera setting is defined as:

{-| Camera settings.
-}
type alias Camera =
    { x : Float
    , y : Float
    , zoom : Float
    , rotation : Float
    }

The x and y are the center coordinates of the camera. The camera will capture a canvas in the virtual coordinate system of size specified in virtual canvas size.

By default, x and y are set to half of the virtual canvas size, which in our case is 960 and 540. zoom is 1 and rotation is 0 by default. The default camera is also called UI camera as it is mainly used for UI drawing.

A great feature of Messenger's camera system is that the global camera setting could be override by using groupWithCamera.

groupWithCamera : Camera -> List Effect -> List Renderable -> Renderable

You may even override the camera inside a groupWithCamera:

groupWithCamera camera1 [
    groupWithCamera camera2 [
        ...
    ]
]

You could use the default camera (UI camera) by calling defaultCamera from Messenger.Coordinate.Camera.

You can update the global camera with helpers from Messenger.Coordinate.Camera:

setCameraPos : ( Float, Float ) -> GlobalData u -> GlobalData u
setCameraScale : Float -> GlobalData u -> GlobalData u
setCameraAngle : Float -> GlobalData u -> GlobalData u
defaultCamera : Runtime -> Camera

Example:

import Messenger.Coordinate.Camera exposing (setCameraPos)

newEnv =
    { env | globalData = setCameraPos ( 960, 540 ) env.globalData }

Manual Coordinate System Transformation

In some cases, users may want to manually transform a coordinate in world space to view space, or vice versa. Messenger provides two handy functions in Messenger.Coordinate.Camera:

{-| Tranform a position from the world coordinate system to the view (camera) coordinate system.
-}
worldToView : Camera -> ( Float, Float ) -> ( Float, Float )
worldToView camera ( x, y ) =

{-| Transform a position from the view coordinate system to the world coordinate system.

This is the inverse of `worldToView`.

-}
viewToWorld : Camera -> ( Float, Float ) -> ( Float, Float )
viewToWorld camera ( x, y ) =

Canvas and HTML Coordinates

Some helpers use Runtime. Pass the runtime argument that Messenger gives to user model functions.

fixedPosToReal : Runtime -> ( Float, Float ) -> ( Float, Float )
posToReal : Runtime -> ( Float, Float ) -> ( Float, Float )
posToVirtual : Runtime -> ( Float, Float ) -> ( Float, Float )
lengthToReal : Runtime -> Float -> Float
fromRealLength : Runtime -> Float -> Float
fromMouseToVirtual : Runtime -> ( Float, Float ) -> ( Float, Float )

• posToReal converts a point from virtual canvas coordinates to real canvas pixels.
• posToVirtual converts real canvas pixels back to virtual coordinates.
• fixedPosToReal is like posToReal, but also includes the canvas offset in the browser window.
• lengthToReal and fromRealLength convert lengths between virtual and real coordinate systems.
• fromMouseToVirtual converts a browser mouse position to Messenger virtual coordinates.

For extra HTML elements, use genAttribute from Messenger.Coordinate.HTML:

genAttribute : Runtime -> ( Float, Float ) -> ( Float, Float ) -> List (Attribute msg)

It generates fixed-position HTML attributes that match a virtual position and size.