Source code of a simple X11 frontend

/*
** Copyright (C) 2003 Daniel Caujolle-Bert <segfault@club-internet.fr>
**  
** This program is free software; you can redistribute it and/or modify
** it under the terms of the GNU General Public License as published by
** the Free Software Foundation; either version 2 of the License, or
** (at your option) any later version.
**  
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
** GNU General Public License for more details.
**  
** You should have received a copy of the GNU General Public License
** along with this program; if not, write to the Free Software
** Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
**  
*/

/*
 * compile-command: "gcc -Wall -O2 `xine-config --cflags` `xine-config --libs` -lX11 -lm -o  xinimin xinimin.c"
 */

#include <stdio.h>
#include <string.h>
#include <math.h>

#include <X11/X.h>
#include <X11/Xlib.h>
#include <X11/Xutil.h>
#include <X11/keysym.h>
#include <X11/Xatom.h>
#include <X11/Xutil.h>
#include <X11/extensions/XShm.h>

#include <xine.h>
#include <xine/xineutils.h>


#define MWM_HINTS_DECORATIONS   (1L << 1)
#define PROP_MWM_HINTS_ELEMENTS 5
typedef struct {
  uint32_t  flags;
  uint32_t  functions;
  uint32_t  decorations;
  int32_t   input_mode;
  uint32_t  status;
} MWMHints;

static xine_t              *xine;
static xine_stream_t       *stream;
static xine_video_port_t   *vo_port;
static xine_audio_port_t   *ao_port;
static xine_event_queue_t  *event_queue;

static Display             *display;
static int                  screen;
static Window               window[2];
static int                  xpos, ypos, width, height, fullscreen;
static double               pixel_aspect;

static int                  running = 0;


/* this will be called by xine, if it wants to know the target size of a frame */
static void dest_size_cb(void *data, int video_width, int video_height, double video_pixel_aspect,
                         int *dest_width, int *dest_height, double *dest_pixel_aspect)  {

  if(!running)
    return;
  
  *dest_width        = width;
  *dest_height       = height;
  *dest_pixel_aspect = pixel_aspect;
}

/* this will be called by xine when it's about to draw the frame */
static void frame_output_cb(void *data, int video_width, int video_height,
                            double video_pixel_aspect, int *dest_x, int *dest_y,
                            int *dest_width, int *dest_height, 
                            double *dest_pixel_aspect, int *win_x, int *win_y) {
  if(!running)
    return;
  
  *dest_x            = 0;
  *dest_y            = 0;
  *win_x             = xpos;
  *win_y             = ypos;
  *dest_width        = width;
  *dest_height       = height;
  *dest_pixel_aspect = pixel_aspect;
}

static void event_listener(void *user_data, const xine_event_t *event) {
  switch(event->type) { 
  case XINE_EVENT_UI_PLAYBACK_FINISHED:
    running = 0;
    break;

  case XINE_EVENT_PROGRESS:
    {
      xine_progress_data_t *pevent = (xine_progress_data_t *) event->data;
      
      printf("%s [%d%%]\n", pevent->description, pevent->percent);
    }
    break;
  
  /* you can handle a lot of other interesting events here */
  }
}

