jpx_composition::add_instruction

Opaque pointer returned by add_frame.

Each instruction involves a single compositing layer, whose index is given here. 0 refers to the first compositing layer in the file. If the frame is to be repeated, this is the index of the compositing layer to use in the first repetition. Thereafter, the index is advanced by increment each time.

Ignored unless the frame is repeated. Each time the frame is repeated (see repeat_count argument to add_frame), the layer index is incremented by this value. Frame repetition stops immediately if the layer index grows beyond the number of layers available from the file. As an example, you might like to build a composite animation from a consecutive sequence of layers ( increment=1) which are composed onto a fixed background layer ( increment=0).

Note that there can be some weird sequences of layer increments which the internal machinery will not be able to represent efficiently. As a general rule, you should try to use only positive and zero-valued increments (although negative increments are not forbidden) and you should try to use the same increments for all instructions in the frame.

Specifies the cropped region within the compositing layer which is to be used by this instruction. The region is expressed on the compositing layer's registration grid, as described with jpx_layer_target::set_codestream_registration.

Specifies the region on the composition surface to which the cropped source region should be rendered. This may involve some scaling.

Note, however, that compositing applications might not necessarily support arbitrary scaling factors. Kakadu's powerful kdu_region_compositor object, for example, might not support anything other than integer-valued upsampling.