IMPORT MODULE WRITING HOWTO

Some very short documentation on writing import modules for transcode

Definitions

The order of the definitions and headers in the import modules is important. Modules should have code like the following at the beginning of the source file.

 #define MOD_NAME      "import_foo.so"
 #define MOD_VERSION   "v0.0.1 (2005-01-01)"
 #define MOD_CODEC     "(video) foo | (audio) foo"
 #define MOD_AUTHOR    "John Q. Hacker <jqh at foo dot net>

Currently unused, and only for the source readers information. However, there are plans to use this information in tcmodinfo and possibly to create the manpage entries for the modules, so please define them.

 #include "transcode.h"

Defines vob_t and transfer_t structures (see 'data exchange structures' below). Also includes config.h and most system headers likely to be needed. transcode.h should always be the first included header file.

 #include "optstr.h"

Defines option handling methods.

 static int verbose_flag = TC_QUIET;

Defines the default verbosity of the module.

 static int capability_flag = TC_CAP_RGB | TC_CAP_YUV | TC_CAP_YUV422;

Defines the transcode core codecs this module decodes it's input to.

 #define MOD_PRE foo

Defines the prefix the MOD_ functions (see 'multiple function interface' below) will be renamed with.

 #include "import_def.h"

Uses MOD_PRE to define module functions.

 #ifdef HAVE_FOO_H
 #include <foo.h>
 #endif

Include any other headers the module may need last.

Data exchange structures

The following structures are available to core import module functions.

 typedef struct vob_s {
 /* see vob.h for details */
 } vob_t;
 
 typedef struct _transfer_t {
 
   int flag;            /* specifies context: TC_VIDEO for video 
                         *                    TC_AUDIO for audio
                         *
                         * or passes an integer to the module
                         */ 

   FILE *fd;            /* file handle for input stream   
                         * NULL if import module performs reading
                         */

   int size;            /* total amount of bytes in the buffer */
 
   char *buffer;        /* pointer to data array with frame data */
 
   char *buffer2;       /* pointer to data array with frame data (UNUSED) */
 
   int attributes;      /* HELP! */

 } transfer_t;

Multiple function interface

The following functions will be called in the following order.

 MOD_open

• Parameters: transfer_t param, vob_t vob
• Requested action: Return a file handle for reading from the pipe or return NULL if import modules handles data read
• Status: Required if following option is not implemented

 MOD_decode

• Parameters : transfer_t param, vob_t vob
• Requested action : Return a frame and the total amount of bytes read
• Status : Required if previous option is not implemented

 MOD_close

• Parameters : transfer_t param
• Requested action : Close streams or any open files, free memory and prepare module removal
• Status : Required

Exit codes

The following are all handled by transcode, and should be used when returning from the above core functions.

 TC_IMPORT_UNKNOWN

option not supported

 TC_IMPORT_OK

no error, hopefully the default

 TC_IMPORT_ERROR

a critical error occurred