| synopsis || arguments || prev || next |
void copy_from( kdu_params * source, int source_tile, int target_tile, int instance=-1, int skip_components=0, int discard_levels=0, bool transpose=false, bool vflip=false, bool hflip=false)
Java: void Copy_from( Kdu_params source, int source_tile, int target_tile, int instance, int skip_components, int discard_levels, boolean transpose, boolean vflip, boolean hflip)
[Declared in "../coresys/common/kdu_params.h"]
This is a very powerful function, which is particularly useful in implementing code-stream transcoders. In the simplest case, the function copies the attributes of the source object into the current object (the target), generating an error if they do not belong to exactly the same derived class (same cluster name, attribute names and definitions).
Copying will not occur unless the source and target objects' tile indices agree with the source_tile and target_tile arguments, respectively, or the source and target objects are both cluster heads. In the latter case, the function automatically locates the tiles which match the source_tile and target_tile arguments before attempting a copy.
If you wish to copy information from all tiles simultaneously, you may use the copy_all function; in many applications, however, it is useful to be able to copy information on a tile-by-tile basis. In particular, if the source parameters are being discovered incrementally as a code-stream is being parsed (usually the case for transcoding operations), the copy_all function will not be appropriate, since information from some tile headers may not yet be available.
When the source and/or target object is the head of a list of tile-components for some tile, all corresponding components are copied, skipping over the first skip_components components of the source list (but not the target list).
If both objects are the heads of their respective instance lists, all instances are visited until one is found which agrees with instance, creating new instances for the target object if necessary. If instance is -1, all instances are copied from the source. If one or both objects is not the head of its instance list, at most that one object will be copied and then only if agreement can be reached with the value of the instance argument.
Finally, and most usefully, when either or both objects is the head of a list of parameter clusters, all corresponding clusters are visited and copied in accordance with the rules outlined above.
Note carefully that no kdu_params-derived object will be copied if the object has already had any record of any of its attributes set by any means. In this event, the object is skipped, but an attempt is still made to copy any other objects in the relevant lists, following the rules outlined above. The intent is to copy source objects into newly constructed (and hence empty) objects; however, the fact that individual objects will not be overwritten can come in handy when copying large parameter groupings, only some of which have already been set.
The actual copying operation is performed by the protected pure virtual function, copy_with_xforms, which must be implemented by each derived class. It is supplied the last 5 arguments, which may be used to modify the data as it is being copied.
Object from which to copy attributes, or head of list whose elements are to be copied, in accordance with the processing rules described above.
Tile index which must be matched by any source objects. As usual, a value of -1 refers to non-tile-specific source objects (i.e., those associated with the main code-stream header, as opposed to tile headers). See the discussion of tile indices and defaults in the comments appearing with the definition of the kdu_params object.
Tile index which must be matched by target objects — same interpretation as source_tile.
Instance index which must be matched by source and target objects, except that a value of -1 matches all instances.
Number of source image components to be skipped during copying. Source objects with a component index of c+ skip_components are copied to target objects with a component index of c. The special component indices of -1 (associated with tile heads, as described in the comments appearing with the declaration of kdu_params) are unaffected by this argument.
Indicates the number of DWT resolution levels which are to be discarded in a transcoding operation to produce a reduced resolution version of a compressed image.
Indicates whether or not horizontal and vertical coordinates of all dimensional and other related parameters are to be swapped so as to describe a transposed image (rows become columns and vice-versa).
If true, the target object will be adjusted to yield a vertically flipped version of the source representation. When transpose is used together with vflip, the interpretation is that the top-most row in the target representation should be equivalent to the right-most column in the source representation. That is, we think of first transposing the source and then flipping it afterwards.
If true, the target object will be adjusted to yield a horizontally flipped version of the source representation. When transpose is used together with hflip, the interpretation is that the left-most target column should be equivalent to the bottom-most source row. That is, we think of first transposing the source and then flipping it afterwards.