path: root/SKINS

How To create text-based skins
------------------------------

[ TODO remove this ]
You may encounter bracketed phrases in this document. Please ignore them, they
are comments for me which will be removed in official release versions.

[ TODO move this to manual ]
The Skin itself is located in a subdirectory "text2skin" inside the "plugins" 
directory of your VDR configuration directory. This usually is the video 
directory, if you didn't specify -c on the commandline. If you did, the 
subdirectory is located there.  Each skin has an own subdirectory there, which 
holds the skin description file and the needed image files. The skin 
description file must have the same name as the skin directory, with the 
extension ".skin"

Example (the Skin is called myskin):
/video0/plugins/text2skin/
/video0/plugins/text2skin/myskin/
/video0/plugins/text2skin/msykin/msykin.skin
/video0/plugins/text2skin/myskin/channeldisplay.png

It is important that you understand the limitations of the OSD memory. If there
are too many objects with too many colors defined, VDR will throw an error and
some areas will not be displayed. For other output devices this limitations may
not apply, so if you are planning to design a skin for another output device,
feel free to use more colors, but remember that VDR can handle a maximum of 256
areas per object.

An object is defined to be a specific area with a specific palette and color 
depth. Those objects will be referred to as 'backgrounds' later on. Calculate
the dimensions of them wisely, since overlapping areas or oversized areas will
lead to an error. Also, the widht and height of each area has to be a multiple
of four [ TODO may not apply to different output devices ].


Creation of an image
--------------------

I used gimp to create some test images displaying things on screen, although
I don't know much about image processing :-). To give an advice, I will point
out how I created those test images.

I've used a template for a menu provided by a community member, tiled it into
sections fully covered by the image. That made three images in this case. Then
I added a little bit of transparency to the image covering the middle part. I've
resized the image so that it's width and height were multiples of four. Now I've
added 50% transparency to the top layer of the image. Then I've reduced the 
colordepth of the image (Image->Mode->Indexed) to 14 colors (of course the 
image may not be too extensive, but 14 colors can give some nice gradients). 
That leaves two colors for text and progress bar in the same display. Reduce 
the number of colors according to the background depth and additional 
decoration you intend to use. I saved the results to a png file and placed the
result into the skin.

If you intend to use xpm's, be aware that VDR doesn't know about named colors,
so some images GIMP creates will not be read on-the-fly, because GIMP may use
some named colors, but VDR only recognizes "None".


The Description File Format
---------------------------

It is a simple configuration file, consisting of Sections and items. 
Commentary lines can be added when they are lead in by a '#'. Blank lines will
be ignored. A section is placed in '[]' brackets. An item is lead in by an 
'Item=object' phrase.

Example:
Item=Skin,name=Test,version=0.0.1;
[Channel]
Item=Background,path=channeltop.xpm,x=42,y=350,width=540,height=32,bg=#00FFFFFF;
Item=Background,path=channel.png,x=48,y=382,width=528,height=84;
Item=ChannelNumberName,x=50,y=355,fg=#FFFFFFFF,bg=#FF1965FF,font=Sml;
Item=PresentTime,x=52,y=387,fg=#FFFFFFFF,bg=#7F002254,font=Osd;
[Volume]
Item=Background,x=10,y=10,width=10,height=100;
Item=Volumebar,x=10,y=10,width=10,height=100,bg=#FF000000,fg=#FFFFFFFF;


Known Sections
--------------

Section:     [ChannelSmall]
Description: The channel display. It displays the current programme and number
             only, together with some decoration.

Section:     [Channel]
Description: The channel display. It displays the current programme and number,
             together with the currently running programme and possibly a 
             timebar and (not implemented yet) channel logo [ TODO remove 
						 comment ].

Section:     [Volume]
Description: The volume display. It displays the volumebar and possibly a mute
             symbol, along with decorative items.

Section:     [ReplayMode]
Description: The replay modes display. Will be shown if only the replay mode
             symbol shall be shown.

Section:     [Replay]
Description: [ TODO ] Full replay display.

Section:     [Message]
Description: [ TODO ] Message only display.

Section:     [Menu]
Description: [ TODO ] Full menu.


Known Items
-----------

Item:        Item=Skin
Description: This identifies the skin and adds a description to it.
Parameters:  name, version

