VLC  4.0.0-dev
Files | Data Structures | Typedefs | Enumerations | Functions

Window management. More...

Collaboration diagram for Video window:

Files

file  vlc_vout_window.h
 Window modules interface.
 

Data Structures

struct  vout_window_mouse_event_t
 Window mouse event. More...
 
struct  vout_window_cfg_t
 Window (desired) configuration. More...
 
struct  vout_window_callbacks
 Window event callbacks structure. More...
 
struct  vout_window_owner
 Window callbacks and opaque data. More...
 
struct  vout_window_operations
 Window implementation callbacks. More...
 
struct  vout_window_t
 Window object. More...
 

Typedefs

typedef struct vout_window_mouse_event_t vout_window_mouse_event_t
 Window mouse event. More...
 
typedef struct vout_window_cfg_t vout_window_cfg_t
 Window (desired) configuration. More...
 
typedef void(* vout_window_ack_cb) (struct vout_window_t *, unsigned width, unsigned height, void *data)
 Callback prototype for window event acknowledgement. More...
 
typedef struct vout_window_owner vout_window_owner_t
 Window callbacks and opaque data. More...
 
typedef struct vout_window_t vout_window_t
 Window object. More...
 

Enumerations

enum  vout_window_type {
  VOUT_WINDOW_TYPE_DUMMY , VOUT_WINDOW_TYPE_XID , VOUT_WINDOW_TYPE_HWND , VOUT_WINDOW_TYPE_NSOBJECT ,
  VOUT_WINDOW_TYPE_ANDROID_NATIVE , VOUT_WINDOW_TYPE_WAYLAND , VOUT_WINDOW_TYPE_DCOMP
}
 Window handle type. More...
 
enum  vout_window_state { VOUT_WINDOW_STATE_NORMAL , VOUT_WINDOW_STATE_ABOVE , VOUT_WINDOW_STATE_BELOW }
 Window states. More...
 
enum  vout_window_mouse_event_type { VOUT_WINDOW_MOUSE_MOVED , VOUT_WINDOW_MOUSE_PRESSED , VOUT_WINDOW_MOUSE_RELEASED , VOUT_WINDOW_MOUSE_DOUBLE_CLICK }
 Window mouse event types. More...
 

Functions

vout_window_tvout_window_New (vlc_object_t *obj, const char *module, const vout_window_owner_t *owner)
 Creates a new window. More...
 
void vout_window_Delete (vout_window_t *window)
 Deletes a window. More...
 
void vout_window_SetInhibition (vout_window_t *window, bool enabled)
 Inhibits or deinhibits the screensaver. More...
 
static void vout_window_SetState (vout_window_t *window, unsigned state)
 Requests a new window state. More...
 
static void vout_window_SetSize (vout_window_t *window, unsigned width, unsigned height)
 Requests a new window size. More...
 
static void vout_window_SetFullScreen (vout_window_t *window, const char *id)
 Requests fullscreen mode. More...
 
static void vout_window_UnsetFullScreen (vout_window_t *window)
 Requests windowed mode. More...
 
static void vout_window_SetTitle (vout_window_t *window, const char *title)
 Request a new window title. More...
 
int vout_window_Enable (vout_window_t *window, const vout_window_cfg_t *cfg)
 Enables a window. More...
 
void vout_window_Disable (vout_window_t *window)
 Disables a window. More...
 
static void vout_window_ReportSize (vout_window_t *window, unsigned width, unsigned height)
 Reports the current window size. More...
 
static void vout_window_ReportClose (vout_window_t *window)
 Reports a request to close the window. More...
 
static void vout_window_ReportState (vout_window_t *window, unsigned state)
 Reports the current window state. More...
 
void vout_window_ReportWindowed (vout_window_t *wnd)
 Reports that the window is not in full screen. More...
 
void vout_window_ReportFullscreen (vout_window_t *wnd, const char *id)
 Reports that the window is in full screen. More...
 
static void vout_window_SendMouseEvent (vout_window_t *window, const vout_window_mouse_event_t *mouse)
 
static void vout_window_ReportMouseMoved (vout_window_t *window, int x, int y)
 Reports a pointer movement. More...
 
static void vout_window_ReportMousePressed (vout_window_t *window, int button)
 Reports a mouse button press. More...
 
static void vout_window_ReportMouseReleased (vout_window_t *window, int button)
 Reports a mouse button release. More...
 
