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

Classes

struct  MirWaitHandle
 
struct  MirKeyEvent
 
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  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  MirCookie
 
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   (1)
 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 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 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 MirGraphicsRegion MirGraphicsRegion
 Retrieved information about a MirSurface. More...
 
typedef struct MirDisplayInfo MirDisplayInfo
 
typedef struct MirDisplayCard MirDisplayCard
 MirDisplayConfiguration provides details of the graphics environment. More...
 
typedef enum MirDisplayOutputType MirDisplayOutputType
 
typedef struct MirDisplayMode MirDisplayMode
 
typedef struct MirDisplayOutput MirDisplayOutput
 
typedef struct MirDisplayConfiguration MirDisplayConfiguration
 
typedef struct MirBufferStreamInfo MirBufferStreamInfo
 The displacement from the top-left corner of the surface. More...
 
typedef struct MirRectangle MirRectangle
 
typedef struct MirScreencastParameters MirScreencastParameters
 MirScreencastParameters is the structure of required information that you must provide to Mir in order to create a MirScreencast. More...
 
typedef void(* mir_screencast_callback) (MirScreencast *screencast, void *client_context)
 Callback to be passed when calling MirScreencast functions. More...
 
typedef void(* mir_prompt_session_callback) (MirPromptSession *prompt_provider, void *context)
 Callback member of MirPromptSession for handling of prompt sessions. More...
 
typedef void(* mir_prompt_session_state_change_callback) (MirPromptSession *prompt_provider, MirPromptSessionState state, void *context)
 Callback member of MirPromptSession for handling of prompt sessions events. More...
 
typedef void(* mir_platform_operation_callback) (MirConnection *connection, MirPlatformMessage *reply, void *context)
 Callback called when a platform operation completes. 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 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 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 struct MirCookie MirCookie
 
typedef struct MirMesaEGLNativeDisplay MirMesaEGLNativeDisplay
 
typedef struct MirMesaEGLNativeSurface MirMesaEGLNativeSurface
 
typedef struct MirBufferPackage MirBufferPackage
 

Enumerations

enum  MirBufferUsage { mir_buffer_usage_hardware = 1, mir_buffer_usage_software }
 MirBufferUsage specifies how a surface can and will be used. More...
 
enum  { mir_platform_package_max = 32 }
 
enum  MirPlatformType { mir_platform_type_gbm, mir_platform_type_android }
 The native buffer type for the system the client is connected on. More...
 
enum  { mir_supported_pixel_format_max = 32 }
 DEPRECATED. More...
 
enum  MirDisplayOutputType {
  mir_display_output_type_unknown, mir_display_output_type_vga, mir_display_output_type_dvii, mir_display_output_type_dvid,
  mir_display_output_type_dvia, mir_display_output_type_composite, mir_display_output_type_svideo, mir_display_output_type_lvds,
  mir_display_output_type_component, mir_display_output_type_ninepindin, mir_display_output_type_displayport, mir_display_output_type_hdmia,
  mir_display_output_type_hdmib, mir_display_output_type_tv, mir_display_output_type_edp
}
 
enum  { mir_display_output_id_invalid = 0 }
 
enum  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
}
 
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  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  MirMesaPlatformOperation { auth_magic = 1, auth_fd = 2, set_gbm_device = 3 }
 

Functions

MirEventType mir_event_get_type (MirEvent const *ev)
 
MirInputEvent const * mir_event_get_input_event (MirEvent const *ev)
 
MirSurfaceEvent const * mir_event_get_surface_event (MirEvent const *ev)
 
MirResizeEvent const * mir_event_get_resize_event (MirEvent const *ev)
 
MirPromptSessionEvent const * mir_event_get_prompt_session_event (MirEvent const *ev)
 
MirOrientationEvent const * mir_event_get_orientation_event (MirEvent const *ev)
 
MirCloseSurfaceEvent const * mir_event_get_close_surface_event (MirEvent const *ev)
 
MirKeymapEvent const * mir_event_get_keymap_event (MirEvent const *ev)
 
MirInputConfigurationEvent const * mir_event_get_input_configuration_event (MirEvent const *ev)
 
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))
 
void mir_event_unref (MirEvent const *ev)
 
MirInputDeviceId mir_input_event_get_device_id (MirInputEvent const *ev)
 
int64_t mir_input_event_get_event_time (MirInputEvent const *ev)
 
MirInputEventType mir_input_event_get_type (MirInputEvent const *ev)
 
MirKeyboardEvent const * mir_input_event_get_keyboard_event (MirInputEvent const *ev)
 
MirTouchEvent const * mir_input_event_get_touch_event (MirInputEvent const *ev)
 
MirPointerEvent const * mir_input_event_get_pointer_event (MirInputEvent const *ev)
 
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)
 
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)
 
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)
 
MirInputConfigurationAction mir_input_configuration_event_get_action (MirInputConfigurationEvent const *ev)
 
int64_t mir_input_configuration_event_get_time (MirInputConfigurationEvent const *ev)
 
MirInputDeviceId mir_input_configuration_event_get_device_id (MirInputConfigurationEvent const *ev)
 
void mir_keymap_event_get_rules (MirKeymapEvent const *ev, struct xkb_rule_names *names)
 
MirOrientation mir_orientation_event_get_direction (MirOrientationEvent const *ev)
 
MirPromptSessionState mir_prompt_session_event_get_state (MirPromptSessionEvent const *ev)
 
int mir_resize_event_get_width (MirResizeEvent const *ev)
 
