BluffTitler file formats

This page describes custom BluffTitler file formats and extensions to standard file formats.

For coders only

This info is only meant for software engineers. You do not have to understand anything on this page in order to use BluffTitler.

BluffTitler effect files

BluffTitler stores its effects in CFX files. The format has been introduced by Outerspace Software at the release of BluffTitler version 12 as replacement for the deprecated DirectX 9 FX format.

For coders only

This info is only meant for software engineers. You do not have to understand anything on this page in order to use effects. Click here to learn how to use effects

Text and binary

Effects come in 2 versions:

BFXa text format containing the HLSL source code
CFXa binary format containing the compiled shaders (bytecode)

The consumer editions of BluffTitler can only load CFX files. You can compile BFX to CFX with the developer edition. The developer edition is currently not for sale.

Content

Header

A BFX file header looks like this:

BFX 2
DESCRIPTION "This effect does this and that and also..."

Textures

Up to 9 textures can be used:

0defined by effect
1defined by effect
2defined by effect
3depth buffer
4stencil buffer
5,6,7,8shadow maps, always added by compiler

Textures are defined like this:

TEXTURE 0 COLOUR MIP * *
TEXTURE 1 DISPLACEMENT MIP * *
TEXTURE 2 CUBE MIP * *

1st string is always TEXTURE

2nd string is the texture index [0,4]

3rd string is the texture type {COLOUR, REFLECTION, CUBE, NORMAL, DEPTH, STENCIL, VOXEL, SKETCH, CARTOON, ALPHA, TONALART, DISPLACEMENT, FUR}

4th string sets mipmapping {*,MIP,LIN}. * means that the effect must not make adjustments.

5th string sets horizontal texture mode {*,CLAMP,WRAP,MIRROR}

6th string sets vertical texture mode {*,CLAMP,WRAP,MIRROR}

Textures can be accessed like this:

float4 c=MyTexture0.Sample(MySampler0, input.tex);
float4 c=MyTexture0.SampleLevel(MySampler0, input.tex, 0);

Variables

An effect file can add 16 extra properties to a layer by using the following annotations:

UINameThe property name as it must appear in the GUI
UIMinThe minimum value
UIMaxThe maximum value
UIDefaultThe default value
UISlidersNumber of sliders {1,2,3}
UIScaleScale to GUI factor
UIIntegerSet to true for integer variables
UIWidgetWidget

The 16 extra properties can be defined this way:

float4 Prop0
<
string UIName="My very own variable";
float UIMin=0;
float UIMax=10;
float3 UIDefault=float3(2,0,0);
int UISliders=1;
float UIScale=1;
bool UIInteger=true;
int UIWidget=0;
>

Widgets

Every property has a widget:

0default
1angle
2colour

Passes

A pass contains render states, links to HLSL code and other properties. A pass is defined like this:

PASS
BLENDING ADDITIVE
ZREAD Y
ZWRITE Y
RGBAWRITE 7
CULL BACK
SOLID Y
CLEARTARGET Y
VS vs_4_0 VS1
HS hs_4_0 HS1
DS ds_4_0 DS1
GS gs_4_0 GS1
PS ps_4_0 PS1

All render states are booleans {Y,N} except the following:

BLENDING can be {NONE, ALPHA, ADDITIVE, SUBTRACTIVE}

RGBAWRITE can be [0,15]. Y is accepted as 15 and N as 0.

CULL can be {FRONT, BACK, NONE}

The next pass in the same effect takes over the renderstates of the previous pass. The next effect resets the renderstates.

Every pass must have a vertex (VS) and pixel shader (PS). Hull (HS), domain (DS) and geometry shaders (GS) are optional.

The CLEARTARGET state is only used in the 2nd pass of a postprocessing effect.

Cascading shadow maps

When only a single light layer is using shadow maps, 4 cascading shadow maps (CSM) are created. In this situation, textures 5 (near), 6, 7 and 8 (far) are used for the 4 sub frusta.