Item:        Item=Background
Description: This adds a background area for the specific display. This area 
             will be used to draw anything else, so you have to define a 
             background for everything that will be drawn later on. You can 
             define a background image for that area here, too. That picture
             has to be the same width and height as the area. If you don't use
             a background image, the area will be initialized with the bg color
             (default 0). If an image is present, the background color will 
             replace the color 0 in the images palette, and the foreground 
             color will replace color 1.
Parameters:  x, y, width, height, bpp, path, bg, fg

Item:        Item=Text
Description: Draws plain text into the given area, using the given foreground
             color. The background color is ignored, so no initializing 
             rectangle will be drawn. If no width or height are given, the
             limits are the background areas.
Parameters:  x, y, text, width, height, fg, font, align

Item:        Item=Image
Description: Draws a plain image into the given area, using background and 
             foreground color (if given) to replace the palette indices 0 
             and 1. 
Parameters:  x, y, width, height, fg, bg, path

Item:        Item=DateTime
Description: Draws a date and time string into the given area. Otherwise, see
             Item=Text
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=Date
Description: Draws a date string into the given area. Otherwise, see Item=Text
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=Time
Description: Draws a time string into the given area. Otherwise, see Item=Text
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=DateTimeF
Description: Draws a string expressing some details of the current date and  
             time. What is to be displayed will be decided by the skin author. 
             The paremeter "format" holds a format string according to the 
             manpage of strftime.
Parameters:  x, y, width, height, fg, font, align, text, format

Item:        Item=ChannelLogo
Description: Draws a logo for the current channel (if present). The logo's 
             filename will be the channel name, and the parameter type 
             gives the file extension. The parameter path can give an 
             additional subdirectory to the skin's directory.
Example:     Item=ChannelLogo,path=logos/,type=png,...;
Parameters:  x, y, width, height, fg, bg, path, type

Item:        Item=ChannelNumberName
Description: Draws the channel number and name into the given area. Otherwise, 
             see Item=Text
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=ChannelNumber
Description: Draws the channel number into the given area. Otherwise, see 
             Item=Text
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=ChannelName
Description: Draws the channel name into the given area. Otherwise, see 
             Item=Text
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=Rectangle
Description: Draws a filled rectangle into the defined area.
Parameters:  x, y, width, height, fg

Item:        Item=Ellipse
Description: Draws a filled ellipse or a part of an ellipse into the defined 
             area.
Parameters:  x, y, width, height, fg

Item:        Item=Timebar
Description: Draws a timebar displaying the progress of the current programme.
             The area will be filled with the background color (if given) and 
             the bar will be drawn using the foreground color. If width is 
             greater than height, the bar will be drawn horizontally, otherwise
             vertically.
Parameters:  x, y, width, height, fg, bg

Item:        Item=PresentTime
Description: Draws the start time of the present programme. 
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=PresentTitle
Description: Draws the title of the present programme. 
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=PresentShortText
Description: Draws the short text (or episode name) of the present programme. 
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=FollowingTime
Description: Draws the start time of the following programme. 
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=FollowingTitle
Description: Draws the title of the following programme. 
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=FollowingShortText
Description: Draws the short text (or episode name) of the following programme. 
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=SymbolTeletext
Description: Draws the specified image into the specified location if the 
             current channel has teletext. If that is not the case, the 
             alternative image (if given) will be displayed. For details on the
             image handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolAudio
Description: Draws the specified image into the specified location if the 
             current channel has multiple languages. If that is not the case, 
             the alternative image (if given) will be displayed. For details on
             the image handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolDolby
Description: Draws the specified image into the specified location if the 
             current channel has ac3 sound. If that is not the case, the 
             alternative image (if given) will be displayed. For details on the
             image handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolEncrypted
Description: Draws the specified image into the specified location if the 
             current channel is encrypted. If that is not the case, the 
             alternative image (if given) will be displayed. For details on the
             image handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolRecording
Description: Draws the specified image into the specified location if VDR is
             currently recording. If that is not the case, the alternative 
             image (if given) will be displayed. For details on the image 
             handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolRadio
Description: Draws the specified image into the specified location if the 
             current channel is a radio channel. If that is not the case, the 
             alternative image (if given) will be displayed. For details on the
             image handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolPlay
