Mir
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes | Macros | Typedefs | Enumerations | Functions | Variables
MIR graphics tools API

Classes

struct  MirWaitHandle
 
struct  MirSurfaceParameters
 MirSurfaceParameters is the structure of minimum required information that you must provide to Mir in order to create a surface. More...
 
struct  MirPlatformPackage
 
struct  MirGraphicsRegion
 Retrieved information about a MirSurface. More...
 
struct  MirDisplayInfo
 
struct  MirDisplayCard
 MirDisplayConfiguration provides details of the graphics environment. More...
 
struct  MirDisplayMode
 
struct  MirDisplayOutput
 
struct  MirDisplayConfiguration
 
struct  MirEventDelegate
 MirEventDelegate may be used to specify (at surface creation time) callbacks for handling of events. More...
 
struct  MirRectangle
 
struct  MirScreencastParameters
 MirScreencastParameters is the structure of required information that you must provide to Mir in order to create a MirScreencast. More...
 
struct  MirKeyEvent
 
struct  MirMotionPointer
 
struct  MirMotionEvent
 
struct  MirSurfaceEvent
 
struct  MirResizeEvent
 
struct  MirPromptSessionEvent
 
struct  MirOrientationEvent
 
union  MirEvent
 
struct  MirMesaEGLNativeDisplay
 
struct  MirMesaEGLNativeSurface
 

Macros

#define MIR_BYTES_PER_PIXEL(f)   (((f) == mir_pixel_format_bgr_888) ? 3 : 4)
 
#define MIR_INPUT_EVENT_MAX_POINTER_COUNT   16
 

Typedefs

typedef void(* mir_drm_auth_magic_callback )(int status, void *context)
 
typedef enum MirBool MirBool
 
typedef void * MirEGLNativeWindowType
 
typedef void * MirEGLNativeDisplayType
 
typedef struct MirConnection MirConnection
 
typedef struct MirSurface MirSurface
 
typedef struct MirScreencast MirScreencast
 
typedef struct MirPromptSession MirPromptSession
 
typedef struct MirWaitHandle MirWaitHandle
 Returned by asynchronous functions. More...
 
typedef void(* mir_connected_callback )(MirConnection *connection, void *client_context)
 Callback to be passed when issuing a mir_connect request. More...
 
typedef void(* mir_surface_callback )(MirSurface *surface, void *client_context)
 Callback to be passed when calling: More...
 
typedef void(* mir_event_delegate_callback )(MirSurface *surface, MirEvent const *event, void *context)
 Callback member of MirEventDelegate for handling of events. More...
 
typedef void(* mir_lifecycle_event_callback )(MirConnection *connection, MirLifecycleState state, void *context)
 Callback called when a lifecycle event/callback is requested from the running server. More...
 
typedef void(* mir_display_config_callback )(MirConnection *connection, void *context)
 Callback called when a display config change has occurred. More...
 
typedef void(* mir_client_fd_callback )(MirPromptSession *prompt_session, size_t count, int const *fds, void *context)
 Callback called when a request for client file descriptors completes. More...
 
typedef enum MirBufferUsage MirBufferUsage
 MirBufferUsage specifies how a surface can and will be used. More...
 
typedef struct MirSurfaceParameters MirSurfaceParameters
 MirSurfaceParameters is the structure of minimum required information that you must provide to Mir in order to create a surface. More...
 
typedef enum MirPlatformType MirPlatformType
 The native buffer type for the system the client is connected on. More...
 
typedef struct MirPlatformPackage MirPlatformPackage
 
typedef struct MirGraphicsRegion MirGraphicsRegion
 Retrieved information about a MirSurface. More...
 
typedef struct MirDisplayInfo MirDisplayInfo
 
typedef struct MirDisplayCard MirDisplayCard
 MirDisplayConfiguration provides details of the graphics environment. More...
 
typedef enum MirDisplayOutputType MirDisplayOutputType
 
typedef struct MirDisplayMode MirDisplayMode
 
typedef struct MirDisplayOutput MirDisplayOutput
 
typedef struct
MirDisplayConfiguration 
MirDisplayConfiguration
 
typedef struct MirEventDelegate MirEventDelegate
 MirEventDelegate may be used to specify (at surface creation time) callbacks for handling of events. More...
 
typedef struct MirRectangle MirRectangle
 
typedef struct
MirScreencastParameters 
MirScreencastParameters
 MirScreencastParameters is the structure of required information that you must provide to Mir in order to create a MirScreencast. More...
 
typedef void(* mir_screencast_callback )(MirScreencast *screencast, void *client_context)
 Callback to be passed when calling MirScreencast functions. More...
 
typedef void(* mir_prompt_session_callback )(MirPromptSession *prompt_provider, void *context)
 Callback member of MirPromptSession for handling of prompt sessions. More...
 
typedef void(* mir_prompt_session_state_change_callback )(MirPromptSession *prompt_provider, MirPromptSessionState state, void *context)
 Callback member of MirPromptSession for handling of prompt sessions events. More...
 
typedef enum MirSurfaceAttrib MirSurfaceAttrib
 Attributes of a surface that the client and server/shell may wish to get or set over the wire. More...
 
typedef enum MirSurfaceType MirSurfaceType
 
typedef enum MirSurfaceState MirSurfaceState
 
typedef enum MirSurfaceFocusState MirSurfaceFocusState
 
typedef enum MirSurfaceVisibility MirSurfaceVisibility
 
typedef enum MirLifecycleState MirLifecycleState
 
typedef enum MirPowerMode MirPowerMode
 
typedef enum MirPromptSessionState MirPromptSessionState
 
typedef enum MirPixelFormat MirPixelFormat
 The order of components in a format enum matches the order of the components as they would be written in an integer representing a pixel value of that format. More...
 
typedef enum MirOrientation MirOrientation
 Direction relative to the "natural" orientation of the display. More...
 
typedef int64_t nsecs_t
 
typedef struct MirOrientationEvent MirOrientationEvent
 