int main(int argc, char **argv) {
  char              configfile[2048];
  x11_visual_t      vis;
  double            res_h, res_v;
  char             *vo_driver = "auto";
  char             *ao_driver = "auto";
  char             *mrl = NULL;
  int               i;
  Atom              XA_NO_BORDER;
  MWMHints          mwmhints;

  /* parsing command line */
  for (i = 1; i < argc; i++) {
    if (strcmp(argv[i], "-vo") == 0) {
      vo_driver = argv[++i];
    }
    else if (strcmp(argv[i], "-ao") == 0) {
      ao_driver = argv[++i];
    }
    else 
      mrl = argv[i];
  }

  if (!mrl) {
    printf("specify an mrl\n");
    return 1;
  }
  printf("mrl: '%s'\n", mrl);

  if (!XInitThreads()) {
    printf("XInitThreads() failed\n");
    return 1;
  }

  /* load xine config file and init xine */
  xine = xine_new();
  sprintf(configfile, "%s%s", xine_get_homedir(), "/.xine/config");
  xine_config_load(xine, configfile);
  xine_init(xine);
  
  display = XOpenDisplay(NULL);
  screen  = XDefaultScreen(display);
  xpos    = 0;
  ypos    = 0;
  width   = 320;
  height  = 200;

  /* some initalization for the X11 Window we will be showing video in */
  XLockDisplay(display);
  fullscreen = 0;
  window[0] = XCreateSimpleWindow(display, XDefaultRootWindow(display),
                                  xpos, ypos, width, height, 1, 0, 0);

  window[1] = XCreateSimpleWindow(display, XDefaultRootWindow(display),
                                  0, 0, (DisplayWidth(display, screen)),
                                  (DisplayHeight(display, screen)), 0, 0, 0);
  
  XSelectInput(display, window[0], (ExposureMask | ButtonPressMask | KeyPressMask |
                                    ButtonMotionMask | StructureNotifyMask | 
                                    PropertyChangeMask | PointerMotionMask));

  XSelectInput(display, window[1], (ExposureMask | ButtonPressMask | KeyPressMask |
                                    ButtonMotionMask | StructureNotifyMask | 
                                    PropertyChangeMask | PointerMotionMask));

  XA_NO_BORDER         = XInternAtom(display, "_MOTIF_WM_HINTS", False);
  mwmhints.flags       = MWM_HINTS_DECORATIONS;
  mwmhints.decorations = 0;
  XChangeProperty(display, window[1],
                  XA_NO_BORDER, XA_NO_BORDER, 32, PropModeReplace, (unsigned char *) &mwmhints,
                  PROP_MWM_HINTS_ELEMENTS);
  
  XMapRaised(display, window[fullscreen]);
  
  res_h = (DisplayWidth(display, screen) * 1000 / DisplayWidthMM(display, screen));
  res_v = (DisplayHeight(display, screen) * 1000 / DisplayHeightMM(display, screen));
  XSync(display, False);
  XUnlockDisplay(display);
  
  /* filling in the xine visual struct */
  vis.display           = display;
  vis.screen            = screen;
  vis.d                 = window[fullscreen];
  vis.dest_size_cb      = dest_size_cb;
  vis.frame_output_cb   = frame_output_cb;
  vis.user_data         = NULL;
  pixel_aspect          = res_v / res_h;
  
  /* opening xine output ports */
  vo_port = xine_open_video_driver(xine, vo_driver, XINE_VISUAL_TYPE_X11, (void *)&vis);
  ao_port = xine_open_audio_driver(xine , ao_driver, NULL);

  /* open a xine stream connected to these ports */
  stream = xine_stream_new(xine, ao_port, vo_port);
  /* hook our event handler into the streams events */
  event_queue = xine_event_new_queue(stream);
  xine_event_create_listener_thread(event_queue, event_listener, NULL);
  
  /* make the video window visible to xine */
  xine_port_send_gui_data(vo_port, XINE_GUI_SEND_DRAWABLE_CHANGED, (void *) window[fullscreen]);
  xine_port_send_gui_data(vo_port, XINE_GUI_SEND_VIDEOWIN_VISIBLE, (void *) 1);
  
  /* start playback */
  if (!xine_open(stream, mrl) || !xine_play(stream, 0, 0)) {
    printf("Unable to open mrl '%s'\n", mrl);
    return 1;
  }

  running = 1;

  while (running) {
    XEvent   xevent;
    
    XNextEvent(display, &xevent);
    
    switch(xevent.type) {

    case KeyPress:
      {
        XKeyEvent  kevent;
        KeySym     ksym;
        char       kbuf[256];
        int        len;
        
        kevent = xevent.xkey;
        
        XLockDisplay(display);
        len = XLookupString(&kevent, kbuf, sizeof(kbuf), &ksym, NULL);
        XUnlockDisplay(display);
        
        switch (ksym) {
        
        case XK_q:
        case XK_Q:
          /* user pressed q => quit */
          running = 0;
          break;
          
        case XK_f:
        case XK_F:
          {
            /* user pressed f => toggle fullscreen */
            Window    tmp_win;
            
            XLockDisplay(display);
            XUnmapWindow(display, window[fullscreen]);
            fullscreen = !fullscreen;
            XMapRaised(display, window[fullscreen]);
            XSync(display, False);
            XTranslateCoordinates(display, window[fullscreen],
                                  DefaultRootWindow(display),
                                  0, 0, &xpos, &ypos, &tmp_win);
            XUnlockDisplay(display);
            
            xine_port_send_gui_data(vo_port, XINE_GUI_SEND_DRAWABLE_CHANGED, 
                                    (void*) window[fullscreen]);
          }
          break;
        
        case XK_Up:
          /* cursor up => increase volume */
          xine_set_param(stream, XINE_PARAM_AUDIO_VOLUME,
                         (xine_get_param(stream, XINE_PARAM_AUDIO_VOLUME) + 1));
          break;
        
        case XK_Down:
          /* cursor down => decrease volume */
          xine_set_param(stream, XINE_PARAM_AUDIO_VOLUME,
                         (xine_get_param(stream, XINE_PARAM_AUDIO_VOLUME) - 1));
          break;
        
        case XK_plus:
          /* plus => next audio channel */
          xine_set_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL, 
                         (xine_get_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL) + 1));
          break;
        
        case XK_minus:
          /* minus => previous audio channel */
          xine_set_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL, 
                         (xine_get_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL) - 1));
          break;
        
        case XK_space:
          /* space => toggle pause mode */
          if (xine_get_param(stream, XINE_PARAM_SPEED) != XINE_SPEED_PAUSE)
            xine_set_param(stream, XINE_PARAM_SPEED, XINE_SPEED_PAUSE);
          else
            xine_set_param(stream, XINE_PARAM_SPEED, XINE_SPEED_NORMAL);
          break;
        
        }
      }
      break;
      
    case Expose:
      /* this handles (partial) occlusion of our video window */
      if (xevent.xexpose.count != 0)
        break;
      xine_port_send_gui_data(vo_port, XINE_GUI_SEND_EXPOSE_EVENT, &xevent);
      break;
      
    case ConfigureNotify:
      {
        XConfigureEvent *cev = (XConfigureEvent *) &xevent;
        Window           tmp_win;
        
        width  = cev->width;
        height = cev->height;
        
        if ((cev->x == 0) && (cev->y == 0)) {
          XLockDisplay(display);
          XTranslateCoordinates(display, cev->window,
                                DefaultRootWindow(cev->display),
                                0, 0, &xpos, &ypos, &tmp_win);
          XUnlockDisplay(display);
        } else {
          xpos = cev->x;
          ypos = cev->y;
        }
      }
      break;
    
    }
  }
  
  /* cleanup */
  xine_close(stream);
  xine_event_dispose_queue(event_queue);
  xine_dispose(stream);
  xine_close_audio_driver(xine, ao_port);  
  xine_close_video_driver(xine, vo_port);  
  xine_exit(xine);
  
  XLockDisplay(display);
  XUnmapWindow(display, window[fullscreen]);
  XDestroyWindow(display, window[0]);
  XDestroyWindow(display, window[1]);
  XUnlockDisplay(display);
  
  XCloseDisplay (display);
  
  return 0;
}

