vlc_vout_display.h 12.7 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
/*****************************************************************************
 * vlc_vout_display.h: vout_display_t definitions
 *****************************************************************************
 * Copyright (C) 2009 Laurent Aimar
 * $Id$
 *
 * Authors: Laurent Aimar <fenrir _AT_ videolan _DOT_ org>
 *
 * 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., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
 *****************************************************************************/

#ifndef VLC_VOUT_DISPLAY_H
#define VLC_VOUT_DISPLAY_H 1

/**
 * \file
 * This file defines vout display structures and functions in vlc
 */

#include <vlc_es.h>
#include <vlc_picture.h>
#include <vlc_subpicture.h>
#include <vlc_keys.h>
#include <vlc_mouse.h>
#include <vlc_vout_window.h>

/* XXX
 * Do NOT use video_format_t::i_aspect but i_sar_num/den everywhere. i_aspect
 * will be removed as soon as possible.
 *
 */
typedef struct vout_display_t vout_display_t;
typedef struct vout_display_sys_t vout_display_sys_t;
typedef struct vout_display_owner_t vout_display_owner_t;
typedef struct vout_display_owner_sys_t vout_display_owner_sys_t;

/**
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
50
 * Possible alignments for vout_display.
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
 */
typedef enum
{
    VOUT_DISPLAY_ALIGN_CENTER,
    /* */
    VOUT_DISPLAY_ALIGN_LEFT,
    VOUT_DISPLAY_ALIGN_RIGHT,
    /* */
    VOUT_DISPLAY_ALIGN_TOP,
    VOUT_DISPLAY_ALIGN_BOTTOM,
} vout_display_align_t;

/**
 * Initial/Current configuration for a vout_display_t
 */
typedef struct {
    bool is_fullscreen;  /* Is the display fullscreen */

    /* Display properties */
    struct {
        /* Window title (may be NULL) */
        const char *title;

        /* Display size */
        int  width;
        int  height;

        /* Display SAR */
        struct {
            int num;
            int den;
        } sar;
    } display;

    /* Alignment of the picture inside the display */
    struct {
        int horizontal;
        int vertical;
    } align;

    /* Do we fill up the display with the video */
    bool is_display_filled;

    /* Zoom to use
     * It will be applied to the whole display if b_display_filled is set, otherwise
     * only on the video source */
    struct {
        int num;
        int den;
    } zoom;

} vout_display_cfg_t;

/**
 * Informations from a vout_display_t to configure
 * the core behaviour.
 *
 * By default they are all false.
 *
 */
typedef struct {
    bool is_slow;            /* The picture memory has slow read/write */
    bool has_double_click;    /* Is double-click generated */
    bool has_hide_mouse;      /* Is mouse automatically hidden */
    bool has_pictures_invalid;/* Will VOUT_DISPLAY_EVENT_PICTURES_INVALID be used */
} vout_display_info_t;

/**
 * Control query for vout_display_t
 */
enum {
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
122
    /* Hide the mouse. It will be sent when
123
124
125
126
127
128
129
130
131
     * vout_display_t::info.b_hide_mouse is false */
    VOUT_DISPLAY_HIDE_MOUSE,

    /* Ask to reset the internal buffers after a VOUT_DISPLAY_EVENT_PICTURES_INVALID
     * request.
     */
    VOUT_DISPLAY_RESET_PICTURES,

    /* Ask the module to acknowledge/refuse the fullscreen state change after
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
132
     * being requested (externally or by VOUT_DISPLAY_EVENT_FULLSCREEN */
133
134
    VOUT_DISPLAY_CHANGE_FULLSCREEN,     /* const vout_display_cfg_t *p_cfg */

Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
135
136
    /* Ask the module to acknowledge/refuse the "always on top" state change
     * after being requested externally */
137
138
139
    VOUT_DISPLAY_CHANGE_ON_TOP,         /* int b_on_top */

    /* Ask the module to acknowledge/refuse the display size change requested
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
140
     * (externally or by VOUT_DISPLAY_EVENT_DISPLAY_SIZE) */
141
142
143
    VOUT_DISPLAY_CHANGE_DISPLAY_SIZE,   /* const vout_display_cfg_t *p_cfg */

    /* Ask the module to acknowledge/refuse fill display state change after
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
144
     * being requested externally */
145
146
147
    VOUT_DISPLAY_CHANGE_DISPLAY_FILLED, /* const vout_display_cfg_t *p_cfg */

    /* Ask the module to acknowledge/refuse zoom change after being requested
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
148
     * externally */
149
150
151
    VOUT_DISPLAY_CHANGE_ZOOM, /* const vout_display_cfg_t *p_cfg */