Description: Draws the specified image into the specified location if the 
             current replay is playing normally. If that is not the case, the 
             alternative image (if given) will be displayed. For details on the
             image handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolPause
Description: Draws the specified image into the specified location if the 
             current replay is paused. If that is not the case, the 
             alternative image (if given) will be displayed. For details on the
             image handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolFastFwd
Description: Draws the specified image into the specified location if the 
             current replay is fast forwarding. If that is not the case, the 
             alternative image (if given) will be displayed. For details on the
             image handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolFastRew
Description: Draws the specified image into the specified location if the 
             current replay is fast rewinding. If that is not the case, the 
             alternative image (if given) will be displayed. For details on the
             image handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolSlowFwd
Description: Draws the specified image into the specified location if the 
             current replay is slow forwarding. If that is not the case, the 
             alternative image (if given) will be displayed. For details on the
             image handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolSlowRew
Description: Draws the specified image into the specified location if the 
             current replay is slow rewinding. If that is not the case, the 
             alternative image (if given) will be displayed. For details on the
             image handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolEventRunning
Description: Draws the specified image into the specified location if the 
             displayed event (in menu display) is currently running. If that 
             is not the case, the alternative image (if given) will be 
             displayed. For details on the image handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolEventTimer
Description: Draws the specified image into the specified location if the 
             displayed event (in menu display) will be recorded. If that is 
             not the case, the alternative image (if given) will be displayed. 
             For details on the image handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolEventVPS
Description: Draws the specified image into the specified location if the 
             displayed event (in menu display) is VPS. If that is not the 
             case, the alternative image (if given) will be displayed. For 
             details on the image handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolScrollUp
Description: Draws the specified image into the specified location if the 
             current display is scrollable and not at the top of its contents.
             If that is not the case, the alternative image (if given) will be 
             displayed. For details on the image handling, see Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=SymbolScrollDown
Description: Draws the specified image into the specified location if the 
             current display is scrollable and not at the bottom of its 
             contents. If that is not the case, the alternative image (if 
             given) will be displayed. For details on the image handling, see 
             Item=Background.
Parameters:  x, y, width, height, path, altpath, fg, bg

Item:        Item=Language
Description: Draws a logo for the current language (currently the only 
             languages VDR knows are "Audio 1" and possibly "Audio 2", 
             regardless of the real language). For more information on how
             the logo is found, see Item=ChannelLogo. The logo's filename will
             be the language's name.
Parameters:  x, y, width, height, path, type, fg, bg

Item:        Item=Volumebar
Description: Draws a volumebar into the specified area. For more details, see
             Item=Timebar.
Parameters:  x, y, width, height, fg, bg

Item:        Item=Mute
Description: Draws a mute symbol and/or text (if given) into the specified area.
             See Item=Text and Item=Background for more on text and image 
             handling.
Parameters:  x, y, width, height, fg, bg, text, font, align, path

Item:        Item=Replaybar
Description: Draws a progressbar displaying the replay progress into the 
             specified area. For more details, see Item=Timebar.
Parameters:  x, y, width, height, fg, bg

Item:        Item=ReplayTitle
Description: Draws the title of the current replay.
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=ReplayCurrent
Description: Draws the current time in the current replay.
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=ReplayTotal
Description: Draws the total length of the current replay.
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=ReplayJump
Description: Draws the "Jump:" prompt (if present) of the current replay.
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=MessageStatus
Description: Draws the current status message (if present).
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=MessageInfo
Description: Draws the current info message (if present).
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=MessageWarning
Description: Draws the current warning message (if present).
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=MessageError
Description: Draws the current error message (if present).
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=MenuArea
Description: Specifies the area in which the menu items will be shown as a
             list.
Parameters:  x, y, width, height

Item:        Item=MenuItem
Description: Specifies how one item is drawn in the list of menu items.
             list.
Parameters:  [x,] [y,] width, height, fg, bg, font, align

Item:        Item=MenuCurrent
Description: Specifies how the currently selected item is drawn in the list of 
             menu items.
             list.
Parameters:  [x,] [y,] width, height, fg, bg, font, align

Item:        Item=MenuTitle
Description: Draws the title line of the displayed menu.
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=MenuRed, Item=MenuGreen, Item=MenuYellow, Item=MenuBlue
Description: Draws the red, green, yellow or blue (respectively) button.
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=MenuText
Description: Draws the current menu text in a scrollable text-area. If this
             item is present, SymbolScrollUp and SymbolScrollDown apply, too.