typedef struct
MirMesaEGLNativeDisplay 
MirMesaEGLNativeDisplay
 
typedef struct
MirMesaEGLNativeSurface 
MirMesaEGLNativeSurface
 
typedef int(* MirMesaEGLNativeDisplayIsValidFunc )(MirMesaEGLNativeDisplay *display)
 

Enumerations

enum  MirBool { mir_false = 0, mir_true = 1 }
 
enum  MirBufferUsage { mir_buffer_usage_hardware = 1, mir_buffer_usage_software }
 MirBufferUsage specifies how a surface can and will be used. More...
 
enum  { mir_platform_package_max = 32 }
 
enum  MirPlatformType { mir_platform_type_gbm, mir_platform_type_android }
 The native buffer type for the system the client is connected on. More...
 
enum  { mir_supported_pixel_format_max = 32 }
 DEPRECATED. More...
 
enum  MirDisplayOutputType {
  mir_display_output_type_unknown, mir_display_output_type_vga, mir_display_output_type_dvii, mir_display_output_type_dvid,
  mir_display_output_type_dvia, mir_display_output_type_composite, mir_display_output_type_svideo, mir_display_output_type_lvds,
  mir_display_output_type_component, mir_display_output_type_ninepindin, mir_display_output_type_displayport, mir_display_output_type_hdmia,
  mir_display_output_type_hdmib, mir_display_output_type_tv, mir_display_output_type_edp
}
 
enum  { mir_display_output_id_invalid = 0 }
 
enum  MirSurfaceAttrib {
  mir_surface_attrib_type, mir_surface_attrib_state, mir_surface_attrib_swapinterval, mir_surface_attrib_focus,
  mir_surface_attrib_dpi, mir_surface_attrib_visibility, mir_surface_attribs
}
 Attributes of a surface that the client and server/shell may wish to get or set over the wire. More...
 
enum  MirSurfaceType {
  mir_surface_type_normal, mir_surface_type_utility, mir_surface_type_dialog, mir_surface_type_overlay,
  mir_surface_type_freestyle, mir_surface_type_popover, mir_surface_type_inputmethod, mir_surface_types
}
 
enum  MirSurfaceState {
  mir_surface_state_unknown, mir_surface_state_restored, mir_surface_state_minimized, mir_surface_state_maximized,
  mir_surface_state_vertmaximized, mir_surface_state_fullscreen, mir_surface_states
}
 
enum  MirSurfaceFocusState { mir_surface_unfocused = 0, mir_surface_focused }
 
enum  MirSurfaceVisibility { mir_surface_visibility_occluded = 0, mir_surface_visibility_exposed }
 
enum  MirLifecycleState { mir_lifecycle_state_will_suspend, mir_lifecycle_state_resumed, mir_lifecycle_connection_lost }
 
enum  MirPowerMode { mir_power_mode_on, mir_power_mode_standby, mir_power_mode_suspend, mir_power_mode_off }
 
enum  MirPromptSessionState { mir_prompt_session_state_stopped = 0, mir_prompt_session_state_started }
 
enum  MirPixelFormat {
  mir_pixel_format_invalid, mir_pixel_format_abgr_8888, mir_pixel_format_xbgr_8888, mir_pixel_format_argb_8888,
  mir_pixel_format_xrgb_8888, mir_pixel_format_bgr_888, mir_pixel_formats
}
 The order of components in a format enum matches the order of the components as they would be written in an integer representing a pixel value of that format. More...
 
enum  MirOrientation { mir_orientation_normal = 0, mir_orientation_left = 90, mir_orientation_inverted = 180, mir_orientation_right = 270 }
 Direction relative to the "natural" orientation of the display. More...
 
enum  MirEventType {
  mir_event_type_key, mir_event_type_motion, mir_event_type_surface, mir_event_type_resize,
  mir_event_type_prompt_session_state_change, mir_event_type_orientation
}
 
enum  MirKeyAction { mir_key_action_down = 0, mir_key_action_up = 1, mir_key_action_multiple = 2 }
 
enum  MirKeyFlag {
  mir_key_flag_woke_here = 0x1, mir_key_flag_soft_keyboard = 0x2, mir_key_flag_keep_touch_mode = 0x4, mir_key_flag_from_system = 0x8,
  mir_key_flag_editor_action = 0x10, mir_key_flag_canceled = 0x20, mir_key_flag_virtual_hard_key = 0x40, mir_key_flag_long_press = 0x80,
  mir_key_flag_canceled_long_press = 0x100, mir_key_flag_tracking = 0x200, mir_key_flag_fallback = 0x400
}
 
enum  MirKeyModifier {
  mir_key_modifier_none = 0, mir_key_modifier_alt = 0x02, mir_key_modifier_alt_left = 0x10, mir_key_modifier_alt_right = 0x20,
  mir_key_modifier_shift = 0x01, mir_key_modifier_shift_left = 0x40, mir_key_modifier_shift_right = 0x80, mir_key_modifier_sym = 0x04,
  mir_key_modifier_function = 0x08, mir_key_modifier_ctrl = 0x1000, mir_key_modifier_ctrl_left = 0x2000, mir_key_modifier_ctrl_right = 0x4000,
  mir_key_modifier_meta = 0x10000, mir_key_modifier_meta_left = 0x20000, mir_key_modifier_meta_right = 0x40000, mir_key_modifier_caps_lock = 0x100000,
  mir_key_modifier_num_lock = 0x200000, mir_key_modifier_scroll_lock = 0x400000
}
 
enum  MirMotionAction {
  mir_motion_action_down = 0, mir_motion_action_up = 1, mir_motion_action_move = 2, mir_motion_action_cancel = 3,
  mir_motion_action_outside = 4, mir_motion_action_pointer_down = 5, mir_motion_action_pointer_up = 6, mir_motion_action_hover_move = 7,
  mir_motion_action_scroll = 8, mir_motion_action_hover_enter = 9, mir_motion_action_hover_exit = 10
}
 
