| synopsis || arguments || prev || next |
void apply_input_restrictions( int first_component, int max_components, int discard_levels, int max_layers, kdu_dims * region_of_interest)
Java: void Apply_input_restrictions( int first_component, int max_components, int discard_levels, int max_layers, Kdu_dims region_of_interest)
[Declared in "../coresys/common/kdu_compressed.h"]
This function may be used only with input codestreams (i.e., kdu_codestream created for reading from a compressed data source) or interchange codestreams ( kdu_codestream created without either a compressed source or a compressed target). It restricts the elements of the compressed image representation which will appear to be present. Since the function has an impact on the dimensions returned by other member functions, these dimensions may need to be re-acquired afterwards. The role of this function is closely related to that of the change_appearance member function; however, the latter function may be applied to output codestreams as well.
The function may be invoked multiple times to alter the region of interest, resolution, image components or number of quality layers visible to the user. However, after the first tile is opened, the function may be applied only to interchange codestreams or input codestreams which are set up in the persistent mode (see set_persistent). This is because non-persistent input codestreams discard compressed data and all associated structural elements (tiles, subbands, etc.) once we know that they will no longer be used — this information is based on the input restrictions themselves. Even in the persistent case, you may not call this function while any tile is open.
Zero valued arguments are always interpreted as meaning that any restrictions should be removed from the relevant parameter.
Identifies the index (starting from 0) of the first component to be presented to the user. If this is non-zero, any interface functions to this or any related object which accept component index arguments will add this first_component value to the component index in order to obtain the index of the true code-stream component which is being identified. An error message will be generated (through kdu_error) if first_component is greater than or equal to the total number of code-stream components.
Identifies the maximum number of components which will appear to be present, starting from the component identified by the first_component argument. If max_components is 0, all components will appear.
Indicates the number of highest resolution levels which will not appear to the user. Image dimensions are essentially divided by 2 to the power of this number. This argument affects the apparent dimensions and number of DWT levels in each tile-component. Note, however, that neither this nor any other argument has any effect on the parameter sub-system, as accessed through the kdu_params object (actually the head of a multi-dimensional list of parameter objects) returned by the access_siz function.
If discard_levels exceeds the number of DWT levels in some tile-component, it will still be possible to open the relevant tile successfully; however, any attempt to access the problem tile-component's resolutions ( kdu_tile_comp::access_resolution) will cause an error message to be generated through kdu_error. The minimum number of DWT levels across all tile-components is incrementally determined as tiles are opened; the current value is reported via the get_min_dwt_levels function.
Identifies the maximum number of quality layers which will appear to be present when precincts or code-blocks are accessed. A value of 0 has the interpretation that all layers should be retained.
If NULL, any region restrictions are removed. Otherwise, provides a region of interest on the high resolution grid. Any attempt to access tiles or other subordinate partitions which do not intersect with this region will result in an error being generated through kdu_error. Note that the region may be larger than the actual image region. Also, the region must be described in terms of the original code-stream geometry. Specifically any appearance transformations supplied by the change_appearance member function have no impact on the interpretation of the region. You may find the map_region member function useful in creating suitable regions.