jpx_target::write_headers

Call this function once all codestreams, compositing layers and composition instructions have been added, and sufficiently initialized. The function scans the various parameters to be written into JPX boxes, reorganizing the information if possible, so as to try to ensure that the generated file is JPX compatible and maximize the likelihood that it can also be JP2 compatible.

All of the fixed-position headers are then written, including the JP2 signature box, the file-type box, the reader requirements box and the JP2 header box.

If codestream_threshold < 0, all codestream header boxes and compositing layer header boxes will also be written at this point. Otherwise, the function writes all codestream header boxes, up to and including the one corresponding to the codestream whose index is codestream_threshold (indices run from 0), and all compositing layer header boxes, up to and including the first one whose compositing layer uses the codestream whose index is codestream_threshold.

When used in this way, the function returns true once it has written this limited set of headers, leaving the application to call the function again, with a larger value of codestream_threshold, once it is prepared to write later codestreams. In this way, compositing layer and codestream header boxes may be interleaved with the contiguous codestream or fragment table codestream boxes.

If you have installed a breakpoint using one of the functions jpx_codestream_target::set_breakpoint or jpx_layer_target::set_breakpoint, the present function will return prematurely, with a pointer to the open super-box (either a Codestream Header (chdr) box, or a Compositing Layer Header (jplh) box) associated with the context in which the breakpoint was installed. In this case, the function must be called again, until all breakpoints have been passed.

NULL if the requested headers have been completely written. This does not necessarily mean that the function need not be called again. Indeed, it may need to be called again if the number of codestreams to be written is greater than codestream_threshold+1. As explained above, this allows codestream header boxes and compositing layer header boxes to be interleaved with the codestream data itself.

A non-NULL return means that a breakpoint has been encountered, which usually means that the application should write some custom box as a sub-box of the open returned super-box, before invoking write_headers again.

i_param [int *]

addr_param [void **]

codestream_threshold [int]