[x264-devel] Major libx264 API change announcement

[Jason Garrett-Glaser]

To all developers,

libx264 API version 76 is going to be committed in one week.  It will
perform a major API change that requires code changes in all calling
applications.  The change will simplify most calling applications, but
it is a change nonetheless.

The purpose of this API change is to accommodate the fact that NAL HRD
requires knowledge of the final size of encoded NAL units--the size
after escaping is performed.  This cannot be calculated currently as
the NAL unit escaping is done by the calling application, not by
libx264 itself.  NAL HRD is not supported by libx264 yet, but
committing a fully correct implementation requires this API change.

The new system will have p_payload in x264_nal_t contain the
NAL-encapsulated data. i_payload will contain the number of bytes in
p_payload, including the startcode.  A new parameter will be added,
"b_annexb", which, if set (default), will result in startcodes being
placed in the data in p_payload.  If it is not set, a 4-byte size
(specifically, the size used by container such as mp4) will instead be
placed in that location.  x264_nal_encode will no longer be a publicly
accessible function.

Additionally, encoder_encode has been modified to return the total
size of all NAL unit payloads.  Combined with the fact that all NAL
unit payloads are guaranteed to be sequential in memory, this means
one can directly write the payload to a file with one or two lines of
code rather than having to iterate over NAL units.

Full API documentation of the changed structures and functions is as follows:

/* The data within the payload is already NAL-encapsulated; the ref_idc and type
 * are merely in the struct for easy access by the calling application.
 * All data returned in an x264_nal_t, including the data in
p_payload, is no longer
 * valid after the next call to x264_encoder_encode.  Thus it must be
used or copied
 * before calling x264_encoder_encode again. */
typedef struct
{
    int i_ref_idc;  /* nal_priority_e */
    int i_type;     /* nal_unit_type_e */

    /* Size of payload in bytes. */
    int     i_payload;
    /* If param->b_annexb is set, Annex-B bytestream with 4-byte startcode.
     * Otherwise, startcode is replaced with a 4-byte size.
     * This size is the size used in mp4/similar muxing; it is equal
to i_payload-4 */
    uint8_t *p_payload;
} x264_nal_t;

/* x264_encoder_encode:
 *      encode one picture.
 *      if i_nal > 0, returns the total size of all NAL payloads.
 *      returns negative on error, zero if no NAL units returned.
 *      the payloads of all output NALs are guaranteed to be
sequential in memory. */
int     x264_encoder_encode ( x264_t *, x264_nal_t **, int *,
x264_picture_t *, x264_picture_t * );

Note that the specifics are subject to change before the final commit
date.  In the case that they do, I will send out another update.

Dark Shikari