static void vout_window_ReportMouseDoubleClick (vout_window_t *window, int button)
 Reports a mouse double-click. More...
 
static void vout_window_ReportKeyPress (vout_window_t *window, int key)
 Reports a keyboard key press. More...
 
static void vout_window_ReportOutputDevice (vout_window_t *window, const char *id, const char *name)
 Adds/removes a fullscreen output. More...
 

Detailed Description

Window management.

Window management provides a partial abstraction for windowing systems and rendering targets (i.e. "windows"). See vout_window_t.

Typedef Documentation

◆ vout_window_ack_cb

typedef void(* vout_window_ack_cb) (struct vout_window_t *, unsigned width, unsigned height, void *data)

Callback prototype for window event acknowledgement.

Parameters
widthpixel width as supplied to vout_window_callbacks::resized
heightpixel height as supplied to vout_window_callbacks::resized
dataopaque pointer as supplied to vout_window_callbacks::resized

◆ vout_window_cfg_t

Window (desired) configuration.

This structure describes the intended initial configuration of a vout_window_t.

◆ vout_window_mouse_event_t

Window mouse event.

This structure describes a pointer input event on a window.

◆ vout_window_owner_t

Window callbacks and opaque data.

◆ vout_window_t

typedef struct vout_window_t vout_window_t

Window object.

This structure is an abstract interface to the windowing system. The window is normally used to draw video (and subpictures) into, but it can also be used for other purpose (e.g. OpenGL visualization).

The window is responsible for providing a window handle, whose exact meaning depends on the windowing system. It also must report some events such as user input (keyboard, mouse) and window resize.

Finally, it must support some control requests such as for fullscreen mode.

Enumeration Type Documentation

◆ vout_window_mouse_event_type

Window mouse event types.

This enumeration defines the possible event types vout_window_mouse_event_t::type.

Enumerator
VOUT_WINDOW_MOUSE_MOVED 

Pointer position change.

VOUT_WINDOW_MOUSE_PRESSED 

Pointer button press or single click.

VOUT_WINDOW_MOUSE_RELEASED 

Pointer button release.

VOUT_WINDOW_MOUSE_DOUBLE_CLICK 

Double click.

◆ vout_window_state

Window states.

Currently, this only handles different window stacking orders. See also vout_window_SetState().

Enumerator
VOUT_WINDOW_STATE_NORMAL 

Normal stacking.

VOUT_WINDOW_STATE_ABOVE 

Stacking above (a.k.a.

always on top)

VOUT_WINDOW_STATE_BELOW 

Stacking below (a.k.a.

wall paper mode)

◆ vout_window_type

Window handle type.

The window handle type specifies the window system protocol that the window was created with. It determines which members of the vout_window_t::handle and vout_window_t::display unions are defined for the given window.

It also establishes some protocol-dependent semantics such as the exact interpretation of the window state (vout_window_state) and the window size.

Enumerator
VOUT_WINDOW_TYPE_DUMMY 

Dummy window (not an actual window)

VOUT_WINDOW_TYPE_XID 

X11 window.

VOUT_WINDOW_TYPE_HWND 

Win32 or OS/2 window.

VOUT_WINDOW_TYPE_NSOBJECT 

macOS/iOS view

VOUT_WINDOW_TYPE_ANDROID_NATIVE 

Android native window.

VOUT_WINDOW_TYPE_WAYLAND 

Wayland surface.

VOUT_WINDOW_TYPE_DCOMP 

Win32 DirectComposition.

Function Documentation

◆ vout_window_Delete()

void vout_window_Delete ( vout_window_t window)

◆ vout_window_Disable()

void vout_window_Disable ( vout_window_t window)

Disables a window.

This informs the window provider that the window is no longer needed.

Note
The window may be re-enabled later by a call to vout_window_Enable().

References vout_window_operations::disable, vout_window_t::ops, and vout_window_SetInhibition().

Referenced by vlc_gl_surface_Create(), vlc_gl_surface_Destroy(), and vout_DisableWindow().

◆ vout_window_Enable()

int vout_window_Enable ( vout_window_t window,
const vout_window_cfg_t cfg 
)

Enables a window.

This informs the window provider that the window is about to be taken into active use. A window is always initially disabled. This is so that the window provider can provide a persistent connection to the display server, and track any useful events, such as monitors hotplug.

The window handle (vout_window_t.handle) must remain valid and constant while the window is enabled.

