]> hackersguide GünterBartsch HeikoSchäfer RichardWareham 2001-2002 the xine project team This document should help xine hackers to find their way through xine's architecture and source code. It's a pretty free-form document containing a loose collection of articles describing various aspects of xine's internals. &intro; The source directory in xine-lib contains several modules, this should give you a quick overview on where to find what sources: The heart of xine - it's engine. Contains code to load and handle all the plugins, as well as the generic decoding and synchroniation/output code. Audio output plugins, these provide a thin abstraction layer over different types of audio output architectures/platforms. Basically an audio output plugin provides functions to query/setup the audio hardware and output audio data (e.g. PCM samples). Demuxer plugins that handle various system layer file formats like avi, asf or mpeg. Code specific to the dxr3 / hollywood+ hardware mpeg decoder. Dolby digital audio decoder plugin. Video decoder plugin using libdivx4linux if it is installed. Audio decoder plugin that does nothing but passing through DTS (AC5) data to the audio output plugin. This is only usefull when using an external hardware DTS decoder. Various Audio/Video decoder plugins based on ffmpeg; most importantly this contains a free mpeg-4 video decoder. Audio decoder plugin that "decodes" raw PCM data; most notably endianess-conversions are done here. Mpeg audio decoder plugin (i.e. mp3 decoding). Quite slow and due to be replaced by ffmpeg's mp3 decoder. Most important mpeg video decoder plugin, provides fast and high-precision mpeg-1/2 video decoding. Various subtitle (spu: subpicture, dvd slang) decoder plugins. Vorbis audio decoder plugin. Video/Audio decoder plugins that exploit some wine code to use win32 (media player) codecs in xine. Works on x86 platforms only. Contains various video output driver plugins. Video output drivers are thin abstraction layers over various video output platforms (e.g. X11, directfb, directX,...). Video output driver plugins provide functions like frame allocation and drawing and handle stuff like hardware acceleration, scaling and colorspace conversion if necessary. They do not handle a/v sync since this is done in the xine-engine already. collection of utility functions and platform abstractions. deprecated. xine architecture Media streams usually consist of audio- and video-packages multiplexed into one bitstream in the so-called system-layer (e.g. AVI, Quicktime or Mpeg). A demuxer plugin is used to parse the system layer and extract audio- and video- packages. The demuxer uses an input-plugin to read the data and stores it in pre-allocated buffers from the global buffer pool. The buffers are then added to the audio- or video- fifo. From the other end of these fifos audio-/video-decoder threads remove the buffers and hand them over to the current audio- or video- decoder plugin for decompression. These plugins then send the decoded data to the audio-/video- output layers. The buffer holding the encoded data is no longer needed and thus released to the global buffer pool. xine uses a lot of design principles normally found in object oriented designs. As xine is written in c, a few basic principles shall be explained here on how xine is object oriented anyway. classes are structs containing (ideally only) function pointers in xine. Example: typedef struct my_stack_s my_class_t; struct my_stack_s { /* method "push" with one parameter and no return value*/ void (*push) (my_stack_t *this, int i); /* method "add" with no parameters and no return value */ void (*add) (my_stack_t *this); /* method "pop" with no parameters (except "this") and a return value */ int (*pop) (my_stack_t *this); } ; /* constructor */ my_class_t *new_my_stack (...); to implement such a "class", frequently "private" member variables can be added: typedef struct { my_stack_t stack; /* public part */ /* private part follows here */ int values[MAX_STACK_SIZE]; int stack_size; } intstack_t; each method is implemented as a static method (static to prevent namespace pollution). The "this" pointer needs to be cast to the private pointer type to gain access to the private member variables. Implementation of the "push" method follows: static void push (my_stack_t *this_gen, int i) { intstack_t *this = (intstack_t *) this_gen; } Finally the contructor mallocs() the data structs (private variant) and fills in function pointers and default values. Usually the constructor is the only public (i.e. non-static) function in the module: my_stack_t *new_my_stack (...) { intstack_t *this; /* alloc memory */ this = malloc (sizeof (intstack_t)); /* fill in methods */ this->push = push; this->add = add; this->pop = pop; /* init data fields */ this->stack_size = 0; /* cast & return */ return (my_stack_t *) this; } Metronom serves two purposes: generate vpts (virtual presentation time stamps) from pts (presentation time stamps) for a/v output and synchronization provide a master clock (system clock reference, scr), possibly provided by external scr plugins (this can be used if some hardware decoder or network server dictates the time) pts/vpts values are given in 1/90000 sec units. pts values in mpeg streams may wrap, can be missing on some frames or (for broken streams) may "dance" around the correct values. Metronom therefore has some heuristics built-in to generate clean vpts values which can then be used in the output layers to schedule audio/video output. The heuristics used in metronom have always been a field of research. xine plugins are built as shared libraries that export at least one public function named init_type_plugin, where type reflects the function of the plugin (video, audio, etc). This function returns a pointer to freshly allocated (typically via malloc()) structure containing mainly function pointers; these are the "methods" of the plugin. If you think this is pretty much an object-oriented aproach, then you're right. All plugins are installed in a special xine plugins directory which can be found using the xine-config --plugindir command. You'll find exact definitions of public functions and plugin structs in the appropriate header files for each plugin type (e.g. demux/demux.h, input/input_plugin.h, xine-engine/video_out.h, etc) within the xine source-code. Many plugins will need some additional "private" data fields. These should be simply added at the end of the plugin structure. For example a demuxer plugin called "foo" with two private fields "xine" and "count" may have a plugin structure declared in the following way: typedef struct { /* public fields "inherited" from demux.h */ demux_plugin_t demux_plugin; xine_t *xine; int count; } demux_foo_t; The plugin would then access public fields via the demux_plugin field and private fields directly. Use an existing demuxer plugin, e.g. demux_mpeg_block as an example. Demuxers need to start/stop their own thread for performance reasons (input plugins may block and if the demuxer runs in a seperate thread other xine modules can work during blocking time). You need to implement all the functions given in demux.h: struct demux_plugin_s { /* * plugin interface version, lower versions _may_ be supported */ int interface_version; /* * ask demuxer to open the given stream (input-plugin) * using the content-detection method specified in "stage" * * return values: * DEMUX_CAN_HANDLE on success * DEMUX_CANNOT_HANDLE on failure */ int (*open) (demux_plugin_t *this, input_plugin_t *ip, int stage); /* * start demux thread * * for seekable streams, a start position can be specified * * start_pos : position in input source * start_time : position measured in seconds from stream start * * if both parameters are !=0 start_pos will be used * for non-seekable streams both values will be ignored */ void (*start) (demux_plugin_t *this, fifo_buffer_t *video_fifo, fifo_buffer_t *audio_fifo, off_t start_pos, int start_time); /* * stop & kill demux thread, free resources associated with current * input stream */ void (*stop) (demux_plugin_t *this) ; /* * close demuxer, free all resources */ void (*close) (demux_plugin_t *this) ; /* * returns DEMUX_OK or DEMUX_FINISHED */ int (*get_status) (demux_plugin_t *this) ; /* * return human readable identifier for this plugin */ char* (*get_identifier) (void); /* * return MIME types supported for this plugin */ char* (*get_mimetypes) (void); /* * estimate stream length in seconds * may return 0 for non-seekable streams */ int (*get_stream_length) (demux_plugin_t *this); } ; Demuxer plugins export only one function: demux_plugin_t *init_demux_plugin (int iface_version, xine_t *xine); this is called on startup when the demuxer plugin is loaded. The funtion should malloc() a demux_plugin_t* pointer, fill in the function pointers and return the demux_plugin_t * pointer. Many media players expect streams to be stored within files on some local medium. In actual fact, media may be streamed over a network (e.g. via HTTP or RTP), encoded onto a specialist medium (e.g. DVD), etc. To allow you to access this media, xine supports the concept of an "input plugin". The tasks performed by an input plugin are: Validation of Media Resource Locators (MRLs). MRL specific session management (e.g. opening and closing local files). Reading blocks/specific numbers of bytes from the input device. In addition to these tasks, the input plugin may keep track of some input device-specific state information (e.g. a DVD plugin may keep track of navigational state data such as current title/chapter). There are two classes of input device which xine recognises. Byte-oriented devices can, upon request, return an arbitary non-zero number of bytes from a stream. Examples of such devices are files or network streams. Block-oriented devices, however, have a prefered block or "frame"-size. An example of such a device is a DVD where data is stored in logical blocks of 2048 bytes. One may pass the hint to xine that the plugin is block-oriented by setting the INPUT_CAP_BLOCK capability. Note that this is only a hint and xine does not guarantee that all requests to the plugin will be purely block based. The input plugin should export at least the following function: input_plugin_t *init_input_plugin (int iface, xine_t *xine) The iface parameter is the input plugin interface xine is requesting (as of writing this is '5'). The xine parameter is a pointer to the global xine_t for this session. The function should return a pointer to an allocated input_plugin_t (defined in xine/input_plugin.h) which has the following definition: struct input_plugin_s { /* * plugin interface version, lower versions _may_ be supported */ int interface_version; /* * return capabilities of input source */ uint32_t (*get_capabilities) (input_plugin_t *this); /* * open input MRL - return 1 if succ */ int (*open) (input_plugin_t *this, char *mrl); /* * read nlen bytes, return number of bytes read */ off_t (*read) (input_plugin_t *this, char *buf, off_t nlen); /* * read one block, return newly allocated block (or NULL on failure) * for blocked input sources len must be == blocksize * the fifo parameter is only used to get access to the buffer_pool_alloc function */ buf_element_t *(*read_block)(input_plugin_t *this, fifo_buffer_t *fifo, off_t len); /* * seek position, return new position * * if seeking failed, -1 is returned */ off_t (*seek) (input_plugin_t *this, off_t offset, int origin); /* * get current position in stream. * */ off_t (*get_current_pos) (input_plugin_t *this); /* * return length of input (-1 => unlimited, e.g. stream) */ off_t (*get_length) (input_plugin_t *this); /* * return block size of input source (if supported, 0 otherwise) */ uint32_t (*get_blocksize) (input_plugin_t *this); /* * ls function * return value: NULL => filename is a file, **char=> filename is a dir */ mrl_t** (*get_dir) (input_plugin_t *this, char *filename, int *nFiles); /* * eject/load the media (if it's possible) * * returns 0 for temporary failures */ int (*eject_media) (input_plugin_t *this); /* * return current MRL */ char * (*get_mrl) (input_plugin_t *this); /* * stop input source */ void (*stop) (input_plugin_t *this); /* * close input source */ void (*close) (input_plugin_t *this); /* * return human readable (verbose = 1 line) description for this plugin */ char* (*get_description) (input_plugin_t *this); /* * return short, human readable identifier for this plugin * this is used for GUI buttons, The identifier must have max. 4 characters * characters (max. 5 including terminating \0) */ char* (*get_identifier) (input_plugin_t *this); /* * generate autoplay list * return value: list of MRLs */ char** (*get_autoplay_list) (input_plugin_t *this, int *nFiles); /* * request optional data from input plugin. */ int (*get_optional_data) (input_plugin_t *this, void *data, int data_type); /* * check if it is possible/valid to directly branch to this MRL * optional: may be NULL */ int (*is_branch_possible) (input_plugin_t *this, char *next_mrl); }; Typically the init_input_plugin function will initialise all these parameters. The get_capabilities parameter points to a function which returns a bit mask describing the input device's capabilities. You may logically OR the following constants together to get a suitable bit-mask (via the '|' operator). INPUT_CAP_NOCAP -- Input device has no capabilities (alias for '0'). INPUT_CAP_SEEKABLE -- Input device may be 'seeked' (i.e. random access is possible, usually not available on, e.g., network streams). INPUT_CAP_BLOCK -- Input device has a prefered block size (i.e. is block-oriented). INPUT_CAP_AUTOPLAY -- Device can return an 'autoplay' list. INPUT_CAP_GET_DIR -- Device supports the concept of 'directorys' or 'folders' containing other MRLs. INPUT_CAP_BROWSABLE -- Device supports possible MRL enumeration and browsing via the MRL browser. INPUT_CAP_CLUT -- Somewhat of an obsolete kludge. Device supports the querying of sub-picture-unit colour palettes. INPUT_CAP_AUDIOLANG -- Device supports multiple audio streams with different names. INPUT_CAP_SPULANG -- Device supports multiple sub-picture-unit (SPU) streams with different names. INPUT_CAP_VARIABLE_BITRATE -- xine may not experimentally read from the plugin in order to guestimate bit-rate. The open parameter points to a function which accepts an MRL and returns a flag indicating whether this plugin accepts the MRL or not. Note that input plugins are not guaranteed to be queried in anay particular order and the first input plugin to claim an MRL gets control so try not to duplicate MRLs already found within xine. You should also do any device-specific initialisation within this function. The close parameter points to a function which cleans up after open. The read reads a specified number of bytes into a buffer and returns the number of bytes actually copied. Should the input plugin set the block-oriented hint and if the demuxer supports it, the function pointed to by read_block will be called to read a block directly into xine's demuxer FIFO buffer. The seek parameter points to a function called by xine when it is required that subsequent reads come from another part of the stream. The get_current_pos parameter points to a function which returns the current position within a finite length stream. Similarly the get_length function returns the length of the stream. The get_blocksize parameter points to a function which returns the device's prefered block-size if applicable. The get_dir parameter point to a function which returns a NULL terminated array of pointers to MRLs which are within the 'directory' passed. The eject_media parameter points to a function called when the user requests that the media be 'ejected' if possible. The get_mrl parameter points to a function which returns the current MRL. The stop parameter points to a function which stops (but does not close) the input device. get_identifier points to a function returning a (short) human-readable description for the plugin (e.g. CDA, NAV, DVD). get_autoplay_list points to a function returning a NULL-temrinated array of MRLs which arise due to the 'autoplay' feature of the plugin. In order to allow for device-dependant acceleration features, xine calls upon the video output plugin for more than just displaying images. The tasks performed by the video plugins are: Allocation of a vo_frame_s structure and its subsequent destruction. Allocation of memory for use by one frame (this is to allow for the ability of some video output plugins to map frames directly into video-card memory hence removing the need for the frame to be copied across the PCI/AGP bus at display time). Most importantly, the ability to render/copy a given frame to the output device. (Optional) The copying of the frame from a file dependant colour-space and depth into the frame structure. This is to allow for on-the fly colour-space conversion and scalaing if required (e.g. the XShm ouput plugin uses this mechanism). Although these extra responsibilities add great complexity to your plugin it should be noted that they allow plugins to take full advantage of any special hardware-acceleration without sacrificing flexibility. All video plugins take the form of a shared library which exports at least the functions init_video_out_plugin() and get_video_out_plugin_info() which returns a pointer to a vo_info_s. This structure has the following declaration: struct vo_info_s { int interface_version; /* plugin interface version */ char *id; /* id of this plugin */ char *description; /* human-readable description of this plugin */ int visual_type; /* visual type supported by this plugin */ int priority; /* priority of this plugin for auto-probing */ }; At the time of writing, the current interface version was `3' but you may wish to look at an existing plugin's source-code to check. The visual_type field is used by the xine UI to determine if it is supported by the UI (e.g. X11 output plugins require the GUI to be running under the X Windowing system) and also to determine the information passed to the init_video_out_plugin() function. The library must also export this function and it has the following declaration: vo_driver_t *init_video_out_plugin (config_values_t *config, void *visual_gen) The arguments to the function are as follows config -- A pointer to an object which allows you to register, change and access configuration information. See elsewhere in this document for more information. visual_gen -- A pointer to a visual-dependant structure/variable. For example, if you had previously claimed your plugin was of the VISUAL_TYPE_X11 type, this would be a pointer to the Display variable associated with the X-server xine is running under. See plugin source-code for other VISUAL_TYPE_... constants and associated structures. Note that this field is provided by the UI and so if you wish to add another visual type you will either need to extend an existing UI or write a new one. The function creates and returns a pointer to a vo_driver_s structure which contains the following function pointers: struct vo_driver_s { uint32_t (*get_capabilities) (vo_driver_t *this); /* for constants see above */ /* * allocate an vo_frame_t struct, * the driver must supply the copy, field and dispose functions */ vo_frame_t* (*alloc_frame) (vo_driver_t *this); /* * check if the given image fullfills the format specified * (re-)allocate memory if necessary */ void (*update_frame_format) (vo_driver_t *this, vo_frame_t *img, uint32_t width, uint32_t height, int ratio_code, int format, int flags); /* display a given frame */ void (*display_frame) (vo_driver_t *this, vo_frame_t *vo_img); /* overlay functions */ void (*overlay_blend) (vo_driver_t *this, vo_frame_t *vo_img, vo_overlay_t *overlay); /* * these can be used by the gui directly: */ int (*get_property) (vo_driver_t *this, int property); int (*set_property) (vo_driver_t *this, int property, int value); void (*get_property_min_max) (vo_driver_t *this, int property, int *min, int *max); /* * general purpose communication channel between gui and driver * * this should be used to propagate events, display data, window sizes * etc. to the driver */ int (*gui_data_exchange) (vo_driver_t *this, int data_type, void *data); void (*exit) (vo_driver_t *this); vo_info_t* (*get_info) (); }; The get_info field is simply a pointer to the get_video_out_plugin_info() function described above. The get_capbilities field points to a function which returns a bit-wise ORed combination of the following constants which reflects the video output plugin's capabilities. #define VO_CAP_COPIES_IMAGE 0x00000001 /* driver will copy image rather than providing */ /* a buffer for xine to write the image into */ #define VO_CAP_RGB 0x00000002 /* driver can handle 24bit rgb pictures */ #define VO_CAP_YV12 0x00000004 /* driver can handle YUV 4:2:0 pictures */ #define VO_CAP_YUY2 0x00000008 /* driver can handle YUY2 pictures */ #define VO_CAP_HUE 0x00000010 /* driver can set HUE value */ #define VO_CAP_SATURATION 0x00000020 /* driver can set SATURATION value */ #define VO_CAP_BRIGHTNESS 0x00000040 /* driver can set BRIGHTNESS value */ #define VO_CAP_CONTRAST 0x00000080 /* driver can set CONTRAST value */ #define VO_CAP_COLORKEY 0x00000100 /* driver can set COLORKEY value */ #define VO_CAP_AUTOPAINT_COLORKEY 0x00000200 /* driver can set AUTOPAINT_COLORKEY value */ A plugin should use the VO_CAP_COPIES_IMAGE flag if it wishes to provide a copy function to perform on-the-fly colour-space conversion and scaling. The get_property, set_proprty and get_property_min_max fields point to functions which handle the getting, setting of properties and define their bounds. Valid property IDs can be found in the video_out.h header file. The gui_data_exchange field points to a function which can accept various forms of data from the UI (e.g. the mouse has moved or the window has been hidden). Look at existing plugins for examples of data exchanges from various UIs. The alloc_frame field points to a function which returns a pointer to a vo_frame_s structure which is defined as: /* public part, video drivers may add private fields */ struct vo_frame_s { struct vo_frame_s *next; uint32_t PTS; uint32_t pts_corrector; /* Repeat first field tricks */ uint32_t SCR; int bad_frame; /* e.g. frame skipped or based on skipped frame */ int drawn; uint8_t *base[3]; /* additional information to be able to duplicate frames: */ int width, height; int ratio, format; int duration; int aspect_ratio; int frame_rate_code; int progressive_sequence; int top_field_first; int repeat_first_field; int progressive_frame; int picture_coding_type; int bitrate; int display_locked, decoder_locked, driver_locked; pthread_mutex_t mutex; /* so the various locks will be serialized */ vo_instance_t *instance; /* * member functions */ /* this frame is no longer used by decoder */ void (*free) (vo_frame_t *vo_img); /* tell video driver to copy/convert a slice of this frame */ void (*copy) (vo_frame_t *vo_img, uint8_t **src); /* tell video driver that the decoder starts a new field */ void (*field) (vo_frame_t *vo_img, int which_field); /* append this frame to the display queue, returns number of frames to skip if decoder is late */ int (*draw) (vo_frame_t *vo_img); /* this frame is no longer used by the video driver */ void (*displayed) (vo_frame_t *vo_img); /* free memory/resources for this frame */ void (*dispose) (vo_frame_t *vo_img); } Typically the video plugin will add private fields to the end of this structure which are used for internal purposes by the plugin. The function pointers within the frame structure provides a mechanism for the driver to retain full control of how the frames are managed and rendered to. If the VO_CAP_COPIES_IMAGE flag was set in the plugins capabilities then the copy field is required and will be called sequentially for each 16-pixel high strip in the image. The plugin may then decide, based on the frame's format, how this is copied into the frame. Returning to the vo_driver_s structure, the update_frame_format field points to a function which will be called each time the colour-depth/space or size of a frame changes. Typically this function would allocate sufficient memory for the frame, assign the pointers to the individual planes of the frame to the base field of the frame and perform and driver-specific changes. The display_frame field points to a function to render a given frame to the output device. The overlay_blend field points to a function which accepts an association between a frame and overlay which will result in the latter being overlayed on the former. This section contains some guidelines for writing xine-code. These are really just guidelines, no strict rules. Contributions will not be rejected if they do not meet these rules but they will be appreciated if they do. when in doubt, use lower case. BTW: This thing is called xine, never Xine. comment your interfaces in the header files. use expressive variable and function identifiers on all public interfaces. use underscores to seperate words in identifiers, not uppercase letters (my_function_name is ok, myFunctionName is not ok). avoid macros if possible. avoid gotos. use #ifdef LOG printf ("module: ..."[,...]); #endif for debug output. All debug output must be prefixed by the module name which generates the output (see example above). refer to emac's c-mode for all questions of proper indentiation. use c-style comments (/* */), not c++-style (//) Make sure you send your patches in unified diff format to the xine-devel mailing list (you'll have to subscribe first, otherwise you're not allowed to post). Please do not send patches to individual developers unless otherwise instructed because your patch is more likely to get lost in an overfull INBOX in that case. Please be patient, it may take 1-2 weeks before you hear any comments on your work (developers may be working on other parts of the code or are simply busy at the moment).