xine_log

Output which is done thru this function will be displayed for the end user by the frontend. If xine->verbosity is not 0 the messages will also be displayed on the console. Ideally these strings are translated. This function is for information which the user should read always.

xine_log(xine_t *xine, int buf, const char *format, ...);

buf is either XINE_LOG_MSG for general messages or XINE_LOG_PLUGIN for messages about plugins.

xprintf

This macro uses the xine->verbosity value to decide if the string should be printed to the console. Possible values are XINE_VERBOSITY_NONE, XINE_VERBOSITY_LOG or XINE_VERBOSITY_DEBUG. By default nothing is printed. When you use xine-ui you can enable this output with the --verbose=[1,2] options. This function should be used for information which the user should only read up on request.

xprintf(xine_t *xine, int verbosity, const char *format, ...);

lprintf/llprintf

These macros are for debugging purpose only. Under normal circumstances it is disabled. And can only be enabled by changing a define statement and a recompilation. It has to be enabled for these files that are of interest. It should only be used for information which is intended for developers.

lprintf(const char *format, ...);    llprintf(bool, const char *format, ...);

bool is a flag which enables or disables this logging.

lprintf can be enabled by defining LOG at the top of the source file. llprintf can be used for more than one categorie per file by using diffent lables:

#define LOG_LOAD 1    #define LOG_SAVE 0        llprintf(LOG_LOAD, "loading was successful\n");    llprintf(LOG_SAVE, "could not save to file %s\n", filename);

In this case only the first messages is printed. To enable/disable change the defines.

LOG_MODULE should be used to set the modulename for xprintf/lprintf/llprintf. Each output line will start with "modulename: ".

#define LOG_MODULE "modulename"

LOG_VERBOSE can be defined to enable the logging of functionname and linenumbers. Then the output will be: "modulename: (function_name:42) message".

Plugin location and filesystem layout

The primary goal for this new plugin mechanism was the need to support simultaneous installation of several (most likely incompatible) libxine versions without them overwriting each other's plugins. Therefore, we have this simple layout:

Plugins are installed below XINE_PLUGINDIR (/usr/local/lib/xine/plugins by default). Note that plugins are never directly installed into XINE_PLUGINDIR. Instead, a separate subdirectory is created for each "plugin provider". A plugin provider is equivalent with the exact version of one source package. Typical examples include "xine-lib-0.9.11" or "xine-vcdnav-1.0". Every source package is free to install an arbitrary number of plugins in its own, private directory. If a package installs several plugins, they may optionally be organized further into subdirectories.

So you will finally end up with something like this:

/usr/local/lib/xine/plugins     xine-lib-0.9.11     demux_mpeg_block.so     decode_mpeg.so     video_out_xv.so     ...     xine-vcdnav-0.9.11     input_vcdnav.so     xine-lib-1.2     input     file.so     stdin_fifo.so     vcd.so     demuxers     fli.so     avi.so     ...     decoders     ffmpeg.so     mpeg.so (may contain mpeg 1/2 audio and video decoders)     pcm.so     ...     output     video_xv.so     audio_oss.so     ...     xine-lib-3.0     avi.so (avi demuxer)     mpeg.so (contains mpeg demuxers and audio/video decoders)     video_out_xv.so (Xv video out)     ...

As you can see, every package is free to organize plugins at will below its own plugin provider directory. Additionally, administrators may choose to put plugins directly into XINE_PLUGINDIR, or in a "local" subdirectory. Users may wish to put additional plugins in ~/.xine/plugins/. Again, there may be subdirectories to help organize the plugins.

The default value for XINE_PLUGINDIR can be obtained using the xine-config --plugindir command.

Plugin Content: What's inside the .so?

Each plugin library (.so file) contains an arbitrary number of (virtual) plugins. Typically, it will contain exactly one plugin. However, it may be useful to put a set of related plugins in one library, so they can share common code.

First of all, what is a virtual plugin? A virtual plugin is essentially a structure that is defined by the xine engine. This structure typically contains lots of function pointers to the actual API functions. For each plugin API, there are several API versions, and each API version may specify a new, incompatible structure. Therefore, it is essential that only those plugins are loaded that support current libxine's API, so the .so file needs a plugin list that provides libxine with the version information, even before it tries to load any of the plugins.

This plugin list is held in an array named xine_plugin_info":

plugin_info_t xine_plugin_info[] = {     /* type, API, "name", version, special_info, init_function */     { PLUGIN_DEMUX, 20, "flac", XINE_VERSION_CODE, NULL, demux_flac_init_class },     { PLUGIN_AUDIO_DECODER, 13, "flacdec", XINE_VERSION_CODE, &dec_info_audio, init_plugin },     { PLUGIN_NONE, 0, "", 0, NULL, NULL }    };

The structure of xine_plugin_info may never be changed. If it ever needs to be changed, it must be renamed to avoid erraneous loading of incompatible plugins.

xine_plugin_info can contain any number of plugins and must be terminated with a PLUGIN_NONE entry. Available plugin types are:

#define PLUGIN_NONE 0    #define PLUGIN_INPUT 1    #define PLUGIN_DEMUX 2    #define PLUGIN_AUDIO_DECODER 3    #define PLUGIN_VIDEO_DECODER 4    #define PLUGIN_SPU_DECODER 5    #define PLUGIN_AUDIO_OUT 6    #define PLUGIN_VIDEO_OUT 7    #define PLUGIN_POST 8

