Mir
Classes | Macros | Typedefs | Enumerations | Enumerator | Functions | Variables
MIR graphics tools API

Classes

struct  MirWaitHandle
 
struct  MirKeyboardEvent
 
struct  MirMotionPointer
 
struct  MirMotionEvent
 
struct  MirInputConfigurationEvent
 
struct  MirSurfaceEvent
 
struct  MirResizeEvent
 
struct  MirPromptSessionEvent
 
struct  MirOrientationEvent
 
struct  MirCloseSurfaceEvent
 
struct  MirKeymapEvent
 
struct  MirSurfaceOutputEvent
 
union  MirEvent
 
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  MirModuleProperties
 Retrieved information about a loadable module. More...
 
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  MirBufferStreamInfo
 The displacement from the top-left corner of the surface. 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  MirPlatformMessageData
 
struct  MirPlatformMessageFds
 
struct  MirMesaEGLNativeDisplay
 
struct  MirMesaEGLNativeSurface
 
struct  MirMesaAuthMagicRequest
 
struct  MirMesaAuthMagicResponse
 
struct  MirMesaSetGBMDeviceRequest
 
struct  MirMesaSetGBMDeviceResponse
 

Macros

#define MIR_INPUT_EVENT_MAX_POINTER_COUNT   16
 
#define MIR_CLIENT_MAJOR_VERSION   (3)
 MIR_CLIENT_MAJOR_VERSION. More...
 
#define MIR_CLIENT_MINOR_VERSION   (3)
 MIR_CLIENT_MINOR_VERSION. More...
 
#define MIR_CLIENT_MICRO_VERSION   (0)
 MIR_CLIENT_MICRO_VERSION. More...
 
#define MIR_CLIENT_VERSION
 MIR_CLIENT_VERSION. More...
 
#define MIR_BYTES_PER_PIXEL(f)
 

Typedefs

typedef struct MirPresentationChain MirPresentationChain
 
typedef struct MirBuffer MirBuffer
 
typedef void * MirNativeFence
 
typedef void(* mir_buffer_callback) (MirPresentationChain *, MirBuffer *, void *context)
 
typedef void(* mir_presentation_chain_callback) (MirPresentationChain *, void *context)
 
typedef enum MirBufferAccess MirBufferAccess
 
typedef void * MirEGLNativeWindowType
 
typedef void * MirEGLNativeDisplayType
 
typedef struct MirConnection MirConnection
 
typedef struct MirSurface MirSurface
 
typedef struct MirSurfaceSpec MirSurfaceSpec
 
typedef struct MirScreencast MirScreencast
 
typedef struct MirPromptSession MirPromptSession
 
typedef struct MirBufferStream MirBufferStream
 
typedef struct MirPersistentId MirPersistentId
 
typedef struct MirBlob MirBlob
 
typedef struct MirDisplayConfig MirDisplayConfig
 
typedef struct MirOutput MirOutput
 Descriptor for an output connection. More...
 
typedef struct MirWaitHandle MirWaitHandle
 Returned by asynchronous functions. More...
 
typedef struct MirPlatformMessage MirPlatformMessage
 
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_buffer_stream_callback) (MirBufferStream *stream, void *client_context)
 Callback to be passed when calling: More...
 
typedef void(* mir_surface_event_callback) (MirSurface *surface, MirEvent const *event, void *context)
 Callback for handling of surface 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_ping_event_callback) (MirConnection *connection, int32_t serial, void *context)
 Callback called when the server pings for responsiveness testing. 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 void(* mir_surface_id_callback) (MirSurface *surface, MirPersistentId *id, void *context)
 
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 MirModuleProperties MirModuleProperties
 Retrieved information about a loadable module. More...
 
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 enum MirOutputType MirOutputType
 
typedef enum MirOutputConnectionState MirOutputConnectionState
 
typedef struct MirDisplayMode MirDisplayMode
 
typedef struct MirDisplayOutput MirDisplayOutput
 
typedef struct MirDisplayConfiguration MirDisplayConfiguration
 
typedef struct MirBufferStreamInfo MirBufferStreamInfo
 The displacement from the top-left corner of the surface. More...
 
typedef struct MirRectangle MirRectangle
 
typedef struct MirInputConfig MirInputConfig
 
typedef struct MirInputDevice MirInputDevice
 
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 void(* mir_platform_operation_callback) (MirConnection *connection, MirPlatformMessage *reply, void *context)
 Callback called when a platform operation completes. More...
 
typedef void(* mir_input_config_callback) (MirConnection *connection, void *context)
 Callback called when a change of input devices has occurred. More...
 
typedef struct MirSurfaceEvent MirSurfaceEvent
 
typedef struct MirResizeEvent MirResizeEvent
 
typedef struct MirPromptSessionEvent MirPromptSessionEvent
 
typedef struct MirOrientationEvent MirOrientationEvent
 
typedef struct MirCloseSurfaceEvent MirCloseSurfaceEvent
 
typedef struct MirInputEvent MirInputEvent
 
typedef struct MirKeymapEvent MirKeymapEvent
 
typedef struct MirInputConfigurationEvent MirInputConfigurationEvent
 
typedef struct MirSurfaceOutputEvent MirSurfaceOutputEvent
 
typedef struct MirCookie MirCookie
 
typedef union MirEvent MirEvent
 
typedef int64_t MirInputDeviceId
 
typedef unsigned int MirInputEventModifiers
 
typedef struct MirKeyboardEvent MirKeyboardEvent
 An event type describing a change in keyboard state. More...
 
typedef struct MirPointerEvent MirPointerEvent
 An event type describing a change in pointer device state. More...
 
typedef unsigned int MirPointerButtons
 
typedef struct MirTouchEvent MirTouchEvent
 An event type describing a change in touch device state. More...
 
typedef int32_t MirTouchId
 An identifier for a touch-point. More...
 
typedef struct MirOutputMode MirOutputMode
 A descriptor for a display mode. More...
 
typedef enum MirPointerHandedness MirPointerHandedness
 
typedef enum MirPointerAcceleration MirPointerAcceleration
 MirPointerAcceleration describes the way pointer movement is filtered: More...
 
typedef enum MirTouchpadClickMode MirTouchpadClickMode
 
typedef unsigned int MirTouchpadClickModes
 
typedef enum MirTouchpadScrollMode MirTouchpadScrollMode
 
typedef unsigned int MirTouchpadScrollModes
 
typedef unsigned int MirInputDeviceCapabilities
 
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
 32-bit pixel formats (8888): The order of components in the 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 enum MirOrientationMode MirOrientationMode
 
typedef enum MirEdgeAttachment MirEdgeAttachment
 
typedef enum MirFormFactor MirFormFactor
 Form factor associated with a physical output. More...
 
typedef enum MirShellChrome MirShellChrome
 Shell chrome. More...
 
typedef struct MirMesaEGLNativeDisplay MirMesaEGLNativeDisplay
 
typedef struct MirMesaEGLNativeSurface MirMesaEGLNativeSurface
 
typedef struct MirBufferPackage MirBufferPackage
 

Enumerations

enum  MirBufferAccess { mir_none, mir_read, mir_read_write }
 
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  MirOutputType {
  mir_output_type_unknown, mir_output_type_vga, mir_output_type_dvii, mir_output_type_dvid,
  mir_output_type_dvia, mir_output_type_composite, mir_output_type_svideo, mir_output_type_lvds,
  mir_output_type_component, mir_output_type_ninepindin, mir_output_type_displayport, mir_output_type_hdmia,
  mir_output_type_hdmib, mir_output_type_tv, mir_output_type_edp
}
 
enum  MirOutputConnectionState { mir_output_connection_state_disconnected = 0, mir_output_connection_state_connected, mir_output_connection_state_unknown }
 
enum  { mir_display_output_id_invalid = 0 }
 
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, mir_event_type_close_surface, mir_event_type_input,
  mir_event_type_keymap, mir_event_type_input_configuration, mir_event_type_surface_output
}
 
enum  MirInputEventType { mir_input_event_type_key = 0, mir_input_event_type_touch = 1, mir_input_event_type_pointer = 2 }
 
enum  MirInputEventModifier {
  mir_input_event_modifier_none = 1 << 0, mir_input_event_modifier_alt = 1 << 1, mir_input_event_modifier_alt_left = 1 << 2, mir_input_event_modifier_alt_right = 1 << 3,
  mir_input_event_modifier_shift = 1 << 4, mir_input_event_modifier_shift_left = 1 << 5, mir_input_event_modifier_shift_right = 1 << 6, mir_input_event_modifier_sym = 1 << 7,
  mir_input_event_modifier_function = 1 << 8, mir_input_event_modifier_ctrl = 1 << 9, mir_input_event_modifier_ctrl_left = 1 << 10, mir_input_event_modifier_ctrl_right = 1 << 11,
  mir_input_event_modifier_meta = 1 << 12, mir_input_event_modifier_meta_left = 1 << 13, mir_input_event_modifier_meta_right = 1 << 14, mir_input_event_modifier_caps_lock = 1 << 15,
  mir_input_event_modifier_num_lock = 1 << 16, mir_input_event_modifier_scroll_lock = 1 << 17
}
 Description of key modifier state. More...
 
enum  MirKeyboardAction { mir_keyboard_action_up, mir_keyboard_action_down, mir_keyboard_action_repeat }
 Possible actions for changing key state. More...
 
enum  MirPointerAction {
  mir_pointer_action_button_up = 0, mir_pointer_action_button_down = 1, mir_pointer_action_enter = 2, mir_pointer_action_leave = 3,
  mir_pointer_action_motion = 4
}
 Possible pointer actions. More...
 
enum  MirPointerAxis {
  mir_pointer_axis_x = 0, mir_pointer_axis_y = 1, mir_pointer_axis_vscroll = 2, mir_pointer_axis_hscroll = 3,
  mir_pointer_axis_relative_x = 4, mir_pointer_axis_relative_y = 5
}
 Identifiers for pointer axis. More...
 
enum  MirPointerButton {
  mir_pointer_button_primary = 1 << 0, mir_pointer_button_secondary = 1 << 1, mir_pointer_button_tertiary = 1 << 2, mir_pointer_button_back = 1 << 3,
  mir_pointer_button_forward = 1 << 4, mir_pointer_button_side = 1 << 5, mir_pointer_button_extra = 1 << 6, mir_pointer_button_task = 1 << 7
}
 
enum  MirTouchAction { mir_touch_action_up = 0, mir_touch_action_down = 1, mir_touch_action_change = 2 }
 Possible per touch actions for state changing. More...
 
enum  MirTouchAxis {
  mir_touch_axis_x = 0, mir_touch_axis_y = 1, mir_touch_axis_pressure = 2, mir_touch_axis_touch_major = 3,
  mir_touch_axis_touch_minor = 4, mir_touch_axis_size = 5
}
 Identifiers for touch axis. More...
 
enum  MirTouchTooltype { mir_touch_tooltype_unknown = 0, mir_touch_tooltype_finger = 1, mir_touch_tooltype_stylus = 2 }
 Identifiers for per-touch tool types. More...
 
enum  MirInputConfigurationAction { mir_input_configuration_action_configuration_changed, mir_input_configuration_action_device_reset }
 MirInputConfigurationEvent indicates a configuration change in the input device subsystem. Eventually it's usage will be required to properly interpret MirInputEvent, for example: If we receive a button down, and then a device reset, we should not expect to receive the button up. More...
 
enum  MirPointerHandedness { mir_pointer_handedness_right = 0, mir_pointer_handedness_left = 1 }
 
enum  MirPointerAcceleration { mir_pointer_acceleration_none = 1, mir_pointer_acceleration_adaptive = 2 }
 MirPointerAcceleration describes the way pointer movement is filtered: More...
 
enum  MirTouchpadClickMode { mir_touchpad_click_mode_none = 0, mir_touchpad_click_mode_area_to_click = 1 << 0, mir_touchpad_click_mode_finger_count = 1 << 1 }
 
enum  MirTouchpadScrollMode { mir_touchpad_scroll_mode_none = 0, mir_touchpad_scroll_mode_two_finger_scroll = 1 << 0, mir_touchpad_scroll_mode_edge_scroll = 1 << 1, mir_touchpad_scroll_mode_button_down_scroll = 1 << 2 }
 
enum  MirInputDeviceCapability {
  mir_input_device_capability_none = 0, mir_input_device_capability_pointer = 1<<1, mir_input_device_capability_keyboard = 1<<2, mir_input_device_capability_touchpad = 1<<3,
  mir_input_device_capability_touchscreen = 1<<4, mir_input_device_capability_gamepad = 1<<5, mir_input_device_capability_joystick = 1<<6, mir_input_device_capability_switch = 1<<7,
  mir_input_device_capability_multitouch = 1<<8, mir_input_device_capability_alpha_numeric = 1<<9
}
 
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_attrib_preferred_orientation, 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_gloss = mir_surface_type_overlay, mir_surface_type_freestyle, mir_surface_type_popover, mir_surface_type_menu = mir_surface_type_popover,
  mir_surface_type_inputmethod, mir_surface_type_satellite, mir_surface_type_tip, 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_state_horizmaximized, mir_surface_state_hidden,
  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, mir_prompt_session_state_suspended }
 
enum  MirPixelFormat {
  mir_pixel_format_invalid = 0, mir_pixel_format_abgr_8888 = 1, mir_pixel_format_xbgr_8888 = 2, mir_pixel_format_argb_8888 = 3,
  mir_pixel_format_xrgb_8888 = 4, mir_pixel_format_bgr_888 = 5, mir_pixel_format_rgb_888 = 6, mir_pixel_format_rgb_565 = 7,
  mir_pixel_format_rgba_5551 = 8, mir_pixel_format_rgba_4444 = 9, mir_pixel_formats
}
 32-bit pixel formats (8888): The order of components in the 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  MirOrientationMode {
  mir_orientation_mode_portrait = 1 << 0, mir_orientation_mode_landscape = 1 << 1, mir_orientation_mode_portrait_inverted = 1 << 2, mir_orientation_mode_landscape_inverted = 1 << 3,
  mir_orientation_mode_portrait_any, mir_orientation_mode_landscape_any, mir_orientation_mode_any
}
 
enum  MirEdgeAttachment { mir_edge_attachment_vertical = 1 << 0, mir_edge_attachment_horizontal = 1 << 1, mir_edge_attachment_any }
 
enum  MirFormFactor {
  mir_form_factor_unknown, mir_form_factor_phone, mir_form_factor_tablet, mir_form_factor_monitor,
  mir_form_factor_tv, mir_form_factor_projector
}
 Form factor associated with a physical output. More...
 
enum  MirShellChrome { mir_shell_chrome_normal, mir_shell_chrome_low }
 Shell chrome. More...
 
enum  MirMesaPlatformOperation { auth_magic = 1, auth_fd = 2, set_gbm_device = 3 }
 

Functions

void mir_buffer_release (MirBuffer *buffer)
 release a MirBuffer More...
 
bool mir_presentation_chain_is_valid (MirPresentationChain *presentation_chain)
 Test for a valid presentation chain. More...
 
char const * mir_presentation_chain_get_error_message (MirPresentationChain *presentation_chain)
 Retrieve a text description of the error. More...
 
void mir_connection_create_presentation_chain (MirConnection *connection, mir_presentation_chain_callback callback, void *context)
 Create a new presentation chain. More...
 
MirPresentationChainmir_connection_create_presentation_chain_sync (MirConnection *connection)
 Create a new presentation chain and wait for the result. More...
 
void mir_presentation_chain_release (MirPresentationChain *presentation_chain)
 Release the specified presentation chain. More...
 
void mir_presentation_chain_allocate_buffer (MirPresentationChain *presentation_chain, int width, int height, MirPixelFormat format, MirBufferUsage buffer_usage, mir_buffer_callback available_callback, void *available_context)
 Allocate a MirBuffer and do not wait for the server to return it. More...
 
void mir_presentation_chain_submit_buffer (MirPresentationChain *presentation_chain, MirBuffer *buffer)
 Submit a buffer to the server so the server can display it. More...
 
void mir_surface_spec_add_presentation_chain (MirSurfaceSpec *spec, int width, int height, int displacement_x, int displacement_y, MirPresentationChain *chain)
 Set the MirSurfaceContent to display a MirPresentationChain. More...
 
void mir_surface_spec_add_buffer_stream (MirSurfaceSpec *spec, int displacement_x, int displacement_y, MirBufferStream *stream)
 Set the MirSurfaceContent to display a MirBufferStream. More...
 
MirEventType mir_event_get_type (MirEvent const *ev)
 Retrieves the type of a MirEvent. More...
 
