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.

 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.

  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 as depth, 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 include r8, 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 and rgba32f.
• type texture_type
  Optional. Can be texture1D, texture2D, texture3D, texture1DArray or texture2DArray. 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. The Update 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 format glFunctionName(parameter0, parameter1, ...) to glFunctionName 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.