The plugin version number is generated from xine-lib's version number like this: MAJOR * 10000 + MINOR * 100 + SUBMINOR. This is not required, but it's an easy way to ensure that the version increases for every release.

Every entry in xine_plugin_info has an initialization function for the plugin class context. This function returns a pointer to freshly allocated (typically via malloc()) structure containing mainly function pointers; these are the "methods" of the plugin class.

The "plugin class" is not what we call to do the job yet (like decoding a video or something), it must be instantiated. One reason for having the class is to hold any global settings that must be accessed by every instance. Remember that xine library is multistream capable: multible videos can be decoded at the same time, thus several instances of the same plugin are possible.

If you think this is pretty much an object-oriented aproach, then you're right.

A fictitious file input plugin that supports input plugin API 12 and 13, found in xine-lib 2.13.7 would then define this plugin list:

#include <xine/plugin.h>    ...    plugin_t *init_api12(void) {     input_plugin_t *this;         this = malloc(sizeof(input_plugin_t));     ...     return (plugin_t *)this;    }    /* same thing, with different initialization for API 13 */        const plugin_info_t xine_plugin_info[] = {     { PLUGIN_INPUT, 12, "file", 21307, init_api12 },     { PLUGIN_INPUT, 13, "file", 21307, init_api13 },     { PLUGIN_NONE, 0, "", 0, NULL }    }

This input plugin supports two APIs, other plugins might provide a mixture of demuxer and decoder plugins that belong together somehow (ie. share common code).

You'll find exact definitions of public functions and plugin structs in the appropriate header files for each plugin type: input/input_plugin.h for input plugins, demuxers/demux.h for demuxer plugins, xine-engine/video_decoder.h for video decoder plugins, xine-engine/audio_decoder.h for audio decoder plugins, xine-engine/post.h for post plugins, xine-engine/video_out.h for video out plugins, xine-engine/audio_out.h for audio out plugins. Additional information will also be given in the dedicated sections below.

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 members via the demux_plugin field and private fields directly.

Summary: Plugins consist of two C-style classes, each representing a different context.

• The first is the so called "plugin class" context. This is a singleton context, which means it will exist either not at all or at most once per xine context. This plugin class context is a C-style class which is subclassing the related class from the xine plugin headers. This contains functions, which are independent of the actual instance of the plugin. Most prominently, it contains a factory method to instantiate the next context.

• The second context is the instance context. This is another C-style class, which is constructed and disposed withing the plugin class context. This one does the actual work and subclasses the related plugin struct from the xine plugin headers. It is instantiated for every separate running instance of the plugin

Overlay Manager

The overlay manager interface is available to any xine plugin. It's a bit unlikely to be used directly, anyway here's a code snippet for enqueueing an overlay for displaying:

video_overlay_event_t event;        event.object.handle = this->video_overlay->get_handle(this->video_overlay,0);        memset(this->event.object.overlay, 0, sizeof(*this->event.object.overlay));        /* set position and size for this overlay */    event.object.overlay->x = 0;    event.object.overlay->y = 0;    event.object.overlay->width = 100;    event.object.overlay->height = 100;        /* clipping region is mostly used by dvd menus for highlighting buttons */    event.object.overlay->clip_top = 0;    event.object.overlay->clip_bottom = image_height;    event.object.overlay->clip_left = 0;    event.object.overlay->clip_right = image_width;        /* the hard part: provide a RLE image */    event.object.overlay->rle = your_rle;    event.object.overlay->data_size = your_size;    event.object.overlay->num_rle = your_rle_count;        /* palette must contain YUV values for each color index */    memcpy(event.object.overlay->clip_color, color, sizeof(color));        /* this table contains transparency levels for each color index.     0 = completely transparent, 15 - completely opaque */    memcpy(event.object.overlay->clip_trans, trans, sizeof(trans));        /* set the event type and time for displaying */    event.event_type = EVENT_SHOW_SPU;    event.vpts = 0; /* zero is a special vpts value, it means 'now' */    video_overlay->add_event(video_overlay, &event);

OSD Renderer

OSD is a general API for rendering stuff over playing video. It's available both to xine plugins and to frontends.

The first thing you need is to allocate a OSD object for drawing from the renderer. The code below allocates a 300x200 area. This size can't be changed during the lifetime of a OSD object, but it's possible to place it anywhere over the image.

   osd_object_t osd;
   
   osd = this->osd_renderer->new_object(osd_renderer, 300, 200);

Now we may want to set font and color for text rendering. Although we will refer to fonts over this document, in fact the OSD can be any kind of bitmap. Font files are searched and loaded during initialization from $prefix/share/xine/fonts/ and ~/.xine/fonts. There's a sample utility to convert truetype fonts at xine-lib/misc/xine-fontconv.c. Palette may be manipulated directly, however most of the time it's convenient to use pre-defined text palettes.

   /* set sans serif 24 font */
   osd_renderer->set_font(osd, "sans", 24);
   
   /* copy pre-defined colors for white, black border, transparent background to
      starting at the index used by the first text palette */
   osd_renderer->set_text_palette(osd, TEXTPALETTE_WHITE_BLACK_TRANSPARENT, OSD_TEXT1);
   
   /* copy pre-defined colors for white, no border, translucid background to
      starting at the index used by the second text palette */
   osd_renderer->set_text_palette(osd, TEXTPALETTE_WHITE_NONE_TRANSLUCID, OSD_TEXT2);

Now render the text and show it:

