Version 1.3.7vdr-1.3.7

- Fixed a memory leak in thread handling when using NPTL (thanks to Jon Burgess).
- Fixed handling Setup.RecordDolbyDigital, which was broken since version 1.1.6.
- Fixed handling text lengths for itemized EPG texts (thanks to Marcel Wiesweg).
- Fixed the help for LSTE and LSTR (was broken in 1.3.6).
- Improved iso8859-7 fonts (thanks to Dimitrios Dimitrakos).
- Added some 3-letter language codes (thanks to Marcus Mönnig).
- Added language code handling to the subtitling descriptor in 'libsi' (thanks to
  Pekka Virtanen).
- Moved several menu item classes from menu.c to menuitems.[hc] to make them
  available for plugins.
- The epg2html.pl script now handles '|' in description texts.
- The new setup option "OSD/Use small font" can be used to control the use of
  the small font (see MANUAL for details).
- Swapped osd.[hc] and osdbase.[hc] to have the virtual OSD base class named cOsd.
  Plugins may need to adjust their #include statements.
- Colors are now given as AARRGGBB instead of AABBGGRR. The values are mapped to
  the driver's (wrong) sequence in dvbosd.c (this should really be fixed in the
  driver, together with the endian problem).
- The new OSD setup parameters "Left" and "Top" can be used to define the top left
  corner of the OSD.
- The OSD size parameters are now in pixel (as opposed to formerly characters).
  When reading a 'setup.conf' file from an older version of VDR, the OSDwidth
  and OSDheight values will be converted to pixel automatically.
- The OSD is now fully device independent. See the comments in VDR/osd.h and the
  description in PLUGINS.html for information on how a plugin can implement an OSD
  display on arbitrary hardware.
- The OSD (actually its cBitmap class) can now handle XPM files. There are several
  XPM files in the VDR/symbols directory which can be used by skins (some of these
  have been taken from the "elchi" patch). See VDR/skinsttng.c for examples on how
  to use these.
- Due to the changes in the OSD handling the DEBUG_OSD option for a textual OSD
  has been dropped. There will be a plugin that implements a skin with this
  functionality later.
- The entire OSD display can now be implemented via "skins". See VDR/skins.[hc],
  VDR/skinclassic.[hc], VDR/skinsttng.[hc] and PLUGINS.html for information on how
  a plugin can implement its own skin. By default VDR comes with a "Classic" skin
  that implements the OSD display known from previous versions, and the new skin
  named "ST:TNG Panels", which is also the default skin now. The actual skin can
  be selected through "Setup/OSD/Skin".
- The colors used in a skin can now be configured using "themes". See PLUGINS.html
  for information on how a skin can make use of themes, and man vdr(5) for the
  structure of a theme file. The actual theme to use can be selected through
  "Setup/OSD/Theme".
- Added Croatian language texts (thanks to Drazen Dupor).
  NOTE: there is apparently a problem with the newly introduced iso8859-2 font,
  because as soon as Setup/OSD/Language is set to Croatian (currently the last one
  in the list) everything freezes and the vdr processes have to be killed with -9
  and the driver needs to be reloaded. Maybe somebody else can find out what's
  going wrong here...
- Added missing NULL checks when accessing sectionHandler in device.c (thanks to
  Pekka Virtanen).
- Fixed setting the time from the DVB data stream (thanks to Helmut Auer for
  pointing out a frequency/transponder handling mixup). This now also takes the
  actual source (sat, cable etc.) into account. Please go into "Setup/EPG" and
  set the "Set system time" and "Use time from transponder" parameters accordingly
  (this is necessary even if you have already set them before!).

1 files changed, 188 insertions, 27 deletions

diff --git a/PLUGINS.html b/PLUGINS.html
index d13ca4a..a2cfe9b 100644
--- a/PLUGINS.html
+++ b/PLUGINS.html
@@ -9,17 +9,20 @@
 <center><b>Version 1.3</b></center>
 <p>
 <center>
-Copyright &copy; 2003 Klaus Schmidinger<br>
+Copyright &copy; 2004 Klaus Schmidinger<br>
 <a href="mailto:kls@cadsoft.de">kls@cadsoft.de</a><br>
 <a href="http://www.cadsoft.de/vdr">www.cadsoft.de/vdr</a>
 </center>
 <p>
-<!--X1.2.6--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
+<!--X1.2.6--><table width=100%><tr><td bgcolor=#00AA00>&nbsp;</td><td width=100%>
 Important modifications introduced in version 1.2.6 are marked like this.
 <!--X1.2.6--></td></tr></table>
-<!--X1.3.0--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+<!--X1.3.0--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
 Important modifications introduced in version 1.3.0 are marked like this.
 <!--X1.3.0--></td></tr></table>