MirInputEvent const * mir_event_get_input_event (MirEvent const *ev)
 Retrieve the MirInputEvent associated with a MirEvent of type mir_event_type_input. More...
 
MirSurfaceEvent const * mir_event_get_surface_event (MirEvent const *ev)
 Retrieve the MirSurfaceEvent associated with a MirEvent of type mir_event_type_surface. More...
 
MirResizeEvent const * mir_event_get_resize_event (MirEvent const *ev)
 Retrieve the MirResizeEvent associated with a MirEvent of type mir_event_type_resize. More...
 
MirPromptSessionEvent const * mir_event_get_prompt_session_event (MirEvent const *ev)
 Retrieve the MirPromptSessionEvent associated with a MirEvent of type mir_event_type_prompt_session_state_change. More...
 
MirOrientationEvent const * mir_event_get_orientation_event (MirEvent const *ev)
 Retrieve the MirOrientationEvent associated with a MirEvent of type mir_event_type_orientation. More...
 
 __attribute__ ((deprecated)) MirCloseSurfaceEvent const *mir_event_get_close_surface_event(MirEvent const *ev)
 Retrieve the MirCloseSurfaceEvent associated with a MirEvent of type mir_event_type_close_surface. More...
 
MirKeymapEvent const * mir_event_get_keymap_event (MirEvent const *ev)
 Retrieve the MirKeymapEvent associated with a MirEvent of type mir_event_type_keymap. More...
 
MirInputConfigurationEvent const * mir_event_get_input_configuration_event (MirEvent const *ev)
 Retrieve the MirInputConfiguration associated with a MirEvent of type mir_event_type_input_configuration. More...
 
MirSurfaceOutputEvent const * mir_event_get_surface_output_event (MirEvent const *ev)
 Retrieve the MirSurfaceOutputEvent associated with a MirEvent of type mir_event_type_surface_output. More...
 
MirEvent const * mir_event_ref (MirEvent const *ev) __attribute__((warn_unused_result))
 Reference this MirEvent and return a pointer to the newly referenced instance. More...
 
void mir_event_unref (MirEvent const *ev)
 Release a reference to a MirEvent. More...
 
MirInputDeviceId mir_input_event_get_device_id (MirInputEvent const *ev)
 Retrieves the device id responsible for generating an input event. More...
 
int64_t mir_input_event_get_event_time (MirInputEvent const *ev)
 Retrieve the time at which an input event occurred. More...
 
MirInputEventType mir_input_event_get_type (MirInputEvent const *ev)
 Retrieve the type of an input event. More...
 
MirKeyboardEvent const * mir_input_event_get_keyboard_event (MirInputEvent const *ev)
 Retrieve the MirKeyboardEvent associated with a given input event. More...
 
MirTouchEvent const * mir_input_event_get_touch_event (MirInputEvent const *ev)
 Retrieve the MirTouchEvent associated with a given input event. More...
 
MirPointerEvent const * mir_input_event_get_pointer_event (MirInputEvent const *ev)
 Retrieve the MirPointerEvent associated with a given input event. More...
 
bool mir_input_event_has_cookie (MirInputEvent const *ev)
 Query if an input event contains a cookie. More...
 
MirCookie const * mir_input_event_get_cookie (MirInputEvent const *ev)
 Returns the cookie associated with an input event. More...
 
MirKeyboardAction mir_keyboard_event_action (MirKeyboardEvent const *event)
 Retrieve the action which triggered a given key event. More...
 
xkb_keysym_t mir_keyboard_event_key_code (MirKeyboardEvent const *event)
 Retrieve the xkb mapped keycode associated with the key acted on. More...
 
int mir_keyboard_event_scan_code (MirKeyboardEvent const *event)
 Retrieve the raw hardware scan code associated with the key acted on. More...
 
MirInputEventModifiers mir_keyboard_event_modifiers (MirKeyboardEvent const *event)
 Retrieve the modifier keys pressed when the key action occured. More...
 
MirInputEvent const * mir_keyboard_event_input_event (MirKeyboardEvent const *event)
 Retrieve the corresponding input event. More...
 
MirInputEventModifiers mir_pointer_event_modifiers (MirPointerEvent const *event)
 Retrieve the modifier keys pressed when the pointer action occured. More...
 
MirPointerAction mir_pointer_event_action (MirPointerEvent const *event)
 Retrieve the action which occured to generate a given pointer event. More...
 
bool mir_pointer_event_button_state (MirPointerEvent const *event, MirPointerButton button)
 Retrieve the state of a given pointer button when the action occurred. More...
 
MirPointerButtons mir_pointer_event_buttons (MirPointerEvent const *event)
 Retreive the pointer button state as a masked set of values. More...
 
float mir_pointer_event_axis_value (MirPointerEvent const *event, MirPointerAxis axis)
 Retrieve the axis value reported by a given pointer event. More...
 
MirInputEvent const * mir_pointer_event_input_event (MirPointerEvent const *event)
 Retrieve the corresponding input event. More...
 
MirInputEventModifiers mir_touch_event_modifiers (MirTouchEvent const *event)
 Retrieve the modifier keys pressed when the touch action occured. More...
 
unsigned int mir_touch_event_point_count (MirTouchEvent const *event)
 Retrieve the number of touches reported for a given touch event. More...
 
MirTouchId mir_touch_event_id (MirTouchEvent const *event, size_t touch_index)
 Retrieve the TouchID for a touch at given index. More...
 
MirTouchAction mir_touch_event_action (MirTouchEvent const *event, size_t touch_index)
 Retrieve the action which occured for a touch at given index. More...
 
MirTouchTooltype mir_touch_event_tooltype (MirTouchEvent const *event, size_t touch_index)
 Retrieve the tooltype for touch at given index. More...
 
float mir_touch_event_axis_value (MirTouchEvent const *event, size_t touch_index, MirTouchAxis axis)
 Retrieve the axis value for a given axis on an indexed touch. More...
 
MirInputEvent const * mir_touch_event_input_event (MirTouchEvent const *event)
 Retrieve the corresponding input event. More...
 
MirInputConfigurationAction mir_input_configuration_event_get_action (MirInputConfigurationEvent const *ev)
 Retrieve the input configuration action which occurred. More...
 
int64_t mir_input_configuration_event_get_time (MirInputConfigurationEvent const *ev)
 Retreive the time associated with a MirInputConfiguration event. More...
 
MirInputDeviceId mir_input_configuration_event_get_device_id (MirInputConfigurationEvent const *ev)
 Retreive the device id associated with a MirInputConfiguration event. More...
 
void mir_keymap_event_get_rules (MirKeymapEvent const *ev, struct xkb_rule_names *names) __attribute__((deprecated))
 Retrieve the new keymap reported by this MirKeymapEvent. More...
 
void mir_keymap_event_get_keymap_buffer (MirKeymapEvent const *ev, char const **buffer, size_t *length)
 Retrieve the new keymap reported by this MirKeymapEvent. More...
 
MirInputDeviceId mir_keymap_event_get_device_id (MirKeymapEvent const *ev)
 Retrieve the device id the keymap reported by this MirKeymapEvent applies to. More...
 
MirOrientation mir_orientation_event_get_direction (MirOrientationEvent const *ev)
 Retrieve the new orientation reported by this MirOrientationEvent. More...
 
MirPromptSessionState mir_prompt_session_event_get_state (MirPromptSessionEvent const *ev)
 Retrieve the new prompt session state reported by a given MirPromptSessionEvent. More...
 
int mir_resize_event_get_width (MirResizeEvent const *ev)
 Retrieve the new width reported by a given MirResizeEvent. More...
 
int mir_resize_event_get_height (MirResizeEvent const *ev)
 Retrieve the new height reported by a given MirResizeEvent. More...
 
MirSurfaceAttrib mir_surface_event_get_attribute (MirSurfaceEvent const *ev)
 Retrieve the attribute index configured with a given MirSurfaceEvent. More...
 
int mir_surface_event_get_attribute_value (MirSurfaceEvent const *ev)
 Retrieve the new value of the associated attribute for a given MirSurfaceEvent. More...
 
int mir_surface_output_event_get_dpi (MirSurfaceOutputEvent const *ev)
 Retrieve the DPI of the new output configuration of a MirSurfaceOutputEvent. More...
 
MirFormFactor mir_surface_output_event_get_form_factor (MirSurfaceOutputEvent const *ev)
 Retrieve the form factor of the new output configuration of a MirSurfaceOutputEvent. More...
 
float mir_surface_output_event_get_scale (MirSurfaceOutputEvent const *ev)
 Retrieve the form factor of the new output configuration of a MirSurfaceOutputEvent. More...
 
uint32_t mir_surface_output_event_get_output_id (MirSurfaceOutputEvent const *ev)
 Retrieve the ID of the output this surface is on from a MirSurfaceOutputEvent. More...
 
MirBlobmir_blob_from_display_configuration (MirDisplayConfiguration *configuration)
 Create a blob from a display configuration. More...
 
MirBlobmir_blob_onto_buffer (void const *buffer, size_t buffer_size)
 Create a blob from a buffer. More...
 
MirDisplayConfigurationmir_blob_to_display_configuration (MirBlob *blob)
 Create a blob from a display configuration. More...
 
size_t mir_blob_size (MirBlob *blob)
 Get the size of a blob. More...
 
void const * mir_blob_data (MirBlob *blob)
 Get the data of a blob. More...
 
void mir_blob_release (MirBlob *blob)
 Release a blob object. More...
 
bool mir_buffer_stream_is_valid (MirBufferStream *buffer_stream)
 Test for a valid buffer stream. More...
 
char const * mir_buffer_stream_get_error_message (MirBufferStream *surface)
 Retrieve a text description of the error. More...
 
MirWaitHandlemir_connection_create_buffer_stream (MirConnection *connection, int width, int height, MirPixelFormat format, MirBufferUsage buffer_usage, mir_buffer_stream_callback callback, void *context)
 Create a new buffer stream. More...
 
MirBufferStreammir_connection_create_buffer_stream_sync (MirConnection *connection, int width, int height, MirPixelFormat format, MirBufferUsage buffer_usage)
 Create a new buffer stream unattached to a surface and wait for the result. More...
 
MirWaitHandlemir_buffer_stream_release (MirBufferStream *buffer_stream, mir_buffer_stream_callback callback, void *context)
 Release the supplied stream and any associated buffer. More...
 
void mir_buffer_stream_release_sync (MirBufferStream *buffer_stream)
 Release the specified buffer stream like in mir,_buffer_stream_release(), but also wait for the operation to complete. More...
 
void mir_buffer_stream_get_current_buffer (MirBufferStream *buffer_stream, MirNativeBuffer **buffer_package)
 Retrieve the current buffer in "raw" representation. More...
 
MirWaitHandlemir_buffer_stream_swap_buffers (MirBufferStream *buffer_stream, mir_buffer_stream_callback callback, void *context)
 Advance a buffer stream's buffer. More...
 
void mir_buffer_stream_swap_buffers_sync (MirBufferStream *buffer_stream)
 Advance a buffer stream's buffer as in mir_buffer stream_swap_buffers(), but also wait for the operation to complete. More...
 
void mir_buffer_stream_get_graphics_region (MirBufferStream *buffer_stream, MirGraphicsRegion *graphics_region)
 Retrieve a buffer stream's graphics region. More...
 
MirEGLNativeWindowType mir_buffer_stream_get_egl_native_window (MirBufferStream *buffer_stream)
 Retrieve a window type which may be used by EGL. More...
 
MirWaitHandlemir_buffer_stream_set_scale (MirBufferStream *stream, float scale)
 Set the scale associated with all buffers in the stream. More...
 
void mir_buffer_stream_set_scale_sync (MirBufferStream *stream, float scale)
 Set the scale as in mir_buffer_stream_set_scale(), but also wait for the operation to complete. 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...
 
bool 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_get_graphics_module (MirConnection *connection, MirModuleProperties *properties)
 Query graphics platform module. 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...
 
void mir_connection_set_ping_event_callback (MirConnection *connection, mir_ping_event_callback callback, void *context)
 Register a callback for server ping events. More...
 
void mir_connection_pong (MirConnection *connection, int32_t serial)
 Respond to a ping event. More...
 
MirDisplayConfigurationmir_connection_create_display_config (MirConnection *connection)
 Query the display. More...
 
