kdu_region_compositor::set_frame

Use this function to add an entire set of compositing layers, corresponding to a single frame provided by the jpx_composition object. For animations, you may use jpx_composition::get_next_frame to walk through the sequence of frames, passing each of them in turn to the present function.

Each frame may be further qualified by an iteration index which allows you to distinguish between repeated instances of the frame instructions. The value must be in the range 0 through R where R is the repeat count returned by jpx_composition::get_frame_info.

The function essentially just adds all of the relevant compositing layers in turn, as though you had explicitly called add_compositing_layer, moving all layers which are no longer required to the inactive list.

Since it does not permanently destroy any of the compositing layers which may have previously been in use, you may wish to invoke cull_inactive_layers after each successful return from the present function.

If none of the required compositing layers is available at the present time, the function returns false without affecting the existing set of installed compositing layers at all. This is convenient when working with client server applications, since it means that the existing frame can continue being rendered until the new frame becomes available.

If some of the required layers are available, but not all, the function returns false after removing all the old layers and installing the layers which it can.

If the function returns false because one or more compositing layers cannot be found, but there is some chance that they might become available later (e.g., if the ultimate data source is a dynamic cache which is waiting for more data to arrive from a remote server), the function sets incomplete_frame and incomplete_iteration to identify the most immediate frame whose compositing layers are still required. In many cases, these values will be the same as frame and iteration, meaning that some of the layers for the current frame are not yet available. However, it can happen that all of the frame's layers are already available, bu there is a previous persistent frame which must be composed with the current frame to obtain the complete result. If some of that frame's layers are not yet available from a dynamic cache, incomplete_frame and incomplete_iteration will be set to reference the relevant persistent frame. There can even be a chain of persistent frame dependencies, which must be resolved one by one. The reason for returning a reference to the most immediate frame whose layers are not all available is that this gives the application an informed opportunity to explicitly request those compositing layers from a server.

It can happen that the frame identifies some compositing layers which are not available and can never become available even if a server were to transfer more data to a dynamic cache, because they were not part of the original JPX data source. It is legal for a jpx_composition box to refer to such layers, so when this happens, the function does not generate an error through kdu_error (note that add_composition_layer does generate such an error if the layer does not exist). Instead, the function returns false, while setting incomplete_frame to NULL.

False if one or more compositing layers from the requested composition frame cannot be found within the file. Whether or not they might later become available as data is added to a dynamic cache may be determined by inspecting the value returned via the incomplete_frame argument.

frame [jx_frame *]

iteration [int]

incomplete_frame [jx_frame * &]

incomplete_iteration [int &]