Post processing

If an effect is applied to the camera layer, the 1st texture contains the render output. This way it can be used as a post processing effect.

Pixel shader chain

If the effect has 2 passes, the output of the 1st pass is used as the input for the 2nd pass. This can be used to optimize effects, like for example a bilinear blur. Note that this convention makes normal 2 pass effects useless for the camera layer.

The render target is cleared by default. For some effects, like for example a bloom, you don't want this. It can be prevented by setting the CLEARTARGET pass property to N:

CLEARTARGET N

Vertex format

BluffTitler uses the following vertex format:

structVS_INPUT{
float4pos:POSITION;
float4normal:NORMAL;
float4col:COLOR;
float2tex:TEXCOORD0;
float4tangent:TANGENT;
};

Meshes created with the Tubular square, Tubular round, Wireframe, Light discs, Light bulbs and Comb text layer styles abuse the tangent field to store special info: (bulb/bulbs, contour, contours)

Matrix parameters

All matrices are 4x4 homogeneous transformation matrices in row major format.

Worldmodel to world space
WorldAtext layer: model (glyph) to text space
WorldBtext layer: text to world space. (World = WorldA * WorldB)
Viewworld to view space
Projectionview to projection(screen) space
WorldViewworld * View
ViewProjectionview * projection
WorldViewProjectionworld * view * projection
WorldNormalnormals to world space
WorldNormalAtext layer: normals from model to text space.
WorldNormalBtext layer: normals from text to world space. (WorldNormal = WorldNormalA * WorldNormalB)
ShadowmapMatrix[4]world to shadow map space
InverseMirrormirrored to non mirrored world space
InverseMirrorNormalmirrored reflection to non mirrored world space
InverseViewinverse view matrix
InverseProjectioninverse projection matrix
InverseViewProjectioninverse projection * inverse view

Vector parameters

All vectors are 4D floats.

EyePosXYZW
TextureResolution[9]widthheightdepthaspect ratio (width/height)
MaterialRGBA
Powerspecular poweralpha test mirrorfog range startfog range full
AmbientColRGB1
Lightsnumber of lights (-1 means the shadow map is being rendered)fog Rfog Gfog B
DiffuseCol[4]RGB1
SpecularCol[4]RGB1
LightPos[4]X (point light) or XN (directional light)Y (point light) or YN (directional light)Z (point light) or ZN (directional light)Shadow intensity
LightType[4]light type:
0 directional
1 point
shadow algorithm:
0 projected shadows
1 shadow volumes
2 shadow maps
soft shadow factor-
Shadowmap[4]K directional light plane (N*P=K)fixed depth biasslope depth bias-
Timeshow time in secondsparticle time in secondsparticle lifetime in secondsalpha test
LocalTimehoursminutessecondsmilliseconds
ModelRepeatpicture layer: model repeat property X
text and scroller layer: word index
voxel layer: tissue density property X
picture layer: model repeat property Y
text and scroller layer: words
voxel layer: tissue density property Y
picture layer: model repeat property Zquality {0,1,2,3}
TextureRepeatpicture and mirror layers: texture repeat property Xpicture and mirror layers: texture repeat property YCSM (1 means yes)-
CharacterIndextext and scroller layer: character index
picture layer when using model repeat prop: tile
text and scroller layer: characters
picture layer when using model repeat prop: tiles
text and scroller layer: Unicode valuesubmodel
PivotPointXYZ1
MirrorSpecularitymirror exists (1 means yes)mirror specularitymirror gradient (Fresnel effect)clip (1 means yes)
MirrorPlaneXNYNZNK (N*P=K)
Amplitude[5]audio amplitudes are stored in 20 floats: [0] contains all, [1] contains lowest frequency, [19] contains highest frequency.
Prop[16]the effect specific variables. The w component is always 1.
WaterHeaderwavessteepness--
WaterData[120]frequencyamplitudeheadingphase

HLSL code