MirDisplayConfigmir_connection_create_display_configuration (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...
 
MirWaitHandlemir_connection_set_base_display_config (MirConnection *connection, MirDisplayConfiguration const *display_configuration)
 Set the base 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...
 
MirPixelFormat mir_connection_get_egl_pixel_format (MirConnection *connection, void *egldisplay, void *eglconfig)
 Get the exact MirPixelFormat to use in creating a surface for a chosen EGLConfig. 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...
 
MirWaitHandlemir_connection_platform_operation (MirConnection *connection, MirPlatformMessage const *request, mir_platform_operation_callback callback, void *context)
 Perform a platform specific operation. More...
 
MirInputConfigmir_connection_create_input_config (MirConnection *connection)
 Create a snapshot of the attached input devices and device configurations. More...
 
void mir_input_config_destroy (MirInputConfig const *config)
 Release this snapshot of the input configuration. More...
 
void mir_connection_set_input_config_change_callback (MirConnection *connection, mir_input_config_callback callback, void *context)
 Register a callback to be called when the input devices change. More...
 
size_t mir_cookie_buffer_size (MirCookie const *cookie)
 Queries the size needed to serialize a given cookie. More...
 
void mir_cookie_to_buffer (MirCookie const *cookie, void *buffer, size_t size)
 Serializes a cookie into the given buffer. More...
 
MirCookie const * mir_cookie_from_buffer (void const *buffer, size_t size)
 Create a cookie from a serialized representation. More...
 
void mir_cookie_release (MirCookie const *cookie)
 Release the MirCookie. 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...
 
MirCursorConfigurationmir_cursor_configuration_from_buffer_stream (MirBufferStream const *stream, int hotspot_x, int hotspot_y)
 Returns a new cursor configuration tied to a given buffer stream. More...
 
void mir_display_config_release (MirDisplayConfig *config)
 Release resources associated with a MirDisplayConfig handle. More...
 
int mir_display_config_get_max_simultaneous_outputs (MirDisplayConfig const *config)
 Get the maximum possible number of simultaneously active outputs this system supports. More...
 
int mir_display_config_get_num_outputs (MirDisplayConfig const *config)
 Get the number of outputs available in this display configuration. More...
 
MirOutput const * mir_display_config_get_output (MirDisplayConfig const *config, size_t index)
 Get a read-only handle to the index 'th output of this configuration. More...
 
int mir_output_get_num_modes (MirOutput const *output)
 Get the number of modes in the supported mode list of this output. More...
 
MirOutputMode const * mir_output_get_mode (MirOutput const *output, size_t index)
 Get a handle for a mode descriptor from the list of supported modes. More...
 
MirOutputMode const * mir_output_get_preferred_mode (MirOutput const *output)
 Get a handle to the output's preferred mode. More...
 
MirOutputMode const * mir_output_get_current_mode (MirOutput const *output)
 Get a handle to the output's current mode. More...
 
int mir_output_get_num_pixel_formats (MirOutput const *output)
 Get the number of pixel formats supported by this output. More...
 
MirPixelFormat mir_output_get_pixel_format (MirOutput const *output, size_t index)
 Get a pixel format from the list of supported formats. More...
 
MirPixelFormat mir_output_get_current_pixel_format (MirOutput const *output)
 Get the current pixel format. More...
 
void mir_output_set_pixel_format (MirOutput *output, MirPixelFormat format)
 Set the output format. More...
 
int mir_output_get_id (MirOutput const *output)
 Get the ID of an output. More...
 
MirOutputType mir_output_get_type (MirOutput const *output)
 Get the physical connection type of an output. More...
 
int mir_output_get_position_x (MirOutput const *output)
 Get the x coordinate of the top-left point of the output in the virtual display space. More...
 
int mir_output_get_position_y (MirOutput const *output)
 Get the y coordinate of the top-left point of the output in the virtual display space. More...
 
MirOutputConnectionState mir_output_get_connection_state (MirOutput const *output)
 Get whether there is a display physically connected to the output. More...
 
bool mir_output_is_enabled (MirOutput const *output)
 Get whether this output is enabled in the current configuration. More...
 
int mir_output_get_physical_width_mm (MirOutput const *output)
 Get the physical width of the connected display, in millimetres. More...
 
int mir_output_get_physical_height_mm (MirOutput const *output)
 Get the physical height of the connected display, in millimetres. More...
 
MirPowerMode mir_output_get_power_mode (MirOutput const *output)
 Get the power state of a connected display. More...
 
MirOrientation mir_output_get_orientation (MirOutput const *output)
 Get the orientation of a display. More...
 
float mir_output_get_scale_factor (MirOutput const *output)
 Get the scale-factor of a display. More...
 
MirFormFactor mir_output_get_form_factor (MirOutput const *output)
 Get the form-factor of a connected output. More...
 
int mir_output_mode_get_width (MirOutputMode const *mode)
 Get the width, in pixels, of a MirOutputMode. More...
 
int mir_output_mode_get_height (MirOutputMode const *mode)
 Get the height, in pixels, of a MirOutputMode. More...
 
double mir_output_mode_get_refresh_rate (MirOutputMode const *mode)
 Get the refresh rate, in Hz, of a MirOutputMode. More...
 
size_t mir_input_config_device_count (MirInputConfig const *config)
 Retrieve the number of available input devices. More...
 
MirInputDevice const * mir_input_config_get_device (MirInputConfig const *config, size_t index)
 Retrieve the input device at given index. More...
 
MirInputDevice const * mir_input_config_get_device_by_id (MirInputConfig const *config, MirInputDeviceId id)
 Retrieve the input device by id. More...
 
MirInputDevicemir_input_config_get_mutable_device (MirInputConfig *config, size_t index)
 Retrieve the input device at given index. More...
 
MirInputDevicemir_input_config_get_mutable_device_by_id (MirInputConfig *config, MirInputDeviceId id)
 Retrieve the input device by id. More...
 
MirInputDeviceCapabilities mir_input_device_get_capabilities (MirInputDevice const *device)
 Retrieve the capabilities of the input device at the given index. More...
 
MirInputDeviceId mir_input_device_get_id (MirInputDevice const *device)
 Retrieve the device id of the input device. More...
 
char const * mir_input_device_get_name (MirInputDevice const *device)
 Retrieve the name of the input device. More...
 
char const * mir_input_device_get_unique_id (MirInputDevice const *device)
 Retrieve the unique id of the input device. More...
 
MirPlatformMessagemir_platform_message_create (unsigned int opcode)
 Create a platform message to use with mir_connection_platform_operation(). More...
 
void mir_platform_message_release (MirPlatformMessage const *message)
 Release a platform message. More...
 
void mir_platform_message_set_data (MirPlatformMessage *message, void const *data, size_t data_size)
 Set the data associated with a message. More...
 
void mir_platform_message_set_fds (MirPlatformMessage *message, int const *fds, size_t num_fds)
 Sets the fds associated with a message. More...
 
unsigned int mir_platform_message_get_opcode (MirPlatformMessage const *message)
 Get the opcode of a message. More...
 
MirPlatformMessageData mir_platform_message_get_data (MirPlatformMessage const *message)
 Get the data associated with a message. More...
 
MirPlatformMessageFds mir_platform_message_get_fds (MirPlatformMessage const *message)
 Gets the fds associated with a message. 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...
 
bool 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...
 
MirBufferStreammir_screencast_get_buffer_stream (MirScreencast *screencast)
 Retrieve the MirBufferStream associated with a screencast (to advance buffers, obtain EGLNativeWindowType, etc...) More...
 
MirSurfaceSpecmir_connection_create_spec_for_normal_surface (MirConnection *connection, int width, int height, MirPixelFormat format)
 Create a surface specification for a normal surface. More...
 
MirSurfaceSpecmir_connection_create_spec_for_menu (MirConnection *connection, int width, int height, MirPixelFormat format, MirSurface *parent, MirRectangle *rect, MirEdgeAttachment edge)
 Create a surface specification for a menu surface. More...
 
MirSurfaceSpecmir_connection_create_spec_for_tooltip (MirConnection *connection, int width, int height, MirPixelFormat format, MirSurface *parent, MirRectangle *zone)
 Create a surface specification for a tooltip surface. More...
 
MirSurfaceSpecmir_connection_create_spec_for_modal_dialog (MirConnection *connection, int width, int height, MirPixelFormat format, MirSurface *parent)
 Create a surface specification for a modal dialog surface. More...
 
MirSurfaceSpecmir_connection_create_spec_for_dialog (MirConnection *connection, int width, int height, MirPixelFormat format)
 Create a surface specification for a parentless dialog surface. More...
 
MirSurfaceSpecmir_create_surface_spec (MirConnection *connection)
 Create a surface specification. More...
 
MirSurfaceSpecmir_connection_create_spec_for_changes (MirConnection *connection)
 Create a surface specification for updating a surface. More...
 
MirWaitHandlemir_surface_create (MirSurfaceSpec *requested_specification, mir_surface_callback callback, void *context)
 Create a surface from a given specification. More...
 
MirSurfacemir_surface_create_sync (MirSurfaceSpec *requested_specification)
 Create a surface from a given specification and wait for the result. More...
 
void mir_surface_spec_set_parent (MirSurfaceSpec *spec, MirSurface *parent)
 Set the requested parent. More...
 
void mir_surface_spec_set_type (MirSurfaceSpec *spec, MirSurfaceType type)
 Update a surface specification with a surface type. More...
 
void mir_surface_spec_set_name (MirSurfaceSpec *spec, char const *name)
 Set the requested name. More...
 
void mir_surface_spec_set_width (MirSurfaceSpec *spec, unsigned width)
 Set the requested width, in pixels. More...
 
void mir_surface_spec_set_height (MirSurfaceSpec *spec, unsigned height)
 Set the requested height, in pixels. More...
 
void mir_surface_spec_set_width_increment (MirSurfaceSpec *spec, unsigned width_inc)
 Set the requested width increment, in pixels. More...
 
void mir_surface_spec_set_height_increment (MirSurfaceSpec *spec, unsigned height_inc)
 Set the requested height increment, in pixels Defines an arithmetic progression of sizes starting with min_height (if set, otherwise 0) into which the surface prefers to be resized. More...
 
void mir_surface_spec_set_min_width (MirSurfaceSpec *spec, unsigned min_width)
 Set the minimum width, in pixels. More...
 
void mir_surface_spec_set_min_height (MirSurfaceSpec *spec, unsigned min_height)
 Set the minimum height, in pixels. More...
 
void mir_surface_spec_set_max_width (MirSurfaceSpec *spec, unsigned max_width)
 Set the maximum width, in pixels. More...
 
void mir_surface_spec_set_max_height (MirSurfaceSpec *spec, unsigned max_height)
 Set the maximum height, in pixels. More...
 
void mir_surface_spec_set_min_aspect_ratio (MirSurfaceSpec *spec, unsigned width, unsigned height)
 Set the minimum aspect ratio. More...
 
void mir_surface_spec_set_max_aspect_ratio (MirSurfaceSpec *spec, unsigned width, unsigned height)
 Set the maximum aspect ratio. More...
 
void mir_surface_spec_set_pixel_format (MirSurfaceSpec *spec, MirPixelFormat format)
 Set the requested pixel format. More...
 
void mir_surface_spec_set_buffer_usage (MirSurfaceSpec *spec, MirBufferUsage usage)
 Set the requested buffer usage. More...
 
void mir_surface_spec_set_fullscreen_on_output (MirSurfaceSpec *spec, uint32_t output_id)
 
void mir_surface_spec_set_preferred_orientation (MirSurfaceSpec *spec, MirOrientationMode mode)
 Set the requested preferred orientation mode. More...
 
bool mir_surface_spec_attach_to_foreign_parent (MirSurfaceSpec *spec, MirPersistentId *parent, MirRectangle *attachment_rect, MirEdgeAttachment edge)
 Request that the created surface be attached to a surface of a different client. More...
 
void mir_surface_spec_set_state (MirSurfaceSpec *spec, MirSurfaceState state)
 Set the requested state. More...
 
void mir_surface_spec_release (MirSurfaceSpec *spec)
 Release the resources held by a MirSurfaceSpec. More...
 
void mir_surface_spec_set_streams (MirSurfaceSpec *spec, MirBufferStreamInfo *streams, unsigned int num_streams)
 Set the streams associated with the spec. More...
 
void mir_surface_spec_set_input_shape (MirSurfaceSpec *spec, MirRectangle const *rectangles, size_t n_rects)
 Set a collection of input rectangles assosciated with the spec. More...
 
void mir_surface_spec_set_event_handler (MirSurfaceSpec *spec, mir_surface_event_callback callback, void *context)
 Set the event handler to be called when events arrive for a surface. More...
 
void mir_surface_spec_set_shell_chrome (MirSurfaceSpec *spec, MirShellChrome style)
 Ask the shell to customize "chrome" for this surface. More...
 
void mir_surface_set_event_handler (MirSurface *surface, mir_surface_event_callback callback, void *context)
 Set the event handler to be called when events arrive for a surface. More...
 
MirBufferStreammir_surface_get_buffer_stream (MirSurface *surface)
 Retrieve the primary MirBufferStream associated with a surface (to advance buffers, obtain EGLNativeWindow, etc...) More...
 
bool 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...
 
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...
 
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...
 
MirSurfaceFocusState mir_surface_get_focus (MirSurface *surface)
 Query the focus state for a surface. More...
 
MirSurfaceVisibility mir_surface_get_visibility (MirSurface *surface)
 Query the visibility state for a surface. 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...
 
MirWaitHandlemir_surface_set_preferred_orientation (MirSurface *surface, MirOrientationMode orientation)
 Request to set the preferred orientations of a surface. More...
 
MirOrientationMode mir_surface_get_preferred_orientation (MirSurface *surface)
 Get the preferred orientation modes of a surface. More...
 
MirSurfaceSpecmir_connection_create_spec_for_input_method (MirConnection *connection, int width, int height, MirPixelFormat format)
 Create a surface specification for an input method surface. More...
 
void mir_surface_apply_spec (MirSurface *surface, MirSurfaceSpec *spec)
 Request changes to the specification of a surface. More...
 
MirWaitHandlemir_surface_request_persistent_id (MirSurface *surface, mir_surface_id_callback callback, void *context)
 Request an ID for the surface that can be shared cross-process and across restarts. More...
 
MirPersistentIdmir_surface_request_persistent_id_sync (MirSurface *surface)
 Request a persistent ID for a surface and wait for the result. More...
 
bool mir_persistent_id_is_valid (MirPersistentId *id)
 Check the validity of a MirPersistentId. More...
 
void mir_persistent_id_release (MirPersistentId *id)
 Free a MirPersistentId. More...
 
char const * mir_persistent_id_as_string (MirPersistentId *id)
 Get a string representation of a MirSurfaceId. More...
 
MirPersistentIdmir_persistent_id_from_string (char const *string_representation)
 Deserialise a string representation of a MirSurfaceId. More...
 
void mir_surface_raise (MirSurface *surface, MirCookie const *cookie)
 Attempts to raise the surface to the front. 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

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...
 
char const *const mir_arrow_cursor_name
 The standard arrow cursor (typically the system default) More...
 
char const *const mir_busy_cursor_name
 The "wait" cursor, typically an hourglass or watch used during operations which prevent the user from interacting. More...
 
char const *const mir_caret_cursor_name
 The caret or ibeam cursor, indicating acceptance of text input. More...
 
char const *const mir_pointing_hand_cursor_name
 The pointing hand cursor, typically used for clickable elements such as hyperlinks. More...
 
char const *const mir_open_hand_cursor_name
 The open handed cursor, typically used to indicate that the area beneath the cursor may be clicked and dragged around. More...
 
char const *const mir_closed_hand_cursor_name
 The close handed cursor, typically used to indicate that a drag operation is in process which involves scrolling. More...
 
char const *const mir_horizontal_resize_cursor_name
 The cursor used to indicate a horizontal resize operation. More...
 
char const *const mir_vertical_resize_cursor_name
 The cursor used to indicate a vertical resize operation. More...
 
char const *const mir_diagonal_resize_bottom_to_top_cursor_name
 The cursor used to indicate diagonal resize from top-right and bottom-left corners. More...
 
char const *const mir_diagonal_resize_top_to_bottom_cursor_name
 The cursor used to indicate diagonal resize from bottom-left and top-right corners. More...
 
char const *const mir_omnidirectional_resize_cursor_name
 The cursor used to indicate resize with no directional constraint. More...
 
char const *const mir_vsplit_resize_cursor_name
 The cursor used for vertical splitters, indicating that a handle may be dragged to adjust vertical space. More...
 
char const *const mir_hsplit_resize_cursor_name
 The cursor used for horizontal splitters, indicating that a handle may be dragged to adjust horizontal space. More...
 
char const *const mir_crosshair_cursor_name
 The cursor used for crosshair, which may be used for picking colors or finer precision. More...
 

Fenced Buffer content access functions.

These functions will wait until it is safe to access the buffer for the given purpose.

If used with mir_none, the buffer will be given the buffer immediately, and without synchronization. It is then up to the user to ensure that the buffer contents are not accessed at inapproprate times.

Note
the following functions (mir_buffer_get_native_buffer, mir_buffer_get_graphics_region) can only be used when the buffer is not submitted to the server.
MirNativeBuffermir_buffer_get_native_buffer (MirBuffer *, MirBufferAccess access)
 Access the native buffer associated with MirBuffer for a given purpose. More...
 
MirGraphicsRegion mir_buffer_get_graphics_region (MirBuffer *buffer, MirBufferAccess access)
 Access a CPU-mapped region associated with a given buffer for the given purpose. More...
 
MirNativeFencemir_buffer_get_fence (MirBuffer *)
 Retrieve the native fence associated with this buffer. More...
 
void mir_buffer_associate_fence (MirBuffer *buffer, MirNativeFence *native_fence, MirBufferAccess access)
 Protect the buffer's contents by associating a native fence with it. More...
 
int mir_buffer_wait_for_access (MirBuffer *buffer, MirBufferAccess access, int timeout)
 Wait for the fence associated with the buffer to signal. More...
 
unsigned int mir_buffer_get_width (MirBuffer *buffer)
 Retrieve the width of the buffer in pixels. More...
 
unsigned int mir_buffer_get_height (MirBuffer *buffer)
 Retrieve the height of the buffer in pixels. More...
 
MirPixelFormat mir_buffer_get_pixel_format (MirBuffer *buffer)
 Retrieve the pixel format of the buffer. More...
 
MirBufferUsage mir_buffer_get_buffer_usage (MirBuffer *buffer)
 Retrieve the buffer usage of the buffer. More...
 

Detailed Description

Macro Definition Documentation

#define MIR_BYTES_PER_PIXEL (   f)
Value:
((f) == mir_pixel_format_bgr_888 ? 3 : \
(f) == mir_pixel_format_rgb_888 ? 3 : \
(f) == mir_pixel_format_rgb_565 ? 2 : \
4)
Definition: common.h:142
Definition: common.h:145
Definition: common.h:141
Definition: common.h:144
Definition: common.h:143
#define MIR_CLIENT_MAJOR_VERSION   (3)

MIR_CLIENT_MAJOR_VERSION.

The major client API version. This will increase once per API incompatible release.

See also: http://semver.org/

#define MIR_CLIENT_MICRO_VERSION   (0)

MIR_CLIENT_MICRO_VERSION.

The micro client API version. This will increment each release. This is usually uninteresting for client code, but may be of use in selecting whether to use a feature that has previously been buggy.

This corresponds to the PATCH field of http://semver.org/

#define MIR_CLIENT_MINOR_VERSION   (3)

MIR_CLIENT_MINOR_VERSION.

The minor client API version. This will increase each time new backwards-compatible API is added, and will reset to 0 each time MIR_CLIENT_MAJOR_VERSION is incremented.

See also: http://semver.org/

#define MIR_CLIENT_VERSION
Value:
#define MIR_CLIENT_MINOR_VERSION
MIR_CLIENT_MINOR_VERSION.
Definition: version.h:46
#define MIR_CLIENT_MICRO_VERSION
MIR_CLIENT_MICRO_VERSION.
Definition: version.h:57
#define MIR_VERSION_NUMBER(major, minor, micro)
MIR_VERSION_NUMBER.
Definition: mir_version_number.h:34
#define MIR_CLIENT_MAJOR_VERSION
MIR_CLIENT_MAJOR_VERSION.
Definition: version.h:36

MIR_CLIENT_VERSION.

The current version of the Mir client headers in use.

#define MIR_INPUT_EVENT_MAX_POINTER_COUNT   16

Typedef Documentation

typedef void(* mir_buffer_callback) (MirPresentationChain *, MirBuffer *, void *context)
typedef void(* mir_buffer_stream_callback) (MirBufferStream *stream, void *client_context)

Callback to be passed when calling:

  • mir_buffer_stream_* functions requiring a callback.
    Parameters
    [in]streamthe buffer stream being updated
    [in,out]client_contextcontext provided by client in calling mir_connect
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_input_config_callback) (MirConnection *connection, void *context)

Callback called when a change of input devices has occurred.

