# Documentation/Display drivers

### From PixieWiki

< Documentation

# [edit] Custom Display Drivers

A display driver is a module [dll/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/save it.

To write a display driver, you need to create a [dll/so] that exports the following three functions:

    void    *displayStart(	const char *name,
        int width,
        int height,
        int numSamples,
        const char *samples,
        TDisplayParameterFunction parameterFunc);

This function is called right after WorldBegin and should initialize your display driver. Most of the parameters have obvious meanings: `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"`. The last parameter `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. The return value from this function is a transparent display handle. This handle will be used to identify the display in the subsequent calls. 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 functions below will not be called.

    int    displayData(	void *image,
        int x,
        int y,
        int w,
        int h,
        float *data);

This function is called to deliver data to the display driver. image is the transparent display handle returned by `displayStart`. The `x,y` parameters give the coordinates of the top left corner of the tile and w,h give the width and height of the tile.

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 raw data is given in data where every float gives a sample (i.e. first numSamples floats give the first pixel).

The data is not quantized or clamped to (0,1) before calling this function. It is the receiver's responsibility to do that. This function must return 1 on success and 0 on failure. On failure, the renderer will not send any more data and will not call the function below (So you should clean whatever data you allocated before returning).

New in 2.0.1

note: Care should be taken that `displayData` is thread safe. In 2.0.1 it may be called simultaneously by multiple threads. So if your function does anything that must be serialized - writing to file for example - then you must create a mutex in display start and lock it inside the `displayData` callback. The Pixie source code has some built in display drivers you can look to for ideas, and `libpixiecommon` provides some cross-platform mutex functions like `osCreateMutex` and `osLock`.

    void    displayFinish(void *image);

This function is called after `WorldEnd` to signal the driver that the rendering is complete and all the pixels have been sent. The image is the transparent display handle returned by `displayStart`. This function will 'not be called if `displayStart` returns `NULL` or if at any previous time `displayData` returns 0.

Notice that `displayStart` is called in `WorldBegin` and `displayFinish` is called in `WorldEnd`. 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. A display driver must implement all three functions to be accepted by the renderer. The following parameters are defined by default:

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] Stanard Display drivers

Pixie supports the following display drivers by default:

## [edit] file (tiff, shadow)

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

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.

## [edit] rgbe

This driver generates a Radiance PIC output. No compression is supported and the output image is always high dynamic range.

## [edit] tsm

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 heavily recommended.

## [edit] OpenEXR

Outputs to OpenEXR format - a high quality HDR format which supports compression

Retrieved from "http://www.george-graphics.co.uk/pixiewiki/Documentation/Display_drivers"

Category: Documentation

##### Views

- Article
- Discussion
- Edit
- History

##### Personal tools

- Log in / create account

##### Search

##### Toolbox

- What links here
- Related changes
- Upload file
- Special pages
- Printable version
- Permanent link