git.sesse.net Git - vlc/blob - include/vlc_osd.h

   1 /*****************************************************************************
   2  * vlc_osd.h - OSD menu definitions and function prototypes
   3  *****************************************************************************
   4  * Copyright (C) 2004-2005 M2X
   5  * $Id$
   6  *
   7  * Authors: Jean-Paul Saman <jpsaman #_at_# m2x dot nl>
   8  *
   9  * Added code from include/osd.h written by:
  10  * Copyright (C) 2003-2005 the VideoLAN team
  11  * Authors: Sigmund Augdal Helberg <dnumgis@videolan.org>
  12  *
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2 of the License, or
  16  * (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with this program; if not, write to the Free Software
  25  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  26  *****************************************************************************/
  27
  28 /**
  29  * \file
  30  * The OSD menu core creates the OSD menu structure in memory. It parses a
  31  * configuration file that defines all elements that are part of the menu. The
  32  * core also handles all actions and menu structure updates on behalf of video
  33  * subpicture filters.
  34  *
  35  * The file modules/video_filters/osdmenu.c implements a subpicture filter that
  36  * specifies the final information on positioning of the current state image.
  37  * A subpicture filter is called each time a video picture has to be rendered, it
  38  * also gives a start and end date to the subpicture. The subpicture can be streamed
  39  * if used inside a transcoding command. For example:
  40  *
  41  *  vlc dvdsimple:///dev/dvd --extraintf rc
  42  *  --sout='#transcode{osd}:std{access=udp,mux=ts,dst=dest_ipaddr}'
  43  *  --osdmenu-file=share/osdmenu/dvd.cfg
  44  *
  45  * Each OSD menu element, called "action", defines a hotkey action. Each action
  46  * can have several states (unselect, select, pressed). Each state has an image
  47  * that represents the state visually. The commands "menu right", "menu left",
  48  * "menu up" and "menu down" are used to navigate through the OSD menu structure.
  49  * The commands "menu on" or "menu show" and "menu off" or "menu hide" respectively
  50  * show and hide the OSD menu subpictures.
  51  *
  52  * There is one special element called "range". A range is an arbritary range
  53  * of state images that can be browsed using "menu up" and "menu down" commands
  54  * on the rc interface.
  55  *
  56  * The OSD menu configuration file uses a very simple syntax and basic parser.
  57  * A configuration file has the ".cfg". An example is "share/osdmenu/dvd256.cfg".
  58  */
  59
  60 #ifndef _VLC_OSD_H
  61 #define _VLC_OSD_H 1
  62
  63 #include "vlc_video.h"
  64
  65 # ifdef __cplusplus
  66 extern "C" {
  67 # endif
  68
  69 /**
  70  * \brief The OSD Menu configuration file format.
  71  *
  72  * The configuration file syntax is very basic and so is its parser. See the
  73  * BNF formal representation below:
  74  *
  75  * The keywords FILENAME and PATHNAME represent the filename and pathname specification
  76  * that is valid for the Operating System VLC is compiled for.
  77  *
  78  * The hotkey actions that are supported by VLC are documented in the file src/libvlc. The
  79  * file include/vlc_keys.h defines some hotkey internals.
  80  *
  81  * CONFIG_FILE = FILENAME '.cfg'
  82  * WS = [ ' ' | '\t' ]+
  83  * OSDMEN_PATH = PATHNAME
  84  * DIR = 'dir' WS OSDMENU_PATH '\n'
  85  * STATE = [ 'unselect' | 'select' | 'pressed' ]
  86  * HOTKEY_ACTION = 'key-' [ 'a' .. 'z', 'A' .. 'Z', '-' ]+
  87  *
  88  * ACTION_TYPE        = 'type' 'volume' '\n'
  89  * ACTION_BLOCK_START = 'action' WS HOTKEY_ACTION WS '('POS','POS')' '\n'
  90  * ACTION_BLOCK_END   = 'end' '\n'
  91  * ACTION_STATE       = STATE WS FILENAME '\n'
  92  * ACTION_RANGE_START = 'range' WS HOTKEY_ACTION WS DEFAULT_INDEX '\n'
  93  * ACTION_RANGE_END   = 'end' '\n'
  94  * ACTION_RANGE_STATE = FILENAME '\n'
  95  *
  96  * ACTION_BLOCK_RANGE = ACTION_RANGE_START [WS ACTION_RANGE_STATE]+ WS ACTION_RANGE_END
  97  * ACTION_BLOCK = ACTION_BLOCK_START [WS ACTION_TYPE*] [ [WS ACTION_STATE]+3 | [WS ACTION_BLOCK_RANGE]+1 ] ACTION_BLOCK_END
  98  * CONFIG_FILE_CONTENTS = DIR [ACTION_BLOCK]+
  99  *
 100  */
 101
 102 /**
 103  * OSD menu position and picture type defines
 104  */
 105
 106 #define OSD_ALIGN_LEFT 0x1
 107 #define OSD_ALIGN_RIGHT 0x2
 108 #define OSD_ALIGN_TOP 0x4
 109 #define OSD_ALIGN_BOTTOM 0x8
 110
 111 #define OSD_HOR_SLIDER 1
 112 #define OSD_VERT_SLIDER 2
 113
 114 #define OSD_PLAY_ICON 1
 115 #define OSD_PAUSE_ICON 2
 116 #define OSD_SPEAKER_ICON 3
 117 #define OSD_MUTE_ICON 4
 118
 119 /**
 120  * Text style information.
 121  * This struct is currently ignored
 122  */
 123 struct text_style_t
 124 {
 125     int i_size;
 126     uint32_t i_color;
 127     vlc_bool_t b_italic;
 128     vlc_bool_t b_bold;
 129     vlc_bool_t b_underline;
 130 };
 131 static const text_style_t default_text_style = { 22, 0xffffff, VLC_FALSE, VLC_FALSE, VLC_FALSE };
 132
 133 /**
 134  * OSD menu button states
 135  *
 136  * Every button has three states, either it is unselected, selected or pressed.
 137  * An OSD menu skin can associate images with each state.
 138  *
 139  *  OSD_BUTTON_UNSELECT 0
 140  *  OSD_BUTTON_SELECT   1
 141  *  OSD_BUTTON_PRESSED  2
 142  */
 143 #define OSD_BUTTON_UNSELECT 0
 144 #define OSD_BUTTON_SELECT   1
 145 #define OSD_BUTTON_PRESSED  2
 146
 147 /**
 148  * OSD State object
 149  *
 150  * The OSD state object holds the state and associated images for a particular state
 151  * on the screen. The picture is displayed when this state is the active state.
 152  */
 153 struct osd_state_t
 154 {
 155     osd_state_t *p_next;    /*< pointer to next state */
 156     osd_state_t *p_prev;    /*< pointer to previous state */
 157     picture_t   *p_pic;     /*< picture of state */
 158
 159     char        *psz_state; /*< state name */
 160     int          i_state;   /*< state index */
 161 };
 162
 163 /**
 164  * OSD Button object
 165  *
 166  * An OSD Button has different states. Each state has an image for display.
 167  */
 168 struct osd_button_t
 169 {
 170     osd_button_t *p_next;   /*< pointer to next button */
 171     osd_button_t *p_prev;   /*< pointer to previous button */
 172     osd_button_t *p_up;     /*< pointer to up button */
 173     osd_button_t *p_down;   /*< pointer to down button */
 174
 175     osd_state_t *p_current_state; /*< pointer to current state image */
 176     osd_state_t *p_states; /*< doubly linked list of states */
 177     picture_t   *p_feedback; /*< feedback picture */
 178
 179     char    *psz_name;     /*< name of button */
 180
 181     /* These member should probably be a struct hotkey */
 182     char    *psz_action;      /*< hotkey action name on button*/
 183     char    *psz_action_down; /*< hotkey action name on range buttons for command "menu down" */
 184     /* end of hotkey specifics */
 185
 186     int     i_x;            /*< x-position of button visible state image */
 187     int     i_y;            /*< y-position of button visible state image */
 188
 189     /* range style button */
 190     vlc_bool_t   b_range;    /*< button should be interpreted as range */
 191     int          i_ranges;   /*< number of states */
 192 };
 193
 194 /**
 195  * OSD Menu State object
 196  *
 197  * Represents the current state as displayed.
 198  */
 199 /* Represent the menu state */
 200 struct osd_menu_state_t
 201 {
 202     int     i_x;        /*< x position of spu region */
 203     int     i_y;        /*< y position of spu region */
 204     int     i_width;    /*< width of spu region */
 205     int     i_height;   /*< height of spu region */
 206
 207     picture_t    *p_pic;  /*< pointer to picture to display */
 208     osd_button_t *p_visible; /*< shortcut to visible button */
 209
 210     vlc_bool_t b_menu_visible; /*< menu currently visible? */
 211     vlc_bool_t b_update;       /*< update OSD Menu when VLC_TRUE */
 212
 213     /* quick hack to volume state. */
 214     osd_button_t *p_volume; /*< pointer to volume range object. */
 215 };
 216
 217 /**
 218  * OSD Menu object
 219  *
 220  * The main OSD Menu object, which holds a linked list to all buttons
 221  * and images that defines the menu. The p_state variable represents the
 222  * current state of the OSD Menu.
 223  */
 224 struct osd_menu_t
 225 {
 226     VLC_COMMON_MEMBERS
 227
 228     int     i_x;        /*< x-position of OSD Menu on the video screen */
 229     int     i_y;        /*< y-position of OSD Menu on the video screen */
 230     int     i_width;    /*< width of OSD Menu on the video screen */
 231     int     i_height;   /*< height of OSD Menu on the video screen */
 232
 233     char             *psz_path;  /*< directory where OSD menu images are stored */
 234     osd_button_t     *p_button;  /*< doubly linked list of buttons */
 235     osd_menu_state_t *p_state;   /*< current state of OSD menu */
 236
 237     /* quick link in the linked list. */
 238     osd_button_t  *p_last_button; /*< pointer to last button in the list */
 239 };
 240
 241 /**
 242  * Initialize an osd_menu_t object
 243  *
 244  * This functions has to be called before any call to other osd_menu_t* functions.
 245  * It creates the osd_menu object and holds a pointer to it during its lifetime.
 246  */
 247 VLC_EXPORT( osd_menu_t *, __osd_MenuCreate, ( vlc_object_t *, const char * ) );
 248
 249 /**
 250  * Delete the osd_menu_t object
 251  *
 252  * This functions has to be called to release the associated module and memory
 253  * for the osdmenu. After return of this function the pointer to osd_menu_t* is invalid.
 254  */
 255 VLC_EXPORT( void, __osd_MenuDelete, ( vlc_object_t *, osd_menu_t * ) );
 256
 257 /**
 258  * Change state on an osd_button_t.
 259  *
 260  * This function selects the specified state and returns a pointer to it. The
 261  * following states are currently supported:
 262  * \see OSD_BUTTON_UNSELECT
 263  * \see OSD_BUTTON_SELECT
 264  * \see OSD_BUTTON_PRESSED
 265  */
 266 VLC_EXPORT( osd_state_t *, __osd_StateChange, ( osd_state_t *, const int ) );
 267
 268 #define osd_MenuCreate(object,file) __osd_MenuCreate( VLC_OBJECT(object), file )
 269 #define osd_MenuDelete(object,osd)  __osd_MenuDelete( VLC_OBJECT(object), osd )
 270 #define osd_StateChange(object,value) __osd_StateChange( object, value )
 271
 272 /**
 273  * Show the OSD menu.
 274  *
 275  * Show the OSD menu on the video output or mux it into the stream.
 276  * Every change to the OSD menu will now be visible in the output. An output
 277  * can be a video output window or a stream (\see stream output)
 278  */
 279 VLC_EXPORT( void, __osd_MenuShow, ( vlc_object_t * ) );
 280
 281 /**
 282  * Hide the OSD menu.
 283  *
 284  * Stop showing the OSD menu on the video output or mux it into the stream.
 285  */
 286 VLC_EXPORT( void, __osd_MenuHide, ( vlc_object_t * ) );
 287
 288 /**
 289  * Activate the action of this OSD menu item.
 290  *
 291  * The rc interface command "menu select" triggers the sending of an hotkey action
 292  * to the hotkey interface. The hotkey that belongs to the current highlighted
 293  * OSD menu item will be used.
 294  */
 295 VLC_EXPORT( void, __osd_MenuActivate,   ( vlc_object_t * ) );
 296
 297 #define osd_MenuShow(object) __osd_MenuShow( VLC_OBJECT(object) )
 298 #define osd_MenuHide(object) __osd_MenuHide( VLC_OBJECT(object) )
 299 #define osd_MenuActivate(object)   __osd_MenuActivate( VLC_OBJECT(object) )
 300
 301 /**
 302  * Next OSD menu item
 303  *
 304  * Select the next OSD menu item to be highlighted.
 305  * Note: The actual position on screen of the menu item is determined by the the
 306  * OSD menu configuration file.
 307  */
 308 VLC_EXPORT( void, __osd_MenuNext, ( vlc_object_t * ) );
 309
 310 /**
 311  * Previous OSD menu item
 312  *
 313  * Select the previous OSD menu item to be highlighted.
 314  * Note: The actual position on screen of the menu item is determined by the the
 315  * OSD menu configuration file.
 316  */
 317 VLC_EXPORT( void, __osd_MenuPrev, ( vlc_object_t * ) );
 318
 319 /**
 320  * OSD menu item above
 321  *
 322  * Select the OSD menu item above the current item to be highlighted.
 323  * Note: The actual position on screen of the menu item is determined by the the
 324  * OSD menu configuration file.
 325  */
 326 VLC_EXPORT( void, __osd_MenuUp,   ( vlc_object_t * ) );
 327
 328 /**
 329  * OSD menu item below
 330  *
 331  * Select the next OSD menu item below the current item to be highlighted.
 332  * Note: The actual position on screen of the menu item is determined by the the
 333  * OSD menu configuration file.
 334  */
 335 VLC_EXPORT( void, __osd_MenuDown, ( vlc_object_t * ) );
 336
 337 #define osd_MenuNext(object) __osd_MenuNext( VLC_OBJECT(object) )
 338 #define osd_MenuPrev(object) __osd_MenuPrev( VLC_OBJECT(object) )
 339 #define osd_MenuUp(object)   __osd_MenuUp( VLC_OBJECT(object) )
 340 #define osd_MenuDown(object) __osd_MenuDown( VLC_OBJECT(object) )
 341
 342 /**
 343  * Display the audio volume bitmap.
 344  *
 345  * Display the correct audio volume bitmap that corresponds to the
 346  * current Audio Volume setting.
 347  */
 348 VLC_EXPORT( void, __osd_Volume, ( vlc_object_t * ) );
 349
 350 #define osd_Volume(object)     __osd_Volume( VLC_OBJECT(object) )
 351
 352 /**
 353  * Retrieve a non modifyable pointer to the OSD Menu state
 354  *
 355  */
 356 static inline const osd_menu_state_t *osd_GetMenuState( osd_menu_t *p_osd )
 357 {
 358     return( p_osd->p_state );
 359 }
 360
 361 /**
 362  * Get the last key press received by the OSD Menu
 363  *
 364  * Returns 0 when no key has been pressed or the value of the key pressed.
 365  */
 366 static inline vlc_bool_t osd_GetKeyPressed( osd_menu_t *p_osd )
 367 {
 368     return( p_osd->p_state->b_update );
 369 }
 370
 371 /**
 372  * Set the key pressed to a value.
 373  *
 374  * Assign a new key value to the last key pressed on the OSD Menu.
 375  */
 376 static inline void osd_SetKeyPressed( vlc_object_t *p_this, int i_value )
 377 {
 378     vlc_value_t val;
 379
 380     val.i_int = i_value;
 381     var_Set( p_this, "key-pressed", val );
 382 }
 383
 384 /**
 385  * Update the OSD Menu visibility flag.
 386  *
 387  * VLC_TRUE means OSD Menu should be shown. VLC_FALSE means OSD Menu should not be shown.
 388  */
 389 static inline void osd_SetMenuVisible( osd_menu_t *p_osd, vlc_bool_t b_value )
 390 {
 391     vlc_value_t val;
 392
 393     val.b_bool = p_osd->p_state->b_menu_visible = b_value;
 394     var_Set( p_osd, "osd-menu-visible", val );
 395 }
 396
 397 /**
 398  * Update the OSD Menu update flag
 399  *
 400  * If the OSD Menu should be updated then set the update flag to VLC_TRUE, else to VLC_FALSE.
 401  */
 402 static inline void osd_SetMenuUpdate( osd_menu_t *p_osd, vlc_bool_t b_value )
 403 {
 404     vlc_value_t val;
 405
 406     val.b_bool = p_osd->p_state->b_update = b_value;
 407     var_Set( p_osd, "osd-menu-update", val );
 408 }
 409
 410 /**
 411  * Textual feedback
 412  *
 413  * Functions that provide the textual feedback on the OSD. They are shown on hotkey commands. The feedback
 414  * is also part of the osd_button_t object. The types are declared in the include file
 415  * include/vlc_osd.h
 416  * @see vlc_osd.h
 417  */
 418 VLC_EXPORT( int, osd_ShowTextRelative, ( spu_t *, int, char *, text_style_t *, int, int, int, mtime_t ) );
 419 VLC_EXPORT( int, osd_ShowTextAbsolute, ( spu_t *, int, char *, text_style_t *, int, int, int, mtime_t, mtime_t ) );
 420 VLC_EXPORT( void,osd_Message, ( spu_t *, int, char *, ... ) );
 421
 422 /**
 423  * Default feedback images
 424  *
 425  * Functions that provide the default OSD feedback images on hotkey commands. These feedback
 426  * images are also part of the osd_button_t object. The types are declared in the include file
 427  * include/vlc_osd.h
 428  * @see vlc_osd.h
 429  */
 430 VLC_EXPORT( int, osd_Slider, ( vlc_object_t *, spu_t *, int, int, int, int, short ) );
 431 VLC_EXPORT( int, osd_Icon, ( vlc_object_t *, spu_t *, int, int, int, short ) );
 432
 433 /**
 434  * Loading and parse the OSD Configuration file
 435  *
 436  * These functions load/unload the OSD menu configuration file and create/destroy the
 437  * themable OSD menu structure on the OSD object.
 438  */
 439 VLC_EXPORT( int,  osd_ConfigLoader, ( vlc_object_t *, const char *, osd_menu_t ** ) );
 440 VLC_EXPORT( void, osd_ConfigUnload, ( vlc_object_t *, osd_menu_t ** ) );
 441
 442 # ifdef __cplusplus
 443 }
 444 # endif
 445
 446 #endif /* _VLC_OSD_H */