GI.Cogl.Structs.Matrix

A CoglMatrix holds a 4x4 transform matrix. This is a single precision, column-major matrix which means it is compatible with what OpenGL expects.

A CoglMatrix can represent transforms such as, rotations, scaling, translation, sheering, and linear projections. You can combine these transforms by multiplying multiple matrices in the order you want them applied.

The transformation of a vertex (x, y, z, w) by a CoglMatrix is given by:

 x_new = xx * x + xy * y + xz * z + xw * w
 y_new = yx * x + yy * y + yz * z + yw * w
 z_new = zx * x + zy * y + zz * z + zw * w
 w_new = wx * x + wy * y + wz * z + ww * w

Where w is normally 1

<note>You must consider the members of the CoglMatrix structure read only, and all matrix modifications must be done via the cogl_matrix API. This allows Cogl to annotate the matrices internally. Violation of this will give undefined results. If you need to initialize a matrix with a constant other than the identity matrix you can use matrixInitFromArray.</note>

Exported types

newtype Matrix

Memory-managed wrapper type.

Constructors

Matrix (ManagedPtr Matrix)

Instances

Eq Matrix

Defined in GI.Cogl.Structs.Matrix

Methods

(==) :: Matrix -> Matrix -> Bool

(/=) :: Matrix -> Matrix -> Bool

GBoxed Matrix

Defined in GI.Cogl.Structs.Matrix

ManagedPtrNewtype Matrix

Defined in GI.Cogl.Structs.Matrix

Methods

toManagedPtr :: Matrix -> ManagedPtr Matrix

TypedObject Matrix

Defined in GI.Cogl.Structs.Matrix

Methods

glibType :: IO GType

HasParentTypes Matrix

Defined in GI.Cogl.Structs.Matrix

tag ~ 'AttrSet => Constructible Matrix tag

Defined in GI.Cogl.Structs.Matrix

Methods

new :: MonadIO m => (ManagedPtr Matrix -> Matrix) -> [AttrOp Matrix tag] -> m Matrix

IsGValue (Maybe Matrix)

Convert Matrix to and from GValue. See toGValue and fromGValue.

Defined in GI.Cogl.Structs.Matrix

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Matrix -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Matrix)

type ParentTypes Matrix

Defined in GI.Cogl.Structs.Matrix

type ParentTypes Matrix = '[] :: [Type]

newZeroMatrix :: MonadIO m => m Matrix

Construct a Matrix struct initialized to zero.

Methods

Click to display all available methods, including inherited ones

Methods

copy, free, frustum, initFromArray, initIdentity, initTranslation, isIdentity, lookAt, multiply, ortho, perspective, rotate, scale, transformPoint, translate, transpose.

Getters

getArray, getInverse.

Setters

None.

copy

matrixCopy

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A 4x4 transformation matrix you want to copy

-> m Matrix

Returns: A newly allocated Matrix which should be freed using matrixFree

Allocates a new Matrix on the heap and initializes it with the same values as matrix.

Since: 1.6

equal

matrixEqual

Arguments

:: (HasCallStack, MonadIO m)

=> Ptr ()

v1: A 4x4 transformation matrix

-> Ptr ()

v2: A 4x4 transformation matrix

-> m Int32

Compares two matrices to see if they represent the same transformation. Although internally the matrices may have different annotations associated with them and may potentially have a cached inverse matrix these are not considered in the comparison.

Since: 1.4

free

matrixFree

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A 4x4 transformation matrix you want to free

-> m ()

Frees a Matrix that was previously allocated via a call to matrixCopy.

Since: 1.6

frustum

matrixFrustum

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A 4x4 transformation matrix

-> Float

left: X position of the left clipping plane where it intersects the near clipping plane

-> Float

right: X position of the right clipping plane where it intersects the near clipping plane

-> Float

bottom: Y position of the bottom clipping plane where it intersects the near clipping plane

-> Float

top: Y position of the top clipping plane where it intersects the near clipping plane

-> Float

zNear: The distance to the near clipping plane (Must be positive)

