/***************************************************************************** * vlc_vout_display.h: vout_display_t definitions ***************************************************************************** * Copyright (C) 2009 Laurent Aimar * $Id: 6f5b35f2eb94223fd3685df862e1fc49ee4ee088 $ * * Authors: Laurent Aimar * * 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 #include #include #include #include #include #include /* 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; /** * Possible alignments for vout_display. */ 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; /** * Window management state. */ enum { VOUT_WINDOW_STATE_NORMAL=0, VOUT_WINDOW_STATE_ABOVE=1, VOUT_WINDOW_STATE_BELOW=2, VOUT_WINDOW_STACK_MASK=3, }; /** * 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 */ unsigned width; unsigned height; /* Display SAR */ struct { unsigned num; unsigned 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 { /* Hide the mouse. It will be sent when * 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 * being requested (externally or by VOUT_DISPLAY_EVENT_FULLSCREEN */ VOUT_DISPLAY_CHANGE_FULLSCREEN, /* const vout_display_cfg_t *p_cfg */ /* Ask the module to acknowledge/refuse the window management state change * after being requested externally or by VOUT_DISPLAY_WINDOW_STATE */ VOUT_DISPLAY_CHANGE_WINDOW_STATE, /* unsigned state */ /* Ask the module to acknowledge/refuse the display size change requested * (externally or by VOUT_DISPLAY_EVENT_DISPLAY_SIZE) */ VOUT_DISPLAY_CHANGE_DISPLAY_SIZE, /* const vout_display_cfg_t *p_cfg, int is_forced */ /* Ask the module to acknowledge/refuse fill display state change after * being requested externally */ VOUT_DISPLAY_CHANGE_DISPLAY_FILLED, /* const vout_display_cfg_t *p_cfg */ /* Ask the module to acknowledge/refuse zoom change after being requested * externally */ VOUT_DISPLAY_CHANGE_ZOOM, /* const vout_display_cfg_t *p_cfg */ /* Ask the module to acknowledge/refuse source aspect ratio after being * requested externally */ VOUT_DISPLAY_CHANGE_SOURCE_ASPECT, /* const video_format_t *p_source */ /* Ask the module to acknowledge/refuse source crop change after being * requested externally. * 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 */ /* Ask an opengl interface if available. */ VOUT_DISPLAY_GET_OPENGL, /* vout_opengl_t ** */ }; /** * Event from vout_display_t * * Events modifiying the state may be sent multiple times. * Only the transition will be retained and acted upon. */ 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_WINDOW_STATE, VOUT_DISPLAY_EVENT_DISPLAY_SIZE, /* The display size need to change : int i_width, int i_height, bool is_fullscreen */ /* */ 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; /* Event coming from the module * * This function is set prior to the module instantiation and must not * be overwritten nor used directly (use the vout_display_SendEvent* * wrapper. * * You can send it at any time i.e. from any vout_display_t functions or * from another thread. * Be careful, it does not ensure correct serialization if it is used * from multiple threads. */ 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. * You cannot modify it directly, you must use the appropriate events. * * It reflects the current values, i.e. after the event has been accepted * and applied/configured if needed. */ const vout_display_cfg_t *cfg; /* video source format. * * Cropping is not requested while in the open function. * You cannot change it. */ video_format_t source; /* picture_t format. * * You can only change it inside the module open function to * match what you want, and when a VOUT_DISPLAY_RESET_PICTURES control * request is made and succeeds. * * By default, it is equal to ::source except for the aspect ratio * which is undefined(0) and is ignored. */ video_format_t fmt; /* Informations * * You can only set them in the open function. */ vout_display_info_t info; /* Return a pointer over the current picture_pool_t* (mandatory). * * For performance reasons, it is best to provide at least count * pictures but it is not mandatory. * You can return NULL when you cannot/do not want to allocate * pictures. * The vout display module keeps the ownership of the pool and can * destroy it only when closing or on invalid pictures control. */ picture_pool_t *(*pool)(vout_display_t *, unsigned count); /* 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 (optional) */ void (*manage)(vout_display_t *); /* Private place holder for the vout_display_t module (optional) * * A module is free to use it as it wishes. */ 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, bool is_fullscreen) { vout_display_SendEvent(vd, VOUT_DISPLAY_EVENT_DISPLAY_SIZE, width, height, is_fullscreen); } 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); } static inline void vout_display_SendWindowState(vout_display_t *vd, unsigned state) { vout_display_SendEvent(vd, VOUT_DISPLAY_EVENT_WINDOW_STATE, state); } /* 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); } /** * Asks for a new window with the given configuration as hint. * * 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); } /** * Computes the default display size given the source and * the display configuration. * * This asssumes that the picture is already cropped. */ VLC_EXPORT( void, vout_display_GetDefaultDisplaySize, (unsigned *width, unsigned *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; unsigned width; unsigned height; } vout_display_place_t; /** * Computes how to place a picture inside the display to respect * the given parameters. * This assumes that cropping is done by an external mean. * * \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 */