Parameters:  x, y, width, height, fg, [bg,] font, [align,] text

Item:        Item=MenuEventTitle
Description: Draws the title of the currently selected event when viewing EPG
             entries.
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=MenuEventShortText
Description: Draws the short text or episode name of the currently selected 
             event when viewing EPG entries.
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=MenuEventDescription
Description: Draws the long text of the currently selected event when viewing 
             EPG entries in a scrollable text-area. If this item is present,
             SymbolScrollUp and SymbolScrollDown apply, too.
Parameters:  x, y, width, height, fg, [bg,] font, [align,] text

Item:        Item=MenuEventTime
Description: Draws the start time of the currently selected event when viewing 
             EPG entries.
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=MenuEventEndTime
Description: Draws the end time of the currently selected event when viewing 
             EPG entries.
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=MenuEventVPSTime
Description: Draws the vps time of the currently selected event when viewing 
             EPG entries, if that is different from the start time.
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=MenuEventDate
Description: Draws the date of the currently selected event when viewing 
             EPG entries.
Parameters:  x, y, width, height, fg, font, align, text

Item:        Item=MenuEventDateTimeF
Description: Draws a string expressing some details of the start time of the
             currently selected event when viewing EPG entries. What is to 
             be displayed will be decided by the skin author. The paremeter 
             "format" holds a format string according to the manpage of 
             strftime.
Parameters:  x, y, width, height, fg, font, align, text, format

Item:        Item=MenuRecording
Description: Draws the summary of the currently selected recording when 
             browsing recordings in a scrollable text-area. If this item is 
             present, SymbolScrollUp and SymbolScrollDown apply, too.
Parameters:  x, y, width, height, fg, [bg,] font, [align,] text

Known Parameters
----------------

Parameter:   x
Description: A positive number representing the vertical offset in pixels.
Default:     MANDATORY

Parameter:   y
Description: A positive number representing the horizontal offset in pixels.
Default:     MANDATORY

Parameter:   width
Description: A positive number representing the width in pixels.
Default:     not given (sometimes mandatory)

Parameter:   height
Description: A positive number representing the height in pixels.
Default:     not given (sometimes mandatory)

Parameter:   bpp
Description: A positive number representing the depth of a background area.
             Possible values are 1, 2, 3, 4 and 8 mapping to 2, 4, 8, 16 and 
             256 colors.
Default:     4 (16 colors)

Parameter:   fg
Description: A hex quadriplet [ TODO is this word correct?! ] introduced by '#'
             representing a 32-bit foreground color in the order ARGB.
Default:     not given
Example:     #ff000000

Parameter:   bg
Description: A hex quadriplet [ TODO is this word correct?! ] introduced by '#'
             representing a 32-bit background color in the order ARGB.
Default:     not given

Parameter:   font
Description: A string representing one of VDR's skins, possible values are 
             'Osd', 'Sml' and 'Fix'.
Default:     Osd

Parameter:   path
Description: A string representing a path- and filename relative to the skin
             directory. Currently, xpm images and png files (with alphachannel
             support) can be loaded, but the number of different colors used
             in the image must not exceed those possible in the corresponding
             background area.
Default:     not given

Parameter:   altpath
Description: A string representing a path- and filename relative to the skin
             directory. This is used for for displaying alternate images i.e. 
             for symbols. For more information, see path=...
Default:     not given

Parameter:   text
Description: For non-text-items (and for the item "Text" itself), this is the
             plain text to be displayed. For items that have it's own texts
             (such as "Date", "PresentTitle" etc.), this is a template that 
             defines how the text is to be displayed. A dollar symbol '$' will
             be replaced by the original text.
Default:     not given
Example:     Item=ReplayCurrent,text=Current: $; would display for example
             "Current: 0:00:21" instead of only "0:00:21".

Parameter:   type
Description: The string giving the file extensions for logos.
Default:     not given

Parameter:   type
Description: The format string for a date/time display according to strftime.
Default:     ""

Parameter:   align
Description: A number describing the text alignment. Possible values are '0'
             for left aligned, '1' for centered and '2' for right aligned.
Default:     0