osd_renderer->render_text(osd, 0, 0, "white text, black border", OSD_TEXT1);    osd_renderer->render_text(osd, 0, 30, "white text, no border", OSD_TEXT2);        osd_renderer->show(osd, 0); /* 0 stands for 'now' */

There's a 1:1 mapping between OSD objects and overlays, therefore the second time you send an OSD object for displaying it will actually substitute the first image. By using set_position() function we can move overlay over the video.

   for( i=0; i < 100; i+=10 ) {
     osd_renderer->set_position(osd, i, i );
     osd_renderer->show(osd, 0);
     sleep(1);
   }
   osd_renderer->hide(osd, 0);

For additional functions please check osd.h or the public header.

   /* 
    Palette entries as used by osd fonts:
   
    0: not used by font, always transparent
    1: font background, usually transparent, may be used to implement
       translucid boxes where the font will be printed.
    2-5: transition between background and border (usually only alpha
         value changes).
    6: font border. if the font is to be displayed without border this
       will probably be adjusted to font background or near.
    7-9: transition between border and foreground
    10: font color (foreground)   
   */

   /* obtains size the text will occupy */
   renderer->get_text_size(osd, text, &width, &height);
   
   /* draws a box using font background color (translucid) */
   renderer->filled_rect(osd, x1, y1, x1+width, y1+height, OSD_TEXT2 + 1);
   
   /* render text */     
   renderer->render_text(osd, x1, y1, text, OSD_TEXT2);

Writing a xine input plugin

An input plugin provides API functions which allow the engine to access the data source the plugin encapsulates. The input plugin API is declared in input/input_plugin.h.

An input plugin exports a public function of the form:

void *input_init_plugin(xine_t *xine, void *data);

This function initializes an input plugin class object with the following functions:

char *get_description(input_class_t *this_gen);

This function returns a plaintext, one-line string describing the plugin.

char *get_identifier(input_class_t *this_gen);

This function returns a shorter identifier describing the plugin.

xine_mrl_t **get_dir(input_class_t *this_gen, const char *filename, int *nFiles);

Retrieves a directory listing from the plugin. This function is optional.

char **get_autoplay_list(input_class_t *this_gen, int *num_files);

Retrieves the autoplay playlist from the plugin. This function is optional.

int eject_media(input_class_t *this_gen);

Ejects the medium. This function is optional.

void dispose(input_class_t *this_gen);

This function frees the memory used by the input plugin class object.

input_plugin_t *get_instance(input_class_t *class_gen, xine_stream_t *stream, const char *mrl);

The plugin should try, if it can handle the specified MRL and return an instance of itself if so. If not, NULL should be returned. 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.

int open(input_plugin_t *this_gen);

You should do any device-specific initialisation within this function.

uint32_t get_capabilities(input_plugin_t *this_gen);

Returns a bit mask describing the input device's capabilities. You may logically OR the INPUT_CAP_* constants together to get a suitable bit-mask (via the '|' operator).

off_t read(input_plugin_t *this_gen, char *buf, off_t nlen);

Reads a specified number of bytes into a buffer and returns the number of bytes actually copied.

buf_element_t *read_block(input_plugin_t *this_gen, fifo_buffer_t *fifo, off_t len);

Should the input plugin set the block-oriented hint and if the demuxer supports it, this function will be called to read a block directly into a xine buffer from the buffer pool.

off_t seek(input_plugin_t *this_gen, off_t offset, int origin);

This function is called by xine when it is required that subsequent reads come from another part of the stream.

off_t get_current_pos(input_plugin_t *this_gen);

Returns the current position within a finite length stream.

off_t get_length(input_plugin_t *this_gen);

Similarly this function returns the length of the stream.

uint32_t get_blocksize(input_plugin_t *this_gen);

Returns the device's prefered block-size if applicable.

char *get_mrl(input_plugin_t *this_gen);

Returns the current MRL.

int get_optional_data(input_plugin_t *this_gen, void *data, int data_type);

This function allows the input to advertise extra information that is not available through other API functions. See INPUT_OPTIONAL_* defines.

void dispose(input_plugin_t *this_gen);

This function closes all resources and frees the input_plugin_t object.

Introduction to demuxer theory

xine's demuxer layer is responsible for taking apart multimedia files or streams so that the engine can decode them and present them to the user. "Demuxer" is short for demultiplexor, which is the opposite of multiplexing. This refers to the process of combining 2 or more things into one. Multimedia streams usually, at a minimum, multiplex an audio stream and a video stream together into one stream. Sometimes, there are multiple audio streams (e.g., for multiple language tracks). Sometimes, there is a subtitle data stream multiplexed into the multimedia stream.

There are many different multimedia formats in existence and there are varying strategies for demuxing different types of multimedia files. Formats in the MPEG family, for example, are designed to allow easy playback from almost any place within the file. Many formats cannot deal with this circumstance and at least need to be demuxed from the beginning of the stream and played through to the end. Some formats, such as MPEG and AVI, have marker information before every chunk in the stream. Other formats, such as Apple Quicktime, are required to have a master index that contains all information for taking apart a file. Many game-oriented multimedia formats are designed strictly for playing from start to finish without any regard to random seeking within the file.

Input considerations

A xine demuxer interacts with xine's input layer in order to receive data. The underlying input plugin might be a file, a network stream, or a block-oriented disc storage device like a DVD. A file input offers the most flexibility in being able to read either blocks of data or individual bytes, and being able to seek freely. Other input plugins may not allow the demuxer to seek (such as stdin or certain network streams). Some input plugins only allow the demuxer to read blocks of data and not individual bytes (such as the CD-DA input plugin). The demuxer needs to check the capabilities of the underlying input plugin before attempting to seek around.

