vlc_osd.h 14.1 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
/*****************************************************************************
 * osd.h - OSD menu definitions and function prototypes
 *****************************************************************************
 * Copyright (C) 2004-2005 M2X
 * $Id: osd.h 9451 2004-12-01 01:07:08Z jpsaman $
 *
 * Authors: Jean-Paul Saman <jpsaman #_at_# m2x dot nl>
 *
 * 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, USA.
 *****************************************************************************/

/**
 * \file
 * The OSD menu core creates the OSD menu structure in memory. It parses a 
 * configuration file that defines all elements that are part of the menu. The 
 * core also handles all actions and menu structure updates on behalf of video 
 * subpicture filters.
 *
 * The file modules/video_filters/osdmenu.c implements a subpicture filter that
 * specifies the final information on positioning of the current state image. 
 * A subpicture filter is called each time a video picture has to be rendered, it
 * also gives a start and end date to the subpicture. The subpicture can be streamed
 * if used inside a transcoding command. For example:
 *
 *  vlc dvdsimple:///dev/dvd --extraintf rc
 *  --sout='#transcode{osdenc=dvbsub,osdcoded=YUVP,sfilter=osdmenu} 
 *  --osdmenu-file share/osdmenu/dvd.cfg
 *
 * Each OSD menu element, called "action", defines a hotkey action. Each action 
 * can have several states (unselect, select, pressed). Each state has an image 
 * that represents the state visually. The commands "menu right", "menu left", 
 * "menu up" and "menu down" are used to navigate through the OSD menu structure.
 * The commands "menu on" or "menu show" and "menu off" or "menu hide" respectively
 * show and hide the OSD menu subpictures.
 *
 * There is one special element called "range". A range is an arbritary range
 * of state images that can be browsed using "menu up" and "menu down" commands
 * on the rc interface. 
 *  
 * The OSD menu configuration file uses a very simple syntax and basic parser. 
 * A configuration file has the ".cfg". An example is "share/osdmenu/dvd256.cfg".
 */
  
#ifndef _VLC_OSD_H
#define _VLC_OSD_H 1

#include "vlc_video.h"

