Blitz3D+ Command Reference

LoaderMatrix file_ext$,xx#,xy#,xz#,yx#,yy#,yz#,zx#,zy#,zz#

Parameters

file_ext$ - file extension the matrix applies to, lower case and without the dot, e.g. "x", "3ds", "b3d", "gltf", "glb"
xx#, xy#, xz# - first row of the 3x3 matrix
yx#, yy#, yz# - second row of the 3x3 matrix
zx#, zy#, zz# - third row of the 3x3 matrix

Description

Sets the coordinate-system conversion applied to every model loaded with a given file extension.

Modelling packages disagree about which way is up and which way is forward, so a model that looks right in its editor can arrive lying on its side or facing backwards. LoaderMatrix is the fix: give the loader a 3x3 matrix that maps the file axes onto Blitz axes, and every model of that type is corrected as it loads.

Each row says where one of the file axes ends up. The identity matrix 1,0,0, 0,1,0, 0,0,1 changes nothing; swapping the last two rows swaps Y and Z, turning a Z-up file into a Y-up one; putting -1 in place of a 1 mirrors that axis.

These are the conversions the runtime installs at startup:

LoaderMatrix "x",1,0,0,0,1,0,0,0,1 ; no change
LoaderMatrix "3ds",1,0,0,0,0,1,0,1,0 ; swap y and z
LoaderMatrix "gltf",1,0,0,0,1,0,0,0,-1 ; negate z
LoaderMatrix "glb",1,0,0,0,1,0,0,0,-1 ; negate z

The .3ds entry is there because 3D Studio files are Z-up; the glTF entries flip handedness, since glTF looks down -Z where Blitz looks down +Z. There is no entry for .b3d, which needs no conversion, and any extension without an entry is loaded unchanged.

Call it before you load anything, and match the extension exactly as the loader sees it: lower case, and with no leading dot. Passing ".x" or "X" quietly registers a matrix that never matches anything, which is the usual reason a LoaderMatrix appears to do nothing.

Correcting the export is generally better than correcting the load, but when you are handed art you cannot re-export - or a whole folder of models with the same problem - this fixes the lot in one line. It affects LoadMesh, LoadAnimMesh and LoadAnimSeq alike.

See also: LoadMesh, LoadAnimMesh, LoadAnimSeq, RotateMesh, ScaleMesh.

Example

; LoaderMatrix Example
; --------------------

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

camera=CreateCamera()
PositionEntity camera,0,1.5,-6

light=CreateLight()
RotateEntity light,45,45,0

AmbientLight 120,120,120

; LoaderMatrix sets the 3x3 conversion matrix applied to every mesh
; loaded with the given file extension.

; This is the default for .3ds files: swap the Y and Z axes, because
; 3DS models are built with Z pointing up
LoaderMatrix "3ds",1,0,0,0,0,1,0,1,0
drum_default=LoadMesh("media/oil-drum/oildrum.3ds")
If drum_default=0 Then RuntimeError "Unable to load oil drum"

; Identity matrix: no conversion at all, so the same drum arrives
; lying on its side
LoaderMatrix "3ds",1,0,0,0,1,0,0,0,1
drum_raw=LoadMesh("media/oil-drum/oildrum.3ds")

; Restore the default so later loads behave normally
LoaderMatrix "3ds",1,0,0,0,0,1,0,1,0

; Fit both drums to the same size and place them side by side
FitMesh drum_default,-1,0,-1,2,2,2,True
FitMesh drum_raw,-1,0,-1,2,2,2,True
PositionEntity drum_default,-1.5,0,0
PositionEntity drum_raw,1.5,0,0

While Not KeyDown(1)

    ; Spin both drums so the axis difference is easy to see
    TurnEntity drum_default,0,1,0
    TurnEntity drum_raw,0,1,0

    ; Arrow keys move the camera
    If KeyDown(200) Then MoveEntity camera,0,0,0.1
    If KeyDown(208) Then MoveEntity camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    RenderWorld

    Text 0,0,"Arrows: camera   Esc: exit"
    Text 0,20,"Left: default LoaderMatrix (Y/Z swapped - drum upright)"
    Text 0,40,"Right: identity LoaderMatrix (no conversion - drum on its side)"

    Flip

Wend

End

Index