| synopsis || return value || arguments || prev || next |
bool start( kdu_codestream codestream, kdu_channel_mapping * mapping, int single_component, int discard_levels, int max_layers, kdu_dims region, kdu_coords sampling, bool precise=false)
Java: boolean Start( Kdu_codestream codestream, Kdu_channel_mapping mapping, int single_component, int discard_levels, int max_layers, Kdu_dims region, Kdu_coords sampling, boolean precise)
[Declared in "../apps/support/kdu_region_decompressor.h"]
Prepares to decompress a new region of interest. The actual decompression work is performed incrementally through successive calls to process and terminated by a call to finish. This incremental processing strategy allows the decompression work to be interleaved with other tasks, usually to preserve the responsiveness of an interactive application. There is no need to process the entire region of interest established by the present function call; finish may be called at any time, and processing restarted with a new region of interest. This is particularly helpful in interactive applications, where an impatient user's interests may change before processing of an outstanding region is complete.
If mapping is NULL, a single image component is to be decompressed, whose index is identified by single_component. Otherwise, one or more image components must be decompressed and subjected to potentially quite complex mapping rules to generate channels for display; the relevant components and mapping rules are identified by the mapping object.
The region argument identifies the image region which is to be decompressed. This region is defined with respect to a rendering canvas. The rendering canvas might be identical to the high resolution canvas associated with the code-stream, but it is often different. Each of the code-stream image components involved in rendering colour image data must have integer sub-sampling factors relative to the rendering canvas. This constraint could be dropped without too much difficulty, although it would make the implementation significantly less comprehensible.
The sampling argument provides sub-sampling factors for the first channel described by mapping (or the single image component if mapping is NULL), relative to the rendering canvas. The sub-sampling factors for other channels and code-stream image components are automatically derived from the code-stream, but they must also be found to have an integer relationship to the rendering grid. This means that S_k*s_0 must be divisible by S_0, where the S_k are the code-stream sub-sampling factors, S_0 is the code-stream sub-sampling factor for the image component used to construct the first channel, and s_0 is the rendering sub-sampling factor supplied via the sampling argument. Of course, these relationships apply separately to each of the horizontal and vertical dimensions.
The individual image components may have additional registration offsets, specified in the code-stream. To clarify the relationship between these registration offsets and the rendering canvas, it is expected that all regions on the rendering canvas are derived with reference to the first channel described by mapping (or the single image component, if mapping is NULL) and its sub-sampling factors. Specifically, the upper-left point on the rendering canvas should have coordinates
where [y0,x0] are the coordinates of the upper-left point of the first channel or single image comonent. Also, the image dimensions on the rendering canvas should be sampling.y*Y by sampling.x*X where the first channel or single image component has dimensions Y by X.
False if a fatal error occurred and an exception (usually generated from within the error handler associated with kdu_error) was caught. In this case, you need not call finish, but you should generally destroy the codestream interface passed in here.
Interface to the internal code-stream management machinery. Must have been created (see codestream.create) for input.
Points to a structure whose contents identify the relationship between code-stream image components and the channels to be rendered. Any or all of the code-stream components may be involved in rendering channels; these might be subjected to a palette lookup operation and/or specific colour space transformations. The channels need not all represent colour, but the initial mapping→num_colour_channels channels do represent the colour of a pixel.
If the mapping pointer is NULL, only one code-stream image component is to be rendered, as a monochrome image; the relevant component's index is supplied via the single_component argument.
Ignored, unless mapping is NULL, in which case this argument identifies the code-stream image component (starting from 0) which is to be rendered as a monochrome image.
Indicates the number of highest resolution levels to be discarded from each image component's DWT. Each discarded level effectively halves the dimensions of each image component. Recall that the rendering canvas is determined by the dimensions of the image component used to construct the first channel, together with the sub-sampling factors specified through sampling. Thus, each discarded resolution level also halves the dimensions of the image on the rendering canvas.
Maximum number of quality layers to use when decompressing code-stream image components for rendering. The actual number of layers which are available might be smaller or larger than this limit and may vary from tile to tile.
Location and dimensions of the new region of interest, expressed on the rendering canvas. The location and dimensions of the unrestricted image on the rendering canvas are governed by the sub-sampling factors supplied by sampling, together with the location and dimensions of the code-stream component used to form the first channel described by mapping (or the single image component, if mapping is NULL).
Used to define the location and dimensions of the entire image, as it appears on the rendering canvas. This relationship is governed by the location and dimensions of the code-stream image component which is used to construct the first channel described by mapping (or the single image component, if mapping is NULL). See the general discussion above for details of this relationship.
Setting this argument to true encourages the implementation to use higher precision internal representations when decompressing image components. The precision of the internal representation is not directly coupled to the particular version of the overloaded process function which is to be used. The lower precision process function may be used with higher precision internal computations, or vice-versa, although it is natural to couple higher precision computations with calls to the higher precision process function.
Note that a higher precision internal representation may be adopted even if precise is false, if it is deemed to be necessary for correct decompression of some particular image component. Note also that higher precision can be maintained throughout the entire process, only for channels whose contents are taken directly from decompressed image components. If any palette lookup, or colour space conversion operations are required, the internal precision for those channels will be reduced (at the point of conversion) to 16-bit fixed-point with KDU_FIX_POINT fraction bits. Of course, most developers may remain blissfully ignorant of such subtleties, since they relate only to internal representations and approximations.
| top || synopsis || return value || arguments || prev || next |