    /* Ask the module to acknowledge/refuse source aspect ratio after being
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
152
     * requested externally */
153
154
155
    VOUT_DISPLAY_CHANGE_SOURCE_ASPECT, /* const video_format_t *p_source */

    /* Ask the module to acknowledge/refuse source crop change after being
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
156
     * requested externally.
157
158
159
160
161
162
163
164
     * The cropping requested is stored by video_format_t::i_x/y_offset and
     * video_format_t::i_visible_width/height */
    VOUT_DISPLAY_CHANGE_SOURCE_CROP,   /* const video_format_t *p_source */
};

/**
 * Event from vout_display_t
 *
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
165
166
 * Events modifiying the state may be sent multiple times.
 * Only the transition will be retained and acted upon.
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
 */
enum {
    /* TODO:
     * ZOOM ? DISPLAY_FILLED ? ON_TOP ?
     */
    /* */
    VOUT_DISPLAY_EVENT_PICTURES_INVALID,    /* The buffer are now invalid and need to be changed */

    VOUT_DISPLAY_EVENT_FULLSCREEN,

    VOUT_DISPLAY_EVENT_DISPLAY_SIZE,        /* The display size need to change : int i_width, int i_height */

    /* */
    VOUT_DISPLAY_EVENT_CLOSE,
    VOUT_DISPLAY_EVENT_KEY,

    /* Full mouse state.
     * You can use it OR use the other mouse events. The core will do
     * the conversion.
     */
    VOUT_DISPLAY_EVENT_MOUSE_STATE,

    /* Mouse event */
    VOUT_DISPLAY_EVENT_MOUSE_MOVED,
    VOUT_DISPLAY_EVENT_MOUSE_PRESSED,
    VOUT_DISPLAY_EVENT_MOUSE_RELEASED,
    VOUT_DISPLAY_EVENT_MOUSE_DOUBLE_CLICK,
};

/**
 * Vout owner structures
 */
struct vout_display_owner_t {
    /* Private place holder for the vout_display_t creator
     */
    vout_display_owner_sys_t *sys;

Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
204
    /* Event coming from the module
205
206
207
208
209
     *
     * This function is set prior to the module instantiation and must not
     * be overwritten nor used directly (use the vout_display_SendEvent*
     * wrapper.
     *
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
210
     * You can send it at any time i.e. from any vout_display_t functions
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
     * (TODO add support from a private thread).
     */
    void            (*event)(vout_display_t *, int, va_list);

    /* Window management
     *
     * These functions are set prior to the module instantiation and must not
     * be overwritten nor used directly (use the vout_display_*Window
     * wrapper */
    vout_window_t *(*window_new)(vout_display_t *, const vout_window_cfg_t *);
    void           (*window_del)(vout_display_t *, vout_window_t *);
};

struct vout_display_t {
    VLC_COMMON_MEMBERS

    /* Module */
    module_t *module;

    /* Initial and current configuration.
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
231
     * You cannot modify it directly, you must use the appropriate events.
232
     *
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
233
     * It reflects the current values, i.e. after the event has been accepted
234
235
236
237
238
239
     * and applied/configured if needed.
     */
    const vout_display_cfg_t *cfg;

    /* video source format.
     *
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
240
     * Cropping is not requested while in the open function.
241
242
243
244
245
246
247
     * You cannot change it.
     */
    video_format_t source;

    /* picture_t format.
     *
     * You can only change it inside the module open function to
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
248
249
     * match what you want, and when a VOUT_DISPLAY_RESET_PICTURES control
     * request is made and succeeds.
250
251
252
253
254
255
256
257
     *
     * By default, it is equal to ::source except for the aspect ratio
     * which is undefined(0) and is ignored.
     */
    video_format_t fmt;

    /* Informations
     *
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
258
     * You can only set them in the open function.
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
     */
    vout_display_info_t info;

    /* Return a new picture_t (mandatory).
     *
     * You can return NULL when you cannot/do not want to allocate
     * more pictures.
     * If you want to create a pool of reusable pictures, you can
     * use a picture_pool_t.
     */
    picture_t *(*get)(vout_display_t *);

    /* Prepare a picture for display (optional).
     *
     * It is called before the next pf_display call to provide as much
     * time as possible to prepare the given picture for display.
     * You are guaranted that pf_display will always be called and using
     * the exact same picture_t.
     * You cannot change the pixel content of the picture_t.
     */
    void       (*prepare)(vout_display_t *, picture_t *);

    /* Display a picture (mandatory).
     *
     * The picture must be displayed as soon as possible.
     * You cannot change the pixel content of the picture_t.
     *
     * This function gives away the ownership of the picture, so you must
     * release it as soon as possible.
     */
    void       (*display)(vout_display_t *, picture_t *);