Parameters
[in]connectionThe connection associated with the input device change
[in,out]contextThe context provided by client
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_ping_event_callback) (MirConnection *connection, int32_t serial, void *context)

Callback called when the server pings for responsiveness testing.

Parameters
[in]connectionThe connection associated with this ping
[in]serialIdentifier of this ping, to be passed to mir_connection_pong()
[in,out]contextThe context provided by the client
typedef void(* mir_platform_operation_callback) (MirConnection *connection, MirPlatformMessage *reply, void *context)

Callback called when a platform operation completes.

Warning
The reply is owned by the callee, who should release it when it's not needed any more.
Parameters
[in]connectionThe connection associated with the platform operation
[in]replyThe platform operation reply
[in,out]contextThe context provided by the client
typedef void(* mir_presentation_chain_callback) (MirPresentationChain *, void *context)
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 void(* mir_surface_event_callback) (MirSurface *surface, MirEvent const *event, void *context)

Callback for handling of surface events.

Parameters
[in]surfaceThe surface on which an event has occurred
[in]eventThe event to be handled
[in,out]contextThe context provided by client
typedef void(* mir_surface_id_callback) (MirSurface *surface, MirPersistentId *id, void *context)
typedef struct MirBlob MirBlob
typedef struct MirBuffer MirBuffer

The displacement from the top-left corner of the surface.

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
typedef struct MirCookie MirCookie

MirDisplayConfiguration provides details of the graphics environment.

typedef void* MirEGLNativeDisplayType
typedef void* MirEGLNativeWindowType
typedef union MirEvent MirEvent

Form factor associated with a physical output.

Retrieved information about a MirSurface.

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

typedef unsigned int MirInputDeviceCapabilities
typedef int64_t MirInputDeviceId
typedef struct MirInputEvent MirInputEvent
typedef unsigned int MirInputEventModifiers

An event type describing a change in keyboard state.

Apology #1: Keyboard events almost always come from a keyboard, except they can also come from system buttons (power, volume, home). This is an issue we've inherited from the Linux kernel and Android, but could be solved in future by giving such system switch events their own input group such as MirSwitchEvent.

Retrieved information about a loadable module.

This allows clients to identify the underlying platform. E.g. whether the graphics are "mir:android" or "mir:mesa". Third party graphics platforms do not currently exist but should be named according to the vendor and platform. Vis: "<vendor>:<platform>"

typedef void* MirNativeFence

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

typedef struct MirOutput MirOutput

Descriptor for an output connection.

Each MirOutput corresponds to a video output. This may be a physical connection on the system, like HDMI or DisplayPort, or may be a virtual output such as a remote display or screencast display.

typedef struct MirOutputMode MirOutputMode

A descriptor for a display mode.

A display mode contains all the information necessary to drive a display. It includes resolution and refresh rate, but also pixel clock, vsync and hsync timings, and so on.

32-bit pixel formats (8888): The order of components in the 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 should be coded as 0xAABBGGRR, which will end up as R,G,B,A in memory on a little endian system, and as A,B,G,R on a big endian system.

24-bit pixel formats (888): These are in literal byte order, regardless of CPU architecture it's always the same. Writing these 3-byte pixels is typically slower than other formats but uses less memory than 32-bit and is endian-independent.

16-bit pixel formats (565/5551/4444): Always interpreted as one 16-bit integer per pixel with components in high-to-low bit order following the format name. These are the fastest formats, however colour quality is visibly lower.

typedef struct MirPlatformMessage MirPlatformMessage

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

Deprecated:
Use of this type is inherently non-portable in the presence of plug-in platform modules as these need not correspond to the available types.
Todo:
This should be removed from the public API at the next API break.

MirPointerAcceleration describes the way pointer movement is filtered:

  • mir_pointer_acceleration_none: (acceleration bias + 1.0) is applied as a factor to the current velocity of the pointer. So a bias of 0 to results to no change of velocity.
  • mir_pointer_acceleration_adaptive: acceleration bias selects an acceleration function based on the current velocity that usually consists of two linear inclines separated by a plateau.
typedef unsigned int MirPointerButtons

An event type describing a change in pointer device state.

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.

Shell chrome.

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 MirTouchEvent MirTouchEvent

An event type describing a change in touch device state.

typedef int32_t MirTouchId

An identifier for a touch-point.

TouchId's are unique per-gesture. That is to say, once a touch has gone down at time T, no other touch will use that touch's ID until all touches at time T have come up.

typedef unsigned int MirTouchpadClickModes
typedef unsigned int MirTouchpadScrollModes
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.

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 
Enumerator
mir_none 
mir_read 
mir_read_write 

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_edge_attachment_vertical 
mir_edge_attachment_horizontal 
mir_edge_attachment_any 
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 
mir_event_type_close_surface 
mir_event_type_input 
mir_event_type_keymap 
mir_event_type_input_configuration 
mir_event_type_surface_output 

Form factor associated with a physical output.

Enumerator
mir_form_factor_unknown 
mir_form_factor_phone 
mir_form_factor_tablet 
mir_form_factor_monitor 
mir_form_factor_tv 
mir_form_factor_projector 

MirInputConfigurationEvent indicates a configuration change in the input device subsystem. Eventually it's usage will be required to properly interpret MirInputEvent, for example: If we receive a button down, and then a device reset, we should not expect to receive the button up.

Another example, the maximum/minimum axis values for a device may have been reconfigured and need to be required.

Of course as things stand there is no client input-device introspection API so these events are difficult to use.

Enumerator
mir_input_configuration_action_configuration_changed 
mir_input_configuration_action_device_reset 
Enumerator
mir_input_device_capability_none 
mir_input_device_capability_pointer 
mir_input_device_capability_keyboard 
mir_input_device_capability_touchpad 
mir_input_device_capability_touchscreen 
mir_input_device_capability_gamepad 
mir_input_device_capability_joystick 
mir_input_device_capability_switch 
mir_input_device_capability_multitouch 
mir_input_device_capability_alpha_numeric 

capable to detect multiple contacts

Description of key modifier state.

Enumerator
mir_input_event_modifier_none 
mir_input_event_modifier_alt 
mir_input_event_modifier_alt_left 
mir_input_event_modifier_alt_right 
mir_input_event_modifier_shift 
mir_input_event_modifier_shift_left 
mir_input_event_modifier_shift_right 
mir_input_event_modifier_sym 
mir_input_event_modifier_function 
mir_input_event_modifier_ctrl 
mir_input_event_modifier_ctrl_left 
mir_input_event_modifier_ctrl_right 
mir_input_event_modifier_meta 
mir_input_event_modifier_meta_left 
mir_input_event_modifier_meta_right 
mir_input_event_modifier_caps_lock 
mir_input_event_modifier_num_lock 
mir_input_event_modifier_scroll_lock 
Enumerator
mir_input_event_type_key 
mir_input_event_type_touch 
mir_input_event_type_pointer 

Possible actions for changing key state.

Enumerator
mir_keyboard_action_up 
mir_keyboard_action_down 
mir_keyboard_action_repeat 
Enumerator
mir_lifecycle_state_will_suspend 
mir_lifecycle_state_resumed 
mir_lifecycle_connection_lost 
Enumerator
auth_magic 
auth_fd 
set_gbm_device 

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

Enumerator
mir_orientation_normal 
mir_orientation_left 
mir_orientation_inverted 
mir_orientation_right 
Enumerator
mir_orientation_mode_portrait 
mir_orientation_mode_landscape 
mir_orientation_mode_portrait_inverted 
mir_orientation_mode_landscape_inverted 
mir_orientation_mode_portrait_any 
mir_orientation_mode_landscape_any 
mir_orientation_mode_any 
Enumerator
mir_output_connection_state_disconnected 
mir_output_connection_state_connected 
mir_output_connection_state_unknown 
Enumerator
mir_output_type_unknown 
mir_output_type_vga 
mir_output_type_dvii 
mir_output_type_dvid 
mir_output_type_dvia 
mir_output_type_composite 
mir_output_type_svideo 
mir_output_type_lvds 
mir_output_type_component 
mir_output_type_ninepindin 
mir_output_type_displayport 
mir_output_type_hdmia 
mir_output_type_hdmib 
mir_output_type_tv 
mir_output_type_edp 

32-bit pixel formats (8888): The order of components in the 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 should be coded as 0xAABBGGRR, which will end up as R,G,B,A in memory on a little endian system, and as A,B,G,R on a big endian system.

24-bit pixel formats (888): These are in literal byte order, regardless of CPU architecture it's always the same. Writing these 3-byte pixels is typically slower than other formats but uses less memory than 32-bit and is endian-independent.

16-bit pixel formats (565/5551/4444): Always interpreted as one 16-bit integer per pixel with components in high-to-low bit order following the format name. These are the fastest formats, however colour quality is visibly lower.

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_format_rgb_888 
mir_pixel_format_rgb_565 
mir_pixel_format_rgba_5551 
mir_pixel_format_rgba_4444 
mir_pixel_formats 

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

Deprecated:
Use of this type is inherently non-portable in the presence of plug-in platform modules as these need not correspond to the available types.
Todo:
This should be removed from the public API at the next API break.
Enumerator
mir_platform_type_gbm 
mir_platform_type_android 

MirPointerAcceleration describes the way pointer movement is filtered:

  • mir_pointer_acceleration_none: (acceleration bias + 1.0) is applied as a factor to the current velocity of the pointer. So a bias of 0 to results to no change of velocity.
  • mir_pointer_acceleration_adaptive: acceleration bias selects an acceleration function based on the current velocity that usually consists of two linear inclines separated by a plateau.
Enumerator
mir_pointer_acceleration_none 
mir_pointer_acceleration_adaptive 

Possible pointer actions.

Enumerator
mir_pointer_action_button_up 
mir_pointer_action_button_down 
mir_pointer_action_enter 
mir_pointer_action_leave 
mir_pointer_action_motion 

Identifiers for pointer axis.

Enumerator
mir_pointer_axis_x 
mir_pointer_axis_y 
mir_pointer_axis_vscroll 
mir_pointer_axis_hscroll 
mir_pointer_axis_relative_x 
mir_pointer_axis_relative_y 
Enumerator
mir_pointer_button_primary 
mir_pointer_button_secondary 
mir_pointer_button_tertiary 
mir_pointer_button_back 
mir_pointer_button_forward 
mir_pointer_button_side 
mir_pointer_button_extra 
mir_pointer_button_task 
Enumerator
mir_pointer_handedness_right 
mir_pointer_handedness_left 
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 
mir_prompt_session_state_suspended 

Shell chrome.

Enumerator
mir_shell_chrome_normal 
mir_shell_chrome_low 

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_attrib_preferred_orientation 
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_state_horizmaximized 
mir_surface_state_hidden 
mir_surface_states 
Examples:
server_example_canonical_window_manager.cpp, and server_example_tiling_window_manager.cpp.
Enumerator
mir_surface_type_normal 

AKA "regular".

mir_surface_type_utility 

AKA "floating".

mir_surface_type_dialog 
mir_surface_type_overlay 
Deprecated:
Use "gloss" instead.
mir_surface_type_gloss 
mir_surface_type_freestyle 
mir_surface_type_popover 
Deprecated:
Choose "menu" or "tip"
mir_surface_type_menu 
mir_surface_type_inputmethod 

AKA "OSK" or handwriting etc.

mir_surface_type_satellite 

AKA "toolbox"/"toolbar".

mir_surface_type_tip 

AKA "tooltip".

mir_surface_types 
Enumerator
mir_surface_visibility_occluded 
mir_surface_visibility_exposed 

Possible per touch actions for state changing.

Enumerator
mir_touch_action_up 
mir_touch_action_down 
mir_touch_action_change 

Identifiers for touch axis.

Enumerator
mir_touch_axis_x 
mir_touch_axis_y 
mir_touch_axis_pressure 
mir_touch_axis_touch_major 
mir_touch_axis_touch_minor 
mir_touch_axis_size 
Enumerator
mir_touchpad_click_mode_none 
mir_touchpad_click_mode_area_to_click 
mir_touchpad_click_mode_finger_count 
Enumerator
mir_touchpad_scroll_mode_none 
mir_touchpad_scroll_mode_two_finger_scroll 
mir_touchpad_scroll_mode_edge_scroll 
mir_touchpad_scroll_mode_button_down_scroll 

Identifiers for per-touch tool types.

Enumerator
mir_touch_tooltype_unknown 
mir_touch_tooltype_finger 
mir_touch_tooltype_stylus 

Function Documentation

__attribute__ ( (deprecated)  ) const

Retrieve the MirCloseSurfaceEvent associated with a MirEvent of type mir_event_type_close_surface.

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

The event is a request to close the surface it is delivered to and has no accessors.

Deprecated:
Use of this function is pointless as there is no way to use the return value.
Todo:
This should be removed from the public API at the next API break.
Parameters
[in]eventThe event
Returns
The associated MirCloseSurfaceEvent
Deprecated:
Use of this function is inherently non-portable in the presence of plug-in platform modules as these need not correspond to the available types. To identify the graphics platform use mir_connection_get_graphics_module(). To safely interpret the buffer contents use mir_buffer_stream_get_graphics_region().
Todo:
This should be removed from the public API at the next API break.
Precondition
The surface is valid
Parameters
[in]surfaceThe surface
Returns
One of mir_platform_type_android or mir_platform_type_gbm
void const* mir_blob_data ( MirBlob blob)

Get the data of a blob.

Parameters
[in]blobThe blob
Returns
the data
MirBlob* mir_blob_from_display_configuration ( MirDisplayConfiguration configuration)

Create a blob from a display configuration.

Parameters
[in]configurationThe display configuration
Returns
A blob
MirBlob* mir_blob_onto_buffer ( void const *  buffer,
size_t  buffer_size 
)

Create a blob from a buffer.

Note
this does not copy the data, the buffer is assumed to be available until the blob is released.
Parameters
[in]bufferthe buffer
[in]buffer_sizethe buffer size
Returns
A blob
void mir_blob_release ( MirBlob blob)

Release a blob object.

Parameters
[in]blobThe blob
size_t mir_blob_size ( MirBlob blob)

Get the size of a blob.

Parameters
[in]blobThe blob
Returns
the size
MirDisplayConfiguration* mir_blob_to_display_configuration ( MirBlob blob)

Create a blob from a display configuration.

Warning
will abort() if the blob doesn't represent a meaningful display configuration
Parameters
[in]blobThe blob
Returns
A display configuration
void mir_buffer_associate_fence ( MirBuffer buffer,
MirNativeFence native_fence,
MirBufferAccess  access 
)

Protect the buffer's contents by associating a native fence with it.

Warning
any fence currently associated with buffer will be replaced in favor of native_fence without waiting for the replaced fence to clear
Parameters
[in]bufferThe buffer
[in]native_fenceThe fence that will be associated with buffer. If nullptr, this will remove the fence associated with this buffer.
[in]accessThe ongoing access that is represented by native_fence. If mir_none is set, this will remove the fence protecting the buffer content.
MirBufferUsage mir_buffer_get_buffer_usage ( MirBuffer buffer)

Retrieve the buffer usage of the buffer.

Parameters
[in]bufferThe buffer
Returns
The buffer usage of the buffer
MirNativeFence* mir_buffer_get_fence ( MirBuffer )

Retrieve the native fence associated with this buffer.

Parameters
[in]bufferThe buffer
Returns
The fence associated with buffer
MirGraphicsRegion mir_buffer_get_graphics_region ( MirBuffer buffer,
MirBufferAccess  access 
)

Access a CPU-mapped region associated with a given buffer for the given purpose.

This will synchronize the buffer for the given purpose.

Parameters
[in]bufferThe buffer
[in]typeThe type of fence to clear before returning.
Returns
region The graphics region associated with the buffer.
Warning
The returned region is only valid until the MirBuffer is submitted to the server. When the buffer is available again, this function must be called before accessing the region again.
If mir_none is designated as access, this function will not wait for the fence. The user must wait for the fence explicitly before using the contents of the buffer.
unsigned int mir_buffer_get_height ( MirBuffer buffer)

Retrieve the height of the buffer in pixels.

Parameters
[in]bufferThe buffer
Returns
The height of the buffer in pixels
MirNativeBuffer* mir_buffer_get_native_buffer ( MirBuffer ,
MirBufferAccess  access 
)

Access the native buffer associated with MirBuffer for a given purpose.

This will synchronize the buffer for the given purpose.

Parameters
[in]bufferThe buffer
[in]accessThe access that is needed for the native buffers content.
Returns
The platform-defined native buffer associated with buffer
Warning
The returned native buffer has the same lifetime as the MirBuffer. It must not be deleted or past the lifetime of the buffer.
If mir_none is designated as access, this function will not wait for the fence. The user must wait for the fence explicitly before using the contents of the buffer.
MirPixelFormat mir_buffer_get_pixel_format ( MirBuffer buffer)

