xvid.h

mpeg4 video codec mpeg4 video codec

/* ------- v1.1.x ------- */
	int vbv_size;                 /* [in] buffer size (bits) */
	int vbv_initial;              /* [in] initial buffer occupancy (bits) */
	int vbv_maxrate;              /* [in] max processing bitrate (bits per second) */
	int vbv_peakrate;             /* [in:opt] max average bitrate over 3 seconds (bits per second) */

}xvid_plugin_2pass2_t;

/*****************************************************************************
 *                             ENCODER API
 ****************************************************************************/

/*----------------------------------------------------------------------------
 * Encoder operations
 *--------------------------------------------------------------------------*/

#define XVID_ENC_CREATE  0 /* create encoder instance; returns 0 on success */
#define XVID_ENC_DESTROY 1 /* destroy encoder instance; returns 0 on success */
#define XVID_ENC_ENCODE  2 /* encode a frame: returns number of ouput bytes
                            * 0 means this frame should not be written (ie. encoder lag) */


/*----------------------------------------------------------------------------
 * Encoder entry point
 *--------------------------------------------------------------------------*/

extern int xvid_encore(void *handle, int opt, void *param1, void *param2);

/* Quick API reference
 *
 * XVID_ENC_CREATE operation
 *  - handle: ignored
 *  - opt: XVID_ENC_CREATE
 *  - param1: address of a xvid_enc_create_t structure
 *  - param2: ignored
 *
 * XVID_ENC_ENCODE operation
 *  - handle: an instance returned by a CREATE op
 *  - opt: XVID_ENC_ENCODE
 *  - param1: address of a xvid_enc_frame_t structure
 *  - param2: address of a xvid_enc_stats_t structure (optional)
 *            its return value is asynchronous to what is written to the buffer
 *            depending on the delay introduced by bvop use. It's display
 *            ordered.
 *
 * XVID_ENC_DESTROY operation
 *  - handle: an instance returned by a CREATE op
 *  - opt: XVID_ENC_DESTROY
 *  - param1: ignored
 *  - param2: ignored
 */


/*----------------------------------------------------------------------------
 * "Global" flags
 *
 * These flags are used for xvid_enc_create_t->global field during instance
 * creation (operation XVID_ENC_CREATE)
 *--------------------------------------------------------------------------*/

#define XVID_GLOBAL_PACKED            (1<<0) /* packed bitstream */
#define XVID_GLOBAL_CLOSED_GOP        (1<<1) /* closed_gop:	was DX50BVOP dx50 bvop compatibility */
#define XVID_GLOBAL_EXTRASTATS_ENABLE (1<<2)
#if 0
#define XVID_GLOBAL_VOL_AT_IVOP       (1<<3) /* write vol at every ivop: WIN32/divx compatibility */
#define XVID_GLOBAL_FORCE_VOL         (1<<4) /* when vol-based parameters are changed, insert an ivop NOT recommended */
#endif
#define XVID_GLOBAL_DIVX5_USERDATA    (1<<5) /* write divx5 userdata string 
                                                this is implied if XVID_GLOBAL_PACKED is set */

/*----------------------------------------------------------------------------
 * "VOL" flags
 *
 * These flags are used for xvid_enc_frame_t->vol_flags field during frame
 * encoding (operation XVID_ENC_ENCODE)
 *--------------------------------------------------------------------------*/

#define XVID_VOL_MPEGQUANT      (1<<0) /* enable MPEG type quantization */
#define XVID_VOL_EXTRASTATS     (1<<1) /* enable plane sse stats */
#define XVID_VOL_QUARTERPEL     (1<<2) /* enable quarterpel: frames will encoded as quarterpel */
#define XVID_VOL_GMC            (1<<3) /* enable GMC; frames will be checked for gmc suitability */
#define XVID_VOL_REDUCED_ENABLE (1<<4) /* enable reduced resolution vops: frames will be checked for rrv suitability */
									   /* NOTE:  the reduced resolution feature is not supported anymore. This flag will have no effect! */
#define XVID_VOL_INTERLACING    (1<<5) /* enable interlaced encoding */


/*----------------------------------------------------------------------------
 * "VOP" flags
 *
 * These flags are used for xvid_enc_frame_t->vop_flags field during frame
 * encoding (operation XVID_ENC_ENCODE)
 *--------------------------------------------------------------------------*/