Seeking Policy

If possible, it is desirable that a demuxer can seek randomly through the stream. This is easier for some file formats and essentially impossible for other formats. xine's seeking API function allows a seek target to be specified in terms of stream offset from 0, or time in milliseconds from 0. Offset-based seeking is useful for seek bars in multimedia applications. Time-based seeking is useful for specifying, e.g., a 1-minute jump forward or backward in a stream.

If a multimedia stream has video, there generally needs to be a way to identify keyframes in the stream in order to facilitate seeking. Many game-oriented formats fall over in this area as they carry no keyframe information aside from the implicit assumption that the first frame is a keyframe.

In a stream with video, a seek operation should always jump to a keyframe. xine Policy: When the seek target is between 2 keyframes, jump to the earlier keyframe. E.g., if there are keyframes at stream offsets 10000 and 20000, and the user requests a seek to offset 18000, choose the keyframe at offset 10000.

Note that there can be difficulties when the audio and video streams are not tightly interleaved. In many formats, the audio frames are several time units ahead of the video frames for the purpose of pre-buffering. This is a typical scenario in the middle of a stream:

audio frame @ time 10    video frame @ time 8    audio frame @ time 11    video frame @ time 9    audio frame @ time 12     keyframe @ time 10    audio frame @ time 13

If the demuxer seeks to the keyframe @ time 10, the next audio chunk will have a timestamp of 13, which is well ahead of where the video is. While the xine engine will eventually recover, it will make playback choppy for a few seconds after the seek. One strategy for dealing with this situation is to seek back to the nearest keyframe before the requested seek and then seek back to find the audio frame with the nearest timestamp before the keyframe. In this example, that would mean seeking back to [af@time 10]. Then, demux the chunks in order, but skip the video frames until the next keyframe is encountered.

Writing a xine demuxer

A demuxer plugin provides API functions which allow the engine to initialize demuxing, dispatch data chunks to the engine, seek within the stream, get the stream length, among other functions. The demuxer API is declared in demuxers/demux.h.

Writing a new xine demuxer is largely a process of using other demuxers as references and understanding how they interact with the engine. This section will give a brief overview of each API function.

A demuxer plugin exports a public function of the form:

void *demux_wc3movie_init_plugin(xine_t *xine, void *data);

This function initializes a demuxer plugin class object with 6 demuxer-specific functions. These functions mainly provide information that a frontend can use to build user-friendly features. These functions include:

char *get_description(demux_class_t *this_gen);

This function returns a plaintext, one-line string describing the plugin.

char *get_identifier(demux_class_t *this_gen);

This function returns a shorter identifier describing the plugin.

char *get_extensions(demux_class_t *this_gen);

This function returns a string with the file extensions that this demuxer is known to use. For example, Microsoft .WAV files use "wav". If there are multiple known extensions, separate each extension with a space. For example, Apple Quicktime has the extensions "mov qt mp4".

char *get_mimetypes(demux_class_t *this_gen)

This function returns a string with the MIME types that this demuxer is known to use. Multiple MIME type specifications should be separated with a semicolon (;). For example, Apple Quicktime uses several MIME types:

return "video/quicktime: mov,qt: Quicktime animation;"     "video/x-quicktime: mov,qt: Quicktime animation;"     "application/x-quicktimeplayer: qtl: Quicktime list;";

void class_dispose(demux_class_t *this_gen);

This function frees the memory used by the demuxer plugin class object.

demux_plugin_t *open_plugin(demux_class_t *class_gen, xine_stream_t *stream, input_plugin_t *input_gen);

This function is invoked by the xine engine to determine if the demuxer is able to handle a particular multimedia stream. The engine can specify if the demuxer is supposed to check the stream by content (validate the actual stream data and see if it is of the expected type), by extension (check the name of the MRL and see if the file extension is correct), or explicitly (the engine is passing on a user request to force this demuxer to be used).

NOTE: In the course of checking the stream by content, care must be taken not to consume bytes out of a non-seekable stream. If the stream is non-seekable, use the input plugin's preview buffer facility to get a cache of the first few bytes. If the stream is seekable, reset the stream before operating on the data (you do not know where some other demuxer left the stream positioned).

If the demuxer can handle the stream, it creates a new demux_plugin_t structure and initializes the main demuxer functions which are called by the engine to do the tough demuxing duty. These functions include:

void demux_send_headers(demux_plugin_t *this_gen);

This function generally reads the headers of the stream, does whatever it has to do to figure out what audio and video codecs are used in the file, and asks the xine engine to initialize the correct decoders with the proper parameters (like width and height for video, sample rate and channels for audio).

int demux_send_chunk(demux_plugin_t *this_gen);

This function reads data from the stream and sends it to the appropriate decoder. This is where the bulk of the demuxing work is performed. Despite the name, the function is actually free to send as much data as it wants to, or as much as it can. A good policy is to send an entire chunk of compressed audio or video data and then return. The chunk is likely large enough that it will have to be broken up into multiple xine buffers. If a chunk of audio is 20000 bytes large, and the engine is returning 4096-byte buffers, send 4 full buffers and 1 partial buffer to the audio decoder and then return.

int demux_seek(demux_plugin_t *this_gen, off_t start_pos, int start_time);

This function is called by the engine to request stream repositioning. This function should be implemented if possible. See the section on "Seeking Policy" for more information. A seek operation should reposition the demuxer's internal accounting variables to be ready to start dispatching chunks from the new position when the xine engine calls demux_send_chunk() again. If seeking is not feasible, the function quietly returns and the demuxer's position is unaffected.