The HLSL source code (vertex, hull, domain, geometry and pixel shaders) follows after the HLSL tag:

HLSL

The compiled bytecode follows after the COMPILED tag:

COMPILED VS 0 2708

2nd string is the shader type {VS,HS,DS,GS,PS}

3rd string is the pass

4th string is the size in bytes

Shaders can be shared between passes like this:

COMPILED VS 0,1,2,3,4 2708

BluffTitler vector files

The sketch layer of BluffTitler uses the EPS format to import line drawings. The EPS format however is limited to 2D positions. BluffTitler adds a few extensions to make 3D positions possible to store, for example, roller coaster paths. Those extensions are introduced at the release of BluffTitler 7.5. They are BluffTitler specific and not compatible with any other software supporting the EPS format.

For coders only

This info is only meant for software engineers. You do not have to understand anything on this page in order to use 3D sketches. Click here to learn how to use 3D sketches

Header

By default, BluffTitler centres and scales all EPS files to fit in the same box. This can be overruled with the following commands:

%%BluffTitler Scale N
%%BluffTitler Centre N

Other BluffTitler commands:

%%BluffTitler MaxLinesPerCurve x

moveto

In analogy with the standard moveto command, BluffTitler adds 2 3D versions.

XYZ are positions, abc are tangents.

X Y moveto
X Y Z moveto
X Y Z a b c moveto

lineto

In analogy with the standard lineto command, BluffTitler adds 2 3D versions.

XYZ are positions, abc are tangents.

X Y lineto
X Y Z lineto
X Y Z a b c lineto

curveto

In analogy with the standard curveto command, BluffTitler adds 2 3D versions.

XYZ are positions, abc are tangents.

X Y X Y X Y curveto
X Y Z X Y Z X Y Z curveto
X Y Z X Y Z X Y Z a b c curveto

BO format

The BO file format has been introduced by Outerspace Software at the release of Bixelangelo version 4. I was meant for debugging only but turned out to be an excellent way to design roller coasters.

The text format does the same as you do in the GUI by adding elements in the WINDOW > Element dialog. The element names and parameters are the same as in the GUI. Here's an example:

Bixelangelo 1.0
Move 0 0 0 0
Element "Straight line"	20
Element "Lift hill" 75 110
Element Dive 50 100
Element "Circular loop" 40 20 0
Element Turn 180 20 00 45
Element "Straight line" 145
Element Turn 180 30 0 45
Close

To open a BO file, start Bixelangelo and choose FILE > Open.... Examples can be found in the Bixelangelo\Media\Sketches folder.

Always start with the header:

Bixelangelo 1.0

The Move command starts a new curve:

Move X Y Z Angle

Element names with a space require quotation marks:

Element "Circular loop" 40 20 0

The Close command is used to connect the last point to the first.

Close

BluffTitler model files

The robotic arm layer of BluffTitler uses 3D models in the .X and .OBJ format. BluffTitler extends these formats to store the robotic arm info.

For coders only

This info is only meant for software engineers. You do not have to understand anything on this page in order to use robotic arms. Click here to learn how to use robotic arms

Arm types

TypeLimbsJointsMirroredHinges (DOF)Hinge orientations
145Y7Shoulder (heading, roll, pitch), Elbow (pitch), Wrist (pitch, roll, heading)
289N7Shoulder (heading, roll, pitch), Elbow (pitch), Wrist (pitch, roll, heading)
334N2Shoulder (heading, pitch)

X

BluffTitlerRoboticArm{
3;
4;
0.0; 0.0; 0.0;,
0.0; 120.0; 0.0;,
0.0; 320.0; 0.0;,
0.0; 490.0; 0.0;;
}

OBJ

#BluffTitlerRoboticArmType 3
#BluffTitlerRoboticArmJoint 0 0 0
#BluffTitlerRoboticArmJoint 0 120 0
#BluffTitlerRoboticArmJoint 0 320 0
#BluffTitlerRoboticArmJoint 0 490 0