◆ vout_window_New()

vout_window_t* vout_window_New ( vlc_object_t obj,
const char *  module,
const vout_window_owner_t owner 
)

Creates a new window.

This function creates a window, or some other kind of rectangle render target.

Parameters
objparent VLC object
moduleplugin name, NULL for default
ownercallbacks and private data
Returns
a new window, or NULL on error.

References window_t::active, window_t::fullscreen, vout_window_t::handle, vout_window_t::has_double_click, vout_window_t::info, window_t::inhibit, window_t::inhibit_windowed, window_t::lock, window_t::module, vout_window_t::owner, vout_window_t::sys, var_InheritInteger(), vlc_custom_create, vlc_inhibit_Create(), vlc_module_load, vlc_mutex_init(), vlc_mutex_lock(), vlc_mutex_unlock(), VLC_OBJECT, vlc_object_delete, vout_window_start(), and window_t::wnd.

Referenced by vlc_gl_surface_Create(), and vout_display_window_New().

◆ vout_window_ReportClose()

static void vout_window_ReportClose ( vout_window_t window)
inlinestatic

Reports a request to close the window.

This function is called by the window implementation to advise that the window is being closed externally, and should be disabled by the owner.

References vout_window_owner::cbs, vout_window_callbacks::closed, and vout_window_t::owner.

◆ vout_window_ReportFullscreen()

void vout_window_ReportFullscreen ( vout_window_t wnd,
const char *  id 
)

Reports that the window is in full screen.

Parameters
idfullscreen output nul-terminated identifier, NULL for default

References vout_window_owner::cbs, container_of, window_t::fullscreen, vout_window_callbacks::fullscreened, window_t::inhibit_windowed, window_t::lock, vout_window_t::owner, vlc_mutex_lock(), vlc_mutex_unlock(), and vout_window_UpdateInhibitionUnlocked().

◆ vout_window_ReportKeyPress()

static void vout_window_ReportKeyPress ( vout_window_t window,
int  key 
)
inlinestatic

Reports a keyboard key press.

Parameters
windowwindow in focus
keyVLC key code

References vout_window_owner::cbs, vout_window_callbacks::keyboard_event, and vout_window_t::owner.

◆ vout_window_ReportMouseDoubleClick()

static void vout_window_ReportMouseDoubleClick ( vout_window_t window,
int  button 
)
inlinestatic

Reports a mouse double-click.

Parameters
windowwindow in focus
buttondouble-clicked button (see vlc_mouse_button)

References VOUT_WINDOW_MOUSE_DOUBLE_CLICK, and vout_window_SendMouseEvent().

◆ vout_window_ReportMouseMoved()

static void vout_window_ReportMouseMoved ( vout_window_t window,
int  x,
int  y 
)
inlinestatic

Reports a pointer movement.

The mouse position must be expressed in window pixel units. See also vout_window_mouse_event_t.

Parameters
windowwindow in focus
xabscissa
yordinate

References VOUT_WINDOW_MOUSE_MOVED, and vout_window_SendMouseEvent().

Referenced by vout_display_SendMouseMovedDisplayCoordinates().

◆ vout_window_ReportMousePressed()

static void vout_window_ReportMousePressed ( vout_window_t window,
int  button 
)
inlinestatic

Reports a mouse button press.

Parameters
windowwindow in focus
buttonpressed button (see vlc_mouse_button)

References VOUT_WINDOW_MOUSE_PRESSED, and vout_window_SendMouseEvent().

Referenced by vout_display_SendEventMousePressed().

◆ vout_window_ReportMouseReleased()

static void vout_window_ReportMouseReleased ( vout_window_t window,
int  button 
)
inlinestatic

Reports a mouse button release.

Parameters
windowwindow in focus
buttonreleased button (see vlc_mouse_button)

References VOUT_WINDOW_MOUSE_RELEASED, and vout_window_SendMouseEvent().

Referenced by vout_display_SendEventMouseReleased().

◆ vout_window_ReportOutputDevice()

static void vout_window_ReportOutputDevice ( vout_window_t window,
const char *  id,
const char *  name 
)
inlinestatic

Adds/removes a fullscreen output.

This notifies the owner of the window that a usable fullscreen output has been added, changed or removed.

If an output with the same identifier is already known, its name will be updated. Otherwise it will be added. If the name parameter is NULL, the output will be removed.

Parameters
idunique nul-terminated identifier for the output
namehuman-readable name