/* Always valid */
#define XVID_VOP_DEBUG                (1<< 0) /* print debug messages in frames */
#define XVID_VOP_HALFPEL              (1<< 1) /* use halfpel interpolation */
#define XVID_VOP_INTER4V              (1<< 2) /* use 4 motion vectors per MB */
#define XVID_VOP_TRELLISQUANT         (1<< 3) /* use trellis based R-D "optimal" quantization */
#define XVID_VOP_CHROMAOPT            (1<< 4) /* enable chroma optimization pre-filter */
#define XVID_VOP_CARTOON              (1<< 5) /* use 'cartoon mode' */
#define XVID_VOP_GREYSCALE            (1<< 6) /* enable greyscale only mode (even for  color input material chroma is ignored) */
#define XVID_VOP_HQACPRED             (1<< 7) /* high quality ac prediction */
#define XVID_VOP_MODEDECISION_RD      (1<< 8) /* enable DCT-ME and use it for mode decision */
#define XVID_VOP_FAST_MODEDECISION_RD (1<<12) /* use simplified R-D mode decision */
#define XVID_VOP_RD_BVOP              (1<<13) /* enable rate-distortion mode decision in b-frames */

/* Only valid for vol_flags|=XVID_VOL_INTERLACING */
#define XVID_VOP_TOPFIELDFIRST        (1<< 9) /* set top-field-first flag  */
#define XVID_VOP_ALTERNATESCAN        (1<<10) /* set alternate vertical scan flag */

/* only valid for vol_flags|=XVID_VOL_REDUCED_ENABLED */
#define XVID_VOP_REDUCED              (1<<11) /* reduced resolution vop */
											  /* NOTE: reduced resolution feature is not supported anymore. This flag will have no effect! */

/*----------------------------------------------------------------------------
 * "Motion" flags
 *
 * These flags are used for xvid_enc_frame_t->motion field during frame
 * encoding (operation XVID_ENC_ENCODE)
 *--------------------------------------------------------------------------*/

/* Motion Estimation Search Patterns */
#define XVID_ME_ADVANCEDDIAMOND16     (1<< 0) /* use advdiamonds instead of diamonds as search pattern */
#define XVID_ME_ADVANCEDDIAMOND8      (1<< 1) /* use advdiamond for XVID_ME_EXTSEARCH8 */
#define XVID_ME_USESQUARES16          (1<< 2) /* use squares instead of diamonds as search pattern */
#define XVID_ME_USESQUARES8           (1<< 3) /* use square for XVID_ME_EXTSEARCH8 */

/* SAD operator based flags */
#define XVID_ME_HALFPELREFINE16       (1<< 4)
#define XVID_ME_HALFPELREFINE8        (1<< 6)
#define XVID_ME_QUARTERPELREFINE16    (1<< 7)
#define XVID_ME_QUARTERPELREFINE8     (1<< 8)
#define XVID_ME_GME_REFINE            (1<< 9)
#define XVID_ME_EXTSEARCH16           (1<<10) /* extend PMV by more searches */
#define XVID_ME_EXTSEARCH8            (1<<11) /* use diamond/square for extended 8x8 search */
#define XVID_ME_CHROMA_PVOP           (1<<12) /* also use chroma for P_VOP/S_VOP ME */
#define XVID_ME_CHROMA_BVOP           (1<<13) /* also use chroma for B_VOP ME */
#define XVID_ME_FASTREFINE16          (1<<25) /* use low-complexity refinement functions */
#define XVID_ME_FASTREFINE8           (1<<29) /* low-complexity 8x8 sub-block refinement */

/* Rate Distortion based flags
 * Valid when XVID_VOP_MODEDECISION_RD is enabled */
#define XVID_ME_HALFPELREFINE16_RD    (1<<14) /* perform RD-based halfpel refinement */
#define XVID_ME_HALFPELREFINE8_RD     (1<<15) /* perform RD-based halfpel refinement for 8x8 mode */
#define XVID_ME_QUARTERPELREFINE16_RD (1<<16) /* perform RD-based qpel refinement */
#define XVID_ME_QUARTERPELREFINE8_RD  (1<<17) /* perform RD-based qpel refinement for 8x8 mode */
#define XVID_ME_EXTSEARCH_RD          (1<<18) /* perform RD-based search using square pattern enable XVID_ME_EXTSEARCH8 to do this in 8x8 search as well */
#define XVID_ME_CHECKPREDICTION_RD    (1<<19) /* always check vector equal to prediction */

/* Other */
#define XVID_ME_DETECT_STATIC_MOTION  (1<<24) /* speed-up ME by detecting stationary scenes */
#define XVID_ME_SKIP_DELTASEARCH      (1<<26) /* speed-up by skipping b-frame delta search */
#define XVID_ME_FAST_MODEINTERPOLATE  (1<<27) /* speed-up by partly skipping interpolate mode */
#define XVID_ME_BFRAME_EARLYSTOP      (1<<28) /* speed-up by early exiting b-search */

