From bd26fdf362d7daf420090b4f811bdb1fad45ea24 Mon Sep 17 00:00:00 2001 From: Klaus Schmidinger Date: Sun, 23 Jun 2002 11:40:24 +0200 Subject: [PATCH] Description for cPlayer plugins --- PLUGINS.html | 188 ++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 172 insertions(+), 16 deletions(-) diff --git a/PLUGINS.html b/PLUGINS.html index a3adc937..1781fcc6 100644 --- a/PLUGINS.html +++ b/PLUGINS.html @@ -12,7 +12,7 @@ This interface allows programmers to develop additional functionality for VDR co separate from the core VDR source, without the need of patching the original VDR code (and all the problems of correlating various patches).

-
  +
  This document is divided into two parts, the first one describing the outside interface of the plugin system, and the second one describing the @@ -23,16 +23,18 @@ The inside interface provides the plugin code access to VDR's internal da structures and allows it to hook itself into specific areas to perform special actions.

-
  +
  Important modifications introduced in version 1.1.1 are marked like this.
-
  +
  Important modifications introduced in version 1.1.2 are marked like this.
-
  +
  Important modifications introduced in version 1.1.3 are marked like this.
- +
  +Important modifications introduced in version 1.1.4 are marked like this. +

Part I - The Outside Interface

@@ -129,7 +131,7 @@ from the web, it will typically have a name like

and will unpack into a directory named

-
  +
  hello-0.0.1

@@ -137,7 +139,7 @@ To use the plugins and plugins-clean targets from the VDR you need to unpack such an archive into the VDR/PLUGINS/src directory and create a symbolic link with the basic plugin name, as in -
  +
  



 ln -s hello-0.0.1 hello

@@ -203,7 +205,7 @@ its memory. You don't need to worry about the details behind all this. If your plugin requires additional source files, simply add them to your plugin's source directory and adjust the Makefile accordingly.

-
  +
  Header files usually contain preprocessor statements that prevent the same file (or rather its contents, to be precise) from being included more than once, like @@ -422,7 +424,7 @@ If a plugin implements a function that runs in the background (presumably in a thread of its own), or wants to make use of internationalization, it needs to implement the function -
  +
  



 virtual bool Start(void);

@@ -434,7 +436,7 @@ its task. This may, for instance, be a thread that collects data from the DVB stream, which is later presented to the user via a function that is available from the main menu.

-
  +
  A return value of false indicates that something has gone wrong and the plugin will not be able to perform its task. In that case, the plugin should write a proper error message to the log file. The first plugin that returns @@ -498,7 +500,7 @@ interaction is possible. If a specific action takes longer than a few seconds, the plugin should launch a separate thread to do this. -
  +
 

Housekeeping

Chores, chores...

@@ -545,7 +547,7 @@ previously stored in the global setup data (see below). It shall return true if the parameter was parsed correctly, false in case of an error. If false is returned, an error message will be written to the log file (and program execution will continue). -
  +
  A possible implementation of SetupParse() could look like this: 



@@ -600,7 +602,7 @@ needs setup parameters that are not directly user adjustable. It can use
 SetupStore() and SetupParse() without presenting these
 parameters to the user.
 
-
 
+
 
 
The Setup menu

 
 
Have it your way!

@@ -660,7 +662,7 @@ your setup parameters and use that one to copy all parameters with one single st
 (like VDR does with its cSetup class).
 

 
-
 
+
 
 
Configuration files

 
 
I want my own stuff!

@@ -746,6 +748,9 @@ const tI18nPhrase Phrases[] = {
     "",// TODO
     "",// TODO
     "",// TODO
+    "",// TODO
+    "",// TODO
+    "",// TODO
   },
   { NULL }
   };
@@ -827,7 +832,7 @@ and display their help and/or version information in addition to its own output.
 
 If you want to make your plugin available to other VDR users, you'll need to
 make a package that can be easily distributed.
-
 
+
 
 The Makefile that has been created by the call to
 newplugin
 provides the target dist, which does this for you.
@@ -849,7 +854,7 @@ vdr-hello-0.0.1.tgz
 in your source directory, where hello will be replaced with your actual
 plugin's name, and 0.0.1 will be your plugin's current version number.
 
-
 
+
 
 
Part II - The Inside Interface

 
 
Status monitor

@@ -926,5 +931,156 @@ member functions are available in cStatus. You only need to implement
 the functions you actually want to use.
 

 
+
 
+
Players

+
+
Play it again, Sam!

+
+Implementing a player is a two step process.
+First you need the actual player class, which is derived from the abstract cPlayer:
+
+


+#include <vdr/player.h>
+
+class cMyPlayer : public cPlayer {
+protected:
+  virtual void Activate(bool On);
+public:
+  cMyPlayer(void);
+  virtual ~cMyPlayer();
+  };
+

