| synopsis || return value || arguments || prev || next |
bool add_compositing_layer( int layer_idx, kdu_dims full_source_dims, kdu_dims full_target_dims)
Java: boolean Add_compositing_layer( int layer_idx, Kdu_dims full_source_dims, Kdu_dims full_target_dims)
[Declared in "../apps/support/kdu_region_compositor.h"]
Use this function to build up a composited image from one or more layers. You must add at least one compositing layer, either directly or via set_frame, or else call set_single_component, before using this object to render imagery. You can add layers to or remove them from the composition at any time, although you should call get_composition_buffer again after you have finished modifying the layer configuration to get a buffer which will legitimately represent the composed imagery.
Regardless of whether the referenced layer has already be added, it will be placed at the end of the compositing list. Where multiple layers are to be composited together, they are rendered onto the composition surface in the order given by this list.
Note that this function may cause an error to be generated through kdu_error if composition is not possible (e.g. due to colour conversion problems), or if an error occurs while examining the embedded code-streams. For many applications, the implementation of kdu_error will throw an exception.
True if the requested compositing layer could be accessed within source with which the present object was opened. A false return occurs only when a JPX/JP2 data-source is served by a dynamic cache which does not currently contain sufficient information to open the compositing layer. If the requested layer simply does not exist, an error will be generated through kdu_error rather than returning false.
For JPX data sources, this is the index (starting from 0) of the compositing layer within that source. For raw code-streams, this argument must be 0.
Ignored if the data source is a raw code-stream (see below for what happens in this case).
For JP2/JPX sources, this argument identifies the portion of this layer which is to be used for compositing. This region is expressed on the layer's own reference grid, relative to the upper left hand corner of the layer image on that grid. The layer reference grid is often identical to the high resolution canvas of its code-stream (or code-streams). More generally, however, the layer reference grid is related to the code-stream canvas grids by the information returned via jpx_layer_source::get_codestream_registration.
If this region is empty ( full_source_dims.is_empty returns true), the entire source layer will be used for compositing.
If the data source is a raw code-stream, rather than a JP2/JPX wrapped set of code-streams, the full_source_dims and full_target_dims arguments are ignored and the composited image dimensions at full size (scale=1) are taken to be those of the first image component, rather than those of the high resolution canvas.
Ignored if the data source is a raw code-stream (see full_source_dims for an explanation of what happens in this case).
For JP2/JPX sources, this argument identifies the region of the composited image onto which the source region should be composited. Scaling may be involved, but the present implementation has only limited capability to handle scaling (up-scaling by integer factors and downscaling by exact powers of 2 are generally OK). The coordinates are expressed relative to the composited image which would be produced if it were rendered without any scaling (zooming), rotation, flipping or transposition. The actual composed image dimensions may be altered by the set_scale function.
| top || synopsis || return value || arguments || prev || next |