void demux_dispose(demux_plugin_t *this_gen);

This function frees the demux_plugin_t object.

int demux_get_status(demux_plugin_t *this_gen);

This function returns the current internal status of the demuxer. There are 2 states: DEMUX_OK, for when the demuxer is demuxing or ready to demux, and DEMUX_FINISHED, for when the demuxer has reached the end of the stream or has encountered some sort of error.

int demux_get_stream_length(demux_plugin_t *this_gen);

This function returns the length (time duration) of the stream in milliseconds. If the length of the stream cannot be determined, return 0.

uint32_t demux_get_capabilities(demux_plugin_t *this_gen);

This function returns an array of bit flags indicating special features of the demuxer. See DEMUX_CAP_* defines.

int demux_get_optional_data(demux_plugin_t *this_gen, void *data, int data_type);

This function allows the demuxer to advertise extra information that is not available through other API functions. See DEMUX_OPTIONAL_* defines.

Buffer types

Demuxer must send data to decoders using two fifos names video_fifo and audio_fifo. Both are available at stream level. The following code fragment shows how it's done.

   buf_element_t *buf;
   
   buf = stream->video_fifo->buffer_pool_alloc(stream->video_fifo);
   buf->type = BUF_CONTROL_START;
   stream->video_fifo->put(stream->video_fifo, buf);

Buffers must have set the type field as shown. All buffer types are defined in xine-engine/buffer.h.

The control buffer types are very important and must be sent by all kinds of demuxers. They tell decoders to start/stop their operations and inform metronom about discontinuities, either relative or absolute. There is also a reset buffer type that must be sent when demuxers are seeking as a "warm restart" indication to the decoders.

To help finding out buffer types for known codecs, functions from buffer_types.c may be used to convert "FOURCC" codes or audio format tags (as used in AVI files) to the xine byffer type:

buf->type = fourcc_to_buf_video((void*)this->avi->bih.biCompression);

Audio and video decoders

Audio and video data requires an enormous amount of storage. Thus, the raw data is encoded using a variety of compression techniques which drastically reduces the amount of space required to transmit and store the data. Before playback, the compressed data needs to be decoded.

The process of decoding data is rather straightforward in a computer science sense: An array of encoded data is fed into a decoder and the decoder outputs an array of decoded data which is ready to be presented to the user (either displayed on the screen or played through the speakers).

Video output formats

Raw video data comes in a variety of formats, most commonly in RGB and YUV. xine's output layer currently only accepts data in YV12 format (a.k.a. YUV 4:2:0 planar) or YUY2 format (a.k.a. YUV 4:2:2 packed). If the output format is a RGB space, the data must be converted to an acceptable YUV format before being dispatched to the video output unit. xine has a number of support functions to facilitate converting RGB to YUV.

Audio output formats

Raw audio data equates to uncompressed PCM audio. xine's audio output modules expect 8-bit PCM data to be unsigned and 16-bit PCM data to be signed and in little endian format. When there is more than one channel, the channel data is interleaved. For example, stereo data is interleaved as left sample, right sample: LRLRLRLR. If there are 4 or 6 channels, the same interleaving applies: 123456123456.

Writing a xine decoder

Writing a new xine decoder for an audio or video format entails accumulating a buffer of encoded data, performing the necessary operations for decoding and then passing it on the appropriate output module. The best reference for understanding the decoder API is the various decoding modules available. In particular, xine has example video and audio decoders named src/libxinevdec/foovideo.c and src/libxineadec/fooaudio.c, respectively.

This section will give a brief overview of each API function. The decoder API is declared in src/xine-engine/video_decoder.h and src/xine-engine/audio_decoder.h.

A decoder plugin must, like every plugin, export a public array of plugin_info_t types. The array usually has 2 entries: The first contains the plugin information regarding the decoder and the second entry is a terminating NULL entry. However, there may be more entries. Each entry contains 6 fields:

• plugin type: Either PLUGIN_VIDEO_DECODER or PLUGIN_AUDIO_DECODER.

• API: The plugin API revision that this plugin adheres to.

• name: A character string that identifies the plugin.

• version: #define'd as XINE_VERSION_CODE.

• supported types: A structure that defines the buffer types that this plugin can handle.

• init function: The function that the xine engine calls in order to initialize this decoder plugin.

void *init_plugin(xine_t *xine, void *data);

This function allocates a plugin class and initializes a set of functions for the xine engine to invoke. These functions include:

char *get_identifier(video_decoder_class_t *this);

char *get_identifier(audio_decoder_class_t *this);

This function returns a brief character string identifying the plugin.

char *get_description(video_decoder_class_t *this);

char *get_description(audio_decoder_class_t *this);

This function returns a slightly longer description of the plugin.

void dispose_class(video_decoder_class_t *this);

void dispose_class(audio_decoder_class_t *this);

This function frees the resources allocated by the plugin class.

video_decoder_t *open_plugin(video_decoder_class_t *class_gen, xine_stream_t *stream);

audio_decoder_t *open_plugin(audio_decoder_class_t *class_gen, xine_stream_t *stream);

This function initializes the decoder plugin's private state. It also initializes and returns either an audio_decoder_t or a video_decoder_t for the engine. The decoder_t contains a number of functions that the plugin invokes to handle data decoding. These functions include:

void decode_data(video_decoder_t *this_gen, buf_element_t *buf);

void decode_data(audio_decoder_t *this_gen, buf_element_t *buf);

This function performs the bulk of the decoding work. The xine engine delivers buffers (xine_buffer_t data types) to this function and it is up to this function to assemble the parts of the buffer, decode the data, and send the decoded data to the proper output unit.