+
+What exactly you do in this class is entirely up to you. If you want to run a separate
+thread which, e.g.,  reads data from a file, you can additionally derive your class from
+cThread and implement the necessary functionality:
+
+


+#include <vdr/player.h>
+
+class cMyPlayer : public cPlayer, cThread {
+protected:
+  virtual void Activate(bool On);
+  virtual void Action(void);
+public:
+  cMyPlayer(void);
+  virtual ~cMyPlayer();
+  };
+

+
+Take a look at the files player.h and dvbplayer.c to see how VDR implements
+its own player for the VDR recordings.
+

+To play the video data, the player needs to call its member function
+
+


+int PlayVideo(const uchar *Data, int Length);
+

+
+where Data point to a block of Length bytes of a PES data
+stream. There are no prerequisites regarding the length or alignment of an
+individual block of data. The sum of all blocks must simply result in the
+desired video data stream, and it must be delivered fast enough so that the
+DVB device doesn't run out of data.
+

+TODO: PlayAudio()???
+

+The second part needed here is a control object that receives user input from the main
+program loop and reacts on this by telling the player what to do:
+
+


+#include <vdr/player.h>
+
+class cMyControl : public cControl {
+private:
+  cMyPlayer *player;
+public:
+  cMyControl(void);
+  virtual ~cMyControl();
+  virtual void Hide(void);
+  virtual eOSState ProcessKey(eKeys Key);
+  };
+

+
+cMyControl shall create an object of type cMyPlayer and
+hand over a pointer to it to the cControl base class, so that it
+can be later attached to the primary DVB device:
+
+


+cMyControl::cMyControl(void)
+:cControl(player = new cMyPlayer)
+{
+}
+

+
+cMyControl will receive the user's key presses through the ProcessKey()
+function. It will get all button presses, except for the volume control buttons
+(kVolUp, kVolDn, kMute), the power button (kPower)
+and the menu button (kMenu). If the user has not pressed a button for a while
+(which is typically in the area of about one second), ProcessKey() will be called
+with kNone, so that the cMyControl gets a chance to check whether its
+player is still active. Once the player has become inactive (because the user has decided
+to stop it or the DVB device has detached it), ProcessKey() must return osEnd
+to make the main program loop shut down the player control.
+

+A derived cControl must implement the Hide() function, in which
+it has to hide itself from the OSD, in case it uses it. Hide() may be called at
+any time, and it may be called even if the cControl is not visible at the moment.
+The reason for this is that the Menu button shall always bring up the main VDR
+menu, so any active cControl needs to be hidden when that button is pressed.
+

+Finally, to get things going, a plugin that implements a player (and the surrounding
+infrastructure like displaying a list of playable stuff etc) simply has to call the
+static function cControl::Launch() with the player control object, as in
+
+


+cControl::Launch(new cMyControl);
+

+
+Ownership of the MyControl object is handed over to the VDR core code,
+so the plugin should not keep a pointer to it, because VDR will destroy the object
+whenever it sees fit (for instance because a recording shall start that needs to
+use the primary DVB device, or the user decides to start a different replay).
+

+The cPlayer class has a member function
+
+


+void DeviceStillPicture(const uchar *Data, int Length);
+

+
+which can be called to display a still picture. VDR uses this function when handling
+its editing marks. A special case of a "player" might use this function to implement
+a "picture viewer". 
+

+For detailed information on how to implement your own player, please take a look
+at VDR's cDvbPlayer and cDvbPlayerControl classes.
+

+User interface
+

+In order for a new player to nicely "blend in" to the overall VDR appearance it
+is recommended that it implements the same functionality with the same keys as the
+VDR player does (as far as this is possible and makes sense). The main points to
+consider here are
+
    
+
  • The Ok button shall bring up some display that indicates what is currently
+    being played, and what the status of this replay session is. As an alternative (for
+    instance with a DVD player) it may display a player specific menu, from which the
+    user can select certain options.
+
  • The Up, Down, Left and Right buttons shall control
+    Play, Pause, Fast Rewind and Fast Forward, respectively
+    (provided that this particular player can implement these functions) if the player
+    is not currently showing any menu. If there is a menu, they shall allow the user
+    to navigate in the menu.
+
  • The Green and Yellow buttons shall skip back- and forward by an
+    amount of time suitable for this player (provided that this particular player can
+    implement these functions).
+
  • The Blue button shall immediately stop the replay session.
+

+Of course, these are only suggestions which should make it easier for VDR users to
+enjoy additional players, since they will be able to control them with actions
+that they already know. If you absolutely want to do things differently, just go
+ahead - it's your show...
+

+