-> Float

zFar: The distance to the far clipping plane (Must be positive)

-> m ()

Multiplies matrix by the given frustum perspective matrix.

getArray

matrixGetArray

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A 4x4 transformation matrix

-> m Float

Returns: a pointer to the float array

Casts matrix to a float array which can be directly passed to OpenGL.

getInverse

matrixGetInverse

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A 4x4 transformation matrix

-> m (Int32, Matrix)

Returns: True if the inverse was successfully calculated or False for degenerate transformations that can't be inverted (in this case the inverse matrix will simply be initialized with the identity matrix)

Gets the inverse transform of a given matrix and uses it to initialize a new Matrix.

<note>Although the first parameter is annotated as const to indicate that the transform it represents isn't modified this function may technically save a copy of the inverse transform within the given Matrix so that subsequent requests for the inverse transform may avoid costly inversion calculations.</note>

Since: 1.2

initFromArray

matrixInitFromArray

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A 4x4 transformation matrix

-> Float

array: A linear array of 16 floats (column-major order)

-> m ()

Initializes matrix with the contents of array

initIdentity

matrixInitIdentity

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A 4x4 transformation matrix

-> m ()

Resets matrix to the identity matrix:

 .xx=1; .xy=0; .xz=0; .xw=0;
 .yx=0; .yy=1; .yz=0; .yw=0;
 .zx=0; .zy=0; .zz=1; .zw=0;
 .wx=0; .wy=0; .wz=0; .ww=1;

initTranslation

matrixInitTranslation

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A 4x4 transformation matrix

-> Float

tx: x coordinate of the translation vector

-> Float

ty: y coordinate of the translation vector

-> Float

tz: z coordinate of the translation vector

-> m ()

Resets matrix to the (tx, ty, tz) translation matrix:

 .xx=1; .xy=0; .xz=0; .xw=tx;
 .yx=0; .yy=1; .yz=0; .yw=ty;
 .zx=0; .zy=0; .zz=1; .zw=tz;
 .wx=0; .wy=0; .wz=0; .ww=1;

Since: 2.0

isIdentity

matrixIsIdentity

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A Matrix

-> m Int32

Returns: True if matrix is an identity matrix else False

Determines if the given matrix is an identity matrix.

Since: 1.8

lookAt

matrixLookAt

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A 4x4 transformation matrix

-> Float

eyePositionX: The X coordinate to look from

-> Float

eyePositionY: The Y coordinate to look from

-> Float

eyePositionZ: The Z coordinate to look from

-> Float

objectX: The X coordinate of the object to look at

-> Float

objectY: The Y coordinate of the object to look at

-> Float

objectZ: The Z coordinate of the object to look at

-> Float

worldUpX: The X component of the world's up direction vector

-> Float

worldUpY: The Y component of the world's up direction vector

-> Float

worldUpZ: The Z component of the world's up direction vector

-> m ()

Applies a view transform matrix that positions the camera at the coordinate (eyePositionX, eyePositionY, eyePositionZ) looking towards an object at the coordinate (objectX, objectY, objectZ). The top of the camera is aligned to the given world up vector, which is normally simply (0, 1, 0) to map up to the positive direction of the y axis.

Because there is a lot of missleading documentation online for gluLookAt regarding the up vector we want to try and be a bit clearer here.

The up vector should simply be relative to your world coordinates and does not need to change as you move the eye and object positions. Many online sources may claim that the up vector needs to be perpendicular to the vector between the eye and object position (partly because the man page is somewhat missleading) but that is not necessary for this function.

<note>You should never look directly along the world-up vector.</note>

<note>It is assumed you are using a typical projection matrix where your origin maps to the center of your viewport.</note>

<note>Almost always when you use this function it should be the first transform applied to a new modelview transform</note>

Since: 1.8

multiply

matrixMultiply

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

result: The address of a 4x4 matrix to store the result in

-> Matrix

a: A 4x4 transformation matrix

-> Matrix

b: A 4x4 transformation matrix

-> m ()

