Dark Shikari
16th September 2009, 08:00
Note: this only applies to users of libx264, not the built-in x264 frontend. The interface provided by the built-in x264 frontend will remain unchanged.
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 post another update.
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 post another update.