Retrieve the pixel format of the buffer.

Parameters
[in]bufferThe buffer
Returns
The pixel format of the buffer
unsigned int mir_buffer_get_width ( MirBuffer buffer)

Retrieve the width of the buffer in pixels.

Parameters
[in]bufferThe buffer
Returns
The width of the buffer in pixels
void mir_buffer_release ( MirBuffer buffer)

release a MirBuffer

Parameters
[in]bufferThe buffer to be released
void mir_buffer_stream_get_current_buffer ( MirBufferStream buffer_stream,
MirNativeBuffer **  buffer_package 
)

Retrieve the current buffer in "raw" representation.

Precondition
The buffer stream is valid
Parameters
[in]surfaceThe buffer stream
[out]buffer_packageStructure to be populated
MirEGLNativeWindowType mir_buffer_stream_get_egl_native_window ( MirBufferStream buffer_stream)

Retrieve a window type which may be used by EGL.

Parameters
[in]buffer_streamThe buffer stream
Returns
An EGLNativeWindowType that the client can use
char const* mir_buffer_stream_get_error_message ( MirBufferStream surface)

Retrieve a text description of the error.

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

Parameters
[in]buffer_streamThe buffer stream
Returns
A text description of any error resulting in an invalid stream, or the empty string "" if the connection is valid.
void mir_buffer_stream_get_graphics_region ( MirBufferStream buffer_stream,
MirGraphicsRegion graphics_region 
)

Retrieve a buffer stream's graphics region.

Warning
Depending on platform, this can map the graphics buffer each time its called. The region remains mapped until mir_buffer_stream_swap_buffers().
Precondition
The buffer stream is valid
Parameters
[in]bufferstream The buffer stream
[out]graphics_regionStructure to be populated
bool mir_buffer_stream_is_valid ( MirBufferStream buffer_stream)

Test for a valid buffer stream.

Parameters
[in]buffer_streamThe buffer stream
Returns
True if the supplied buffer_stream is valid, or false otherwise.
MirWaitHandle* mir_buffer_stream_release ( MirBufferStream buffer_stream,
mir_buffer_stream_callback  callback,
void *  context 
)