Multiplies the two supplied matrices together and stores the resulting matrix inside result.

<note>It is possible to multiply the a matrix in-place, so result can be equal to a but can't be equal to b.</note>

ortho

matrixOrtho

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A 4x4 transformation matrix

-> Float

left: The coordinate for the left clipping plane

-> Float

right: The coordinate for the right clipping plane

-> Float

bottom: The coordinate for the bottom clipping plane

-> Float

top: The coordinate for the top clipping plane

-> Float

near: The <emphasis>distance</emphasis> to the near clipping plane (will be <emphasis>negative</emphasis> if the plane is behind the viewer)

-> Float

far: The <emphasis>distance</emphasis> to the far clipping plane (will be <emphasis>negative</emphasis> if the plane is behind the viewer)

-> m ()

Deprecated: (Since version 1.10)Use cogl_matrix_orthographic()

Multiplies matrix by a parallel projection matrix.

perspective

matrixPerspective

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A 4x4 transformation matrix

-> Float

fovY: Vertical field of view angle in degrees.

-> Float

aspect: The (width over height) aspect ratio for display

-> Float

zNear: The distance to the near clipping plane (Must be positive, and must not be 0)

-> Float

zFar: The distance to the far clipping plane (Must be positive)

-> m ()

Multiplies matrix by the described perspective matrix

<note>You should be careful not to have to great a zFar / zNear ratio since that will reduce the effectiveness of depth testing since there wont be enough precision to identify the depth of objects near to each other.</note>

rotate

matrixRotate

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A 4x4 transformation matrix

-> Float

angle: The angle you want to rotate in degrees

-> Float

x: X component of your rotation vector

-> Float

y: Y component of your rotation vector

-> Float

z: Z component of your rotation vector

-> m ()

Multiplies matrix with a rotation matrix that applies a rotation of angle degrees around the specified 3D vector.

scale

matrixScale

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A 4x4 transformation matrix

-> Float

sx: The X scale factor

-> Float

sy: The Y scale factor

-> Float

sz: The Z scale factor

-> m ()

Multiplies matrix with a transform matrix that scales along the X, Y and Z axis.

transformPoint

matrixTransformPoint

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A 4x4 transformation matrix

-> Float

x: The X component of your points position

-> Float

y: The Y component of your points position

-> Float

z: The Z component of your points position

-> Float

w: The W component of your points position

-> m (Float, Float, Float, Float)

Transforms a point whos position is given and returned as four float components.

translate

matrixTranslate

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A 4x4 transformation matrix

-> Float

x: The X translation you want to apply

-> Float

y: The Y translation you want to apply

-> Float

z: The Z translation you want to apply

-> m ()

Multiplies matrix with a transform matrix that translates along the X, Y and Z axis.

transpose

matrixTranspose

Arguments

:: (HasCallStack, MonadIO m)

=> Matrix

matrix: A Matrix

-> m ()

Replaces matrix with its transpose. Ie, every element (i,j) in the new matrix is taken from element (j,i) in the old matrix.

Since: 1.10

Properties

ww

No description available in the introspection data.

getMatrixWw :: MonadIO m => Matrix -> m Float

Get the value of the “ww” field. When overloading is enabled, this is equivalent to

get matrix #ww

setMatrixWw :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “ww” field. When overloading is enabled, this is equivalent to