enum  MirMotionFlag { mir_motion_flag_window_is_obscured = 0x1 }
 
enum  MirMotionButton {
  mir_motion_button_primary = 1 << 0, mir_motion_button_secondary = 1 << 1, mir_motion_button_tertiary = 1 << 2, mir_motion_button_back = 1 << 3,
  mir_motion_button_forward = 1 << 4
}
 
enum  MirMotionToolType {
  mir_motion_tool_type_unknown = 0, mir_motion_tool_type_finger = 1, mir_motion_tool_type_stylus = 2, mir_motion_tool_type_mouse = 3,
  mir_motion_tool_type_eraser = 4
}
 

Functions

MirWaitHandlemir_connection_drm_auth_magic (MirConnection *connection, unsigned int magic, mir_drm_auth_magic_callback callback, void *context)
 
int mir_connection_drm_set_gbm_device (MirConnection *connection, struct gbm_device *dev)
 Set the gbm_device to be used by the EGL implementation. More...
 
MirWaitHandlemir_connect (char const *server, char const *app_name, mir_connected_callback callback, void *context)
 Request a connection to the Mir server. More...
 
MirConnectionmir_connect_sync (char const *server, char const *app_name)
 Perform a mir_connect() but also wait for and return the result. More...
 
MirBool mir_connection_is_valid (MirConnection *connection)
 Test for a valid connection. More...
 
char const * mir_connection_get_error_message (MirConnection *connection)
 Retrieve a text description of the last error. More...
 
void mir_connection_release (MirConnection *connection)
 Release a connection to the Mir server. More...
 
void mir_connection_get_platform (MirConnection *connection, MirPlatformPackage *platform_package)
 Query platform-specific data and/or file descriptors that are required to initialize GL/EGL features. More...
 