Release the supplied stream 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]streamThe stream
[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_buffer_stream_release_sync ( MirBufferStream buffer_stream)

Release the specified buffer stream like in mir,_buffer_stream_release(), but also wait for the operation to complete.

Parameters
[in]bufferstream The buffer stream to be released
MirWaitHandle* mir_buffer_stream_set_scale ( MirBufferStream stream,
float  scale 
)

Set the scale associated with all buffers in the stream.

Parameters
[in]buffer_streamThe buffer stream
[in]scaleThe scale
Returns
A handle that can be passed to mir_wait_for
void mir_buffer_stream_set_scale_sync ( MirBufferStream stream,
float  scale 
)

Set the scale as in mir_buffer_stream_set_scale(), but also wait for the operation to complete.

Parameters
[in]buffer_streamThe buffer stream
[in]scaleThe scale
MirWaitHandle* mir_buffer_stream_swap_buffers ( MirBufferStream buffer_stream,
mir_buffer_stream_callback  callback,
void *  context 
)

Advance a buffer stream's buffer.

The returned handle remains valid until the next call to mir_buffer_stream_swap_buffers, until the buffer stream 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]buffer_streamThe buffer stream
[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_buffer_stream_swap_buffers_sync ( MirBufferStream buffer_stream)

Advance a buffer stream's buffer as in mir_buffer stream_swap_buffers(), but also wait for the operation to complete.

Parameters
[in]bufferstream The buffer stream whose buffer to advance
int mir_buffer_wait_for_access ( MirBuffer buffer,
MirBufferAccess  access,
int  timeout 
)

Wait for the fence associated with the buffer to signal.

After returning, it is permissible to access the buffer's content for the designated purpose in access.

Parameters
[in]bufferThe buffer
[in]accessThe access to wait for.
[in]timeoutThe amount of time to wait for the fence in nanoseconds, or -1 for infinite timeout.
Returns
zero when fence was cleared successfully, or a negative number when the timeout was reached before the fence signals
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
MirWaitHandle* mir_connection_create_buffer_stream ( MirConnection connection,
int  width,
int  height,
MirPixelFormat  format,
MirBufferUsage  buffer_usage,
mir_buffer_stream_callback  callback,
void *  context 
)

Create a new buffer stream.

For example, the resulting buffer stream may be used with mir_cursor_configuration_from_buffer_stream, in order to post images to the system cursor.

Parameters
[in]connectionA valid connection
[in]widthRequested buffer width
[in]heightRequested buffer height
[in]buffer_usageRequested buffer usage, use mir_buffer_usage_software for cursor image streams
[in]callbackCallback to be invoked when the request completes The callback is guaranteed to be called and called with a non-null MirBufferStream*, but the stream may be invalid in case of an error.
[in]contextUserdata to pass to callback function
Returns
A handle that can be supplied to mir_wait_for
MirBufferStream* mir_connection_create_buffer_stream_sync ( MirConnection connection,
int  width,
int  height,
MirPixelFormat  format,
MirBufferUsage  buffer_usage 
)

Create a new buffer stream unattached to a surface and wait for the result.

The resulting buffer stream may be used with mir_cursor_configuration_from_buffer_stream in order to post images to the system cursor.

Parameters
[in]connectionA valid connection
[in]widthRequested buffer width
[in]heightRequested buffer height
[in]buffer_usageRequested buffer usage, use mir_buffer_usage_software for cursor image streams
Returns
The new buffer stream. This is guaranteed non-null, but may be invalid in the case of error.
MirDisplayConfiguration* mir_connection_create_display_config ( MirConnection connection)

Query the display.

Deprecated:
Use mir_connection_create_display_configuration() instead.
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
MirDisplayConfig* mir_connection_create_display_configuration ( MirConnection connection)

Query the display.

Precondition
mir_connection_is_valid(connection) == true
Warning
return value must be destroyed via mir_display_config_release()
Parameters
[in]connectionThe connection
Returns
structure that describes the display configuration
MirInputConfig* mir_connection_create_input_config ( MirConnection connection)

Create a snapshot of the attached input devices and device configurations.

Warning
return value must be destroyed via mir_input_config_destroy()
may return null if connection is invalid
Parameters
[in]connectionThe connection
Returns
structure that describes the input configuration
void mir_connection_create_presentation_chain ( MirConnection connection,
mir_presentation_chain_callback  callback,
void *  context 
)

Create a new presentation chain.

Parameters
[in]connectionA valid connection
[in]callbackCallback to be invoked when the request completes. The callback is guaranteed to be called and called with a non-null MirPresentationChain*, but the chain may be invalid in case of an error.
[in]presentation_chainUserdata to pass to callback function
MirPresentationChain* mir_connection_create_presentation_chain_sync ( MirConnection connection)

Create a new presentation chain and wait for the result.

Parameters
[in]connectionA valid connection
Returns
The new presentation chain. This is guaranteed to be non-null, but may be invalid in the case of error.
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
MirSurfaceSpec* mir_connection_create_spec_for_changes ( MirConnection connection)

Create a surface specification for updating a surface.

This can be applied to one or more target surfaces using mir_surface_apply_spec(...).

Parameters
[in]connectiona valid mir connection
MirSurfaceSpec* mir_connection_create_spec_for_dialog ( MirConnection connection,
int  width,
int  height,
MirPixelFormat  format 
)

Create a surface specification for a parentless dialog surface.

A parentless dialog surface is similar to a normal surface, but it cannot be fullscreen and typically won't have any maximize/close button decorations.

A parentless dialog is not allowed to have other dialog children. The server may decide to close the parent and show the child dialog only.

Parameters
[in]connectionConnection the surface will be created on
[in]widthRequested width. The server is not guaranteed to return a surface of this width.
[in]heightRequested height. The server is not guaranteed to return a surface of this height.
[in]formatPixel format for the surface.
MirSurfaceSpec* mir_connection_create_spec_for_input_method ( MirConnection connection,
int  width,
int  height,
MirPixelFormat  format 
)

Create a surface specification for an input method surface.

Currently this is only appropriate for the Unity On-Screen-Keyboard.

Parameters
[in]connectionConnection the surface will be created on
[in]widthRequested width. The server is not guaranteed to return a surface of this width.
[in]heightRequested height. The server is not guaranteed to return a surface of this height.
[in]formatPixel format for the surface.
Returns
A handle that can be passed to mir_surface_create() to complete construction.
MirSurfaceSpec* mir_connection_create_spec_for_menu ( MirConnection connection,
int  width,
int  height,
MirPixelFormat  format,
MirSurface parent,
MirRectangle rect,
MirEdgeAttachment  edge 
)

Create a surface specification for a menu surface.

Positioning of the surface is specified with respect to the parent surface via an adjacency rectangle. The server will attempt to choose an edge of the adjacency rectangle on which to place the surface taking in to account screen-edge proximity or similar constraints. In addition, the server can use the edge affinity hint to consider only horizontal or only vertical adjacency edges in the given rectangle.

Parameters
[in]connectionConnection the surface will be created on
[in]widthRequested width. The server is not guaranteed to return a surface of this width.
[in]heightRequested height. The server is not guaranteed to return a surface of this height.
[in]formatPixel format for the surface.
[in]parentA valid parent surface for this menu.
[in]rectThe adjacency rectangle. The server is not guaranteed to create a surface at the requested location.
[in]edgeThe preferred edge direction to attach to. Use mir_edge_attachment_any for no preference.
Returns
A handle that can be passed to mir_surface_create() to complete construction.
MirSurfaceSpec* mir_connection_create_spec_for_modal_dialog ( MirConnection connection,
int  width,
int  height,
MirPixelFormat  format,
MirSurface parent 
)

Create a surface specification for a modal dialog surface.

The dialog surface will have input focus; the parent can still be moved, resized or hidden/minimized but no interaction is possible until the dialog is dismissed.

A dialog will typically have no close/maximize button decorations.

During surface creation, if the specified parent is another dialog surface the server may choose to close the specified parent in order to show this new dialog surface.

Parameters
[in]connectionConnection the surface will be created on
[in]widthRequested width. The server is not guaranteed to return a surface of this width.
[in]heightRequested height. The server is not guaranteed to return a surface of this height.
[in]formatPixel format for the surface.
[in]parentA valid parent surface.
MirSurfaceSpec* mir_connection_create_spec_for_normal_surface ( MirConnection connection,
int  width,
int  height,
MirPixelFormat  format 
)

Create a surface specification for a normal surface.

A normal surface is suitable for most application windows. It has no special semantics. On a desktop shell it will typically have a title-bar, be movable, resizeable, etc.

Parameters
[in]connectionConnection the surface will be created on
[in]widthRequested width. The server is not guaranteed to return a surface of this width.
[in]heightRequested height. The server is not guaranteed to return a surface of this height.
[in]formatPixel format for the surface.
Returns
A handle that can be passed to mir_surface_create() to complete construction.
MirSurfaceSpec* mir_connection_create_spec_for_tooltip ( MirConnection connection,
int  width,
int  height,
MirPixelFormat  format,
MirSurface parent,
MirRectangle zone 
)

Create a surface specification for a tooltip surface.

A tooltip surface becomes visible when the pointer hovers the specified target zone. A tooltip surface has no input focus and will be closed when the pointer moves out of the target zone or the parent closes, moves or hides

The tooltip parent cannot be another tooltip surface.

The tooltip position is decided by the server but typically it will appear near the pointer.

Parameters
[in]connectionConnection the surface will be created on
[in]widthRequested width. The server is not guaranteed to return a surface of this width.
[in]heightRequested height. The server is not guaranteed to return a surface of this height.
[in]formatPixel format for the surface.
[in]parentA valid parent surface for this tooltip.
[in]rectA target zone relative to parent.
Returns
A handle that can be passed to mir_surface_create() to complete construction.
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
Note
Users of EGL should call mir_connection_get_egl_pixel_format instead, as it will take the guesswork out of choosing between similar pixel formats. At the moment, this function returns a compatible list of formats likely to work for either software or hardware rendering. However it is not the full or accurate list and will be replaced in future by a function that takes the intended MirBufferUsage into account.
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
MirPixelFormat mir_connection_get_egl_pixel_format ( MirConnection connection,
void *  egldisplay,
void *  eglconfig 
)

Get the exact MirPixelFormat to use in creating a surface for a chosen EGLConfig.

Parameters
[in]connectionThe connection
[in]egldisplayThe EGLDisplay for the given config
[in]eglconfigThe EGLConfig you have chosen to use
Returns
The MirPixelFormat to use in surface creation
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_graphics_module ( MirConnection connection,
MirModuleProperties properties 
)

Query graphics platform module.

Note
The char pointers in MirModuleProperties are owned by the connection and should not be freed. They remain valid until the connection is released.
Parameters
[in]connectionThe connection
[out]propertiesStructure to be populated
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
bool 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.
MirWaitHandle* mir_connection_platform_operation ( MirConnection connection,
MirPlatformMessage const *  request,
mir_platform_operation_callback  callback,
void *  context 
)

Perform a platform specific operation.

The MirPlatformMessage used for the request needs to remain valid until this operation finishes.

Parameters
[in]connectionThe connection
[in]requestThe message used for this operation
[in]callbackThe callback to call when the operation finishes
[in,out]contextUser data passed to the callback function
Returns
A handle that can be passed to mir_wait_for
void mir_connection_pong ( MirConnection connection,
int32_t  serial 
)

Respond to a ping event.

Parameters
[in]connectionThe connection
[in]serialSerial from the ping event
void mir_connection_release ( MirConnection connection)

Release a connection to the Mir server.

Parameters
[in]connectionThe connection
MirWaitHandle* mir_connection_set_base_display_config ( MirConnection connection,
MirDisplayConfiguration const *  display_configuration 
)

Set the base display configuration.

The base display configuration is the configuration the server applies when there is no active per-connection configuration.

When the wait handle returned by this function becomes ready, clients can use mir_connection_get_error_message() to check if an authorization error occurred. Only authorization errors are guaranteed to return an error message for this operation.

A successful result (i.e. no error) does not guarantee that the base display configuration has been changed to the desired value. Clients should register a callback with mir_connection_set_display_config_change_callback() to monitor actual base display configuration changes.

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 set as base
Returns
A handle that can be passed to mir_wait_for
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_configuration 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_input_config_change_callback ( MirConnection connection,
mir_input_config_callback  callback,
void *  context 
)

Register a callback to be called when the input devices change.

Once a change has occurred, you can use mir_connection_create_input_config to get an updated snapshot of the input device configuration.

Parameters
[in]connectionThe connection
[in]callbackThe function to be called when a 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_connection_set_ping_event_callback ( MirConnection connection,
mir_ping_event_callback  callback,
void *  context 
)

Register a callback for server ping events.

The server may send ping requests to detect unresponsive applications. Clients should process this with their regular event handling, and call mir_connection_pong() in response.

The shell may treat a client which fails to pong in a timely fashion differently; a common response is to overlay the surface with an unresponsive application message.

A default implementation that immediately calls pong is provided; toolkits SHOULD override this default implementation to more accurately reflect the state of their event processing loop.

Parameters
[in]connectionThe connection
[in]callbackThe function to be called on ping events.
[in]contextUser data passed to the callback function
size_t mir_cookie_buffer_size ( MirCookie const *  cookie)

Queries the size needed to serialize a given cookie.

[in] cookie A cookie instance

Returns
The size of the serialized representation of the given cookie
MirCookie const* mir_cookie_from_buffer ( void const *  buffer,
size_t  size 
)

Create a cookie from a serialized representation.

[in] buffer The buffer containing a serialized cookie. The buffer may be freed immediately after this call.

Returns
A MirCookie instance. The instance must be released with a call to mir_cookie_release. NULL will be returned if the buffer and size don't describe the contents of a MirCookie.
void mir_cookie_release ( MirCookie const *  cookie)

Release the MirCookie.

[in] cookie The cookie to release

void mir_cookie_to_buffer ( MirCookie const *  cookie,
void *  buffer,
size_t  size 
)

Serializes a cookie into the given buffer.

Precondition
The size must be equal to mir_cookie_size [in] cookie A cookie instance [in] buffer A buffer which is filled with the serialized representation of the given cookie [in] size The size of the given buffer
MirSurfaceSpec* mir_create_surface_spec ( MirConnection connection)

Create a surface specification.

This can be used with mir_surface_create() to create a surface or with mir_surface_apply_spec() to change an existing surface.

Remarks
For use with mir_surface_create() at least the type, width, height, format and buffer_usage must be set. (And for types requiring a parent that too must be set.)
Parameters
[in]connectiona valid mir connection
Returns
A handle that can ultimately be passed to mir_surface_create() or mir_surface_apply_spec()
void mir_cursor_configuration_destroy ( MirCursorConfiguration parameters)

Release resources assosciated with cursor parameters.

Parameters
[in]parametersThe operand
MirCursorConfiguration* mir_cursor_configuration_from_buffer_stream ( MirBufferStream const *  stream,
int  hotspot_x,
int  hotspot_y 
)

Returns a new cursor configuration tied to a given buffer stream.

If the configuration is successfully applied buffers from the stream will be used to fill the system cursor.

Parameters
[in]nameThe buffer stream
[in]hotspot_xThe x-coordinate to use as the cursor's hotspot.
[in]hotspot_yThe y-coordinate to use as the cursor's hotspot.
Returns
A cursor parameters object which must be passed to_mir_cursor_configuration_destroy
MirCursorConfiguration* mir_cursor_configuration_from_name ( char const *  name)

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

Symbolic cursor names, such as mir_default_cursor_name and mir_caret_cursor_name are available see (mir_toolkit/cursors.h). 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
int mir_display_config_get_max_simultaneous_outputs ( MirDisplayConfig const *  config)

Get the maximum possible number of simultaneously active outputs this system supports.

Note
There may be restrictions on the configuration required to achieve this many active outputs. Typically the achievable number of simultaneously active outputs is lower than this number.
Parameters
[in]configThe configuration to query
Returns
The maximum number of simultaneously active outputs supportable at this time.
int mir_display_config_get_num_outputs ( MirDisplayConfig const *  config)

Get the number of outputs available in this display configuration.

This returns the total number of outputs the system has. This includes both enabled and disabled output connections, and is typically larger than the value returned from mir_display_config_get_max_simultaneous_outputs().

Typically this will be constant over the lifetime of a client as devices usually do not gain extra physical ports at runtime. However, hotpluggable display devices exist and the number of virtual outputs may change at runtime, so this should always be called to determine the number of outputs to iterate over.

Parameters
[in]configThe configuration to query
Returns
The number of outputs available in this configuration.
MirOutput const* mir_display_config_get_output ( MirDisplayConfig const *  config,
size_t  index 
)

Get a read-only handle to the index 'th output of this configuration.

Note
The MirOutput handle is only valid while config is valid.
Precondition
0 <= index < mir_display_config_get_num_outputs(config)
Parameters
[in]configThe configuration to query
[in]indexThe index of the output to get
Returns
A read-only handle to a MirOutput within config which is valid until mir_display_config_release(config) is called.
void mir_display_config_release ( MirDisplayConfig config)

Release resources associated with a MirDisplayConfig handle.

Parameters
[in]configThe handle to release
MirInputConfigurationEvent const* mir_event_get_input_configuration_event ( MirEvent const *  ev)

Retrieve the MirInputConfiguration associated with a MirEvent of type mir_event_type_input_configuration.

The event signifies that the input device configuration has changed.

Parameters
[in]eventThe event
Returns
The associated MirInputConfigurationEvent
MirInputEvent const* mir_event_get_input_event ( MirEvent const *  ev)

Retrieve the MirInputEvent associated with a MirEvent of type mir_event_type_input.

See <mir_toolkit/events/input/input_event.h> for accessors.

Parameters
[in]eventThe event
Returns
The associated MirInputEvent
MirKeymapEvent const* mir_event_get_keymap_event ( MirEvent const *  ev)

Retrieve the MirKeymapEvent associated with a MirEvent of type mir_event_type_keymap.

The event signifies that the keymap applied for the relevant surface has changed.

Parameters
[in]eventThe event
Returns
The associated MirKeymapEvent
MirOrientationEvent const* mir_event_get_orientation_event ( MirEvent const *  ev)

Retrieve the MirOrientationEvent associated with a MirEvent of type mir_event_type_orientation.

See <mir_toolkit/events/orientation_event.h> for accessors.

Parameters
[in]eventThe event
Returns
The associated MirOrientationEvent
MirPromptSessionEvent const* mir_event_get_prompt_session_event ( MirEvent const *  ev)

Retrieve the MirPromptSessionEvent associated with a MirEvent of type mir_event_type_prompt_session_state_change.

See <mir_toolkits/events/prompt_session_event.h> for accessors.

Parameters
[in]eventThe event
Returns
The associated MirPromptSessionEvent
MirResizeEvent const* mir_event_get_resize_event ( MirEvent const *  ev)

Retrieve the MirResizeEvent associated with a MirEvent of type mir_event_type_resize.

See <mir_toolkits/events/resize_event.h> for accessors.

Parameters
[in]eventThe event
Returns
The associated MirResizeEvent
MirSurfaceEvent const* mir_event_get_surface_event ( MirEvent const *  ev)

Retrieve the MirSurfaceEvent associated with a MirEvent of type mir_event_type_surface.

See <mir_toolkit/events/surface_event.h> for accessors.

Parameters
[in]eventThe event
Returns
The associated MirSurfaceEvent
MirSurfaceOutputEvent const* mir_event_get_surface_output_event ( MirEvent const *  ev)

Retrieve the MirSurfaceOutputEvent associated with a MirEvent of type mir_event_type_surface_output.

The event signifies that the properties of the output the surface is displayed upon have changed.

A MirSurfaceOutputEvent is generated either when the properties of the output the surface is primarily on change (for example: by user configuration of resolution) or when the output the surface is primarily on changes (for example: when a user moves the surface from one monitor to another).

Parameters
[in]eventThe event
Returns
The associated MirSurfaceOutputEvent
MirEventType mir_event_get_type ( MirEvent const *  ev)

Retrieves the type of a MirEvent.

Now preferred over direct access to ev->type. In particular ev->type will never be mir_event_type_input and mir_event_get_type is the only way to ensure mir_event_get_input_event will succeed.

Parameters
[in]eventThe event
Returns
The event type
MirEvent const* mir_event_ref ( MirEvent const *  ev)

Reference this MirEvent and return a pointer to the newly referenced instance.

Parameters
[in]Theevent to reference
Returns
The event pointer to now use
void mir_event_unref ( MirEvent const *  ev)

Release a reference to a MirEvent.

Parameters
[in]Theevent to un-reference
void mir_input_config_destroy ( MirInputConfig const *  config)

Release this snapshot of the input configuration.

This invalidates any pointers retrieved from this structure.

Parameters
[in]devicesThe input configuration
size_t mir_input_config_device_count ( MirInputConfig const *  config)

Retrieve the number of available input devices.

Parameters
[in]configThe input configuration snapshot
Returns
Number of input devices
MirInputDevice const* mir_input_config_get_device ( MirInputConfig const *  config,
size_t  index 
)

Retrieve the input device at given index.

The pointer returned stays valid until mir_input_config_destroy is called with config.

Parameters
[in]configThe input configuration snapshot
[in]indexThe index of the input device to return.
Returns
input device
MirInputDevice const* mir_input_config_get_device_by_id ( MirInputConfig const *  config,
MirInputDeviceId  id 
)

Retrieve the input device by id.

The MirInputDevice returned stays valid until mir_input_config_destroy is called with config. If no device with the given id is found NULL will be returned.

Parameters
[in]configThe input configuration snapshot
[in]idThe input device id to search for
Returns
input device
MirInputDevice* mir_input_config_get_mutable_device ( MirInputConfig config,
size_t  index 
)

Retrieve the input device at given index.

The pointer returned stays valid until mir_input_config_destroy is called with config.

Parameters
[in]configThe input configuration snapshot
[in]indexThe index of the input device to return.
Returns
input device
MirInputDevice* mir_input_config_get_mutable_device_by_id ( MirInputConfig config,
MirInputDeviceId  id 
)

Retrieve the input device by id.

The MirInputDevice returned stays valid until mir_input_config_destroy is called with config. If no device with the given id is found NULL will be returned.

Parameters
[in]configThe input configuration snapshot
[in]idThe input device id to search for
Returns
input device
MirInputConfigurationAction mir_input_configuration_event_get_action ( MirInputConfigurationEvent const *  ev)

Retrieve the input configuration action which occurred.

Parameters
[in]evThe input configuration event
Returns
The action
MirInputDeviceId mir_input_configuration_event_get_device_id ( MirInputConfigurationEvent const *  ev)

Retreive the device id associated with a MirInputConfiguration event.

Parameters
[in]evThe input configuration event
Returns
The device id or -1 if not applicable to events of this action
int64_t mir_input_configuration_event_get_time ( MirInputConfigurationEvent const *  ev)

Retreive the time associated with a MirInputConfiguration event.

Parameters
[in]evThe input configuration event
Returns
The time in nanoseconds since epoch
MirInputDeviceCapabilities mir_input_device_get_capabilities ( MirInputDevice const *  device)

Retrieve the capabilities of the input device at the given index.

Parameters
[in]deviceThe input device
Returns
The capability flags of the input device
MirInputDeviceId mir_input_device_get_id ( MirInputDevice const *  device)

Retrieve the device id of the input device.

The device id is a unique integer value, only valid while the device is attached. The device id matches the device id attached every input event.

Parameters
[in]deviceThe input device
Returns
The device id of the input device
char const* mir_input_device_get_name ( MirInputDevice const *  device)

Retrieve the name of the input device.

The string pointed to will be valid as long as MirInputDevice is valid. The name may be empty but never NULL.

Parameters
[in]deviceThe input device
Returns
The name of the input device
char const* mir_input_device_get_unique_id ( MirInputDevice const *  device)

Retrieve the unique id of the input device.

The string pointed to will be valid as long as device is valid. The value of the unique id of a given device should be valid across mir connections session and servers of the same version.

Parameters
[in]deviceThe input device
Returns
The unique id of the input device
MirCookie const* mir_input_event_get_cookie ( MirInputEvent const *  ev)

Returns the cookie associated with an input event.

Precondition
The input event must have a MirCookie [in] ev An input event
Returns
The cookie associated with the given input event The cookie must be released by calling mir_cookie_release
MirInputDeviceId mir_input_event_get_device_id ( MirInputEvent const *  ev)

Retrieves the device id responsible for generating an input event.

Parameters
[in]eventThe input event
Returns
The id of the generating device
int64_t mir_input_event_get_event_time ( MirInputEvent const *  ev)

Retrieve the time at which an input event occurred.

Parameters
[in]eventThe input event
Returns
A timestamp in nanoseconds-since-epoch
MirKeyboardEvent const* mir_input_event_get_keyboard_event ( MirInputEvent const *  ev)

Retrieve the MirKeyboardEvent associated with a given input event.

Parameters
[in]eventThe input event
Returns
The MirKeyboardEvent or NULL if event type is not mir_input_event_type_key
MirPointerEvent const* mir_input_event_get_pointer_event ( MirInputEvent const *  ev)

Retrieve the MirPointerEvent associated with a given input event.

Parameters
[in]eventThe input event
Returns
The MirPointerEvent or NULL if event type is not mir_input_event_type_pointer
MirTouchEvent const* mir_input_event_get_touch_event ( MirInputEvent const *  ev)

Retrieve the MirTouchEvent associated with a given input event.

Parameters
[in]eventThe input event
Returns
The MirTouchEvent or NULL if event type is not mir_input_event_type_touch
MirInputEventType mir_input_event_get_type ( MirInputEvent const *  ev)

Retrieve the type of an input event.

E.g. key, touch...

Parameters
[in]eventThe input event
Returns
The input event type
bool mir_input_event_has_cookie ( MirInputEvent const *  ev)

Query if an input event contains a cookie.

[in] ev The input event

Returns
True if the input event contains a cookie
MirKeyboardAction mir_keyboard_event_action ( MirKeyboardEvent const *  event)

Retrieve the action which triggered a given key event.

Parameters
[in]eventThe key event
Returns
The associated action
MirInputEvent const* mir_keyboard_event_input_event ( MirKeyboardEvent const *  event)

Retrieve the corresponding input event.

Parameters
[in]eventThe keyboard event
Returns
The input event
xkb_keysym_t mir_keyboard_event_key_code ( MirKeyboardEvent const *  event)

Retrieve the xkb mapped keycode associated with the key acted on.

. May be interpreted as per <xkbcommon/xkb-keysyms.h>

Parameters
[in]eventThe key event
Returns
The xkb_keysym
MirInputEventModifiers mir_keyboard_event_modifiers ( MirKeyboardEvent const *  event)

Retrieve the modifier keys pressed when the key action occured.

Parameters
[in]eventThe key event
Returns
The modifier mask
int mir_keyboard_event_scan_code ( MirKeyboardEvent const *  event)

Retrieve the raw hardware scan code associated with the key acted on.

May be interpreted as per <linux/input.h>

Parameters
[in]eventThe key event
Returns
The scancode
MirInputDeviceId mir_keymap_event_get_device_id ( MirKeymapEvent const *  ev)

Retrieve the device id the keymap reported by this MirKeymapEvent applies to.

Parameters
[in]evThe keymap event
[out]rulesXKB rules describing the new keymap.
void mir_keymap_event_get_keymap_buffer ( MirKeymapEvent const *  ev,
char const **  buffer,
size_t *  length 
)

Retrieve the new keymap reported by this MirKeymapEvent.

The keymap buffer is only valid while the MirKeymapEvent is valid. The buffer can be used via xkb_keymap_new_from_buffer

Parameters
[in]evThe keymap event
[out]bufferthe xkbcommon keymap
[out]lengthof the buffer
void mir_keymap_event_get_rules ( MirKeymapEvent const *  ev,
struct xkb_rule_names *  names 
)

Retrieve the new keymap reported by this MirKeymapEvent.

Deprecated:
keymap credentials are no longer available use mir_keymap_event_get_keymap_buffer instead.
Parameters
[in]evThe keymap event
[out]rulesXKB rules describing the new keymap.
MirOrientation mir_orientation_event_get_direction ( MirOrientationEvent const *  ev)

Retrieve the new orientation reported by this MirOrientationEvent.

Parameters
[in]evThe orientation event
Returns
The new orientation
MirOutputConnectionState mir_output_get_connection_state ( MirOutput const *  output)

Get whether there is a display physically connected to the output.

This gives a best-effort determination of whether or not enabling this output will result in an image being displayed to the user.

The accuracy of this determination varies with connection type - for example, for DisplayPort and HDMI connections a return value of mir_output_connection_state_connected is usually a reliable indicator that there is a powered-on display connected.

VGA and DVI connectors can usually determine whether or not there is a physically connected display, but cannot distinguish between a powered or unpowered display.

It is not always possible to determine whether or not there is a display connected; in such cases mir_output_connection_state_unknown is returned.

Parameters
[in]outputThe MirOutput to query
Returns
Whether there is a display connected to this output.
MirOutputMode const* mir_output_get_current_mode ( MirOutput const *  output)

Get a handle to the output's current mode.

An output may not have a current mode (for example, if it is disabled), in which case this call will return NULL.

Note
The handle remains valid as long as output is valid.
Parameters
[in]outputThe MirOutput to query
Returns
A handle for a description of the supported mode. This is valid for as long as output is valid. If the output does not have a current mode, it returns NULL.
MirPixelFormat mir_output_get_current_pixel_format ( MirOutput const *  output)

Get the current pixel format.

Parameters
[in]outputThe MirOutput to query
Returns
The current pixel format. This may be mir_pixel_format_invalid (for example, if the output is not currently enabled).
MirFormFactor mir_output_get_form_factor ( MirOutput const *  output)

Get the form-factor of a connected output.

This call succeeds even if the output is not connected, but may return nonsense values.

Parameters
[in]outputThe MirOutput to query
Returns
The form factor of this output
int mir_output_get_id ( MirOutput const *  output)

Get the ID of an output.

This can be used to refer to the output in other parts of the API, such as mir_surface_spec_set_fullscreen_on_output().

Parameters
[in]outputThe MirOutput to query.
Returns
The ID of output, which may be used to refer to it in other parts of the API.
MirOutputMode const* mir_output_get_mode ( MirOutput const *  output,
size_t  index 
)

Get a handle for a mode descriptor from the list of supported modes.

The list of supported modes is retrieved from the hardware, possibly modified by any applicable quirk tables, and may not be exhaustive.

Precondition
0 <= index < mir_output_get_num_modes(output)
Note
The handle remains valid as long as output is valid.
Parameters
[in]outputThe MirOutput to query
[in]indexThe index of the mode to retrieve.
Returns
A handle for a description of the supported mode. This is valid for as long as output is valid. The return value is never null.
int mir_output_get_num_modes ( MirOutput const *  output)

Get the number of modes in the supported mode list of this output.

The list of supported modes is retrieved from the hardware, possibly modified by any applicable quirk tables, and may not be exhaustive.

Parameters
[in]outputThe MirOutput to query
Returns
The number of modes in the supported mode list of output.
int mir_output_get_num_pixel_formats ( MirOutput const *  output)

Get the number of pixel formats supported by this output.

Parameters
[in]outputThe MirOutput to query
Returns
The number of pixel formats for output.
MirOrientation mir_output_get_orientation ( MirOutput const *  output)

Get the orientation of a display.

Parameters
[in]outputThe MirOutput to query
Returns
The orientation of output
int mir_output_get_physical_height_mm ( MirOutput const *  output)

Get the physical height of the connected display, in millimetres.

A best-effort report of the physical height of the display connected to this output. This is retrieved from the display hardware, possibly modified by any applicable quirk tables.

Where this information is unavailable or inapplicable (for example, projectors), 0 is returned.

Parameters
[in]outputthe MirOutput to query
Returns
Physical height of the connected display, in mm.
int mir_output_get_physical_width_mm ( MirOutput const *  output)

Get the physical width of the connected display, in millimetres.

A best-effort report of the physical width of the display connected to this output. This is retrieved from the display hardware, possibly modified by any applicable quirk tables.

Where this information is unavailable or inapplicable (for example, projectors), 0 is returned.

Parameters
[in]outputthe MirOutput to query
Returns
Physical width of the connected display, in mm.
MirPixelFormat mir_output_get_pixel_format ( MirOutput const *  output,
size_t  index 
)

Get a pixel format from the list of supported formats.

Precondition
0 <= index < mir_output_get_num_pixel_formats(output)
Parameters
[in]outputThe MirOutput to query
[in]indexThe index of the format to query
Returns
The index 'th supported pixel format.
int mir_output_get_position_x ( MirOutput const *  output)

Get the x coordinate of the top-left point of the output in the virtual display space.

Outputs can be thought of as viewports into a virtual display space. They may freely overlap, coincide, or be disjoint as desired.

Output orientation changes the orientation of the output rectangle in virtual display space, but does not change its top-left corner.

Parameters
[in]outputThe MirOutput to query
Returns
The x coordinate of the top-left point of the output in the virtual display space.
int mir_output_get_position_y ( MirOutput const *  output)

Get the y coordinate of the top-left point of the output in the virtual display space.

Outputs can be thought of as viewports into a virtual display space. They may freely overlap, coincide, or be disjoint as desired.

Output orientation changes the orientation of the output rectangle in virtual display space, but does not change its top-left corner.

Parameters
[in]outputThe MirOutput to query
Returns
The y coordinate of the top-left point of the output in the virtual display space.
MirPowerMode mir_output_get_power_mode ( MirOutput const *  output)

Get the power state of a connected display.

It is undefined which power state is returned for an output which is not connected.

Parameters
[in]outputThe MirOutput to query
Returns
The power state of the display connected to output.
MirOutputMode const* mir_output_get_preferred_mode ( MirOutput const *  output)

Get a handle to the output's preferred mode.

This is provided by the output itself. For modern displays (LCD, OLED, etc) it is typically a mode with the native resolution.

An output may not have a preferred mode, in which case this call will return NULL.

Note
The handle remains valid as long as output is valid.
Parameters
[in]outputThe MirOutput to query
Returns
A handle for a description of the supported mode. This is valid for as long as output is valid. If the output does not have a preferred mode, it returns NULL.
float mir_output_get_scale_factor ( MirOutput const *  output)

Get the scale-factor of a display.

The scale-factor specifies the conversion between logical pixels and physical pixels on this output.

A surface with dimensions 200×100 on an output with scale-factor 2.0 will display 400x200 pixels on this output, will display 300x150 pixels on an output with scale-factor 1.5, and so on.

Where this calculation would result in a fractional number of pixels the floor is used, so a surface with dimensions 101x100 on an output with scale-factor of 1.5 will display 151x150 pixels, not 152x150.

Parameters
[in]outputThe MirOutput to query
Returns
The scale-factor of this monitor
MirOutputType mir_output_get_type ( MirOutput const *  output)

Get the physical connection type of an output.

This is a best-effort determination, and may be incorrect.

Parameters
[in]outputThe MirOutput to query
Returns
The type of the display connection, or mir_output_type_unknown if it cannot be determined.
bool mir_output_is_enabled ( MirOutput const *  output)

Get whether this output is enabled in the current configuration.

Parameters
[in]outputthe MirOutput to query
Returns
Whether the output is enabled.
int mir_output_mode_get_height ( MirOutputMode const *  mode)

Get the height, in pixels, of a MirOutputMode.

Note
This is unaffected by the orientation of the output
Parameters
[in]modeThe MirOutputMode to query
Returns
The height, in pixels, of mode.
double mir_output_mode_get_refresh_rate ( MirOutputMode const *  mode)

Get the refresh rate, in Hz, of a MirOutputMode.

Parameters
[in]modeThe MirOutputMode to query
Returns
The refresh rate, in Hz, of mode
int mir_output_mode_get_width ( MirOutputMode const *  mode)

Get the width, in pixels, of a MirOutputMode.

Note
This is unaffected by the orientation of the output
Parameters
[in]modeThe MirOutputMode to query
Returns
The width, in pixels, of mode.
void mir_output_set_pixel_format ( MirOutput output,
MirPixelFormat  format 
)

Set the output format.

Parameters
[in]outputThe MirOutput to modify
[in]formatThe MirPixelFormat to set
char const* mir_persistent_id_as_string ( MirPersistentId id)

Get a string representation of a MirSurfaceId.

Parameters
[in]idThe ID to serialise
Returns
A string representation of id. This string is owned by the MirSurfaceId, and must not be freed by the caller.
See also
mir_surface_id_from_string
MirPersistentId* mir_persistent_id_from_string ( char const *  string_representation)

Deserialise a string representation of a MirSurfaceId.

Parameters
[in]string_representationSerialised representation of the ID
Returns
The deserialised MirSurfaceId
bool mir_persistent_id_is_valid ( MirPersistentId id)

Check the validity of a MirPersistentId.

Parameters
[in]idThe MirPersistentId
Returns
True iff the MirPersistentId contains a valid ID value.
Note
This does not guarantee that the ID refers to a currently valid object.
void mir_persistent_id_release ( MirPersistentId id)

Free a MirPersistentId.

Parameters
[in]idThe MirPersistentId to free
Note
This frees only the client-side representation; it has no effect on the object referred to by
  • id.
MirPlatformMessage* mir_platform_message_create ( unsigned int  opcode)

Create a platform message to use with mir_connection_platform_operation().

Each call to mir_platform_message_create() should be matched by a call to mir_platform_message_release() to avoid memory leaks.

Parameters
[in]opcodeThe platform message opcode
Returns
The created MirPlatformMessage
MirPlatformMessageData mir_platform_message_get_data ( MirPlatformMessage const *  message)

Get the data associated with a message.

The memory holding the returned data array is owned by the message and is valid only as long as the message is valid and mir_platform_set_data() is not called. You must not change or free the returned data array.

Parameters
[in]messageThe MirPlatformMessage
Returns
The data
MirPlatformMessageFds mir_platform_message_get_fds ( MirPlatformMessage const *  message)

Gets the fds associated with a message.

The memory of the returned fd array is owned by the message and is valid only as long as the message is valid and mir_platform_set_fds() is not called. You must not change or free the returned fd array.

Note that the fds associated with a message will not be closed when the message is released. Users are responsible for getting and closing the fds to avoid leaks.

Parameters
[in]messageThe MirPlatformMessage
Returns
The fds
unsigned int mir_platform_message_get_opcode ( MirPlatformMessage const *  message)

Get the opcode of a message.

Parameters
[in]messageThe MirPlatformMessage
Returns
The opcode
void mir_platform_message_release ( MirPlatformMessage const *  message)

Release a platform message.

Parameters
[in]messageThe MirPlatformMessage
void mir_platform_message_set_data ( MirPlatformMessage message,
void const *  data,
size_t  data_size 
)

Set the data associated with a message.

The data is copied into the message.

Parameters
[in]messageThe MirPlatformMessage
[in]dataPointer to the data
[in]data_sizeThe size of the data in bytes
void mir_platform_message_set_fds ( MirPlatformMessage message,
int const *  fds,
size_t  num_fds 
)

Sets the fds associated with a message.

The fd array is copied into the message, but the message does not take ownership of the fds, i.e., the caller is responsible for keeping the fds open for as long as this message needs to remain valid.

Note that the fds associated with a message are not closed when the message is released. The caller is responsible for closing the fds when the message doesn't need them anymore (see also mir_platform_message_get_fds()).

Parameters
[in]messageThe MirPlatformMessage
[in]fdsPointer to the array of fds
[in]num_fdsThe number of fds
MirPointerAction mir_pointer_event_action ( MirPointerEvent const *  event)

Retrieve the action which occured to generate a given pointer event.

Parameters
[in]eventThe pointer event
Returns
Action performed by the pointer
float mir_pointer_event_axis_value ( MirPointerEvent const *  event,
MirPointerAxis  axis 
)

Retrieve the axis value reported by a given pointer event.

Parameters
[in]eventThe pointer event
[in]axisThe axis to retreive a value from
Returns
The value of the given axis
bool mir_pointer_event_button_state ( MirPointerEvent const *  event,
MirPointerButton  button 
)

Retrieve the state of a given pointer button when the action occurred.

Parameters
[in]eventThe pointer event
[in]buttonThe button to check
Returns
Whether the given button is depressed
MirPointerButtons mir_pointer_event_buttons ( MirPointerEvent const *  event)

Retreive the pointer button state as a masked set of values.

Parameters
[in]eventThe pointer event
Returns
The button state
MirInputEvent const* mir_pointer_event_input_event ( MirPointerEvent const *  event)

Retrieve the corresponding input event.

Parameters
[in]eventThe pointer event
Returns
The input event
MirInputEventModifiers mir_pointer_event_modifiers ( MirPointerEvent const *  event)

Retrieve the modifier keys pressed when the pointer action occured.

Parameters
[in]eventThe pointer event
Returns
The modifier mask
void mir_presentation_chain_allocate_buffer ( MirPresentationChain presentation_chain,
int  width,
int  height,
MirPixelFormat  format,
MirBufferUsage  buffer_usage,
mir_buffer_callback  available_callback,
void *  available_context 
)

Allocate a MirBuffer and do not wait for the server to return it.

The callback will be called when the buffer is available for use. It will be called once when created, and once per every mir_presentation_chain_submit_buffer.

Parameters
[in]presentation_chainThe presentation chain
[in]widthRequested buffer width
[in]heightRequested buffer height
[in]buffer_usageRequested buffer usage
[in]available_callbackThe callback called when the buffer is available
[in]available_contextThe context for the available_callback
char const* mir_presentation_chain_get_error_message ( MirPresentationChain presentation_chain)

Retrieve a text description of the error.

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

Parameters
[in]presentation_chainThe presentation chain
Returns
A text description of any error resulting in an invalid chain, or the empty string "" if the chain is valid.
bool mir_presentation_chain_is_valid ( MirPresentationChain presentation_chain)

Test for a valid presentation chain.

Parameters
[in]presentation_chainThe presentation chain
Returns
True if the supplied presentation_chain is valid, or false otherwise.
void mir_presentation_chain_release ( MirPresentationChain presentation_chain)

Release the specified presentation chain.

Parameters
[in]presentation_chainThe presentation chain to be released
void mir_presentation_chain_submit_buffer ( MirPresentationChain presentation_chain,
MirBuffer buffer 
)

Submit a buffer to the server so the server can display it.

The server will notify the client when the buffer is available again via the callback registered during buffer creation.

Warning
: Once submitted, the buffer cannot be modified until the server has returned it. There's no guarantee about how long a server may hold the submitted buffer.
Parameters
[in]presentation_chainThe presentation chain
[in]bufferThe buffer to be submitted
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.
MirPromptSessionState mir_prompt_session_event_get_state ( MirPromptSessionEvent const *  ev)

Retrieve the new prompt session state reported by a given MirPromptSessionEvent.

Parameters
[in]eventThe prompt session event
Returns
The new state
bool 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
int mir_resize_event_get_height ( MirResizeEvent const *  ev)

Retrieve the new height reported by a given MirResizeEvent.

Parameters
[in]evThe resize event
Returns
The reported height
int mir_resize_event_get_width ( MirResizeEvent const *  ev)

Retrieve the new width reported by a given MirResizeEvent.

Parameters
[in]evThe resize event
Returns
The reported width
MirBufferStream* mir_screencast_get_buffer_stream ( MirScreencast screencast)

Retrieve the MirBufferStream associated with a screencast (to advance buffers, obtain EGLNativeWindowType, etc...)

Parameters
[in]screencastThe screencast
void mir_screencast_release_sync ( MirScreencast screencast)

Release the specified screencast.

Parameters
[in]screencastThe screencast to be released
void mir_surface_apply_spec ( MirSurface surface,
MirSurfaceSpec spec 
)

Request changes to the specification of a surface.

The server will decide whether and how the request can be honoured.

Parameters
[in]surfaceThe surface to rename
[in]specSpec with the requested changes applied
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.
MirWaitHandle* mir_surface_create ( MirSurfaceSpec requested_specification,
mir_surface_callback  callback,
void *  context 
)

Create a surface from a given specification.

Parameters
[in]requested_specificationSpecification of the attributes for the created surface
[in]callbackCallback function to be invoked when creation is complete
[in,out]contextUser data passed to callback function. This callback is guaranteed to be called, and called with a non-null MirSurface*, but the surface may be invalid in case of an error.
Returns
A handle that can be passed to mir_wait_for()
MirSurface* mir_surface_create_sync ( MirSurfaceSpec requested_specification)

Create a surface from a given specification and wait for the result.

Parameters
[in]requested_specificationSpecification of the attributes for the created surface
Returns
The new surface. This is guaranteed non-null, but may be invalid in the case of error.
MirSurfaceAttrib mir_surface_event_get_attribute ( MirSurfaceEvent const *  ev)

Retrieve the attribute index configured with a given MirSurfaceEvent.

Parameters
[in]EventThe event
Returns
The associated attribute
int mir_surface_event_get_attribute_value ( MirSurfaceEvent const *  ev)

Retrieve the new value of the associated attribute for a given MirSurfaceEvent.

Parameters
[in]EventThe event
Returns
The associated attribute value
MirBufferStream* mir_surface_get_buffer_stream ( MirSurface surface)

Retrieve the primary MirBufferStream associated with a surface (to advance buffers, obtain EGLNativeWindow, etc...)

Parameters
[in]surfaceThe surface
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.
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.
MirSurfaceFocusState mir_surface_get_focus ( MirSurface surface)

Query the focus state for a surface.

Parameters
[in]surfaceThe surface to operate on
Returns
The focus state of said surface
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
MirOrientationMode mir_surface_get_preferred_orientation ( MirSurface surface)

Get the preferred orientation modes of a surface.

Parameters
[in]surfaceThe surface to query
Returns
The preferred orientation modes
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
MirSurfaceVisibility mir_surface_get_visibility ( MirSurface surface)

Query the visibility state for a surface.

Parameters
[in]surfaceThe surface to operate on
Returns
The visibility state of said surface
bool 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.
int mir_surface_output_event_get_dpi ( MirSurfaceOutputEvent const *  ev)

Retrieve the DPI of the new output configuration of a MirSurfaceOutputEvent.

Parameters
[in]evThe event
Returns
The new DPI value for the surface is primarily on.
MirFormFactor mir_surface_output_event_get_form_factor ( MirSurfaceOutputEvent const *  ev)

Retrieve the form factor of the new output configuration of a MirSurfaceOutputEvent.

Parameters
[in]evThe event
Returns
The new form factor of the output the surface is primarily on.
uint32_t mir_surface_output_event_get_output_id ( MirSurfaceOutputEvent const *  ev)

Retrieve the ID of the output this surface is on from a MirSurfaceOutputEvent.

Parameters
[in]evThe event
Returns
The ID of the output the surface is currently considered to be on. (From MirDisplayOutput::output_id)
float mir_surface_output_event_get_scale ( MirSurfaceOutputEvent const *  ev)

Retrieve the form factor of the new output configuration of a MirSurfaceOutputEvent.

Parameters
[in]evThe event
Returns
The new form factor of the output the surface is primarily on.
void mir_surface_raise ( MirSurface surface,
MirCookie const *  cookie 
)

Attempts to raise the surface to the front.

Parameters
[in]surfaceThe surface to raise
[in]cookieA cookie instance obtained from an input event. An invalid cookie will terminate the client connection.
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
MirWaitHandle* mir_surface_request_persistent_id ( MirSurface surface,
mir_surface_id_callback  callback,
void *  context 
)

Request an ID for the surface that can be shared cross-process and across restarts.

This call acquires a MirPersistentId for this MirSurface. This MirPersistentId can be serialized to a string, stored or sent to another process, and then later deserialized to refer to the same surface.

Parameters
[in]surfaceThe surface to acquire a persistent reference to.
[in]callbackCallback to invoke when the request completes.
[in,out]contextUser data passed to completion callback.
Returns
A MirWaitHandle that can be used in mir_wait_for to await completion.
MirPersistentId* mir_surface_request_persistent_id_sync ( MirSurface surface)

Request a persistent ID for a surface and wait for the result.

Parameters
[in]surfaceThe surface to acquire a persistent ID for.
Returns
A MirPersistentId. This MirPersistentId is owned by the calling code, and must be freed with a call to mir_persistent_id_release()
void mir_surface_set_event_handler ( MirSurface surface,
mir_surface_event_callback  callback,
void *  context 
)

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]callbackThe callback function
[in]contextAdditional argument to be passed to callback
MirWaitHandle* mir_surface_set_preferred_orientation ( MirSurface surface,
MirOrientationMode  orientation 
)