    /* Control on the module (mandatory) */
    int        (*control)(vout_display_t *, int, va_list);

    /* Manage pending event (mandatory for now) */
    void       (*manage)(vout_display_t *);

    /* Private place holder for the vout_display_t module (optional)
     *
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
299
     * A module is free to use it as it wishes.
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
     */
    vout_display_sys_t *sys;

    /* Reserved for the vout_display_t owner.
     *
     * It must not be overwritten nor used directly by a module.
     */
    vout_display_owner_t owner;
};

static inline void vout_display_SendEvent(vout_display_t *vd, int query, ...)
{
    va_list args;
    va_start(args, query);
    vd->owner.event(vd, query, args);
    va_end(args);
}

static inline void vout_display_SendEventDisplaySize(vout_display_t *vd, int width, int height)
{
    vout_display_SendEvent(vd, VOUT_DISPLAY_EVENT_DISPLAY_SIZE, width, height);
}
static inline void vout_display_SendEventPicturesInvalid(vout_display_t *vd)
{
    vout_display_SendEvent(vd, VOUT_DISPLAY_EVENT_PICTURES_INVALID);
}
static inline void vout_display_SendEventClose(vout_display_t *vd)
{
    vout_display_SendEvent(vd, VOUT_DISPLAY_EVENT_CLOSE);
}
static inline void vout_display_SendEventKey(vout_display_t *vd, int key)
{
    vout_display_SendEvent(vd, VOUT_DISPLAY_EVENT_KEY, key);
}
static inline void vout_display_SendEventFullscreen(vout_display_t *vd, bool is_fullscreen)
{
    vout_display_SendEvent(vd, VOUT_DISPLAY_EVENT_FULLSCREEN, is_fullscreen);
}
/* The mouse position (State and Moved event) must be expressed against vout_display_t::source unit */
static inline void vout_display_SendEventMouseState(vout_display_t *vd, int x, int y, int button_mask)
{
    vout_display_SendEvent(vd, VOUT_DISPLAY_EVENT_MOUSE_STATE, x, y, button_mask);
}
static inline void vout_display_SendEventMouseMoved(vout_display_t *vd, int x, int y)
{
    vout_display_SendEvent(vd, VOUT_DISPLAY_EVENT_MOUSE_MOVED, x, y);
}
static inline void vout_display_SendEventMousePressed(vout_display_t *vd, int button)
{
    vout_display_SendEvent(vd, VOUT_DISPLAY_EVENT_MOUSE_PRESSED, button);
}
static inline void vout_display_SendEventMouseReleased(vout_display_t *vd, int button)
{
    vout_display_SendEvent(vd, VOUT_DISPLAY_EVENT_MOUSE_RELEASED, button);
}
static inline void vout_display_SendEventMouseDoubleClick(vout_display_t *vd)
{
    vout_display_SendEvent(vd, VOUT_DISPLAY_EVENT_MOUSE_DOUBLE_CLICK);
}

/**
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
361
 * Asks for a new window with the given configuration as hint.
362
363
364
365
366
367
368
369
370
371
372
373
374
375
 *
 * b_standalone/i_x/i_y may be overwritten by the core
 */
static inline vout_window_t *vout_display_NewWindow(vout_display_t *vd, const vout_window_cfg_t *cfg)
{
    return vd->owner.window_new(vd, cfg);
}
static inline void vout_display_DeleteWindow(vout_display_t *vd,
                                             vout_window_t *window)
{
    vd->owner.window_del(vd, window);
}

/**
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
376
 * Computes the default display size given the source and
377
378
 * the display configuration.
 *
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
379
 * This asssumes that the picture is already cropped.
380
381
382
383
384
385
386
387
388
389
 */
VLC_EXPORT( void, vout_display_GetDefaultDisplaySize, (int *width, int *height, const video_format_t *source, const vout_display_cfg_t *) );


/**
 * Structure used to store the result of a vout_display_PlacePicture.
 */
typedef struct {
    int x;
    int y;
390
391
    unsigned width;
    unsigned height;
392
393
394
} vout_display_place_t;

/**
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
395
 * Computes how to place a picture inside the display to respect
396
 * the given parameters.
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
397
 * This assumes that cropping is done by an external mean.
398
399
400
401
402
403
404
405
406
407
 *
 * \param p_place Place inside the window (window pixel unit)
 * \param p_source Video source format
 * \param p_cfg Display configuration
 * \param b_clip If true, prevent the video to go outside the display (break zoom).
 */
VLC_EXPORT( void, vout_display_PlacePicture, (vout_display_place_t *place, const video_format_t *source, const vout_display_cfg_t *cfg, bool do_clipping) );

#endif /* VLC_VOUT_DISPLAY_H */