[svn] / branches / dev-api-3 / xvidcore / doc / xvid-encoder.txt Repository:
ViewVC logotype

Annotation of /branches/dev-api-3/xvidcore/doc/xvid-encoder.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3 - (view) (download)
Original Path: trunk/xvidcore/doc/xvid-encoder.txt

1 : Isibaar 3 /*************************************************************
2 :     * Short explanation for the XviD data strutures and routines
3 :     *
4 :     * encoding part
5 :     *
6 :     * if you have further questions, visit http://www.xvid.org
7 :     *
8 :     **************************************************************/
9 :    
10 :     /* these are are structures/routines from xvid.h needed for encoding */
11 :    
12 :     --------------------------------------------------------------------------
13 :    
14 :     #define API_VERSION ((1 << 16) | (0))
15 :    
16 :     This is the revision of the xvid.h file that you have in front of you. Check it against the library's version.
17 :    
18 :     --------------------------------------------------------------------------
19 :    
20 :     typedef struct
21 :     {
22 :     int cpu_flags; [in/out]
23 :     int api_version; [out]
24 :     int core_build; [out]
25 :     } XVID_INIT_PARAM;
26 :    
27 :     This is filled by xvid_init with the correct CPU flags for initialization
28 :     (auto-detect), unless you pass flag to it (cpu_flags!=0). Do not use that
29 :     unless you really know what you are doing.
30 :     api_version can (should) be checked against API_VERSION, to see if you
31 :     have the right core library.
32 :    
33 :     Used in: xvid_init(NULL, 0, &xinit, NULL);
34 :    
35 :     --------------------------------------------------------------------------
36 :    
37 :     typedef struct
38 :     {
39 :     int width, height;
40 :     int fincr; // frame increment is relative to fbase
41 :     int fbase; // so each frame takes "fincr/fbase" seconds
42 :     int bitrate; // the bitrate of the target encoded stream, in bits/second
43 :     int rc_period; // the intended rate control averaging period
44 :     int rc_reaction_period; // the reaction period for rate control
45 :     int rc_reaction_ratio; // the ratio for down/up rate control
46 :     int max_quantizer; // the upper limit of the quantizer
47 :     int min_quantizer; // the lower limit of the quantizer
48 :     int max_key_interval; // the maximum interval between key frames
49 :     int motion_search; // the quality of compression ( 1=fastest, 6=best )
50 :     int lum_masking; // lum masking on/off
51 :     int quant_type; // 0=h.263, 1=mpeg4
52 :    
53 :     void * handle; // [out] encoder instance handle
54 :    
55 :     } XVID_ENC_PARAM;
56 :    
57 :     This structure has to be filled to create a new encoding instance:
58 :    
59 :     width and height are the size of the image to be encoded.
60 :    
61 :     fincr and fbase are the MPEG-way of defining the framerate.
62 :     If you have an integer framerate, say 24, 25 or 30fps, use
63 :     fincr=1, fbase=framerate.
64 :     However, if framerate is non-integer, like 23.996fps you can
65 :     e.g. multiply with 1000, getting fincr=1000 and fbase=23996,
66 :     giving you integer values again.
67 :    
68 :     rc-parameters are for ratecontrol, you don't have to change them,
69 :     good defaults are
70 :     rc_period = 2000 rc_reacton_period = 10 rc_reaction_ratio = 20
71 :    
72 :     min_quantizer, max_quantizer limit the range of allowed quantizers.
73 :     normally quantizers range is [1..31], so min=1 and max=31.
74 :     !!! the HIGHER the quantizer, the LOWER the quality !!!
75 :     !!! the HIGHER the quantizer, the HIGHER the compression ratio !!!
76 :    
77 :     min_quant=1 is somewhat overkill, min_quant=2 is good enough
78 :     max_quant depends on what you encode, leave it with 31 or lower it
79 :     to something like 15 or 10 for better quality (but encoding with
80 :     very low bitrate might fail then).
81 :    
82 :     max_key_interval is the maximum value of frames between two keyframe
83 :     (I-frames). Keyframes are also inserted dynamically at scene breaks.
84 :     It is important to have some keyframes, even in longer scenes, if you
85 :     want to skip position in the resulting file, because skipping is only
86 :     possible from one keyframe to the next. However, keyframes are much larger
87 :     than non-keyframes, so do not use too many of them.
88 :     A value of framerate*10 is a good choice normally.
89 :    
90 :     motion_search determines the quality of motion search done by the codec.
91 :     The better the search, the smaller the files (or the better the quality).
92 :     Since low modes (1-3) are hardly faster than high modes (4,5) a value of
93 :     5 is a good choice normally. 6 is possible, but a little slower. If you
94 :     want absolutely highest quality, use 6.
95 :    
96 :     lum_masking stand for "luminance masking" which is an experimental feature.
97 :     It tries to compress better by using facts about the human eye.
98 :     You might try to switch it on and decide yourself, if you gain anything from it.
99 :    
100 :     quant_type is technical, is changes the way coefficient are quantized.
101 :     Both values are okay, though a value of 0 might be faster.
102 :    
103 :     Used in: xerr = xvid_encore(NULL, XVID_ENC_CREATE, &xparam, NULL);
104 :    
105 :     --------------------------------------------------------------------------
106 :    
107 :    
108 :     typedef struct
109 :     {
110 :     void * bitstream; // [in] bitstream ptr
111 :     int length; // [out] bitstream length (bytes)
112 :    
113 :     void * image; // [in] image ptr
114 :     int colorspace; // [in] source colorspace
115 :    
116 :     int quant; // [in] frame quantizer (vbr)
117 :     int intra; // [in] force intra frame (vbr only)
118 :     // [out] intra state
119 :     } XVID_ENC_FRAME;
120 :    
121 :    
122 :     The main structure to encode a frame: image points to the picture,
123 :     in a format that is given by colorspace, e.g. XVID_CSP_RGB24 or
124 :     XVID_CSP_YV12.
125 :    
126 :     If you set quant=0, then the ratecontrol chooses quantizer for you.
127 :     If quant!=0, then this value is used as quantizer, so make 1<=quant<=31.
128 :    
129 :     intra decides where the frame is going to be a keyframe or not.
130 :     intra=1 means: make it a keyframe
131 :     intra=0 means: don't make it a keyframe
132 :     intra=-1 means: let encoder decide (based on contents and max_key_interval)
133 :    
134 :     So for an ordinary encoding step, you would set quant=0 and intra=-1.
135 :    
136 :     The length of the MPEG4-bitstream is returned in length, and
137 :     if you set intra to -1, it now contains the encoder's decision:
138 :     0 for non-keyframe,
139 :     1 for keyframe because of a scene change,
140 :     2 for keyframe because max_key_interval was reached.
141 :    
142 :     Used in: xerr = xvid_encore(enchandle, XVID_ENC_ENCODE, &xframe, &xstats);
143 :    
144 :     --------------------------------------------------------------------------
145 :    
146 :     typedef struct
147 :     {
148 :     int quant; // [out] frame quantizer
149 :     int hlength; // [out] header length (bytes)
150 :     int kblks, mblks, ublks; // [out]
151 :    
152 :     } XVID_ENC_STATS;
153 :    
154 :     In this structure the encoder return statistical data about the encoding
155 :     process, e.g. to be saved for two-pass-encoding.
156 :     quant is the quantizer chosen for this frame (if you let ratecontrol do it)
157 :     hlength is the length of the frame's header, including motion information etc.
158 :     kblks, mblks, ublks are unused at the moment.
159 :    
160 :     Used in: xerr = xvid_encore(enchandle, XVID_ENC_ENCODE, &xframe, &xstats);
161 :    
162 :     --------------------------------------------------------------------------
163 :    
164 :     int xvid_encore(void * handle,
165 :     int opt,
166 :     void * param1,
167 :     void * param2);
168 :    
169 :    
170 :     XviD uses a single-function API, so everything you want to do is done by
171 :     this routine. The opt parameter chooses the behaviour of the routine:
172 :    
173 :     XVID_ENC_CREATE: create a new encoder, XVID_ENC_PARAM in param1,
174 :     a handle to the new encoder is returned in handle
175 :    
176 :     XVID_ENC_ENCODE: encode one frame, XVID_ENC_FRAME-structure in param1,
177 :     XVID_ENC_STATS in param2 (or NULL, if you are not
178 :     interested in statistical data).
179 :    
180 :     XVID_DEC_DESTROY: shut down this encoder, do not use handle afterwards
181 :    

No admin address has been configured
ViewVC Help
Powered by ViewVC 1.0.4