+<!--X1.3.7--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+Important modifications introduced in version 1.3.7 are marked like this.
+<!--X1.3.7--></td></tr></table>
 <p>
 VDR provides an easy to use plugin interface that allows additional functionality
 to be added to the program by implementing a dynamically loadable library file.
@@ -67,10 +70,14 @@ structures and allows it to hook itself into specific areas to perform special a
 <li><a href="#Status monitor">Status monitor</a>
 <li><a href="#Players">Players</a>
 <li><a href="#Receivers">Receivers</a>
-<!--X1.3.0--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+<!--X1.3.0--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
 <li><a href="#Filters">Filters</a>
 <!--X1.3.0--></td></tr></table>
 <li><a href="#The On Screen Display">The On Screen Display</a>
+<!--X1.3.7--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+<li><a href="#Skins">Skins</a>
+<li><a href="#Themes">Themes</a>
+<!--X1.3.7--></td></tr></table>
 <li><a href="#Devices">Devices</a>
 <li><a href="#Dolby Digital">Dolby Digital</a>
 <li><a href="#Remote Control">Remote Control</a>
@@ -1207,7 +1214,7 @@ Mode</i>).
 If the <tt>cReceiver</tt> isn't needed any more, it may simply be <i>deleted</i>
 and will automatically detach itself from the <tt>cDevice</tt>.
 
-<!--X1.3.0--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+<!--X1.3.0--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
 <a name="Filters"><hr><h2>Filters</h2>
 
 <center><i><b>A Fistful of Datas</b></i></center><p>
@@ -1253,35 +1260,166 @@ and will automatically detach itself from the <tt>cDevice</tt>.
 See VDR/eit.c or VDR/pat.c to learn how to process filter data.
 <!--X1.3.0--></td></tr></table>
 
+<!--X1.3.7--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
 <a name="The On Screen Display"><hr><h2>The On Screen Display</h2>
 
-<center><i><b>Express yourself</b></i></center><p>
+<center><i><b>Window to the world</b></i></center><p>
 
-Most of the time a plugin should be able to access the OSD through the
-standard mechanisms also used by VDR itself. However, these set up the OSD in
-a manner of textual rows and columns, and automatically set the various
-windows and color depths.
-<p>
 If a plugin needs to have total control over the OSD, it can call the
 static function
 
 <p><table><tr><td bgcolor=#F0F0F0><pre>
 #include &lt;vdr/osd.h&gt;
 
-cOsdBase *MyOsd = cOsd::OpenRaw(x, y);
+cOsd *MyOsd = cOsdProvider::NewOsd(x, y);
 </pre></td></tr></table><p>
 
 where <tt>x</tt> and <tt>y</tt> are the coordinates of the upper left corner
-of the OSD area on the screen. Such a "raw" OSD doesn't display anything
+of the OSD area on the screen. Such an OSD doesn't display anything
 yet, so you need to at least call the function
 
 <p><table><tr><td bgcolor=#F0F0F0><pre>
-MyOsd-&gt;Create(...);
+tArea Area = { 0, 0, 100, 100, 4 };
+MyOsd-&gt;SetAreas(Area, 1);
 </pre></td></tr></table><p>
 