void mir_connection_set_lifecycle_event_callback (MirConnection *connection, mir_lifecycle_event_callback callback, void *context)
 Register a callback to be called when a Lifecycle state change occurs. More...
 
 __attribute__ ((__deprecated__("Use mir_connection_create_display_config()"))) void mir_connection_get_display_info(MirConnection *connection
 
MirDisplayConfigurationmir_connection_create_display_config (MirConnection *connection)
 Query the display. More...
 
void mir_connection_set_display_config_change_callback (MirConnection *connection, mir_display_config_callback callback, void *context)
 Register a callback to be called when the hardware display configuration changes. More...
 
void mir_display_config_destroy (MirDisplayConfiguration *display_configuration)
 Destroy the DisplayConfiguration resource acquired from mir_connection_create_display_config. More...
 
MirWaitHandlemir_connection_apply_display_config (MirConnection *connection, MirDisplayConfiguration *display_configuration)
 Apply the display configuration. More...
 
MirEGLNativeDisplayType mir_connection_get_egl_native_display (MirConnection *connection)
 Get a display type that can be used for OpenGL ES 2.0 acceleration. More...
 
void mir_connection_get_available_surface_formats (MirConnection *connection, MirPixelFormat *formats, unsigned const int format_size, unsigned int *num_valid_formats)
 Get the list of possible formats that a surface can be created with. More...
 
void mir_cursor_configuration_destroy (MirCursorConfiguration *parameters)
 Release resources assosciated with cursor parameters. More...
 
MirCursorConfigurationmir_cursor_configuration_from_name (char const *name)
 Returns a new MirCursorConfiguration representing a named cursor from the system cursor theme. More...
 
MirPromptSessionmir_connection_create_prompt_session_sync (MirConnection *connection, pid_t application_pid, mir_prompt_session_state_change_callback state_change_callback, void *context)
 Create and start a new prompt session. More...
 
MirWaitHandlemir_prompt_session_new_fds_for_prompt_providers (MirPromptSession *prompt_session, unsigned int no_of_fds, mir_client_fd_callback callback, void *context)
 Allocate some FDs for prompt providers to connect on. More...
 
void mir_prompt_session_release_sync (MirPromptSession *prompt_session)
 Stop and release the specified prompt session. More...
 
MirBool mir_prompt_session_is_valid (MirPromptSession *prompt_session)
 Test for a valid prompt session. More...
 
char const * mir_prompt_session_error_message (MirPromptSession *prompt_session)
 Retrieve a text description of the last error. More...
 
MirScreencastmir_connection_create_screencast_sync (MirConnection *connection, MirScreencastParameters *parameters)
 Create a screencast on the supplied connection. More...
 
void mir_screencast_release_sync (MirScreencast *screencast)
 Release the specified screencast. More...
 
MirEGLNativeWindowType mir_screencast_egl_native_window (MirScreencast *screencast)
 Get a window type that can be used by EGL. More...
 
MirWaitHandlemir_connection_create_surface (MirConnection *connection, MirSurfaceParameters const *surface_parameters, mir_surface_callback callback, void *context)
 Request a new Mir surface on the supplied connection with the supplied parameters. More...
 
MirSurfacemir_connection_create_surface_sync (MirConnection *connection, MirSurfaceParameters const *params)
 Create a surface like in mir_connection_create_surface(), but also wait for creation to complete and return the resulting surface. More...
 
void mir_surface_set_event_handler (MirSurface *surface, MirEventDelegate const *event_handler)
 Set the event handler to be called when events arrive for a surface. More...
 
MirEGLNativeWindowType mir_surface_get_egl_native_window (MirSurface *surface)
 Get a window type that can be used for OpenGL ES 2.0 acceleration. More...
 
MirBool mir_surface_is_valid (MirSurface *surface)
 Test for a valid surface. More...
 
char const * mir_surface_get_error_message (MirSurface *surface)
 Retrieve a text description of the error. More...
 
void mir_surface_get_parameters (MirSurface *surface, MirSurfaceParameters *parameters)
 Get a surface's parameters. More...
 
MirPlatformType mir_surface_get_platform_type (MirSurface *surface)
 Get the underlying platform type so the buffer obtained in "raw" representation in mir_surface_get_current_buffer() can be understood. More...
 
void mir_surface_get_current_buffer (MirSurface *surface, MirNativeBuffer **buffer_package)
 Get a surface's buffer in "raw" representation. More...
 
void mir_surface_get_graphics_region (MirSurface *surface, MirGraphicsRegion *graphics_region)
 Get a surface's graphics_region, i.e., map the graphics buffer to main memory. More...
 
MirWaitHandlemir_surface_swap_buffers (MirSurface *surface, mir_surface_callback callback, void *context)
 Advance a surface's buffer. More...
 
void mir_surface_swap_buffers_sync (MirSurface *surface)
 Advance a surface's buffer as in mir_surface_swap_buffers(), but also wait for the operation to complete. More...
 
MirWaitHandlemir_surface_release (MirSurface *surface, mir_surface_callback callback, void *context)
 Release the supplied surface and any associated buffer. More...
 
void mir_surface_release_sync (MirSurface *surface)
 Release the specified surface like in mir_surface_release(), but also wait for the operation to complete. More...
 
 __attribute__ ((__deprecated__("Use mir_debug_surface_id()"))) int mir_surface_get_id(MirSurface *surface)
 
MirWaitHandlemir_surface_set_type (MirSurface *surface, MirSurfaceType type)
 Set the type (purpose) of a surface. More...
 
MirSurfaceType mir_surface_get_type (MirSurface *surface)
 Get the type (purpose) of a surface. More...
 
MirWaitHandlemir_surface_set_state (MirSurface *surface, MirSurfaceState state)
 Change the state of a surface. More...
 
MirSurfaceState mir_surface_get_state (MirSurface *surface)
 Get the current state of a surface. More...
 
MirWaitHandlemir_surface_set_swapinterval (MirSurface *surface, int interval)
 Set the swapinterval for mir_surface_swap_buffers. More...
 
int mir_surface_get_swapinterval (MirSurface *surface)
 Query the swapinterval that the surface is operating with. More...
 
int mir_surface_get_dpi (MirSurface *surface)
 Query the DPI value of the surface (dots per inch). More...
 
MirWaitHandlemir_surface_configure_cursor (MirSurface *surface, MirCursorConfiguration const *parameters)
 Choose the cursor state for a surface: whether a cursor is shown, and which cursor if so. More...
 
MirOrientation mir_surface_get_orientation (MirSurface *surface)
 Get the orientation of a surface. More...
 
void mir_wait_for (MirWaitHandle *wait_handle)
 Wait on the supplied handle until all instances of the associated request have completed. More...
 
void mir_wait_for_one (MirWaitHandle *wait_handle)
 Wait on the supplied handle until one instance of the associated request has completed. More...
 

Variables

MirDisplayInfodisplay_info
 
char const *const mir_default_cursor_name
 A special cursor name for use with mir_cursor_configuration_from_name representing the system default cursor. More...
 
char const *const mir_disabled_cursor_name
 A special cursor name for use with mir_cursor_configuration_from_name representing a disabled cursor image. More...
 

Detailed Description

Macro Definition Documentation

#define MIR_BYTES_PER_PIXEL (   f)    (((f) == mir_pixel_format_bgr_888) ? 3 : 4)
#define MIR_INPUT_EVENT_MAX_POINTER_COUNT   16

Typedef Documentation

typedef void(* mir_client_fd_callback)(MirPromptSession *prompt_session, size_t count, int const *fds, void *context)

Callback called when a request for client file descriptors completes.

Parameters
[in]prompt_sessionThe prompt session
[in]countThe number of FDs allocated
[in]fdsArray of FDs
[in,out]contextThe context provided by client
Note
Copy the FDs as the array will be invalidated after callback completes
typedef void(* mir_connected_callback)(MirConnection *connection, void *client_context)

Callback to be passed when issuing a mir_connect request.

Parameters
[in]connectionthe new connection
[in,out]client_contextcontext provided by client in calling mir_connect
typedef void(* mir_display_config_callback)(MirConnection *connection, void *context)

Callback called when a display config change has occurred.

Parameters
[in]connectionThe connection associated with the display change
[in,out]contextThe context provided by client
typedef void(* mir_drm_auth_magic_callback)(int status, void *context)
typedef void(* mir_event_delegate_callback)(MirSurface *surface, MirEvent const *event, void *context)

Callback member of MirEventDelegate for handling of events.

Parameters
[in]surfaceThe surface on which an event has occurred
[in]eventThe event to be handled
[in,out]contextThe context provided by client during delegate registration.
typedef void(* mir_lifecycle_event_callback)(MirConnection *connection, MirLifecycleState state, void *context)

Callback called when a lifecycle event/callback is requested from the running server.

Parameters
[in]connectionThe connection associated with the lifecycle event
[in]cbThe callback requested
[in,out]contextThe context provided by the client
typedef void(* mir_prompt_session_callback)(MirPromptSession *prompt_provider, void *context)

Callback member of MirPromptSession for handling of prompt sessions.

Parameters
[in]prompt_providerThe prompt session associated with the callback
[in,out]contextThe context provided by the client
typedef void(* mir_prompt_session_state_change_callback)(MirPromptSession *prompt_provider, MirPromptSessionState state, void *context)

Callback member of MirPromptSession for handling of prompt sessions events.

Parameters
[in]prompt_providerThe prompt session associated with the callback
[in]stateThe state of the prompt session
[in,out]contextThe context provided by the client
typedef void(* mir_screencast_callback)(MirScreencast *screencast, void *client_context)

Callback to be passed when calling MirScreencast functions.

Parameters
[in]screencastthe screencast being updated
[in,out]client_contextcontext provided by the client
typedef void(* mir_surface_callback)(MirSurface *surface, void *client_context)

Callback to be passed when calling:

  • mir_connection_create_surface
  • mir_surface_swap_buffers
  • mir_surface_release
    Parameters
    [in]surfacethe surface being updated
    [in,out]client_contextcontext provided by client in calling mir_connect
typedef enum MirBool MirBool

MirBufferUsage specifies how a surface can and will be used.

A "hardware" surface can be used for OpenGL accelerated rendering. A "software" surface is one that can be addressed in main memory and blitted to directly.

typedef struct MirConnection MirConnection

MirDisplayConfiguration provides details of the graphics environment.

typedef void* MirEGLNativeDisplayType
typedef void* MirEGLNativeWindowType

MirEventDelegate may be used to specify (at surface creation time) callbacks for handling of events.

Retrieved information about a MirSurface.

This is most useful for learning how and where to write to a 'mir_buffer_usage_software' surface.

typedef int(* MirMesaEGLNativeDisplayIsValidFunc)(MirMesaEGLNativeDisplay *display)

Direction relative to the "natural" orientation of the display.

The order of components in a format enum matches the order of the components as they would be written in an integer representing a pixel value of that format.

For example, abgr_8888 corresponds to 0xAABBGGRR, which will end up as R,G,B,A in memory in a little endian system, and as A,B,G,R in memory in a big endian system.

The native buffer type for the system the client is connected on.

typedef enum MirPowerMode MirPowerMode
typedef struct MirRectangle MirRectangle
typedef struct MirScreencast MirScreencast

MirScreencastParameters is the structure of required information that you must provide to Mir in order to create a MirScreencast.

The width and height parameters can be used to down-scale the screencast For no scaling set them to the region width and height.

typedef struct MirSurface MirSurface

Attributes of a surface that the client and server/shell may wish to get or set over the wire.

MirSurfaceParameters is the structure of minimum required information that you must provide to Mir in order to create a surface.

typedef struct MirWaitHandle MirWaitHandle

Returned by asynchronous functions.

Must not be free'd by callers. See the individual function documentation for information on the lifetime of wait handles.

typedef int64_t nsecs_t

Enumeration Type Documentation

anonymous enum
Enumerator
mir_platform_package_max 
anonymous enum

DEPRECATED.

use MirDisplayConfiguration

Enumerator
mir_supported_pixel_format_max 
anonymous enum
Enumerator
mir_display_output_id_invalid 
enum MirBool
Enumerator
mir_false 
mir_true 

MirBufferUsage specifies how a surface can and will be used.

A "hardware" surface can be used for OpenGL accelerated rendering. A "software" surface is one that can be addressed in main memory and blitted to directly.

Enumerator
mir_buffer_usage_hardware 
mir_buffer_usage_software 
Enumerator
mir_display_output_type_unknown 
mir_display_output_type_vga 
mir_display_output_type_dvii 
mir_display_output_type_dvid 
mir_display_output_type_dvia 
mir_display_output_type_composite 
mir_display_output_type_svideo 
mir_display_output_type_lvds 
mir_display_output_type_component 
mir_display_output_type_ninepindin 
mir_display_output_type_displayport 
mir_display_output_type_hdmia 
mir_display_output_type_hdmib 
mir_display_output_type_tv 
mir_display_output_type_edp 
Enumerator
mir_event_type_key 
mir_event_type_motion 
mir_event_type_surface 
mir_event_type_resize 
mir_event_type_prompt_session_state_change 
mir_event_type_orientation 
Enumerator
mir_key_action_down 
mir_key_action_up 
mir_key_action_multiple 
enum MirKeyFlag
Enumerator
mir_key_flag_woke_here 
mir_key_flag_soft_keyboard 
mir_key_flag_keep_touch_mode 
mir_key_flag_from_system 
mir_key_flag_editor_action 
mir_key_flag_canceled 
mir_key_flag_virtual_hard_key 
mir_key_flag_long_press 
mir_key_flag_canceled_long_press 
mir_key_flag_tracking 
mir_key_flag_fallback 
Enumerator
mir_key_modifier_none 
mir_key_modifier_alt 
mir_key_modifier_alt_left 
mir_key_modifier_alt_right 
mir_key_modifier_shift 
mir_key_modifier_shift_left 
mir_key_modifier_shift_right 
mir_key_modifier_sym 
mir_key_modifier_function 
mir_key_modifier_ctrl 
mir_key_modifier_ctrl_left 
mir_key_modifier_ctrl_right 
mir_key_modifier_meta 
mir_key_modifier_meta_left 
mir_key_modifier_meta_right 
mir_key_modifier_caps_lock 
mir_key_modifier_num_lock 
mir_key_modifier_scroll_lock 
Enumerator
mir_lifecycle_state_will_suspend 
mir_lifecycle_state_resumed 
mir_lifecycle_connection_lost 
Enumerator
mir_motion_action_down 
mir_motion_action_up 
mir_motion_action_move 
mir_motion_action_cancel 
mir_motion_action_outside 
mir_motion_action_pointer_down 
mir_motion_action_pointer_up 
mir_motion_action_hover_move 
mir_motion_action_scroll 
mir_motion_action_hover_enter 
mir_motion_action_hover_exit 
Enumerator
mir_motion_button_primary 
mir_motion_button_secondary 
mir_motion_button_tertiary 
mir_motion_button_back 
mir_motion_button_forward 
Enumerator
mir_motion_flag_window_is_obscured 
Enumerator
mir_motion_tool_type_unknown 
mir_motion_tool_type_finger 
mir_motion_tool_type_stylus 
mir_motion_tool_type_mouse 
mir_motion_tool_type_eraser 

Direction relative to the "natural" orientation of the display.

Enumerator
mir_orientation_normal 
mir_orientation_left 
mir_orientation_inverted 
mir_orientation_right 

The order of components in a format enum matches the order of the components as they would be written in an integer representing a pixel value of that format.

For example, abgr_8888 corresponds to 0xAABBGGRR, which will end up as R,G,B,A in memory in a little endian system, and as A,B,G,R in memory in a big endian system.

Enumerator
mir_pixel_format_invalid 
mir_pixel_format_abgr_8888 
mir_pixel_format_xbgr_8888 
mir_pixel_format_argb_8888 
mir_pixel_format_xrgb_8888 
mir_pixel_format_bgr_888 
mir_pixel_formats 

The native buffer type for the system the client is connected on.

Enumerator
mir_platform_type_gbm 
mir_platform_type_android 
Enumerator
mir_power_mode_on 
mir_power_mode_standby 
mir_power_mode_suspend 
mir_power_mode_off 
Enumerator
mir_prompt_session_state_stopped 
mir_prompt_session_state_started 

Attributes of a surface that the client and server/shell may wish to get or set over the wire.

Enumerator
mir_surface_attrib_type 
mir_surface_attrib_state 
mir_surface_attrib_swapinterval 
mir_surface_attrib_focus 
mir_surface_attrib_dpi 
mir_surface_attrib_visibility 
mir_surface_attribs 
Enumerator
mir_surface_unfocused 
mir_surface_focused 
Enumerator
mir_surface_state_unknown 
mir_surface_state_restored 
mir_surface_state_minimized 
mir_surface_state_maximized 
mir_surface_state_vertmaximized 
mir_surface_state_fullscreen 
mir_surface_states 
Enumerator
mir_surface_type_normal 
mir_surface_type_utility 
mir_surface_type_dialog 
mir_surface_type_overlay 
mir_surface_type_freestyle 
mir_surface_type_popover 
mir_surface_type_inputmethod 
mir_surface_types 
Enumerator
mir_surface_visibility_occluded 
mir_surface_visibility_exposed 

Function Documentation

__attribute__ ( (__deprecated__("Use mir_connection_create_display_config()"))  )
Deprecated:
Use mir_connection_create_display_config
__attribute__ ( (__deprecated__("Use mir_debug_surface_id()"))  )
MirWaitHandle* mir_connect ( char const *  server,
char const *  app_name,
mir_connected_callback  callback,
void *  context 
)

Request a connection to the Mir server.

The supplied callback is called when the connection is established, or fails. The returned wait handle remains valid until the connection has been released.

Warning
callback could be called from another thread. You must do any locking appropriate to protect your data accessed in the callback.
Parameters
[in]serverFile path of the server socket to connect to, or NULL to choose the default server (can be set by the $MIR_SOCKET environment variable)
[in]app_nameA name referring to the application
[in]callbackCallback function to be invoked when request completes
[in,out]contextUser data passed to the callback function
Returns
A handle that can be passed to mir_wait_for
MirConnection* mir_connect_sync ( char const *  server,
char const *  app_name 
)

Perform a mir_connect() but also wait for and return the result.

Parameters
[in]serverFile path of the server socket to connect to, or NULL to choose the default server
[in]app_nameA name referring to the application
Returns
The resulting MirConnection
MirWaitHandle* mir_connection_apply_display_config ( MirConnection connection,
MirDisplayConfiguration display_configuration 
)

Apply the display configuration.

The display configuration is applied to this connection only (per-connection configuration) and is invalidated when a hardware change occurs. Clients should register a callback with mir_connection_set_display_config_change_callback() to get notified about hardware changes, so that the can apply a new configuration.

Warning
This request may be denied. Check that the request succeeded with mir_connection_get_error_message.
Parameters
[in]connectionThe connection
[in]display_configurationThe display_configuration to apply
Returns
A handle that can be passed to mir_wait_for
MirDisplayConfiguration* mir_connection_create_display_config ( MirConnection connection)

Query the display.

Warning
return value must be destroyed via mir_display_config_destroy()
may return null if connection is invalid
Parameters
[in]connectionThe connection
Returns
structure that describes the display configuration
MirPromptSession* mir_connection_create_prompt_session_sync ( MirConnection connection,
pid_t  application_pid,
mir_prompt_session_state_change_callback  state_change_callback,
void *  context 
)

Create and start a new prompt session.

Parameters
[in]connectionThe connection
[in]application_pidThe process id of the initiating application
[in]state_change_callbackThe function to be called when a prompt session state change occurs
[in,out]contextUser data passed to the callback functions
Returns
A handle that can be passed to mir_wait_for
MirScreencast* mir_connection_create_screencast_sync ( MirConnection connection,
MirScreencastParameters parameters 
)

Create a screencast on the supplied connection.

A screencast allows clients to read the contents of the screen.

Warning
This request may be denied.
Parameters
[in]connectionThe connection
[in]parametersThe screencast parameters
Returns
The resulting screencast
MirWaitHandle* mir_connection_create_surface ( MirConnection connection,
MirSurfaceParameters const *  surface_parameters,
mir_surface_callback  callback,
void *  context 
)

Request a new Mir surface on the supplied connection with the supplied parameters.

The returned handle remains valid until the surface has been released.

Warning
callback could be called from another thread. You must do any locking appropriate to protect your data accessed in the callback.
Parameters
[in]connectionThe connection
[in]surface_parametersRequest surface parameters
[in]callbackCallback function to be invoked when request completes
[in,out]contextUser data passed to the callback function
Returns
A handle that can be passed to mir_wait_for
MirSurface* mir_connection_create_surface_sync ( MirConnection connection,
MirSurfaceParameters const *  params 
)

Create a surface like in mir_connection_create_surface(), but also wait for creation to complete and return the resulting surface.

Parameters
[in]connectionThe connection
[in]paramsParameters describing the desired surface
Returns
The resulting surface
MirWaitHandle* mir_connection_drm_auth_magic ( MirConnection connection,
unsigned int  magic,
mir_drm_auth_magic_callback  callback,
void *  context 
)
int mir_connection_drm_set_gbm_device ( MirConnection connection,
struct gbm_device *  dev 
)

Set the gbm_device to be used by the EGL implementation.

This is required if the application needs to create EGLImages from gbm buffers objects created on that gbm device.

Parameters
[in]connectionThe connection
[in]devThe gbm_device to set
Returns
A non-zero value if the operation was successful, 0 otherwise
void mir_connection_get_available_surface_formats ( MirConnection connection,
MirPixelFormat formats,
unsigned const int  format_size,
unsigned int *  num_valid_formats 
)

Get the list of possible formats that a surface can be created with.

Parameters
[in]connectionThe connection
[out]formatsList of valid formats to create surfaces with
[in]formats_sizesize of formats list
[out]num_valid_formatsnumber of valid formats returned in formats
MirEGLNativeDisplayType mir_connection_get_egl_native_display ( MirConnection connection)

Get a display type that can be used for OpenGL ES 2.0 acceleration.

Parameters
[in]connectionThe connection
Returns
An EGLNativeDisplayType that the client can use
char const* mir_connection_get_error_message ( MirConnection connection)

Retrieve a text description of the last error.

The returned string is owned by the library and remains valid until the connection has been released.

Parameters
[in]connectionThe connection
Returns
A text description of any error resulting in an invalid connection, or the empty string "" if the connection is valid.
void mir_connection_get_platform ( MirConnection connection,
MirPlatformPackage platform_package 
)

Query platform-specific data and/or file descriptors that are required to initialize GL/EGL features.

Parameters
[in]connectionThe connection
[out]platform_packageStructure to be populated
MirBool mir_connection_is_valid ( MirConnection connection)

Test for a valid connection.

Parameters
[in]connectionThe connection
Returns
True if the supplied connection is valid, or false otherwise.
void mir_connection_release ( MirConnection connection)

Release a connection to the Mir server.

Parameters
[in]connectionThe connection
void mir_connection_set_display_config_change_callback ( MirConnection connection,
mir_display_config_callback  callback,
void *  context 
)

Register a callback to be called when the hardware display configuration changes.

Once a change has occurred, you can use mir_connection_create_display_config to see the new configuration.

Parameters
[in]connectionThe connection
[in]callbackThe function to be called when a display change occurs
[in,out]contextUser data passed to the callback function
void mir_connection_set_lifecycle_event_callback ( MirConnection connection,
mir_lifecycle_event_callback  callback,
void *  context 
)

Register a callback to be called when a Lifecycle state change occurs.

Parameters
[in]connectionThe connection
[in]callbackThe function to be called when the state change occurs
[in,out]contextUser data passed to the callback function
void mir_cursor_configuration_destroy ( MirCursorConfiguration parameters)

Release resources assosciated with cursor parameters.

Parameters
[in]parametersThe operand
MirCursorConfiguration* mir_cursor_configuration_from_name ( char const *  name)

Returns a new MirCursorConfiguration representing a named cursor from the system cursor theme.

Currently only the symbolic values, mir_default_cursor_name and mir_disabled_cursor_name are supported as input.

Parameters
[in]nameThe cursor name
Returns
A cursor parameters object which must be passed to_mir_cursor_configuration_destroy
void mir_display_config_destroy ( MirDisplayConfiguration display_configuration)

Destroy the DisplayConfiguration resource acquired from mir_connection_create_display_config.

Parameters
[in]display_configurationThe display_configuration information resource to be destroyed
char const* mir_prompt_session_error_message ( MirPromptSession prompt_session)

Retrieve a text description of the last error.

The returned string is owned by the library and remains valid until the prompt session has been released.

Parameters
[in]prompt_sessionThe prompt session
Returns
A text description of any error resulting in an invalid connection, or the empty string "" if the connection is valid.
MirBool mir_prompt_session_is_valid ( MirPromptSession prompt_session)

Test for a valid prompt session.

Parameters
[in]prompt_sessionThe prompt session
Returns
True if prompt_session is valid, false otherwise
MirWaitHandle* mir_prompt_session_new_fds_for_prompt_providers ( MirPromptSession prompt_session,
unsigned int  no_of_fds,
mir_client_fd_callback  callback,
void *  context 
)

Allocate some FDs for prompt providers to connect on.

Prompt helpers need to allocate connection FDs it will pass to prompt providers to use when connecting to the server. The server can then associate them with the prompt session.

Warning
This API is tentative until the implementation of prompt sessions is complete
Parameters
[in]prompt_sessionThe prompt session
[in]no_of_fdsThe number of fds to allocate
[in]callbackCallback invoked when request completes
[in,out]contextUser data passed to the callback function
Returns
A handle that can be passed to mir_wait_for
void mir_prompt_session_release_sync ( MirPromptSession prompt_session)

Stop and release the specified prompt session.

Parameters
[in]prompt_sessionThe prompt session
MirEGLNativeWindowType mir_screencast_egl_native_window ( MirScreencast screencast)

Get a window type that can be used by EGL.

Parameters
[in]screencastThe screencast
Returns
An EGLNativeWindowType that the client can use
void mir_screencast_release_sync ( MirScreencast screencast)

Release the specified screencast.

Parameters
[in]screencastThe screencast to be released
MirWaitHandle* mir_surface_configure_cursor ( MirSurface surface,
MirCursorConfiguration const *  parameters 
)

Choose the cursor state for a surface: whether a cursor is shown, and which cursor if so.

Parameters
[in]surfaceThe surface to operate on
[in]parametersThe configuration parameters obtained from mir_cursor* family of functions.
Returns
A wait handle that can be passed to mir_wait_for, or NULL if parameters is invalid.
void mir_surface_get_current_buffer ( MirSurface surface,
MirNativeBuffer **  buffer_package 
)

Get a surface's buffer in "raw" representation.

Precondition
The surface is valid
Parameters
[in]surfaceThe surface
[out]buffer_packageStructure to be populated
int mir_surface_get_dpi ( MirSurface surface)

Query the DPI value of the surface (dots per inch).

This will vary depending on the physical display configuration and where the surface is within it.

Returns
The DPI of the surface, or zero if unknown.
MirEGLNativeWindowType mir_surface_get_egl_native_window ( MirSurface surface)

Get a window type that can be used for OpenGL ES 2.0 acceleration.

Parameters
[in]surfaceThe surface
Returns
An EGLNativeWindowType that the client can use
char const* mir_surface_get_error_message ( MirSurface surface)

Retrieve a text description of the error.

The returned string is owned by the library and remains valid until the surface or the associated connection has been released.

Parameters
[in]surfaceThe surface
Returns
A text description of any error resulting in an invalid surface, or the empty string "" if the connection is valid.
void mir_surface_get_graphics_region ( MirSurface surface,
MirGraphicsRegion graphics_region 
)

Get a surface's graphics_region, i.e., map the graphics buffer to main memory.

Precondition
The surface is valid
Parameters
[in]surfaceThe surface
[out]graphics_regionStructure to be populated
MirOrientation mir_surface_get_orientation ( MirSurface surface)

Get the orientation of a surface.

Parameters
[in]surfaceThe surface to query
Returns
The orientation of the surface
void mir_surface_get_parameters ( MirSurface surface,
MirSurfaceParameters parameters 
)

Get a surface's parameters.

Precondition
The surface is valid
Parameters
[in]surfaceThe surface
[out]parametersStructure to be populated
MirPlatformType mir_surface_get_platform_type ( MirSurface surface)

Get the underlying platform type so the buffer obtained in "raw" representation in mir_surface_get_current_buffer() can be understood.

Precondition
The surface is valid
Parameters
[in]surfaceThe surface
Returns
One of mir_platform_type_android or mir_platform_type_gbm
MirSurfaceState mir_surface_get_state ( MirSurface surface)

Get the current state of a surface.

Parameters
[in]surfaceThe surface to query
Returns
The state of the surface
int mir_surface_get_swapinterval ( MirSurface surface)

Query the swapinterval that the surface is operating with.

The default interval is 1.

Parameters
[in]surfaceThe surface to operate on
Returns
The swapinterval value that the client is operating with. Returns -1 if surface is invalid.
MirSurfaceType mir_surface_get_type ( MirSurface surface)

Get the type (purpose) of a surface.

Parameters
[in]surfaceThe surface to query
Returns
The type of the surface
MirBool mir_surface_is_valid ( MirSurface surface)

Test for a valid surface.

Parameters
[in]surfaceThe surface
Returns
True if the supplied surface is valid, or false otherwise.
MirWaitHandle* mir_surface_release ( MirSurface surface,
mir_surface_callback  callback,
void *  context 
)

Release the supplied surface and any associated buffer.

The returned wait handle remains valid until the connection to the server is released.

Warning
callback could be called from another thread. You must do any locking appropriate to protect your data accessed in the callback.
Parameters
[in]surfaceThe surface
[in]callbackCallback function to be invoked when the request completes
[in,out]contextUser data passed to the callback function
Returns
A handle that can be passed to mir_wait_for
void mir_surface_release_sync ( MirSurface surface)

Release the specified surface like in mir_surface_release(), but also wait for the operation to complete.

Parameters
[in]surfaceThe surface to be released
void mir_surface_set_event_handler ( MirSurface surface,
MirEventDelegate const *  event_handler 
)

Set the event handler to be called when events arrive for a surface.

Warning
event_handler could be called from another thread. You must do any locking appropriate to protect your data accessed in the callback. There is also a chance that different events will be called back in different threads, for the same surface, simultaneously.
Parameters
[in]surfaceThe surface
[in]event_handlerThe event handler to call
MirWaitHandle* mir_surface_set_state ( MirSurface surface,
MirSurfaceState  state 
)

Change the state of a surface.

Parameters
[in]surfaceThe surface to operate on
[in]stateThe new state of the surface
Returns
A wait handle that can be passed to mir_wait_for
MirWaitHandle* mir_surface_set_swapinterval ( MirSurface surface,
int  interval 
)

Set the swapinterval for mir_surface_swap_buffers.

EGL users should use eglSwapInterval directly. At the time being, only swapinterval of 0 or 1 is supported.

Parameters
[in]surfaceThe surface to operate on
[in]intervalThe number of vblank signals that mir_surface_swap_buffers will wait for
Returns
A wait handle that can be passed to mir_wait_for, or NULL if the interval could not be supported
MirWaitHandle* mir_surface_set_type ( MirSurface surface,
MirSurfaceType  type 
)

Set the type (purpose) of a surface.

This is not guaranteed to always work with some shell types (e.g. phone/tablet UIs). As such, you may have to wait on the function and check the result using mir_surface_get_type.

Parameters
[in]surfaceThe surface to operate on
[in]typeThe new type of the surface
Returns
A wait handle that can be passed to mir_wait_for
MirWaitHandle* mir_surface_swap_buffers ( MirSurface surface,
mir_surface_callback  callback,
void *  context 
)

Advance a surface's buffer.

The returned handle remains valid until the next call to mir_surface_swap_buffers, until the surface has been released or the connection to the server has been released.

Warning
callback could be called from another thread. You must do any locking appropriate to protect your data accessed in the callback.
Parameters
[in]surfaceThe surface
[in]callbackCallback function to be invoked when the request completes
[in,out]contextUser data passed to the callback function
Returns
A handle that can be passed to mir_wait_for
void mir_surface_swap_buffers_sync ( MirSurface surface)

Advance a surface's buffer as in mir_surface_swap_buffers(), but also wait for the operation to complete.

Parameters
[in]surfaceThe surface whose buffer to advance
void mir_wait_for ( MirWaitHandle wait_handle)

Wait on the supplied handle until all instances of the associated request have completed.

Parameters
[in]wait_handleHandle returned by an asynchronous request
void mir_wait_for_one ( MirWaitHandle wait_handle)

Wait on the supplied handle until one instance of the associated request has completed.

Use this instead of mir_wait_for in a threaded environment to ensure that the act of waiting does not clear all results associated with the wait handle; only one.

Parameters
[in]wait_handleHandle returned by an asynchronous request

Variable Documentation

MirDisplayInfo* display_info
char const* const mir_default_cursor_name

A special cursor name for use with mir_cursor_configuration_from_name representing the system default cursor.

char const* const mir_disabled_cursor_name

A special cursor name for use with mir_cursor_configuration_from_name representing a disabled cursor image.


Copyright © 2012,2013 Canonical Ltd.
Generated on Thu Jul 24 08:33:56 UTC 2014