Documentation/Display drivers
From PixieWiki
A display driver is a module (dll or so) that handles the image output. The renderer will essentially send the rendered tiles of the image to a display driver and then the driver can display or save them.
Contents |
[edit] Standard Display drivers
Pixie supports the following display drivers by default:
[edit] file, tiff, shadow drivers
This is the default display driver that saved the scene into a TIF file. This is the same driver as tiff and shadow (the renderer will replace those names with file). You can specify the compression method by:
Display "name" "file" "mode" "string compression" "compression"
Where compression argument is either one of NONE,LZW,JPEG or Deflate. If no compression is specified, the output file will be uncompressed. You can have Pixie generate a high dynamic range TIFF output by the following line:
Quantize "rgba" 0 0 0 0
Ps: Due to the LZW patent dispute, it may not be available on all platforms.
[edit] framebuffer driver
This driver will simply display the rendered image on the screen. The default background image is a checkerboard image. So if you have alpha channel in your output, the image will be composited automatically to the image generated by the renderer.
The latest Git sources have a new, significantly improved framebuffer for Windows platforms. See the build instructions for information on how to build Pixie on Windows.
See the documentation for the new Windows framebuffer for details.[edit] rgbe driver
This driver generates a Radiance PIC output. No compression is supported and the output image is always high dynamic range.
[edit] tsm driver
This driver stands for Transparency Shadow Map. tsm is very similar to Deep Shadow Maps. This driver will only save a shadow map which contains an opacity function for each pixel. So the output mode is ignored. In fact, this driver is hard-coded into the renderer. So there is no module for this driver. In general, for scenes with volumetric objects, this shadow map can be quite large. You can compress the generated shadow map by passing an opacity threshold by:
Display "name" "tsm" "mode" "float threshold" "t"
where t is the opacity threshold. The compressed file will not have an opacity error greater than this number. Unlike regular shadow maps, tsm can be filtered and can contain motion blur or depth of field effects as well as colored / transparent objects. If you have a scene with lots of transparent stuff casting transparent / colored shadows, this driver is strongly recommended.
[edit] OpenEXR driver
Outputs to OpenEXR format — a high quality HDR format which supports compression.
The optional argument "string compression" is one of
- RLE,
- ZIPS,
- ZIP,
- PIZ or
- PXR24.
Default compression mode is ZIP.
Example:
Display "name" "OpenEXR" "mode" "compression" "PIZ"
[edit] Custom Display Drivers
You can write your own display drivers to handle special processing. To do this, you need to create a module that exports the following three functions:
[edit] displayStart function
This function is called right after WorldBegin and should initialize your display driver.
void *displayStart(const char * name,
int width,
int height,
int numSamples,
const char * samples,
TDisplayParameterFunction parameterFunc);
[edit] Parameters
- name is the display name given by Display.
- width, height give the image size given by Format.
- The numSamples and samples argument give the number of samples per pixel and the textual definition of the samples given in Display.
For example:
Display "ri" "file" "rgb"
will call the displayStart function of the display driver file with numSamples=3, samples="rgb".
- parameterFunc can be used to fetch individual options or parameters given in the Display. The prototype for this function is defined in dsply.h in the include/ directory.
[edit] Return value
Applications should return an opaque handle that they can use to identify the display in the subsequent calls. Pixie does not use this handle.
A return value of NULL indicates an error. In this case, no data about this image will be sent to the driver and thus the remaining functions will not be called.
[edit] displayData function
This function is called to deliver data to the display driver.
int displayData(void * image,
int x,
int y,
int w,
int h,
float * data);
[edit] Parameters
- image is the opaque handle returned by displayStart.
- x, y give the coordinates of the top left corner of the tile and
- w, h give the width and height of the tile.
- data is a pointer to the raw image data in unclamped floating-point representation.
[edit] Remarks
The raw data is given in data where every float gives a sample (i.e. the first numSamples floats define the first pixel).
The renderer will always cover every pixel once and only once. However, the renderer makes no guarantees about the order or the size of the tiles (i.e. the renderer may change the tile size and send tiles out of order).
The data is not quantized or clamped to [0,1] before calling this function. It is the receiver's responsibility to do that.
On failure, the renderer will not send any more data and will not call your cleanup function below, so you should clean whatever data you allocated before returning.
This does not apply to the latest Git version: Do not attempt to free resources in this function, as they will be cleaned up in your displayFinish function. Freeing them in this function will lead to race conditions (and hence multiple destructions), since multiple threads will attempt to do so concurrently.[edit] Return value
This function must return 1 on success and 0 on failure.
[edit] displayFinish function
This function is called after WorldEnd to signal the driver that the rendering is complete and all the pixels have been sent. You may use this function to clean up any resources allocated in displayStart.
void displayFinish(void *image);
[edit] Parameters
- image is the opaque handle returned by displayStart.
[edit] Remarks
All resources allocated in displayStart should be freed here.
[edit] Misc Notes
Notice that displayStart is called in WorldBegin and displayFinish is called in WorldEnd.
A display driver must implement all three functions to be accepted by the renderer.
The implementation of the default display drivers file and framebuffer are provided in source distribution directory.
The parameters in the table below are always defined and the function parameterFunc will return them.
| Name | Type | Description |
|---|---|---|
| quantize | float[4] | The quantization(min,max,zero,one) |
| dither | float | The dithering amount |
| near | float | The near clipping plane |
| far | float | The far clipping plane |
| Nl | float[16] | Column major world to camera transformation matrix |
| Np | float[16] | Column major world to NDC transformation matrix |
Pixie supports opening multiple displays with any combination of global or user defined variable output types. So you can define a variable before the "Display" statement and use it as the output type. Note that if your shaders do not set this global output variable, the result will be garbage. You can also pass different quantization constants to different displays by specifying "custom" as the quantization type in "Quantize" call (i.e., Quantize "custom" 0 0 0 0 0). This will cause the last display to use this quantization settings.
[edit] Compiling
To compile your display driver, you need to include the dsply.h header. There are no special libraries needed to link against.
Using Visual C++, you can compile with:
cl /LD /I"%PIXIEHOME%\include" mydisplay.cpp
Using g++:
g++ -shared -I$PIXIEHOME/include -omydisplay.so mydisplay.cpp