-to define an actual OSD drawing area (see VDR/osdbase.h for the declarations
-of these functions, and VDR/osd.c to see how VDR opens the OSD and sets up
+to define an actual OSD drawing area (see VDR/osd.h for the declarations
+of these functions, and VDR/skinsttng.c to see how VDR opens the OSD and sets up
 its windows and color depths).
+<p>
+Theoretically the OSD supports a full screen drawing area, with 32 bit color
+depth. However, the actual OSD device in use may not be able to provide the
+full area or color depth, maybe because of lack of OSD memory or other restrictions.
+A plugin that uses the OSD should therefore test whether the OSD is able to
+provide the requested functionality, and should offer alternate color depths
+to allow a less powerfull OSD implementation to still work reasonably.
+Since it is often not really necessary to have hundreds or thousands of colors
+all over the OSD area, a plugin can divide the total drawing area into several
+sub-areas with different color depths and separate color palettes, as in
+
+<p><table><tr><td bgcolor=#F0F0F0><pre>
+tArea Area = { 0, 0, 99, 99, 4 };
+if (osd-&gt;CanHandleAreas(Area, 1) == oeOk)
+   osd-&gt;SetAreas(Area, 1);
+else {
+   tArea Areas[] = { { 0,  0, 99, 19, 2 },
+                     { 0, 20, 99, 79, 2 },
+                     { 0, 80, 99, 99, 4 }
+                   };
+   osd-&gt;SetAreas(Areas, sizeof(Areas) / sizeof(tArea));
+   }
+</pre></td></tr></table><p>
+
+In this example an OSD with 100 by 100 pixel and 4 bit color depth shall
+be opened, so at first a single area with the full required resolution
+is set up and <tt>CanHandleAreas()</tt> is called with it. If the result indicates
+that the OSD will be able to handle this drawing area, a call to <tt>SetAreas()</tt>
+actually sets it. If a single area with that resolution can't be handled,
+a second attempt is made in which the total drawing area is divided into
+three horizontal stripes, two of which use only 2 bit color depth (because
+the objects drawn in there can be displayed with 4 colors) while the third
+one still requests 4 bit color depth.
+<p>
+Note that a plugin should always at first request a single drawing area
+with the full required resolution. Only if this fails shall it use alternate
+areas. Drawing areas are always rectangular and may not overlap (but do not need
+to be adjacent).
+
+<a name="Skins"><hr><h2>Skins</h2>
+
+<center><i><b>The emperor's new clothes</b></i></center><p>
+
+The way VDR displays its menus to the user is implemented through <i>skins</i>.
+A particular skin provides several functions that return objects to be used
+for displaying a specific part of the OSD, like a menu, the channel display
+or the volume bar.
+<p>
+By default VDR offers the <i>Classic</i> and the <i>ST:TNG Panels</i> skins,
+which can be selected through Setup/OSD/Skin. A plugin can implement an
+arbitrary skin of its own by doing something similar to what's done in
+<tt>VDR/skinclassic.c</tt>.
+<p>
+The first step in implementing a new skin is to derive a class from <tt>cSkin</tt>
+that provides the handling objects necessary to do the actual work:
+
+<p><table><tr><td bgcolor=#F0F0F0><pre>
+#include "skins.h"
+
+class cMySkin : public cSkin {
+public:
+  cMySkin(void);
+  virtual const char *Description(void);
+  virtual cSkinDisplayChannel *DisplayChannel(bool WithInfo);
+  virtual cSkinDisplayMenu *DisplayMenu(void);
+  virtual cSkinDisplayReplay *DisplayReplay(bool ModeOnly);
+  virtual cSkinDisplayVolume *DisplayVolume(void);
+  virtual cSkinDisplayMessage *DisplayMessage(void);
+  };
+</pre></td></tr></table><p>
+
+See the comments in <tt>VDR/skins.h</tt> for details. <tt>VDR/skinclassic.[hc]</tt>
+can be used as an example for how to implement all the necessary classes and
+functions to compose a complete skin. See also the chapter about <a href="#Themes">themes</a>
+if you want to make the colors used by your skin configurable.
+<p>
+To add your new skin to the list of skins available to the user in Setup/OSD/Skin,
+all you need to do is create a new object of your skin class, as in
+
+<p><table><tr><td bgcolor=#F0F0F0><pre>
+new cMySkin;
+</pre></td></tr></table><p>
+
+in the <a href="#Getting started"><tt>Start()</tt></a> function of your plugin.
+Do not delete this object, it will be automatically deleted when the program ends.
+
+<a name="Themes"><hr><h2>Themes</h2>
+
+<center><i><b>Eye of the beholder...</b></i></center><p>
+
+A <i>theme</i> is a collection of colors that can be used by a <a href="#Skins">skin</a>.
+Since every skin most likely has its own idea about what parts of it can be
+<i>themed</i>, and different skins may have completely different numbers of
+"themeable" parts, a particular theme can only be used with the skin it was designed
+for. A particular skin, however, can have any number of themes. Which theme
+will be actually used can be defined in Setup/OSD/Theme.
+<p>
+In order to make a skin "themeable" is shall create an object of type cTheme, as in
+
+<p><table><tr><td bgcolor=#F0F0F0><pre>
+static cTheme Theme;
+</pre></td></tr></table><p>
+
+The next step is to define the colors that shall be provided by this theme, as in
+
+<p><table><tr><td bgcolor=#F0F0F0><pre>
+THEME_CLR(Theme, clrTitle,        0xFFBC8024);
+THEME_CLR(Theme, clrButtonRedFg,  clrWhite);
+THEME_CLR(Theme, clrButtonRedBg,  clrRed);
+</pre></td></tr></table><p>
+
+<tt>THEME_CLR()</tt> is a helper macro that adds the given color name
+and its default color value to the theme.
+<p>
+Any color names can be used, but they should always start with <tt>clr...</tt> and
+if a given color has a foreground and a background value, the two names shall be
+distinguished by appending <tt>...Fg</tt> and <tt>...Bg</tt>, respectively.
+<p>
+Color values can be either 32 bit hexadecimal numbers in the form 0xAARRGGBB
+(where the individual bytes represent Alpha (transparency), Red, Green
+and Blue component, respectively), or one of the predefined color names from
+<tt>VDR/osd.h</tt>.
+<p>
+In the actual drawing code of a skin, the color names defined with the <tt>THEME_CLR()</tt>
+macros can be used to fetch the actual color values from the theme, as in
+
+<p><table><tr><td bgcolor=#F0F0F0><pre>
+osd-&gt;DrawText(x, y, s, Theme.Color(clrButtonRedFg), Theme.Color(clrButtonRedBg), font);
+</pre></td></tr></table><p>
+
+By default this will use the colors that have been defined in the respective
+<tt>THEME_CLR()</tt> line, but may be overwritten through user supplied theme
+files (see <tt>man vdr(5)</tt> for information about the format of a theme file).
+<!--X1.3.7--></td></tr></table>
 
 <a name="Devices"><hr><h2>Devices</h2>
 
@@ -1297,7 +1435,7 @@ into a VDR system; or an analog TV receiver card, which does the MPEG encoding
 "on the fly" - assuming your machine is fast enough), or just a software program that takes an MPEG data
 stream and displays it, for instance, on an existing graphics adapter.
 <p>
