[XviD-devel] versioning

[peter ross]

currently we're at api version 2.1. when bframes are undef'd the next 
release will probably be 3.0. i propose we implement a proper versioning 
system, such that we can provide true "api backward compatibility"


version numbers
===============

currently we have MAJOR.MINOR notion, but its not being used correctly.

MAJOR : represents a significant api change; api is not backward compatible
MINOR : represents a small api change; api remains compatible

#define XVID_VERSION(A,B)       ((A) << 16) | (B))
#define XVID_API_VERSION	XVID_VERSION(3,0)


version field
=============
all xvid api structures will include a "version" field, such that xvidcore 
can identify what the application supports.

example.


aplication-v30.c
	xparam.version = XVID_VERSION(3,0);


aplication-v31.c
	xparam.version = XVID_VERSION(3,1);
	xparam.blah = 123;


aplication-v32.c
	xparam.version = XVID_VERSION(3,2);
	xparam.blah = 123;
	xparam.blah2 = 456;


encoder.c
	if (xparam.version && 0xff != 3)
	{
		return XVID_ERR_VERSION;
	}

	...

	if (xparam.version >= XVID_VERSION(3.1)) {	/* version test */
		pEnc->blah = xparam.blah
	} else {
		pEnc->blah = some_default_value;
	}


applications should hard-code the version number (as above) *instead* of 
using xparam.version = XVID_API_VERSION. when an application supports an 
older api version than xvidcore, default values are used. when an 
application supports a new api version than xvidcore, the new fields in the 
structure are ignored.



api modifications
=================
if your new xvid feature/patch requires an api modification, follow these 
simple rules:

- increment the minor version number by 1
- append your api field(s) to the end-of the api structure.
- NEVER remove an api field from the structure; if you nolonger need it, 
just ignore it
- perform a version test before accessing the field as demonstrated above in 
encoder.c (if necessary provide a default value)

some api modifications, like bframes, will break api-compatibility. in this 
case we would have no choice but to increment the major version number. 
whenever we do this, we can also:
- reset the minor version to zero & remove prior version tests
- remove deprecated(usused) fields, and/or reorganise the structures for 
readability


-- pete



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