A buffer has a decoder_flags field which can have a number of flags set. The first buffer that a decoder receives ought to have the BUF_FLAG_HEADER flag set. This indicates that the buffer content contains the essential setup information for decoding (width, height, etc. for video; sample rate, channels, etc. for audio).

If the BUF_FLAG_HEADER flag is not set, the content of the buffer should be accumulated in a private buffer until a buffer with a BUF_FLAG_FRAME_END flag is set. This indicates that the entire chunk has been transmitted to the decoder and is ready to be decoded. Fetch either an empty video frame or audio buffer from the appropriate output unit. Perform the appropriate decoding operations and set the pts for the output buffer (and the duration, a.k.a. video_step, for video). Dispatch the decoded data to the output and reset the internal buffer accumulation accounting.

void flush(video_decoder_t *this_gen);

void flush(audio_decoder_t *this_gen);

This function is called when either the xine engine flushes the stream, e.g., after a seek operation or when decoding runs too slow and frames arrive in the output loops fast enough. Decoders should release everything they have already decoded, drop the rest and wait for new input.

void reset(video_decoder_t *this_gen);

void reset(audio_decoder_t *this_gen);

This function is called when the xine engine resets the stream. Decoders should get ready to receive data that has nothing to do with the one it worked on up to now.

void discontinuity(video_decoder_t *this_gen);

void discontinuity(audio_decoder_t *this_gen);

This function is called when the xine engine encounters a pts discontinuity. Decoders should forget all timestamping information they might have accumulated from the stream to not confuse metronom.

void dispose(video_decoder_t *this_gen);

void dispose(audio_decoder_t *this_gen);

This function frees the resources used by the decoder plugin.

SPU decoder

A lot written above also applies for subpicture unit (SPU) decoders. The SPU decoder API is declared in src/xine-engine/spu_decoder.h. Details on the data, SPU decoders are expected to output, see the section on overlays and OSD.

However, there are some differences to consider. At first, unlike audio and video, subtitles do not form a continuous stream. The decoder will therefore only be called once in a while. The metronom call for timestamping, which for audio and video is done by the engine, has to be done manually for SPU:

vpts = metronom->got_spu_packet(metronom, buf->pts);

There are also two functions in the SPU decoder API, which have not been discussed above:

int get_interact_info(spu_decoder_t *this_gen, void *data);

Since SPUs are sometimes (on DVDs for example) used for user interaction like menu highlights, this function can be called to get data filled with the current interaction information. The caller and the decoder have to agree on what this is exactly. With DVDs, you can get a copy of the current NAV packet here.

void set_button(spu_decoder_t *this_gen, int32_t button, int32_t mode);

Also for interaction, you can ask the decoder here to change the current highlighting.

Writing a xine video out plugin

The video out plugin API is declared in src/xine-engine/video_out.h The plugin info of video out plugins contains the visual type, priority, and the init_class function of the plugin.

The visual_type field is used by xine to determine if the GUI used by the client is supported by the plugin (e.g. X11 output plugins require the GUI to be running under the X Windowing system) and also to determine the type of information passed to the open_plugin() function as its visual parameter.

char *get_description(video_driver_class_t *this_gen);

This function returns a plaintext, one-line string describing the plugin.

char *get_identifier(video_driver_class_t *this_gen);

This function returns a shorter identifier describing the plugin.

void dispose(video_driver_class_t *this_gen);

This function frees the memory used by the video out plugin class object.

vo_driver_t *get_instance(video_driver_class_t *class_gen, const void *visual);

Returns an instance of the plugin. The visual is 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 a x11_visual_t, which amongst other things hold the Display variable associated with the X-server xine should display to. See plugin source-code for other VISUAL_TYPE_* constants and associated structures. Note that this field is provided by the client application and so if you wish to add another visual type you will either need to extend an existing client or write a new one.

uint32_t get_capabilities(vo_driver_t *this_gen);

Returns a bit mask describing the output plugin's capabilities. You may logically OR the VO_CAP_* constants together to get a suitable bit-mask (via the '|' operator).

int get_property(vo_driver_t *self, int property);    int set_property(vo_driver_t *self, int property, int value);    void get_property_min_max(vo_driver_t *self, int property, int *min, int *max);

Handle the getting, setting of properties and define their bounds. Valid property IDs can be found in the video_out.h header file.

int gui_data_exchange(vo_driver_t *self, int data_type, void *data);

Accepts 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.

vo_frame_t *alloc_frame(vo_driver_t *self);

Returns a pointer to a xine video frame. Typically the video plugin will add private fields to the end of the vo_frame_t structure which are used for internal purposes by the plugin.

The function pointers within the frame structure provide 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.

void update_frame_format(vo_driver_t *self, vo_frame_t *img, uint32_t width, uint32_t height, double ratio, int format, int flags);

This function 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 any driver-specific changes.

void display_frame(vo_driver_t *self, vo_frame_t *vo_img);

Renders a given frame to the output device.

void overlay_begin(vo_driver_t *self, vo_frame_t *vo_img, int changed);    void overlay_blend(vo_driver_t *self, vo_frame_t *vo_img, vo_overlay_t *overlay);    void overlay_end(vo_driver_t *self, vo_frame_t *vo_img);

These are used to blend overlays on frames. overlay_begin() is called, when the overlay appears for the first time, overlay_blend() is then called for every subsequent frame and overlay_end() is called, when the overlay should disappear again.

int redraw_needed(vo_driver_t *self);

Queries the driver, if the current frame needs to be drawn again.

void dispose(vo_driver_t *self);

Releases all resources and frees the plugin.