Parent Directory
| 
Revision Log
Revision 3 - (view) (download)
| 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 |