This section will give a sort introduction into the application by showing you how to use the user interface and debugging tools.
First you need to download the application. There are two ways to do that. You can download the binary files or clone the Git repository from GitHub and building the application yourself.
There are currently no binary downloads available, because the application is still in its beta-phase.
Go to the projects GitHub page. There you can find the HTTPS/SSH link you need to clone the Git repository. If you need more information on how to clone a GitHub repository, please have a look at how to set up Git.
Ctrl + O
Open an existing file.
Ctrl + S
Save the currently selected tab to a new or existing file.
Ctrl + Shift + S
Save all tabs.
Alt + S
Save the currently selected tab as a new file.
F5
Compile and run the currently selected tab.
F6
Compile and debug the currently selected tab.
Pick a new pixel in the OpenGL view for debugging.
The Compiler Output
table summarizes all errors that occurred during compile and runtime time. A double click on the error will jump to the respective line in the code. Runtime errors are marked with a text in the line column, indicating at which runtime stage the error occurred (e.g., render
means the error occurred during rendering).
File
indicates in which file caused the error.
Line
indicates in which line in the file caused the error.
Description
of the raised error.
![](https://github.com/h3tch/ProtoFX/blob/master/App/resources/wiki/Debug Variables.png)
To debug an effect just hit F6
or press the Debug button. The code will be compiled the same way, but with debug information generated by the shaders. You can debug variables by surrounding them with the debug indicator <<variable_name>>
. Placing the caret in the respective line will show all debug variables of that line in the Debug Variables tab. Moving the mouse over a debug indicator will show the value of this variable for the specified primitives. To change the debug primitive (e.g., vertex index, fragment position), use the property editor in the Debug Variables tab. To change the debug fragment position you can also use the Debug Fragment picking tool. Just click on the button and move the cursor to the desired fragment position, then hit the left mouse button.
![](https://github.com/h3tch/ProtoFX/blob/master/App/resources/wiki/Resources Images.png) ![](https://github.com/h3tch/ProtoFX/blob/master/App/resources/wiki/Resources Buffers.png) The resource view ("Resources") allows you to view and inspect texture images and buffer data created by the compiled effect technique.
In the property view ("Properties") you can view and update class instances like cameras, lights and other extensions.
To search for a string in the active tab, press Ctrl + F
and start typing. The search will be case sensitive and search for whole words. The caret will change to a red color for as long as the application is in search mode.
To replace a certain string, either place the caret at a word or select a specific string in the code. Press Ctrl + R
to start replacing the word or selected string in the currently active tab. This can also be combined with the search functionality when pressing Ctrl + R
while in search mode.
Simply press Ctrl + Space
to open the code completion dialog. This dialog provides all possible keywords that could be used in the current situation. Note that errors in the code might cause the code completion dialog to provide wrong keywords or to not be shown at all.
ProtoFX *.tech
files consist of a list of so called objects which define how to allocate and initialize resources or how to bind them together. The order is critical! If an object references (binds) another object, the referenced object must have been defined before in the code. Code blocks defining objects have the following syntax (except for shader and text objects):
object_type object_name [annotation] {
command_type1 argument1 [argument2 argument3 ...]
[command_type2 argument1 [argument2 argument3 ...]]
[...]
}
Objects can be categorized as follows:
buffer
Allocate buffer memory on the GPU.
size
int_value
The size of the buffer memory in bytes (optional if a file with data is also specified). In case both, a file and size are set size bytes will be allocated.txt
txt_name
Loads data from the specified txt object (or file if a txt object is not present). Note, that the data will not by converted after loading (see also point Text Object).usage
usage_hint
Driver usage hint. See OpenGL documentation on glBufferData usage argument.xml
filename
node
Load data from the specified xml file. This command must specify the filename and the node-path to load. E.g.,xml "geom/cube.xml" data/position
.
image
Allocate image memory on the GPU.
size
int_value
The width and height of the image data to be allocated (optional if a file is also provided).depth
int_value
The depth of the image data to be allocated (optional if a file is also provided).length
int_value
Same asdepth
, but specifies an image array instead of a 3D image.file
filename0
[filename1 ...]
An image file (or files) to by loaded into memory. Each file is loaded into a new layer of the image.format
pixel_format
The texture format. Valid formats includer8, r8i, r8ui, r16, r16i, r16ui, r16f, r32i, r32ui, r32f, rg8, rg8i, rg8ui, rg16, rg16i, rg16ui, rg16f, rg32i, rg32ui, rg32f, rgb8, rgb8i, rgb8ui, rgb16, rgb16i, rgb16ui, rgb16f, rgb32i, rgb32ui, rgb32f, rgba8, rgba8i, rgba8ui, rgba16, rgba16i, rgba16ui, rgba16f, rgba32i, rgba32ui
andrgba32f
.type
texture_type
Optional. Can betexture1D, texture2D, texture3D, texture1DArray
ortexture2DArray
. Otherwise the type will be derived from width, height, depth and length.
Memory input objects define how data can be accessed by shaders.
vertinput
Specify how to access buffer objects as vertex stream.
attr
buffer_name
type_name
length
[stride offset divisor]
Attach a buffer object to a vertex attribute. attr can be specified multible times. Each time the attribute counter increases. So the first attribute specified by attr will have index 0, the second 1, and so on. buffer_name references an existing buffer object. type_name specifies the variable type (e.g., float, int, uint, short, ushort, ...). length the vector dimension of the type (e.g., 4 for vec4, 2 for vec2, 1 for float). stride specifies the stride between input vectors. offset specifies the offset into the buffer object where the first vector is located. divisor if specified, a vector will be used for divisor instances when using instanced drawing commands (see also here).
sampler
How to sample image data in a shader (optional).
magfilter
interpolation
How to interpolate image data if an image pixel is bigger than a screen pixel. Must be either linear (linear interpolation between neighboring pixels) or nearest.minfilter
interpolation
How to interpolate image data if an image pixel is smaller than a screen pixel. Must be either linear (linear interpolation between neighboring pixels), nearest, linearMipmapLinear (linear interpolation between neighboring pixels and linear interpolation between mipmaps), linearMipmapNearest, nearestMipmapLinear, nearestMipmapNearest.wrap
mode
Must be either clampToBorder, clampToEdge, mirroredRepeat or repeat (default).
texture
Which data shoud be accessed and how to access it in a shader.
buff
buffer_name
Bind a buffer object to the texture using the buffer object name. Either buff or img has to be provided.img
image_name
Bind a image object to the texture using the image object name. Either buff or img has to be provided.samp
sampler_name
Bind a sampler object to the texture using the sampler object name (optional).
vertoutput
Vertex output object (similar to OpenGL transform feedback). Used to store vertices from vertex or geometry shaders in buffer objects.
buff
buffer_name
Attach buffer as vertex output. Can be specified multible times. Each time the attribute counter increases. So the first attachment specified by buff will have index 0, the second 1, and so on.pause
bool_value
If set to true, writing to the buffer objects will be paused after rendering pass execution. When resuming writing, vertices will ba appended to the end of the already stored vertex data.resume
bool_value
Resume writing to the buffer objects when the rendering pass is executed. Only works if the vertex output object was set to pause by another rendering pass. Otherwise begin writing at buffer index 0.
fragoutput
Fragment output object (similar to OpenGL framebuffers). Used to write fragment shader output into an image object.
color
image_name
Attach image as color output. Can be specified multible times. Each time the attribute counter increases. So the first attachment specified by color will have index 0, the second 1, and so on.depth
image_name
Attach image as depth output.size
int_value
Optionally defines the width and height of the output image.
csharp
Compile external C# code.
file
"filename1"
["filename2" ...]
A list of filenames to be compiled.
instance
Instantiate and instance of a csharp code object.
class
csharp_name
class_name
Specify which class to instantiate. The class name must include the namespace (e.g.,external.code.Classname
).name
unique_name
The instance name of the object (optional, default is the name of the object). This name is used to set uniform variables and buffers.
Shader object are defined as follows:
shader shader_name [vert|tess|eval|geom|frag|comp] { /*GLSL code*/ }
vert
annotation specifies a vertex shader.tess
annotation specifies a tessellation control shader.eval
annotation specifies a tessellation evaluation shader.geom
annotation specifies a geometry shader.frag
annotation specifies a fragment shader.comp
annotation specifies a compute shader.
pass
Combine shaders and resources to create a rendering pass.
vert
shader_name
Vertex shader to be used in this pass.tess
shader_name
Tesselation control shader to be used in this pass.eval
shader_name
Tesselation evaluation shader to be used in this pass.geom
shader_name
Geometry shader to be used in this pass.frag
shader_name
Fragment shader to be used in this pass.comp
shader_name
Compute shader to be used in this pass. Note that a compute shader cannot be used in combination with any other shader.tex
texture_name
texture_unit
Bind a texture bject to the specified texture unit.samp
sampler_name
texture_unit
Bind a sampler object to the specified texture unit.fragout
fragoutput_name
Make the specified fragment output object the target for rendering results.vertout
vertoutput_name
Make the specified vertex output object the target for vertex output stream from the shaders.exec
instance_name
Use the specified instance in this pass. TheUpdate
method of the class will called after all OpenGL calls of the pass were executed.compute
num_group_x
num_group_y
[num_group_z]
Dispatch a compute call to execute a compute shader. A compute shader needs to be bound when using these functions (see also OpenGL documentation).compute
callbuffer_name
Dispatch an indirect compute call to execute a compute shader (see also OpenGL documentation).draw
vertinput_name
primitive_type
base_vertex
vertex_count
[base_instance instance_count]
Draw geometry using only a vertex buffer. primitive_type must be points, lines, lineLoop, lineStrip, triangles, triangleFan, triangleStrip or patch.draw
vertinput_name
indexbuffer_name
index_type
primitive_type
base_vertex
base_index
index_count
[base_instance instance_count]
Draw geometry using a vertex and index buffer. index_type must be ushort or uint.draw
vertinput_name
callbuffer_name
primitive_type
[buffer_offset]
[draw_count]
[stride]
Use indirect draw calls to draw geometry using only vertex buffers.draw
vertinput_name
indexbuffer_name
index_type
callbuffer_name
primitive_type
[buffer_offset]
[draw_count]
[stride]
Use indirect draw calls to draw geometry using vertex and index buffers.draw
vertoutput_name
primitive_type
[vertoutput_stream instance_count]
Draw geometry using the results stored in a vertex output object. vertoutput_stream lets you select an output stream other than 0.OpenGL Calls
Any OpenGL functions can be called in a pass to change the OpenGL state. They will be called in the order they were declared. To call an OpenGL function, you simple need to convert it from the formatglFunctionName(parameter0, parameter1, ...)
toglFunctionName parameter0 parameter1 ...
(the "gl" prefix is optional).
tech
Combines passes into a single rendering technique.
init
pass_name
Attach a initialization pass object to the technique object. init can be specified multiple times. Passes are then executed in the order they were listed. Initialization pass are executed before "normal" passes.pass
pass_name
Attach a pass object to the technique object. pass can be specified multiple times. Passes are then executed in the order they were listed.
text name [annotation] { /*Text*/ }
Define a text object that can be referenced by other objects. Text objects are typically used as data input.
#include "<filename>"
Include another file relative to the main file.
#define <keyword> <replacement>
Define a keyword that should be replaced.
Plugins can be writen in C# 4.0 compatible code. To be executable by ProtoFX, a class needs to provide at least
- a contructor of the format
public ClassName(string name, Dictionary<string, string[]> commandList) { ... }
where name is the name defined in the ProtoFX code and commandList is a dictionary of command keys and the respective argument lists. - an update method which will be called at the beginning of a pass
public void Update(int program, int width, int height, int widthTex, int heightTex) { ... }
where program is the OpenGL program ID (which can also identify a pass), width and height provide the size of the OpenGL backbuffer, and texWidth and texHeight provide the size of the current render target. - and a delete method which will be called when the program exits or is recompiled
public void Delete() { ... }
.
Optionally a public void EndPass(int program) { }
method can be provided, which will be executed at the end of a pass. To pass error string to ProtoFX, you can provide the method public List<string> GetErrors() { ... }
which will be called after instantiation of the class.
The ProtoFX/App/csharp folder contains several samples of ProtoFX extensions.