/* Unused */
#define XVID_ME_UNRESTRICTED16        (1<<20) /* unrestricted ME, not implemented */
#define XVID_ME_OVERLAPPING16         (1<<21) /* overlapping ME, not implemented */
#define XVID_ME_UNRESTRICTED8         (1<<22) /* unrestricted ME, not implemented */
#define XVID_ME_OVERLAPPING8          (1<<23) /* overlapping ME, not implemented */


/*----------------------------------------------------------------------------
 * xvid_enc_create_t structure definition
 *
 * This structure is passed as param1 during an instance creation (operation
 * XVID_ENC_CREATE)
 *--------------------------------------------------------------------------*/

typedef struct {
	int version;

	int profile;                 /* [in] profile@level; refer to XVID_PROFILE_xxx */
	int width;                   /* [in] frame dimensions; width, pixel units */
	int height;                  /* [in] frame dimensions; height, pixel units */

	int num_zones;               /* [in:opt] number of bitrate zones */
	xvid_enc_zone_t * zones;     /*          ^^ zone array */

	int num_plugins;             /* [in:opt] number of plugins */
	xvid_enc_plugin_t * plugins; /*          ^^ plugin array */

	int num_threads;             /* [in:opt] number of threads */
	int max_bframes;             /* [in:opt] max sequential bframes (0=disable bframes) */

	int global;                  /* [in:opt] global flags; controls encoding behavior */

	/* --- vol-based stuff; included here for convenience */
	int fincr;                   /* [in:opt] framerate increment; set to zero for variable framerate */
	int fbase;                   /* [in] framerate base frame_duration = fincr/fbase seconds*/
    /* ---------------------------------------------- */

	/* --- vop-based; included here for convenience */
	int max_key_interval;        /* [in:opt] the maximum interval between key frames */

	int frame_drop_ratio;        /* [in:opt] frame dropping: 0=drop none... 100=drop all */

	int bquant_ratio;            /* [in:opt] bframe quantizer multipier/offeset; used to decide bframes quant when bquant==-1 */
	int bquant_offset;           /* bquant = (avg(past_ref_quant,future_ref_quant)*bquant_ratio + bquant_offset) / 100 */

	int min_quant[3];            /* [in:opt] */
	int max_quant[3];            /* [in:opt] */
	/* ---------------------------------------------- */

	void *handle;                /* [out] encoder instance handle */
} xvid_enc_create_t;


/*----------------------------------------------------------------------------
 * xvid_enc_frame_t structure definition
 *
 * This structure is passed as param1 during a frame encoding (operation
 * XVID_ENC_ENCODE)
 *--------------------------------------------------------------------------*/

/* out value for the frame structure->type field
 * unlike stats output in param2, this field is not asynchronous and tells
 * the client app, if the frame written into the stream buffer is an ivop
 * usually used for indexing purpose in the container */
#define XVID_KEYFRAME (1<<1)

/* The structure */
typedef struct {
	int version;

	/* VOL related stuff
	 * unless XVID_FORCEVOL is set, the encoder will not react to any changes
	 * here until the next VOL (keyframe). */

	int vol_flags;                     /* [in] vol flags */
	unsigned char *quant_intra_matrix; /* [in:opt] custom intra qmatrix */
	unsigned char *quant_inter_matrix; /* [in:opt] custom inter qmatrix */

	int par;                           /* [in:opt] pixel aspect ratio (refer to XVID_PAR_xxx above) */
	int par_width;                     /* [in:opt] aspect ratio width */
	int par_height;                    /* [in:opt] aspect ratio height */

	/* Other fields that can change on a frame base */

	int fincr;                         /* [in:opt] framerate increment, for variable framerate only */
	int vop_flags;                     /* [in] (general)vop-based flags */
	int motion;                        /* [in] ME options */

	xvid_image_t input;                /* [in] input image (read from) */

	int type;                          /* [in:opt] coding type */
	int quant;                         /* [in] frame quantizer; if <=0, automatic (ratecontrol) */
	int bframe_threshold;

	void *bitstream;                   /* [in:opt] bitstream ptr (written to)*/
	int length;                        /* [in:opt] bitstream length (bytes) */

	int out_flags;                     /* [out] bitstream output flags */
} xvid_enc_frame_t;

#ifdef __cplusplus
}
#endif

#endif