set matrix [ #ww := value ]

wx

No description available in the introspection data.

getMatrixWx :: MonadIO m => Matrix -> m Float

Get the value of the “wx” field. When overloading is enabled, this is equivalent to

get matrix #wx

setMatrixWx :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “wx” field. When overloading is enabled, this is equivalent to

set matrix [ #wx := value ]

wy

No description available in the introspection data.

getMatrixWy :: MonadIO m => Matrix -> m Float

Get the value of the “wy” field. When overloading is enabled, this is equivalent to

get matrix #wy

setMatrixWy :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “wy” field. When overloading is enabled, this is equivalent to

set matrix [ #wy := value ]

wz

No description available in the introspection data.

getMatrixWz :: MonadIO m => Matrix -> m Float

Get the value of the “wz” field. When overloading is enabled, this is equivalent to

get matrix #wz

setMatrixWz :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “wz” field. When overloading is enabled, this is equivalent to

set matrix [ #wz := value ]

xw

No description available in the introspection data.

getMatrixXw :: MonadIO m => Matrix -> m Float

Get the value of the “xw” field. When overloading is enabled, this is equivalent to

get matrix #xw

setMatrixXw :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “xw” field. When overloading is enabled, this is equivalent to

set matrix [ #xw := value ]

xx

No description available in the introspection data.

getMatrixXx :: MonadIO m => Matrix -> m Float

Get the value of the “xx” field. When overloading is enabled, this is equivalent to

get matrix #xx

setMatrixXx :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “xx” field. When overloading is enabled, this is equivalent to

set matrix [ #xx := value ]

xy

No description available in the introspection data.

getMatrixXy :: MonadIO m => Matrix -> m Float

Get the value of the “xy” field. When overloading is enabled, this is equivalent to

get matrix #xy

setMatrixXy :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “xy” field. When overloading is enabled, this is equivalent to

set matrix [ #xy := value ]

xz

No description available in the introspection data.

getMatrixXz :: MonadIO m => Matrix -> m Float

Get the value of the “xz” field. When overloading is enabled, this is equivalent to

get matrix #xz

setMatrixXz :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “xz” field. When overloading is enabled, this is equivalent to

set matrix [ #xz := value ]

yw

No description available in the introspection data.

getMatrixYw :: MonadIO m => Matrix -> m Float

Get the value of the “yw” field. When overloading is enabled, this is equivalent to

get matrix #yw

setMatrixYw :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “yw” field. When overloading is enabled, this is equivalent to

set matrix [ #yw := value ]

yx

No description available in the introspection data.

getMatrixYx :: MonadIO m => Matrix -> m Float

Get the value of the “yx” field. When overloading is enabled, this is equivalent to

get matrix #yx

setMatrixYx :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “yx” field. When overloading is enabled, this is equivalent to

set matrix [ #yx := value ]

yy

No description available in the introspection data.

getMatrixYy :: MonadIO m => Matrix -> m Float

Get the value of the “yy” field. When overloading is enabled, this is equivalent to

get matrix #yy

setMatrixYy :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “yy” field. When overloading is enabled, this is equivalent to

set matrix [ #yy := value ]

yz

No description available in the introspection data.

getMatrixYz :: MonadIO m => Matrix -> m Float

Get the value of the “yz” field. When overloading is enabled, this is equivalent to

get matrix #yz

setMatrixYz :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “yz” field. When overloading is enabled, this is equivalent to

set matrix [ #yz := value ]

zw

No description available in the introspection data.

getMatrixZw :: MonadIO m => Matrix -> m Float

Get the value of the “zw” field. When overloading is enabled, this is equivalent to

get matrix #zw

setMatrixZw :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “zw” field. When overloading is enabled, this is equivalent to

set matrix [ #zw := value ]

zx

No description available in the introspection data.

getMatrixZx :: MonadIO m => Matrix -> m Float

Get the value of the “zx” field. When overloading is enabled, this is equivalent to

get matrix #zx

setMatrixZx :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “zx” field. When overloading is enabled, this is equivalent to

set matrix [ #zx := value ]

zy

No description available in the introspection data.

getMatrixZy :: MonadIO m => Matrix -> m Float

Get the value of the “zy” field. When overloading is enabled, this is equivalent to

get matrix #zy

setMatrixZy :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “zy” field. When overloading is enabled, this is equivalent to

set matrix [ #zy := value ]

zz

No description available in the introspection data.

getMatrixZz :: MonadIO m => Matrix -> m Float

Get the value of the “zz” field. When overloading is enabled, this is equivalent to

get matrix #zz

setMatrixZz :: MonadIO m => Matrix -> Float -> m ()

Set the value of the “zz” field. When overloading is enabled, this is equivalent to

set matrix [ #zz := value ]