Request to set the preferred orientations of a surface.

The request may be rejected by the server; to check wait on the result and check the applied value using mir_surface_get_preferred_orientation

Parameters
[in]surfaceThe surface to operate on
[in]orientationThe preferred orientation modes
Returns
A wait handle that can be passed to mir_wait_for
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
void mir_surface_spec_add_buffer_stream ( MirSurfaceSpec spec,
int  displacement_x,
int  displacement_y,
MirBufferStream stream 
)

Set the MirSurfaceContent to display a MirBufferStream.

The initial call to mir_surface_spec_add_presentation_chain or mir_surface_spec_add_buffer_stream will set the bottom-most content, and subsequent calls to either will stack the content on top.

Warning
Setting the displacements to exceed the bounds of MirSurface may result in clipping to the size of the MirSurface, at the server's discretion.
Parameters
specThe surface_spec to be updated.
displacement_xThe x displacement from the top-left corner of the MirSurface.
displacement_yThe y displacement from the top-left corner of the MirSurface.
streamThe stream containing the content to be displayed.
void mir_surface_spec_add_presentation_chain ( MirSurfaceSpec spec,
int  width,
int  height,
int  displacement_x,
int  displacement_y,
MirPresentationChain chain 
)

Set the MirSurfaceContent to display a MirPresentationChain.

