Kakadu Hyper-Doc (kdu_region_compositor::paint

virtual void paint_overlay( kdu_uint32 * buffer, kdu_dims buffer_region, int buffer_row_gap, kdu_dims bounding_region, int codestream_idx, jpx_metanode node, int painting_param, kdu_coords image_offset, kdu_coords subsampling, bool transpose, bool vflip, bool hflip, kdu_coords expansion, kdu_coords compositing_offset)

Synopsis

This function is called from the internal machinery whenever the overlay for some spatially sensitive metadata needs to be painted. The default implementation simply paints a shaded box into the relevant region of the overlay buffer. More sophisitcated implementations may override this function to paint more interesting overlays, possibly incorporating text labels.

The buffer argument provides the upper left hand corner of a raster scan overlay buffer, which represents the entire buffered area associated with a particular codestream. For reliable behaviour, you should confine your painting to the supplied bounding_region. The reason for this is that anything painted outside this region might not be correctly erased or repainted as the associated metadata region moves onto and off the overlay buffer surface (due to user panning, for example).

While detailed descriptions of the various arguments appear below, it is worth describing the geometric mapping process up front. Region sensitive metadata is always associated with specific codestreams, via an ROI description box. The ROI description box describes the regions on the codestream's high resolution canvas, with locations offset relative to the upper left hand corner of the image region on this canvas (the image region might not necessarily start at the canvas origin). By contrast, the overlay buffer's coordinate system is referred to a compositing reference grid, which depends upon compositing instructions in the JPX data source, as well as the current scale and orientation of the rendering surface. To map from an ROI description region, R, to the compositing reference grid, the following steps are required:

Add image_offset to all locations in R. This translates the region to one which is correctly registered against the codestream's high resolution canvas.
Divide the starting (or entry) coordinates Ex,Ey and ending (or finishing) coordinates Fx,Fy, by the factors in subsampling, rounding upwards. Here (Ex,Ey) corresponds to the upper left hand corner of the region, while the finishing coordinates are exclusive upper bounds to that (Fx-1,Fy-1) corresponds to the lower right hand corner of the region. The policy of dividing these coordinates and rounding upwards is the convention adopted by the JPEG2000 canvas coordinate system, as described in the book by Taubman and Marcellin.
Apply kdu_dims::to_apparent, supplying the transpose vflip and hflip parameters, in order to map the region coordinates to the orientatation currently being used for the rendering surface.
Multiply the coordinates of the region by the factors found in expansion.
Subtract compositing_offset from all region coordinates. Override this function to provide your own image buffer allocation. For example, you may want to allocate the image buffer as part of a system resource from which rendering to a display can be accomplished more easily or efficiently. Note that each pixel is represented by 4 bytes. You may allocate a larger buffer than the one requested, returning the actual buffer size via the actual_size argument. This reduces the likelihood that reallocation will be necessary during interactive viewing. Override this function to deallocate any resources which you allocated using an overridden allocate_buffer implementation.

Arguments

buffer [kdu_uint32 *]

Points to the upper left hand corner of the current overlay buffer. The size and organization of this buffer are described by the buffer_region and buffer_row_gap arguments. The overlay buffer has alpha, R, G and B components and is alpha blended with the image component associated with this overlay. When painting the buffer, it is your responsibility to write alpha, R, G and B values at each desired location. You are not responsible for performing the alpha blending itself. The organization of the four channels within each 32-bit word is as follows:

the most significant byte of the word holds the alpha value;
the second most significant byte holds the red channel value;
the next byte holds the green channel value; and
the least significant byte holds the blue channel value.

buffer_region [kdu_dims]

Region occupied by the overlay buffer, expressed on the compositing reference grid. See the description of region mapping conventions in the introduction to this function.

buffer_row_gap [int]

Separation between vertically adjacent entries in the buffer array.

bounding_region [kdu_dims]

Bounding rectangle, containing all of the regions described by the ROI description box associated with node. This bounding rectangle is not necessarily fully contained within the buffer_region, but they should intersect. It uses the same coordinate system as buffer_region — i.e., the compositing reference grid, as opposed to the codestream canvas.

codestream_idx [int]

Identity of the codestream with which this overlay is associated. Each overlay is associated with exactly one codestream, since region-specific metadata is always registered against the canvas of some codestream.

node [jpx_metanode]

This is guaranteed to represent an ROI description box. Use the jpx_metanode::get_regions member (for example) to recover the geometrical properties of the region. Use other jpx_metanode members to examine any descendant nodes, describing metadata which is associated with this spatial region. A typical implementation might look for label boxes, XML boxes or UUID boxes (with associated URL's) in the descendants of node.

painting_param [int]

This is a copy of the parameter supplied in the most recent call to configure_overlays. Your implementation may use this parameter to adjust the appearance of the overlay image.