Building an Effect

A brief overview of the structure of the PFX file format

The PowerVR Effects (PFX) format is a small, simple, easy-to-use effects file format that allows for the declaration of ‘application data’ semantics so that shaders can be accurately simulated.

A single PFX file consists of several blocks that describe how a given effect is put together and, by default, consists of a single effect. Multiple effects may exist within a single PFX file, each with their own effect block. Likewise, multiple shaders may exist within a single PFX, each referenced by name. It is also possible for separate PFX files to reference the same shaders by placing those shaders in separate files and linking to them from the vertex shader and fragment shader blocks.

The full specification for the PFX format is included in the PVRShaman package and is also available from docs.imgtec.com.

PFX Blocks

Each PFX file is broken down into several blocks, with each block serving a different purpose.

A basic effect consists of:
  • a header
  • an effect
  • a vertex shader block
  • a fragment shader block
  • one or more texture and/or target blocks

[HEADER]

The header block contains information about the PFX file being edited, as explained in the table below.

[HEADER]
VERSION 01.00.00.00
DESCRIPTION header example
COPYRIGHT Imagination Technologies
[/HEADER]
Keyword Explanation
VERSION The version of the PowerVR Effects file specification that the file uses.
DESCRIPTION A description of what the effect does.
COPYRIGHT A copyright string.

[EFFECT]

The effect block is used by PVRShaman to set up the shader. It defines all the attributes and uniforms to be passed to the shader, a name for the shader and the names of the vertex and fragment shaders that are to be used for this given effect, all of which are listed in the table below. It can also be used to set annotations, and to set the texture number for a given texture. Seven keywords, and one nested block are available for use:

[EFFECT]
NAME Bumpmapping
VERTEXSHADER VertShader
FRAGMENTSHADER FragShader
TEXTURE 0 base
TARGET COLOR0 rendertarget
ATTRIBUTE inVertex POSITION
ATTRIBUTE inNormal NORMAL
ATTRIBUTE inTexCoord UV
ATTRIBUTE inTangent TANGENT
UNIFORM MVPMatrix WORLDVIEWPROJECTION
UNIFORM LightPosition LIGHTPOSMODEL0
UNIFORM sampler2D TEXTURE0
[/EFFECT]
Keyword Explanation
NAME The name for the overall effect.
UNIFORM This keyword can be used multiple times to set-up a given uniform in the shader. This is written in the form:
UNIFORM <NAME> <SEMANTIC>
where the NAME represents the name of the PVRShaman semantic list.
ATTRIBUTE This keyword can be used multiple times to set-up a given attribute in the shader. This is written in the form
ATTRIBUTE <NAME> <SEMANTIC>
where the NAME represents the name of the attribute as it is written in the shader and the semantic represents a semantic from the PVRShaman semantic list.
TARGET This keyword can be used multiple times to set a target number and name for a given render-to-texture target represented by a [TARGET] block. It is declared in the form:
TARGET COLOR<NUMBER> <NAME>
where NUMBER represents the ID of the target and the name represents the name of the texture as set in the [TARGET] block. Its purpose is to specify the render target to be used by an effect.
TEXTURE Used multiple times. This is used to set a texture number and name for a given texture set by a texture block. It is declared in the form:
TEXTURE <NUMBER> <NAME>
where NUMBER represents the ID of the texture and NAME represents the name of the texture as set in the texture block.
FRAGMENTSHADER This is used to specify the fragment shader which should be used for this effect. This is required as multiple fragment shaders can be specified within a single PFX file.
VERTEXSHADER This is used to specify the vertex shader which should be used for this effect. This is required as multiple vertex shaders can be specified within a single PFX file.
[ANNOTATION] All text within the annotation sub block will be read into a string. This string is not used in PVRShaman, although it can be used to pass information to other applications that may later read the PFX file.

[VERTEXSHADER] and [FRAGMENTSHADER]

The vertex and fragment shader blocks describe vertex or fragment shaders. These blocks contain the name of the shader and the shader source code. This can be directly in the block or can be referenced in a file.

[FRAGMENTSHADER]
NAME FragShader
[GLSL_CODE]
uniform sampler2D sampler2d;
varying highp vec2 texCoordinateMain;
void main (void)
{
gl_FragColor = texture2D(sampler2d, texCoordinateMain);
}
[/GLSL_CODE]
[/FRAGMENTSHADER]

[VERTEXSHADER]
NAME VertShader
FILE VertShader.vsh
[/VERTEXSHADER]
Keyword Explanation
NAME The name of the vertex shader for use in the effect block.
FILE The FILE tag can be used to specify a file that contains the vertex shader in cases where the GLSL code block is not used.
[GLSL_CODE] Code within the GLSL code block is passed verbatim to the GLSL compiler and represents the actual shader code to be run.

[TEXTURE]

The texture block contains information about a texture to be loaded and the flags to be used when drawing it, listed in the table below.

[TEXTURE]
NAME Lena
PATH "LenaPVR"
MINIFICATION LINEAR
MAGNIFICATION LINEAR
MIPMAP NEAREST
WRAP_T REPEAT
WRAP_S CLAMP
[/TEXTURE]
Keyword Explanation
NAME The name of the texture, for use in the effect block.
PATH The path to the file the texture block represents. Currently this file must be in the same folder as the PFX file.
MINIFICATION This option states how to handle texture minification. Two valid values exist, either LINEAR or NEAREST
MAGNIFICATION This option states how to handle texture magnification, two valid values exist, either LINEAR or NEAREST.
MIPMAP This option states how to pick the correct MIP map. Three valid values exist, either LINEAR, NONE, or NEAREST.
WRAP_T/WRAP_S These two options indicate which wrap mode is to be used for the texture. Two valid values exist, either REPEAT or CLAMP.
VIEW/CAMERA Used when performing a render-to-texture. These tags indicate which camera should be rendered to this texture. Valid values are PFX_CURRENTVIEW, the currently selected view in PVRShaman, or the name of any camera from the POD file.

When no values are provided the default values are:

  • MINIFICATION – NEAREST

  • MAGNIFICATION – NEAREST

  • MIPMAP – NONE

  • WRAP_T/WRAP_S – REPEAT

[TARGET]

The target block contains information about a render target, displayed in full in the table below. The target’s name is used in an effects block to signify that the effect associated with that block should render to the named off-screen buffer.

[TARGET]
NAME Mix
SURFACETYPE RGB888
RESOLUTION 512 512
MINIFICATION LINEAR
MAGNIFICATION LINEAR
[/TARGET]
Keyword Explanation
NAME The name of the target, for use in the effect block.
SURFACETYPE The pixel format of the target, currently the following formats are accepted:
  • RGBA8888
  • RGBA4444
  • RGB888
  • RGB565
RESOLUTION This specifies the resolution of the target buffer in the form <X-SIZE> <Y-SIZE>, where size is a number of pixels.
MINIFICATION This option states how to handle texture minification. Two valid values exist, either LINEAR or NEAREST.
MAGNIFICATION This option states how to handle texture magnification Two valid values exist, either LINEAR or NEAREST.