The width and height can be different from the physical dimensions of the MirBuffer's in the MirPresentationChain. If the two differ, the content will be scaled to fit width and height.

The initial call to mir_surface_spec_add_presentation_chain or mir_surface_spec_add_buffer_stream will set the bottom-most content, and subsequent calls to either will stack the content on top.

Warning
Setting the dimensions or displacements to exceed the bounds of MirSurface may result in clipping to the size of the MirSurface, at the server's discretion.
Parameters
specThe surface_spec to be updated.
widthThe width that the content will displayed at.
heightThe height that the content will be displayed at.
displacement_xThe x displacement from the top-left corner of the MirSurface.
displacement_yThe y displacement from the top-left corner of the MirSurface.
chainThe chain containing the content to be displayed.
bool mir_surface_spec_attach_to_foreign_parent ( MirSurfaceSpec spec,
MirPersistentId parent,
MirRectangle attachment_rect,
MirEdgeAttachment  edge 
)

Request that the created surface be attached to a surface of a different client.

This is restricted to input methods, which need to attach their suggestion surface to text entry widgets of other processes.

Parameters
[in]specSpecification to mutate
[in]parentA MirPersistentId reference to the parent surface
[in]attachment_rectA rectangle specifying the region (in parent surface coordinates) that the created surface should be attached to.
[in]edgeThe preferred edge direction to attach to. Use mir_edge_attachment_any for no preference.
Returns
False if the operation is invalid for this surface type.
Note
If the parent surface becomes invalid before mir_surface_create() is processed, it will return an invalid surface. If the parent surface is valid at the time mir_surface_create() is called but is later closed, this surface will also receive a close event.
void mir_surface_spec_release ( MirSurfaceSpec spec)

Release the resources held by a MirSurfaceSpec.

Parameters
[in]specSpecification to release
void mir_surface_spec_set_buffer_usage ( MirSurfaceSpec spec,
MirBufferUsage  usage 
)

Set the requested buffer usage.

Parameters
[in]specSpecification to mutate
[in]usageRequested buffer usage
Note
If this call returns true then the server is guaranteed to honour this request. If the server is unable to create a surface with this buffer usage at the point mir_surface_create() is called it will instead return an invalid surface.
void mir_surface_spec_set_event_handler ( MirSurfaceSpec spec,
mir_surface_event_callback  callback,
void *  context 
)

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]specThe spec to accumulate the request in.
[in]callbackThe callback function
[in]contextAdditional argument to be passed to callback
void mir_surface_spec_set_fullscreen_on_output ( MirSurfaceSpec spec,
uint32_t  output_id 
)
Parameters
[in]specSpecification to mutate
[in]output_idID of output to place surface on. From MirDisplayOutput.output_id
Note
If this call returns true then a valid surface returned from mir_surface_create() is guaranteed to be fullscreen on the specified output. An invalid surface is returned if the server unable to, or policy prevents it from, honouring this request.
void mir_surface_spec_set_height ( MirSurfaceSpec spec,
unsigned  height 
)

Set the requested height, in pixels.

Parameters
[in]specSpecification to mutate
[in]heightRequested height.
Note
The requested dimensions are a hint only. The server is not guaranteed to create a surface of any specific width or height.
void mir_surface_spec_set_height_increment ( MirSurfaceSpec spec,
unsigned  height_inc 
)

Set the requested height increment, in pixels Defines an arithmetic progression of sizes starting with min_height (if set, otherwise 0) into which the surface prefers to be resized.

Parameters
[in]specSpecification to mutate
[in]height_incRequested height increment.
Note
The requested dimensions are a hint only. The server is not guaranteed to create a surface of any specific width or height.
void mir_surface_spec_set_input_shape ( MirSurfaceSpec spec,
MirRectangle const *  rectangles,
size_t  n_rects 
)

Set a collection of input rectangles assosciated with the spec.

Rectangles are specified as a list of regions relative to the top left of the specified surface. If the server applies this specification to a surface input which would normally go to the surface but is not contained within any of the input rectangles instead passes on to the next client.

Parameters
[in]specThe spec to accumulate the request in.
[in]rectanglesAn array of MirRectangles specifying the input shape.
[in]num_streamsThe number of elements in the rectangles array.
void mir_surface_spec_set_max_aspect_ratio ( MirSurfaceSpec spec,
unsigned  width,
unsigned  height 
)

Set the maximum aspect ratio.

This is the maximum ratio of surface width to height. It is independent of orientation changes and/or preferences.

Parameters
[in]specSpecification to mutate
[in]widthnumerator
[in]heightdenominator
Note
The requested aspect ratio is a hint only. The server is not guaranteed to create a surface of any specific aspect.
void mir_surface_spec_set_max_height ( MirSurfaceSpec spec,
unsigned  max_height 
)

Set the maximum height, in pixels.

Parameters
[in]specSpecification to mutate
[in]heightMaximum height.
Note
The requested dimensions are a hint only. The server is not guaranteed to create a surface of any specific width or height.
void mir_surface_spec_set_max_width ( MirSurfaceSpec spec,
unsigned  max_width 
)

Set the maximum width, in pixels.

Parameters
[in]specSpecification to mutate
[in]widthMaximum width.
Note
The requested dimensions are a hint only. The server is not guaranteed to create a surface of any specific width or height.
void mir_surface_spec_set_min_aspect_ratio ( MirSurfaceSpec spec,
unsigned  width,
unsigned  height 
)

Set the minimum aspect ratio.

This is the minimum ratio of surface width to height. It is independent of orientation changes and/or preferences.

Parameters
[in]specSpecification to mutate
[in]widthnumerator
[in]heightdenominator
Note
The requested aspect ratio is a hint only. The server is not guaranteed to create a surface of any specific aspect.
void mir_surface_spec_set_min_height ( MirSurfaceSpec spec,
unsigned  min_height 
)

Set the minimum height, in pixels.

Parameters
[in]specSpecification to mutate
[in]heightMinimum height.
Note
The requested dimensions are a hint only. The server is not guaranteed to create a surface of any specific width or height.
void mir_surface_spec_set_min_width ( MirSurfaceSpec spec,
unsigned  min_width 
)

Set the minimum width, in pixels.

Parameters
[in]specSpecification to mutate
[in]widthMinimum width.
Note
The requested dimensions are a hint only. The server is not guaranteed to create a surface of any specific width or height.
void mir_surface_spec_set_name ( MirSurfaceSpec spec,
char const *  name 
)

Set the requested name.

The surface name helps the user to distinguish between multiple surfaces from the same application. A typical desktop shell may use it to provide text in the window titlebar, in an alt-tab switcher, or equivalent.

Parameters
[in]specSpecification to mutate
[in]nameRequested name. This must be valid UTF-8. Copied into spec; clients can free the buffer passed after this call.
void mir_surface_spec_set_parent ( MirSurfaceSpec spec,
MirSurface parent 
)

Set the requested parent.

Parameters
[in]specSpecification to mutate
[in]parentA valid parent surface.
void mir_surface_spec_set_pixel_format ( MirSurfaceSpec spec,
MirPixelFormat  format 
)

Set the requested pixel format.

Parameters
[in]specSpecification to mutate
[in]formatRequested pixel format
Note
If this call returns true then the server is guaranteed to honour this request. If the server is unable to create a surface with this pixel format at the point mir_surface_create() is called it will instead return an invalid surface.
void mir_surface_spec_set_preferred_orientation ( MirSurfaceSpec spec,
MirOrientationMode  mode 
)

Set the requested preferred orientation mode.

Parameters
[in]specSpecification to mutate
[in]modeRequested preferred orientation
Note
If the server is unable to create a surface with the preferred orientation at the point mir_surface_create() is called it will instead return an invalid surface.
void mir_surface_spec_set_shell_chrome ( MirSurfaceSpec spec,
MirShellChrome  style 
)

Ask the shell to customize "chrome" for this surface.

For example, on the phone hide indicators when this surface is active.

Parameters
[in]specThe spec to accumulate the request in.
[in]styleThe requested level of "chrome"
void mir_surface_spec_set_state ( MirSurfaceSpec spec,
MirSurfaceState  state 
)

Set the requested state.

Parameters
[in]specSpecification to mutate
[in]modeRequested state
Note
If the server is unable to create a surface with the requested state at the point mir_surface_create() is called it will instead return an invalid surface.
void mir_surface_spec_set_streams ( MirSurfaceSpec spec,
MirBufferStreamInfo streams,
unsigned int  num_streams 
)

Set the streams associated with the spec.

streams[0] is the bottom-most stream, and streams[size-1] is the topmost. On application of the spec, a stream that is present in the surface, but is not in the list will be disassociated from the surface. On application of the spec, a stream that is not present in the surface, but is in the list will be associated with the surface. Streams set a displacement from the top-left corner of the surface.

Warning
disassociating streams from the surface will not release() them.
It is wiser to arrange the streams within the bounds of the surface the spec is applied to. Shells can define their own behavior as to what happens to an out-of-bound stream.
Parameters
[in]specThe spec to accumulate the request in.
[in]streamsAn array of non-null streams info.
[in]num_streamsThe number of elements in the streams array.
void mir_surface_spec_set_type ( MirSurfaceSpec spec,
MirSurfaceType  type 
)

Update a surface specification with a surface type.

This can be used with mir_surface_create() to create a surface or with mir_surface_apply_spec() to change an existing surface.

Remarks
For use with mir_surface_apply_spec() the shell need not support arbitrary changes of type and some target types may require the setting of properties such as "parent" that are not already present on the surface. The type transformations the server is required to support are:
regular => utility, dialog or satellite
utility => regular, dialog or satellite
dialog => regular, utility or satellite
satellite => regular, utility or dialog
popup => satellite
Parameters
[in]specSpecification to mutate
[in]typethe target type of the surface
void mir_surface_spec_set_width ( MirSurfaceSpec spec,
unsigned  width 
)

Set the requested width, in pixels.

Parameters
[in]specSpecification to mutate
[in]widthRequested width.
Note
The requested dimensions are a hint only. The server is not guaranteed to create a surface of any specific width or height.
void mir_surface_spec_set_width_increment ( MirSurfaceSpec spec,
unsigned  width_inc 
)

Set the requested width increment, in pixels.

Defines an arithmetic progression of sizes starting with min_width (if set, otherwise 0) into which the surface prefers to be resized.

Parameters
[in]specSpecification to mutate
[in]width_incRequested width increment.
Note
The requested dimensions are a hint only. The server is not guaranteed to create a surface of any specific width or height.
MirTouchAction mir_touch_event_action ( MirTouchEvent const *  event,
size_t  touch_index 
)

Retrieve the action which occured for a touch at given index.

Parameters
[in]eventThe touch event
[in]touch_indexThe touch index. Must be less than (touch_count - 1).
Returns
Action performed for the touch at index.
float mir_touch_event_axis_value ( MirTouchEvent const *  event,
size_t  touch_index,
MirTouchAxis  axis 
)

Retrieve the axis value for a given axis on an indexed touch.

Parameters
[in]eventThe touch event
[in]touch_indexThe touch index. Must be less than (touch_count - 1).
[in]axisThe axis to retreive a value from
Returns
The value of the given axis
MirTouchId mir_touch_event_id ( MirTouchEvent const *  event,
size_t  touch_index 
)

Retrieve the TouchID for a touch at given index.

Parameters
[in]eventThe touch event
[in]touch_indexThe touch index. Must be less than (touch_count - 1).
Returns
ID of the touch at index
MirInputEvent const* mir_touch_event_input_event ( MirTouchEvent const *  event)

Retrieve the corresponding input event.

Parameters
[in]eventThe touch event
Returns
The input event
MirInputEventModifiers mir_touch_event_modifiers ( MirTouchEvent const *  event)

Retrieve the modifier keys pressed when the touch action occured.

Parameters
[in]eventThe key event
Returns
The modifier mask
unsigned int mir_touch_event_point_count ( MirTouchEvent const *  event)

Retrieve the number of touches reported for a given touch event.

Each touch is said to be index in the event and may be accessed by index 0, 1, ... , (touch_count - 1)

Parameters
[in]eventThe touch event
Returns
The number of touches
MirTouchTooltype mir_touch_event_tooltype ( MirTouchEvent const *  event,
size_t  touch_index 
)

Retrieve the tooltype for touch at given index.

Parameters
[in]eventThe touch event
[in]touch_indexThe touch index. Must be less than (touch_count - 1).
Returns
Tooltype used for the touch at index
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

char const* const mir_arrow_cursor_name

The standard arrow cursor (typically the system default)

char const* const mir_busy_cursor_name

The "wait" cursor, typically an hourglass or watch used during operations which prevent the user from interacting.

char const* const mir_caret_cursor_name

The caret or ibeam cursor, indicating acceptance of text input.

char const* const mir_closed_hand_cursor_name

The close handed cursor, typically used to indicate that a drag operation is in process which involves scrolling.

char const* const mir_crosshair_cursor_name

The cursor used for crosshair, which may be used for picking colors or finer precision.

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_diagonal_resize_bottom_to_top_cursor_name

The cursor used to indicate diagonal resize from top-right and bottom-left corners.

char const* const mir_diagonal_resize_top_to_bottom_cursor_name

The cursor used to indicate diagonal resize from bottom-left and top-right corners.

char const* const mir_disabled_cursor_name

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

char const* const mir_horizontal_resize_cursor_name

The cursor used to indicate a horizontal resize operation.

char const* const mir_hsplit_resize_cursor_name

The cursor used for horizontal splitters, indicating that a handle may be dragged to adjust horizontal space.

char const* const mir_omnidirectional_resize_cursor_name

The cursor used to indicate resize with no directional constraint.

char const* const mir_open_hand_cursor_name

The open handed cursor, typically used to indicate that the area beneath the cursor may be clicked and dragged around.

char const* const mir_pointing_hand_cursor_name

The pointing hand cursor, typically used for clickable elements such as hyperlinks.

char const* const mir_vertical_resize_cursor_name

The cursor used to indicate a vertical resize operation.

char const* const mir_vsplit_resize_cursor_name

The cursor used for vertical splitters, indicating that a handle may be dragged to adjust vertical space.


Copyright © 2012-2015 Canonical Ltd.
Generated on Wed Mar 30 00:29:56 UTC 2016