-To implement an additional device, a plugin must derive a class from cDevice:
+To implement an additional device, a plugin must derive a class from <tt>cDevice</tt>:
 
 <p><table><tr><td bgcolor=#F0F0F0><pre>
 #include &lt;vdr/device.h&gt;
@@ -1374,7 +1512,7 @@ The functions to implement replaying capabilites are
 virtual bool HasDecoder(void) const;
 virtual bool CanReplay(void) const;
 virtual bool SetPlayMode(ePlayMode PlayMode);
-<!--X1.2.6--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
+<!--X1.2.6--><table width=100%><tr><td bgcolor=#00AA00>&nbsp;</td><td width=100%>
 virtual int64_t GetSTC(void);
 <!--X1.2.6--></td></tr></table>
 virtual void TrickSpeed(int Speed);
@@ -1396,7 +1534,7 @@ virtual void SetVideoFormat(bool VideoFormat16_9);
 virtual void SetVolumeDevice(int Volume);
 </pre></td></tr></table><p>
 
-<!--X1.3.0--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+<!--X1.3.0--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
 <p>
 <b>Section Filtering</b>
 <p>
@@ -1426,23 +1564,46 @@ handle section data.
 <p>
 <b>On Screen Display</b>
 <p>
+<!--X1.3.7--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
 If your device provides On Screen Display (OSD) capabilities (which every device
-that is supposed to be used as a primary device should do), it can implement
-the function
+that is supposed to be used as a primary device should do), it shall implement
+an "OSD provider" class, derived from <tt>cOsdProvider</tt>, which, when its <tt>CreateOsd()</tt>
+function is called, returns an object derived from <tt>cOsd</tt>, which can be used to
+access the device's OSD:
+
+<p><table><tr><td bgcolor=#F0F0F0><pre>
+class cMyOsdProvider : public cOsdProvider {
+public:
+  cMyOsdProvider(void);
+  virtual cOsd *CreateOsd(int Left, int Top);
+  };
+</pre></td></tr></table><p>
+
+In its <tt>MakePrimaryDevice()</tt> function the device shall create an object
+of this class, as in
 
 <p><table><tr><td bgcolor=#F0F0F0><pre>
-virtual cOsdBase *NewOsd(int x, int y);
+void cMyDevice::MakePrimaryDevice(bool On)
+{
+  new cMyOsdProvider;
+}
 </pre></td></tr></table><p>
 
-which must return a newly created object of a derived cOsdBase class that
-implements the functions necessary to display OSD information on your device.
-The caller of this function will delete the object as soon as it is no longer
-needed.
+The OSD provider object is allocated on the heap and shall not be deleted
+(it will be deleted automatically in case a different device sets up an OSD
+provider, or when the program ends).
+
+Note that an OSD implementation need not be physically linked to the device
+in any way. All it needs to make sure is that the OSD will be visible to the
+user - whether this goes through OSD facilities of the physical device (like
+a "full featured" DVB card) or through a graphics adapter that overlays its
+output with the video signal, doesn't matter.
+<!--X1.3.7--></td></tr></table>
 
 <p>
 <b>Initializing new devices</b>
 <p>
-A derived cDevice class shall implement a static function
+A derived <tt>cDevice</tt> class shall implement a static function
 in which it determines whether the necessary hardware to run this sort of
 device is actually present in this machine (or whatever other prerequisites
 might be important), and then creates as many device objects as necessary.