| synopsis || arguments || prev |
jpx_metanode insert_node( int num_codestreams, const int * codestream_indices, int num_compositing_layers, const int * layer_indices, bool applies_to_rendered_result, int num_regions, const jpx_roi * regions)
[Declared in "../apps/compressed_io/jpx.h"]
This function provides an especially convenient mechanism for creating new metadata nodes. Although it is possible to create the nodes directly using functions such as jpx_metanode::add_numlist and jpx_metanode::add_regions, multiple function calls may be needed to determine whether an appropriate association context has already been created.
The present function does all the work for you. It analyzes the existing metadata tree to see if it already contains a node which is associated with exactly the same set of image entities (codestreams, compositing layers or the rendered result). If so, the function returns a reference to that node or, if num_regions > 0, it returns a reference to a newly created ROI description node which is added as a descendant to that node.
If necessary, the function creates new entries in the metadata tree to hold a number list representing the image entities specified via the first five arguments and the image regions specified via the last two arguments, returning a reference to the relevant node.
If num_regions is 0, the returned node lies in a context which does not associated it with any image region. Otherwise, there must be at least one codestream specified, since ROI description boxes are meaningless unless associated with codestreams. If num_regions is non-zero, the function always creates a new ROI description node, even if an identical one already exists with the same image entity associations. This saves us the overhead of tracking down unlikely events.
If num_codestreams and num_compositing_layers are 0 and applies_to_rendered_result is false, the returned node lies in a context which does not associate it with any number list.
If both of the above sets of conditions apply, the function simply returns the root of the metadata tree.
Number of codestreams with which the returned node must be associated. It should be associated with no more and no fewer.
Array with num_codestreams entries containing the indices of the codestreams with which the returned node must be associated. All indices start from 0, which represents the first codestream in the file.
Number of compositing layers with which the returned node must be associated. It should be associated with no more and no fewer.
Array with num_compositing_layers entries containing the indices of the compositing layers with which the returned node must be associated. All indices start from 0, which represents the first compositing layer in the file.
True if the returned node is to be associated with the "rendered result"; otherwise it is not to be associated with the rendered result.
Number of elements in the regions array. If this is non-zero, the num_codestreams argument must also be non-zero, since the contents of an ROI description box are meaningless unless its regions are associated with some code-stream. If this argument is zero, the returned node is not to be associated with any image regions through ROI description boxes.
Array with num_regions entries, holding the collection of image regions which are to be recorded in an ROI description box with which the returned node is to be associated.