◆ vout_window_ReportSize()

static void vout_window_ReportSize ( vout_window_t window,
unsigned  width,
unsigned  height 
)
inlinestatic

Reports the current window size.

This function is called by the window implementation and notifies the owner of the window what the pixel dimensions of the window are (or should be, depending on the windowing system).

Note
This function is thread-safe. In case of concurrent call, it is undefined which one is taken into account (but at least one is).

References vout_window_owner::cbs, vout_window_t::owner, and vout_window_callbacks::resized.

◆ vout_window_ReportState()

static void vout_window_ReportState ( vout_window_t window,
unsigned  state 
)
inlinestatic

Reports the current window state.

This function is called by the window implementation to notify the owner of the window that the state of the window changed.

Parameters
state
See also
vout_window_state

References vout_window_owner::cbs, vout_window_t::owner, state, and vout_window_callbacks::state_changed.

◆ vout_window_ReportWindowed()

void vout_window_ReportWindowed ( vout_window_t wnd)

Reports that the window is not in full screen.

This notifies the owner of the window that the window is windowed, i.e. not in full screen mode.

References vout_window_owner::cbs, container_of, window_t::fullscreen, window_t::inhibit_windowed, window_t::lock, vout_window_t::owner, vlc_mutex_lock(), vlc_mutex_unlock(), vout_window_UpdateInhibitionUnlocked(), and vout_window_callbacks::windowed.

◆ vout_window_SendMouseEvent()

static void vout_window_SendMouseEvent ( vout_window_t window,
const vout_window_mouse_event_t mouse 
)
inlinestatic

◆ vout_window_SetFullScreen()

static void vout_window_SetFullScreen ( vout_window_t window,
const char *  id 
)
inlinestatic

Requests fullscreen mode.

Parameters
windowwindow to be brought to fullscreen mode.
idnul-terminated output identifier, NULL for default

References vout_window_t::ops, and vout_window_operations::set_fullscreen.

Referenced by vout_ChangeFullscreen().

◆ vout_window_SetInhibition()

void vout_window_SetInhibition ( vout_window_t window,
bool  enabled 
)

Inhibits or deinhibits the screensaver.

Parameters
windowwindow in respect to which the screensaver should be inhibited or deinhibited
trueto inhibit, false to deinhibit

References window_t::active, container_of, window_t::lock, vlc_mutex_lock(), vlc_mutex_unlock(), and vout_window_UpdateInhibitionUnlocked().

Referenced by vout_ChangePause(), vout_window_Disable(), and vout_window_Enable().

◆ vout_window_SetSize()

static void vout_window_SetSize ( vout_window_t window,
unsigned  width,
unsigned  height 
)
inlinestatic

Requests a new window size.

This requests a change of the window size. In general and unless otherwise stated, the size is expressed in pixels. However, the exact interpretation of the window size depends on the windowing system.

There is no return value as the request may be processed asynchronously, ignored and/or modified by the window system. The actual size of the window is determined by the vout_window_callbacks::resized callback function that was supplied to vout_window_New().

Note
The size is expressed in terms of the "useful" area, i.e. it excludes any side decoration added by the windowing system.
Parameters
windowwindow whom a size change is requested for
widthpixel width
heightheight width

References vout_window_t::ops, and vout_window_operations::resize.

Referenced by vout_UpdateWindowSizeLocked().

◆ vout_window_SetState()

static void vout_window_SetState ( vout_window_t window,
unsigned  state 
)
inlinestatic

Requests a new window state.

This requests a change of the state of a window from the windowing system. See vout_window_state for possible states.

Parameters
windowwindow whose state to change
staterequested state

References vout_window_t::ops, vout_window_operations::set_state, and state.

Referenced by vout_ChangeWindowState(), and vout_Create().

◆ vout_window_SetTitle()

static void vout_window_SetTitle ( vout_window_t window,
const char *  title 
)
inlinestatic

Request a new window title.

Parameters
windowwindow to change the title.
titlewindow title to use.

References vout_window_t::ops, and vout_window_operations::set_title.

◆ vout_window_UnsetFullScreen()

static void vout_window_UnsetFullScreen ( vout_window_t window)
inlinestatic

Requests windowed mode.

Parameters
windowwindow to be brought into windowed mode.

References vout_window_t::ops, and vout_window_operations::unset_fullscreen.

Referenced by vout_ChangeWindowed().