[XviD-devel] XVID API v3.0

[peter ross]

here's my suggested changes to the xvid api.


API modification list
---------------------

* define a XVID_MAKE_VERSION(A,B) macro; rename API_VERSION to
  XVID_VERSION and set the value to XVID_MAKE_VERSION(3,0)

* make XVID_ERR_FAIL a positve value; such that the whole api is in
  the positive domain.

* add an XVID_ERR_VERSION, which indicates the structures provided are
  not supported.

* maybe: add XVID_ERR_NOTIFY, which is notifies the calling application
  to do something. in the case of the decoder, this would be
  notification of a video-image dimensions change. we also need to
   define a XVID_DEC_STATS structure to store such data as width,
   height, low_delay and any other info the decoding application might
   need.
  the encoder probably doesnt need to notifiy the encoding application?

* remove the _SMP #defs
* num_threads should remain in the API even if pthreads is not linked.
* maybe: include a XVID_CPU_THREADS flag in xinit.cpu_flags, which is
  set when xvid is linked with pthreads??

* remove BFRAMES #defs
* add XVID_GLOBAL_BFRAMES to enable the bframes encoder, such that
  nolonger need max_bframes=-1.
  NOTE: its better that we merge the two encoders() together, however
  this sounds like an good interim solution?

* replace bquant_ratio with bquant_ratio_a & bquant_ratio_b.
  the new bframe-quantizer forumula will be a linear function:
     bquant =  AVG(past_quant + future_quant) * bquant_ratio_a + 
bquant_ratio_b

* add stride field to XVID_ENC_FRAME

* add a XVID_DEC_FRAME field to describe the time base/increment
* add a XVID_DEC_FRAME field to tell the application to skip/dont-
  display this frame (e.g. to avoidbframe lag)
  NOTE: we need suggestions on what to call these fields ??

* each structures includes a 'version' field.
* rename init.version to 'init.max_supported_version'
* maybe: replace XVID_CPU_CHKONLY with something else ??


API versioning and extension rules
----------------------------------
all structures include a 'version' field and take the form

	typedef struct
	{
	    int version;

	    int fields...;                /* version [int/out/opt] desc */

	    struct {
	        int extended_fields...;   /* version [int/out/opt] desc */
	    } ext;
	} XVID_CONTEXT_NAME;


* the version field informs core what version the application is using

* "fields" are data fields which are found in the inital major-version
  of the api release. eg. v3.0

* "extended_fields" are data fields which have been added in minor-
  version api releases. eg. v3.1. these fields are always considered
  optional by the calling application.

* comments beside each field should indicate
    - the version in which the field first appeared
    - the input/output/optional semantics of the field
   - a brief description.

minor-release (or "new") fields can only be appended to the ext sub-
structure. when reading the field from the strucutre, the version
field should be checked inthis manner.

    if (struct.api_version >= XVID_MAKE_VERSION(3,1)) {
       read/do-something-with struct.ext.field
    } else {
       dont read the field & disable the relevant functionality
    }

    very important to remain backwards compatible & future proof:
    if the field vale is ZERO, or the field not supported in the
    specified version, the functionality associated with the field should be 
disabled.

   optional fields are just that, means that the calling application
   does not have to set them (they are zero'd by memset). e.g.:
   encoder_param.width and height, bitstream, image are required,
   however fields like min_quantizer/max_quantizer and frame drop
   ratio are NOT. iam not sure how far we wish to take this ???


API usage rules
---------------

1. always perform a memset(&structure, 0, sizeof(structure)) and
   set structure.version = XVID_VERSION.
   this ensures all optional and unknown fields are disabled.

2. all mandatory/non-optional fields _must_ be set

3. call xvid_init() before calling anything else


-- pete

_________________________________________________________________
Join the world’s largest e-mail service with MSN Hotmail. 
http://www.hotmail.com