...

Bucket coordinates:

The xmin, ymin, xmax, and ymax fields give the coordinates of the bucket’s rectangle relative to the image. They are inclusive on the lower bounds and exclusive on the upper bounds. Note that due to filter padding, they may be negative or extend outside the image proper.

Read/write access:

The overloads of the Read() and Write() method allow the plugin to inspect and change the pixel data. The coordinates must be inside the bucket boundary or else a read will simply store a black result and a write will be silently ignored. Note that with multi-camera rendering not all possible channel ids found in the integrator environment may be valid during a given call to Filter(). The read and write functions will return false when called with a channel that is not valid for the current instance data.

Reading arbitrary regions:

Normally the read functions are only allowed to read pixels within the boundaries of the present bucket. However, for image processing operations that require a neighborhood it may be useful to be able to read from a enlarged set of pixels from around the bucket. The ReadRegion() offers the ability to fetch a copy of an arbitrary rectangle of pixels from anywhere in the framebuffer (with zero padding for pixels outside the image). Like Read(), it may fail for some channels. Note that due to multi-threading, successive calls to ReadRegion() may produce different results (and different results from the equivalent Read()) as other rendering threads may continue to update the framebuffer and this may produce transitory bucket artifacts if a display filter does not take care. By contrast, the standard Read() and Write() calls work on data locked to the current thread and so are stable. See the source to the PxrEdgeDetect plugin in the examples bundle for a use of this call.

Access to other filters:

The IsEnabled() call allows a display filter plugin to get a pointer to the instance data for another plugin instance and determine if that instance is currently enabled. This allows one Filter() invocation to recursively invoke another filter instance's Filter() function. See the source to the PxrDisplayFilterCombiner in the examples bundle for using use of this to chain together plugins.