CFX file format

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 page 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

It comes in 2 versions:

BFXa text format containing the HLSL source code
CFXa binary format containing 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.

An effect contains:

Header

A BFX file header looks like this:

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

Textures

Up to 5 textures can be used:

0defined by effect
1defined by effect
2defined by effect
3depth buffer
4stencil buffer

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.

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(character) to text space
WorldBtext layer: text to world space. (World = WorldA x WorldB)
Viewworld to view space
Projectionview to projection(screen) space
WorldViewWorld x View
ViewProjectionView x Projection
WorldViewProjectionWorld x View x Projection
WorldNormalnormals to world space
WorldNormalAtext layer: normals from model to text space.
WorldNormalBtext layer: normals from text to world space. (WorldNormal = WorldNormalA * WorldNormalB)
InverseMirrorNormalmirrored reflection to non mirrored world space
InverseViewThe inverse view matrix of the last 3D view
InverseProjectionThe inverse projection matrix of the last 3D projection
InverseViewProjectionInverseProjection x InverseView

Vector parameters

All vectors are 4D floats.

EyePosXYZW
TextureResolution[5]widthheightdepthaspect ratio (width/height)
MaterialRGBA
Powerspecular poweralpha test mirror depth--
AmbientColRGB1
Lightsnumber of lights---
DiffuseCol[4]RGB1
SpecularCol[4]RGB1
LightPos[4]XYZ1
Timeshow time in secondsparticle time in secondsparticle lifetime in seconds-
LocalTimehoursminutessecondsmilliseconds
ModelRepeatpicture layer: model repeat prop X
text and scroller layer: word index
voxel layer: tissue density prop X
picture layer: model repeat prop Y
text and scroller layer: words
voxel layer: tissue density prop Y
picture layer: model repeat prop Z-
TextureRepeatpicture and mirror layers: texture repeat prop Xpicture and mirror layers: texture repeat prop Y--
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
Mirrormirror exists (1 means yes)mirror specularitymirror gradientclip (1 means yes)
MirrorPlaneX normalY normalZ normaldot product normal and pos
Amplitude[5]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