int mir_resize_event_get_height (MirResizeEvent const *ev)
 
MirSurfaceAttrib mir_surface_event_get_attribute (MirSurfaceEvent const *ev)
 
int mir_surface_event_get_attribute_value (MirSurfaceEvent const *ev)
 
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...
 
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...
 
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...
 
MirPlatformType mir_buffer_stream_get_platform_type (MirBufferStream *stream)
 Get the underlying platform type so the buffer obtained in "raw" representation in mir_buffer_stream_get_current_buffer() may be understood. 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, e.g. 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_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...
 
void mir_connection_set_display_config_change_callback (MirConnection *connection, mir_display_config_callback callback, void *context)
 Register a callback to be called when the hardware display configuration changes. More...
 
void mir_display_config_destroy (MirDisplayConfiguration *display_configuration)
 Destroy the DisplayConfiguration resource acquired from mir_connection_create_display_config. More...
 
MirWaitHandlemir_connection_apply_display_config (MirConnection *connection, MirDisplayConfiguration *display_configuration)
 Apply the display configuration. More...
 
MirEGLNativeDisplayType mir_connection_get_egl_native_display (MirConnection *connection)
 Get a display type that can be used for OpenGL ES 2.0 acceleration. More...
 
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...
 
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...
 
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)
 
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_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...
 

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
Examples:
server_example_canonical_window_manager.cpp.
#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   (1)

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

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 int64_t MirInputDeviceId
typedef struct MirInputEvent MirInputEvent
typedef unsigned int MirInputEventModifiers

An event type describing a change in keyboard state.

Apology #1: The name "MirKeyboardEvent" is used instead of "MirKeyEvent" because the latter still exists in the old Mir event API.

Apology #2: 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.

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

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.

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.

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

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 

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 

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.

Enumerator
mir_platform_type_gbm 
mir_platform_type_android 

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

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_basic_window_manager.h, 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 

Identifiers for per-touch tool types.

Enumerator
mir_touch_tooltype_unknown 
mir_touch_tooltype_finger 
mir_touch_tooltype_stylus 

Function Documentation

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_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
void mir_buffer_stream_get_graphics_region ( MirBufferStream buffer_stream,
MirGraphicsRegion graphics_region 
)

Retrieve a buffer stream's graphics region, e.g.

map the graphics buffer to main memory.

Precondition
The buffer stream is valid
Parameters
[in]bufferstream The buffer stream
[out]graphics_regionStructure to be populated
MirPlatformType mir_buffer_stream_get_platform_type ( MirBufferStream stream)

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

Precondition
The surface is valid
Parameters
[in]surfaceThe surface
Returns
One of mir_platform_type_android or mir_platform_type_gbm
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
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
[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.

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

Create and start a new prompt session.

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

Create a screencast on the supplied connection.

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

Warning
This request may be denied.
Parameters
[in]connectionThe connection
[in]parametersThe screencast parameters
Returns
The resulting screencast
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_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
void mir_connection_set_display_config_change_callback ( MirConnection connection,
mir_display_config_callback  callback,
void *  context 
)

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

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

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

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

Parameters
[in]connectionThe connection
[in]callbackThe function to be called when the state change occurs
[in,out]contextUser data passed to the callback function
void mir_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
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
MirCloseSurfaceEvent const* mir_event_get_close_surface_event ( MirEvent const *  ev)
MirInputConfigurationEvent const* mir_event_get_input_configuration_event ( MirEvent const *  ev)
MirInputEvent const* mir_event_get_input_event ( MirEvent const *  ev)
MirKeymapEvent const* mir_event_get_keymap_event ( MirEvent const *  ev)
MirOrientationEvent const* mir_event_get_orientation_event ( MirEvent const *  ev)
MirPromptSessionEvent const* mir_event_get_prompt_session_event ( MirEvent const *  ev)
MirResizeEvent const* mir_event_get_resize_event ( MirEvent const *  ev)
MirSurfaceEvent const* mir_event_get_surface_event ( MirEvent const *  ev)
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)
MirEvent const* mir_event_ref ( MirEvent const *  ev)
void mir_event_unref ( MirEvent const *  ev)
MirInputConfigurationAction mir_input_configuration_event_get_action ( MirInputConfigurationEvent const *  ev)
MirInputDeviceId mir_input_configuration_event_get_device_id ( MirInputConfigurationEvent const *  ev)
int64_t mir_input_configuration_event_get_time ( MirInputConfigurationEvent const *  ev)
MirInputDeviceId mir_input_event_get_device_id ( MirInputEvent const *  ev)
int64_t mir_input_event_get_event_time ( MirInputEvent const *  ev)
MirKeyboardEvent const* mir_input_event_get_keyboard_event ( MirInputEvent const *  ev)
MirPointerEvent const* mir_input_event_get_pointer_event ( MirInputEvent const *  ev)
MirTouchEvent const* mir_input_event_get_touch_event ( MirInputEvent const *  ev)
MirInputEventType mir_input_event_get_type ( MirInputEvent const *  ev)
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)
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
void mir_keymap_event_get_rules ( MirKeymapEvent const *  ev,
struct xkb_rule_names *  names 
)
MirOrientation mir_orientation_event_get_direction ( MirOrientationEvent const *  ev)
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)
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
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)
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)
int mir_resize_event_get_width ( MirResizeEvent const *  ev)
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)
int mir_surface_event_get_attribute_value ( MirSurfaceEvent const *  ev)
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.
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.
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
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 
)
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_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)
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 Thu Oct 8 16:20:16 UTC 2015