# ifdef __cplusplus
extern "C" {
# endif

/**
 * The OSD Menu configuration file format.
 *
 * The configuration file syntax is very basic and so is its parser. See the
 * BNF formal representation below:
 *
 * The keywords FILENAME and PATHNAME represent the filename and pathname specification
 * that is valid for the Operating System VLC is compiled for. 
 *
 * The hotkey actions that are supported by VLC are documented in the file src/libvlc. The
 * file include/vlc_keys.h defines some hotkey internals.
 *
 * CONFIG_FILE = FILENAME '.cfg'
 * WS = [ ' ' | '\t' ]+
 * OSDMEN_PATH = PATHNAME
 * DIR = 'dir' WS OSDMENU_PATH '\n'
 * STATE = [ 'unselect' | 'select' | 'pressed' ]
 * HOTKEY_ACTION = 'key-' [ 'a' .. 'z', 'A' .. 'Z', '-' ]+
 * 
 * ACTION_TYPE        = 'type' 'volume' '\n'
 * ACTION_BLOCK_START = 'action' WS HOTKEY_ACTION WS '('POS','POS')' '\n'
 * ACTION_BLOCK_END   = 'end' '\n'
 * ACTION_STATE       = STATE WS FILENAME '\n'
 * ACTION_RANGE_START = 'range' WS HOTKEY_ACTION WS DEFAULT_INDEX '\n'
 * ACTION_RANGE_END   = 'end' '\n'
 * ACTION_RANGE_STATE = FILENAME '\n'
 *
 * ACTION_BLOCK_RANGE = ACTION_RANGE_START [WS ACTION_RANGE_STATE]+ WS ACTION_RANGE_END
 * ACTION_BLOCK = ACTION_BLOCK_START [WS ACTION_TYPE*] [ [WS ACTION_STATE]+3 | [WS ACTION_BLOCK_RANGE]+1 ] ACTION_BLOCK_END
 * CONFIG_FILE_CONTENTS = DIR [ACTION_BLOCK]+
 *
 */ 

/**
 * OSD menu button states
 *
 * Every button has three states, either it is unselected, selected or pressed.
 * An OSD menu skin can associate images with each state.
 *
 *  OSD_BUTTON_UNSELECT 0
 *  OSD_BUTTON_SELECT   1
 *  OSD_BUTTON_PRESSED  2
 */
#define OSD_BUTTON_UNSELECT 0
#define OSD_BUTTON_SELECT   1
#define OSD_BUTTON_PRESSED  2

/**
 * OSD State object
 *
 * The OSD state object holds the state and associated images for a particular state
 * on the screen. The picture is displayed when this state is the active state.
 */
struct osd_state_t
{
    osd_state_t *p_next;    /*< pointer to next state */
    osd_state_t *p_prev;    /*< pointer to previous state */
    picture_t   *p_pic;     /*< picture of state */
    
    char        *psz_state; /*< state name */
    int          i_state;   /*< state index */ 
};

/** 
 * OSD Button object
 *
 * An OSD Button has different states. Each state has an image for display. 
 */
struct osd_button_t
{
    osd_button_t *p_next;   /*< pointer to next button */
    osd_button_t *p_prev;   /*< pointer to previous button */
    osd_button_t *p_up;     /*< pointer to up button */
    osd_button_t *p_down;   /*< pointer to down button */
    
    osd_state_t *p_current_state; /*< pointer to current state image */
    osd_state_t *p_states; /*< doubly linked list of states */
    picture_t   *p_feedback; /*< feedback picture */
        
    char    *psz_name;     /*< name of button */
    
    /* These member should probably be a struct hotkey */
    char    *psz_action;      /*< hotkey action name on button*/
    char    *psz_action_down; /*< hotkey action name on range buttons for command "menu down" */
    /* end of hotkey specifics */
    
    int     i_x;            /*< x-position of button visible state image */
    int     i_y;            /*< y-position of button visible state image */ 
    
    /* range style button */    
    vlc_bool_t   b_range;    /*< button should be interpreted as range */
    int          i_ranges;   /*< number of states */
};

/** 
 * OSD Menu State object
 *
 * Represents the current state as displayed. 
 */
/* Represent the menu state */
struct osd_menu_state_t
{
    int     i_x;        /*< x position of spu region */
    int     i_y;        /*< y position of spu region */
    int     i_width;    /*< width of spu region */
    int     i_height;   /*< height of spu region */    
    
    picture_t    *p_pic;  /*< pointer to picture to display */
    osd_button_t *p_visible; /*< shortcut to visible button */
    
    vlc_bool_t b_menu_visible; /*< menu currently visible? */
    vlc_bool_t b_update;       /*< update OSD Menu when VLC_TRUE */
    
    /* quick hack to volume state. */
    osd_button_t *p_volume; /*< pointer to volume range object. */
};

/**
 * OSD Menu object
 *
 * The main OSD Menu object, which holds a linked list to all buttons
 * and images that defines the menu. The p_state variable represents the
 * current state of the OSD Menu.
 */
struct osd_menu_t
{
    VLC_COMMON_MEMBERS
    
    int     i_x;        /*< x-position of OSD Menu on the video screen */ 
    int     i_y;        /*< y-position of OSD Menu on the video screen */ 
    int     i_width;    /*< width of OSD Menu on the video screen */ 
    int     i_height;   /*< height of OSD Menu on the video screen */ 
    
    char             *psz_path;  /*< directory where OSD menu images are stored */
    osd_button_t     *p_button;  /*< doubly linked list of buttons */
    osd_menu_state_t *p_state;   /*< current state of OSD menu */
        
    /* quick link in the linked list. */
    osd_button_t  *p_last_button; /*< pointer to last button in the list */
};

/**
 * Initialize an osd_menu_t object
 *
 * This functions has to be called before any call to other osd_menu_t* functions.
 * It creates the osd_menu object and holds a pointer to it during its lifetime.
 */
VLC_EXPORT( osd_menu_t *, __osd_MenuCreate, ( vlc_object_t *, const char * ) );

/**
 * Delete the osd_menu_t object
 *
 * This functions has to be called to release the associated module and memory
 * for the osdmenu. After return of this function the pointer to osd_menu_t* is invalid.
 */
VLC_EXPORT( void, __osd_MenuDelete, ( vlc_object_t *, osd_menu_t * ) );

/**
 * Change state on an osd_button_t.
 *
 * This function selects the specified state and returns a pointer to it. The 
 * following states are currently supported: 
 * \see OSD_BUTTON_UNSELECT
 * \see OSD_BUTTON_SELECT   
 * \see OSD_BUTTON_PRESSED  
 */
VLC_EXPORT( osd_state_t *, __osd_StateChange, ( osd_state_t *, const int ) );

#define osd_MenuCreate(object,file) __osd_MenuCreate( VLC_OBJECT(object), file )
#define osd_MenuDelete(object,osd)  __osd_MenuDelete( VLC_OBJECT(object), osd )
#define osd_StateChange(object,value) __osd_StateChange( object, value )

/**
 * Show the OSD menu.
 *
 * Show the OSD menu on the video output or mux it into the stream. 
 * Every change to the OSD menu will now be visible in the output. An output 
 * can be a video output window or a stream (\see stream output)
 */
VLC_EXPORT( void, __osd_MenuShow, ( vlc_object_t * ) ); 

/**
 * Hide the OSD menu.
 *
 * Stop showing the OSD menu on the video output or mux it into the stream.
 */
VLC_EXPORT( void, __osd_MenuHide, ( vlc_object_t * ) );

/**
 * Activate the action of this OSD menu item.
 *
 * The rc interface command "menu select" triggers the sending of an hotkey action
 * to the hotkey interface. The hotkey that belongs to the current highlighted 
 * OSD menu item will be used.
 */
VLC_EXPORT( void, __osd_MenuActivate,   ( vlc_object_t * ) );

#define osd_MenuShow(object) __osd_MenuShow( VLC_OBJECT(object) )
#define osd_MenuHide(object) __osd_MenuHide( VLC_OBJECT(object) )
#define osd_MenuActivate(object)   __osd_MenuActivate( VLC_OBJECT(object) )

/**
 * Next OSD menu item
 *
 * Select the next OSD menu item to be highlighted.
 * Note: The actual position on screen of the menu item is determined by the the
 * OSD menu configuration file.
 */
VLC_EXPORT( void, __osd_MenuNext, ( vlc_object_t * ) ); 

/**
 * Previous OSD menu item
 *
 * Select the previous OSD menu item to be highlighted.
 * Note: The actual position on screen of the menu item is determined by the the
 * OSD menu configuration file.
 */
VLC_EXPORT( void, __osd_MenuPrev, ( vlc_object_t * ) );

/**
 * OSD menu item above
 *
 * Select the OSD menu item above the current item to be highlighted. 
 * Note: The actual position on screen of the menu item is determined by the the
 * OSD menu configuration file.
 */
VLC_EXPORT( void, __osd_MenuUp,   ( vlc_object_t * ) );

/**
 * OSD menu item below
 *
 * Select the next OSD menu item below the current item to be highlighted.
 * Note: The actual position on screen of the menu item is determined by the the
 * OSD menu configuration file.
 */
VLC_EXPORT( void, __osd_MenuDown, ( vlc_object_t * ) );

#define osd_MenuNext(object) __osd_MenuNext( VLC_OBJECT(object) )
#define osd_MenuPrev(object) __osd_MenuPrev( VLC_OBJECT(object) )
#define osd_MenuUp(object)   __osd_MenuUp( VLC_OBJECT(object) )
#define osd_MenuDown(object) __osd_MenuDown( VLC_OBJECT(object) )

/**
 * Turn Volume Up
 *
 * Use the OSD menu to turn the audio volume up.
 */
VLC_EXPORT( void, __osd_VolumeUp, ( vlc_object_t * ) );

/**
 * Turn Volume Down
 *
 * Use the OSD menu to turn the audio volume down.
 */
VLC_EXPORT( void, __osd_VolumeDown, ( vlc_object_t * ) );

#define osd_VolumeUp(object)   __osd_VolumeUp( VLC_OBJECT(object) )
#define osd_VolumeDown(object) __osd_VolumeDown( VLC_OBJECT(object) )

/**
 * Retrieve a non modifyable pointer to the OSD Menu state
 *
 */
static inline const osd_menu_state_t *osd_GetMenuState( osd_menu_t *p_osd )
{
    return( p_osd->p_state );
}

/**
 * Get the last key press received by the OSD Menu
 *
 * Returns 0 when no key has been pressed or the value of the key pressed.
 */
static inline vlc_bool_t osd_GetKeyPressed( osd_menu_t *p_osd )
{
    return( p_osd->p_state->b_update );
}       

/**
 * Set the key pressed to a value.
 *
 * Assign a new key value to the last key pressed on the OSD Menu.
 */
static inline void osd_SetKeyPressed( vlc_object_t *p_this, int i_value )
{
    vlc_value_t val;
    
    val.i_int = i_value;    
    var_Set( p_this, "key-pressed", val );            
}

/**
 * Update the OSD Menu visibility flag.
 *
 * VLC_TRUE means OSD Menu should be shown. VLC_FALSE means OSD Menu should not be shown.
 */
static inline void osd_SetMenuVisible( osd_menu_t *p_osd, vlc_bool_t b_value )
{
    vlc_value_t val;
    
    val.b_bool = p_osd->p_state->b_menu_visible = b_value; 
    var_Set( p_osd, "osd-menu-visible", val );
}

/**
 * Update the OSD Menu update flag
 *
 * If the OSD Menu should be updated then set the update flag to VLC_TRUE, else to VLC_FALSE.
 */
static inline void osd_SetMenuUpdate( osd_menu_t *p_osd, vlc_bool_t b_value )
{
    vlc_value_t val;
    
    val.b_bool = p_osd->p_state->b_update = b_value;
    var_Set( p_osd, "osd-menu-update", val );
} 

/**
 * Default feedback images
 *
 * Functions that provide the default OSD feedback images on hotkey commands. These feedback
 * images are also part of the osd_button_t object. The types are declared in the include file
 * include/osd.h
 * @see osd.h 
 */
VLC_EXPORT( picture_t *, osd_Slider, ( int i_width, int i_height, int i_position, short i_type ) );
VLC_EXPORT( picture_t *, osd_Icon,   ( int i_width, int i_height, short i_type ) );

/**
 * Loading and parse the OSD Configuration file
 *
 * These functions load/unload the OSD menu configuration file and create/destroy the
 * themable OSD menu structure on the OSD object.
 */
VLC_EXPORT( int,  osd_ConfigLoader, ( vlc_object_t *, const char *, osd_menu_t ** ) );
VLC_EXPORT( void, osd_ConfigUnload, ( vlc_object_t *, osd_menu_t ** ) );

# ifdef __cplusplus
}
# endif

#endif /* _VLC_OSD_H */