← Back to branch summary

~morphis/mir/fix-screencast-orientation

« back to all changes in this revision

Viewing changes to include/client/mir_toolkit/mir_display_configuration.h

  • Committer: Simon Fels
  • Date: 2016-04-20 06:56:22 UTC
  • mfrom: (1266.1.6 mir)
  • Revision ID: simon.fels@canonical.com-20160420065622-fa4i1zkav6tqhs54
Merge lp:mir/ubuntu

[ Alberto Aguirre ]
* New upstream release 0.21.0 (https://launchpad.net/mir/+milestone/0.21.0)
  - ABI summary:
    . mirclient ABI unchanged at 9
    . mirserver ABI unchanged at 38
    . mircommon ABI unchanged at 5
    . mirplatform ABI unchanged at 11
    . mirprotobuf ABI unchanged at 3
    . mirplatformgraphics ABI unchaged at 8
    . mirclientplatform ABI bumped to 5
    . mirinputplatform ABI unchanged at 5
  - Enhancements:
    . New display enumeration API
    . Added Android diagnostic tests to assist during porting to
      new devices
    . Added mir_demo_client_camera: a Video4Linux2 client
  - Bugs fixed:
    . Sometimes devices don't suspend - display turns back on
      immediately (LP: #1549701)
    . Mir crashed with exception 'failed to add sync point to command
      buffer' (LP: #1554635)
    . Mouse cursor is unusably slow in Unity 8 with a 1000Hz mouse
      (LP: #1539009)
    . Packaged mir_unit_tests binary is not suitable for general use
      (LP: #1547015)
    . [regression] Mir stops receiving input after a pause/resume
      cycle (LP: #1548989)
    . NBS (--nbuffers=0) causes software clients to crash with
      std::exception::what: Failed to mmap buffer 13, "Permission denied")
      (LP: #1550432)
    . Fullscreen clients freeze when using NBS with multiple monitors
      (LP: #1551536)
    . [ FAILED ] DisplayConfigurationTest.output_position_is_independent_of_
      orientation (LP: #1552065)
    . The server-side use of MIR_SOCKET is confusing (LP: #1290345)
    . [regression] FTBFS with -DMIR_LINK_TIME_OPTIMIZATION=on
      -Duse_debflags=on (LP: #1350343)
    . Mir On X (mesa-x11) keeps receiving mouse movement events even
      when not focused (LP: #1528110)
    . x11 platform: mouse cursor moves strange (LP: #1546324)
    . Cross compiling to wily/vivid doesn't work (LP: #1549152)
    . Rendering stutters when a new client establishes a connection
      (LP: #1549359)
    . 'mir_demo_server --test-client' crashes (SIGSEGV) when client
      dies (LP: #1555620)
    . [testfail] CI failure: TestClientInput.client_input_config_request_
      receives_all_attached_devices (LP: #1555708)
    . [regression] Mir FTBFS when MIR_ENABLE_TESTS=no (LP: #1556080)
    . Mir-on-X11 doesn't exit (until it gets an event) (LP: #1556210)
    . InputPlatformProbe.x11_platform_found_and_used_when_display_connection_
      works breaks with old input drivers present (LP: #1543049)
    . [regression] MIR_CLIENT_PERF_REPORT is missing window/surface
      names (LP: #1546933)
    . Installed binaries fail to run with mir_demo_server --test-client XXXX
      (LP: #1556160)
    . mir_demo_server --test-client [mir_demo_client_scroll|
      mir_demo_client_flicker] fails (LP: #1556205)
    . The contents of debian/mir-demos.examples are out of date and useless
      (LP: #1557446)
[ CI Train Bot ]
* No-change rebuild.

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/client/mir_toolkit/mir_display_configuration.h
 
1
/*
 
2
 * Copyright © 2016 Canonical Ltd.
 
3
 *
 
4
 * This program is free software: you can redistribute it and/or modify it
 
5
 * under the terms of the GNU Lesser General Public License version 3,
 
6
 * as published by the Free Software Foundation.
 
7
 *
 
8
 * This program is distributed in the hope that it will be useful,
 
9
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 
10
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
11
 * GNU Lesser General Public License for more details.
 
12
 *
 
13
 * You should have received a copy of the GNU Lesser General Public License
 
14
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
15
 *
 
16
 * Authored by: Christopher James Halse Rogers <christopher.halse.rogers@canonical.com>
 
17
 */
 
18
 
 
19
#ifndef MIR_TOOLKIT_MIR_DISPLAY_CONFIGURATION_H_
 
20
#define MIR_TOOLKIT_MIR_DISPLAY_CONFIGURATION_H_
 
21
 
 
22
#include "client_types.h"
 
23
 
 
24
#ifdef __cplusplus
 
25
extern "C" {
 
26
#endif
 
27
 
 
28
/**
 
29
 * \addtogroup mir_toolkit
 
30
 * @{
 
31
 */
 
32
 
 
33
/**
 
34
 * A descriptor for a display mode.
 
35
 *
 
36
 * A display mode contains all the information necessary to drive a display.  It
 
37
 * includes resolution and refresh rate, but also pixel clock, vsync and hsync
 
38
 * timings, and so on.
 
39
 */
 
40
typedef struct MirOutputMode MirOutputMode;
 
41
 
 
42
/**
 
43
 * Release resources associated with a MirDisplayConfig handle.
 
44
 *
 
45
 * \param [in]  config              The handle to release
 
46
 */
 
47
void mir_display_config_release(MirDisplayConfig* config);
 
48
 
 
49
/**
 
50
 * Get the maximum possible number of simultaneously active outputs this system
 
51
 * supports.
 
52
 *
 
53
 * \note There may be restrictions on the configuration required to achieve this
 
54
 * many active outputs. Typically the achievable number of simultaneously active
 
55
 * outputs is lower than this number.
 
56
 *
 
57
 * \param [in]  config    The configuration to query
 
58
 * \returns      The maximum number of simultaneously active outputs
 
59
 *               supportable at this time.
 
60
 */
 
61
int mir_display_config_get_max_simultaneous_outputs(
 
62
    MirDisplayConfig const* config);
 
63
 
 
64
/**
 
65
 * Get the number of outputs available in this display configuration.
 
66
 *
 
67
 * This returns the total number of outputs the system has. This includes both
 
68
 * enabled and disabled output connections, and is typically larger than the
 
69
 * value returned from mir_display_config_get_max_simultaneous_outputs().
 
70
 *
 
71
 * Typically this will be constant over the lifetime of a client as devices
 
72
 * usually do not gain extra physical ports at runtime. However, hotpluggable
 
73
 * display devices exist and the number of virtual outputs may change at
 
74
 * runtime, so this should always be called to determine the number of outputs
 
75
 * to iterate over.
 
76
 *
 
77
 * \param [in]  config    The configuration to query
 
78
 * \returns      The number of outputs available in this configuration.
 
79
 */
 
80
int mir_display_config_get_num_outputs(MirDisplayConfig const* config);
 
81
 
 
82
/**
 
83
 * Get a read-only handle to the index 'th output of this configuration
 
84
 *
 
85
 * \note The MirOutput handle is only valid while config is valid.
 
86
 * \pre 0 <= index < mir_display_config_get_num_outputs(config)
 
87
 * \param [in]  config  The configuration to query
 
88
 * \param [in]  index   The index of the output to get
 
89
 * \returns     A read-only handle to a MirOutput within config which is valid
 
90
 *              until mir_display_config_release(config) is called.
 
91
 */
 
92
MirOutput const* mir_display_config_get_output(MirDisplayConfig const* config,
 
93
    size_t index);
 
94
 
 
95
/**
 
96
 * Get the number of modes in the supported mode list of this output.
 
97
 *
 
98
 * The list of supported modes is retrieved from the hardware, possibly modified
 
99
 * by any applicable quirk tables, and may not be exhaustive.
 
100
 *
 
101
 * \param [in]  output  The MirOutput to query
 
102
 * \returns     The number of modes in the supported mode list of output.
 
103
 */
 
104
int mir_output_get_num_modes(MirOutput const* output);
 
105
 
 
106
/**
 
107
 * Get a handle for a mode descriptor from the list of supported modes.
 
108
 *
 
109
 * The list of supported modes is retrieved from the hardware, possibly modified
 
110
 * by any applicable quirk tables, and may not be exhaustive.
 
111
 *
 
112
 * \pre 0 <= index < mir_output_get_num_modes(output)
 
113
 * \note    The handle remains valid as long as output is valid.
 
114
 *
 
115
 * \param [in]  output  The MirOutput to query
 
116
 * \param [in]  index   The index of the mode to retrieve.
 
117
 * \returns     A handle for a description of the supported mode. This is valid
 
118
 *              for as long as output is valid. The return value is never null.
 
119
 */
 
120
MirOutputMode const* mir_output_get_mode(MirOutput const* output, size_t index);
 
121
 
 
122
/**
 
123
 * Get a handle to the output's preferred mode.
 
124
 *
 
125
 * This is provided by the output itself. For modern displays (LCD, OLED, etc)
 
126
 * it is typically a mode with the native resolution.
 
127
 *
 
128
 * An output may not have a preferred mode, in which case this call will return
 
129
 * NULL.
 
130
 *
 
131
 * \note    The handle remains valid as long as output is valid.
 
132
 *
 
133
 * \param [in]  output  The MirOutput to query
 
134
 * \returns     A handle for a description of the supported mode. This is valid
 
135
 *              for as long as output is valid. If the output does not have a
 
136
 *              preferred mode, it returns NULL.
 
137
 */
 
138
MirOutputMode const* mir_output_get_preferred_mode(MirOutput const* output);
 
139
 
 
140
/**
 
141
 * Get a handle to the output's current mode.
 
142
 *
 
143
 * An output may not have a current mode (for example, if it is disabled), in
 
144
 * which case this call will return NULL.
 
145
 *
 
146
 * \note    The handle remains valid as long as output is valid.
 
147
 *
 
148
 * \param [in]  output  The MirOutput to query
 
149
 * \returns     A handle for a description of the supported mode. This is valid
 
150
 *              for as long as output is valid. If the output does not have a
 
151
 *              current mode, it returns NULL.
 
152
 */
 
153
MirOutputMode const* mir_output_get_current_mode(MirOutput const* output);
 
154
 
 
155
/**
 
156
 * Get the number of pixel formats supported by this output
 
157
 *
 
158
 * \param [in]  output  The MirOutput to query
 
159
 * \returns     The number of pixel formats for output.
 
160
 */
 
161
int mir_output_get_num_pixel_formats(MirOutput const* output);
 
162
 
 
163
/**
 
164
 * Get a pixel format from the list of supported formats
 
165
 *
 
166
 * \pre 0 <= index < mir_output_get_num_pixel_formats(output)
 
167
 *
 
168
 * \param [in] output  The MirOutput to query
 
169
 * \param [in] index   The index of the format to query
 
170
 * \returns    The index 'th supported pixel format.
 
171
 */
 
172
MirPixelFormat mir_output_get_pixel_format(MirOutput const* output,
 
173
    size_t index);
 
174
 
 
175
/**
 
176
 * Get the current pixel format.
 
177
 *
 
178
 * \param [in]  output  The MirOutput to query
 
179
 * \returns     The current pixel format. This may be mir_pixel_format_invalid
 
180
 *              (for example, if the output is not currently enabled).
 
181
 */
 
182
MirPixelFormat mir_output_get_current_pixel_format(MirOutput const* output);
 
183
 
 
184
/**
 
185
 * Set the output format
 
186
 *
 
187
 * \param [in]  output  The MirOutput to modify
 
188
 * \param [in]  format  The MirPixelFormat to set
 
189
 */
 
190
void mir_output_set_pixel_format(MirOutput* output, MirPixelFormat format);
 
191
 
 
192
/**
 
193
 * Get the ID of an output
 
194
 *
 
195
 * This can be used to refer to the output in other parts of the API, such as
 
196
 * mir_surface_spec_set_fullscreen_on_output().
 
197
 *
 
198
 * \param [in]  output  The MirOutput to query.
 
199
 * \returns     The ID of output, which may be used to refer to it in other
 
200
 *              parts of the API.
 
201
 */
 
202
int mir_output_get_id(MirOutput const* output);
 
203
 
 
204
/**
 
205
 * Get the physical connection type of an output.
 
206
 *
 
207
 * This is a best-effort determination, and may be incorrect.
 
208
 *
 
209
 * \param [in]  output  The MirOutput to query
 
210
 * \returns     The type of the display connection, or mir_output_type_unknown
 
211
 *              if it cannot be determined.
 
212
 */
 
213
MirOutputType mir_output_get_type(MirOutput const* output);
 
214
 
 
215
/**
 
216
 * Get the x coordinate of the top-left point of the output in the virtual
 
217
 * display space.
 
218
 *
 
219
 * Outputs can be thought of as viewports into a virtual display space. They may
 
220
 * freely overlap, coincide, or be disjoint as desired.
 
221
 *
 
222
 * Output orientation changes the orientation of the output rectangle in virtual
 
223
 * display space, but does not change its top-left corner.
 
224
 *
 
225
 * \param [in]  output  The MirOutput to query
 
226
 * \returns     The x coordinate of the top-left point of the output in the
 
227
 *              virtual display space.
 
228
 */
 
229
int mir_output_get_position_x(MirOutput const* output);
 
230
 
 
231
/**
 
232
 * Get the y coordinate of the top-left point of the output in the virtual
 
233
 * display space.
 
234
 *
 
235
 * Outputs can be thought of as viewports into a virtual display space. They may
 
236
 * freely overlap, coincide, or be disjoint as desired.
 
237
 *
 
238
 * Output orientation changes the orientation of the output rectangle in virtual
 
239
 * display space, but does not change its top-left corner.
 
240
 *
 
241
 * \param [in]  output  The MirOutput to query
 
242
 * \returns     The y coordinate of the top-left point of the output in the
 
243
 *              virtual display space.
 
244
 */
 
245
int mir_output_get_position_y(MirOutput const* output);
 
246
 
 
247
/**
 
248
 * Get whether there is a display physically connected to the output.
 
249
 *
 
250
 * This gives a best-effort determination of whether or not enabling this output
 
251
 * will result in an image being displayed to the user.
 
252
 *
 
253
 * The accuracy of this determination varies with connection type - for example,
 
254
 * for DisplayPort and HDMI connections a return value of
 
255
 * mir_output_connection_state_connected is usually a reliable indicator that
 
256
 * there is a powered-on display connected.
 
257
 *
 
258
 * VGA and DVI connectors can usually determine whether or not there is a
 
259
 * physically connected display, but cannot distinguish between a powered or
 
260
 * unpowered display.
 
261
 *
 
262
 * It is not always possible to determine whether or not there is a display
 
263
 * connected; in such cases mir_output_connection_state_unknown is returned.
 
264
 *
 
265
 * \param [in]  output  The MirOutput to query
 
266
 * \returns     Whether there is a display connected to this output.
 
267
 */
 
268
MirOutputConnectionState mir_output_get_connection_state(
 
269
    MirOutput const* output);
 
270
 
 
271
/**
 
272
 * Get whether this output is enabled in the current configuration.
 
273
 *
 
274
 * \param [in]  output  the MirOutput to query
 
275
 * \returns     Whether the output is enabled.
 
276
 */
 
277
bool mir_output_is_enabled(MirOutput const* output);
 
278
 
 
279
/**
 
280
 * Get the physical width of the connected display, in millimetres.
 
281
 *
 
282
 * A best-effort report of the physical width of the display connected to this
 
283
 * output. This is retrieved from the display hardware, possibly modified by any
 
284
 * applicable quirk tables.
 
285
 *
 
286
 * Where this information is unavailable or inapplicable (for example,
 
287
 * projectors), 0 is returned.
 
288
 *
 
289
 * \param [in]  output  the MirOutput to query
 
290
 * \returns     Physical width of the connected display, in mm.
 
291
 */
 
292
int mir_output_get_physical_width_mm(MirOutput const* output);
 
293
 
 
294
/**
 
295
 * Get the physical height of the connected display, in millimetres.
 
296
 *
 
297
 * A best-effort report of the physical height of the display connected to this
 
298
 * output. This is retrieved from the display hardware, possibly modified by any
 
299
 * applicable quirk tables.
 
300
 *
 
301
 * Where this information is unavailable or inapplicable (for example,
 
302
 * projectors), 0 is returned.
 
303
 *
 
304
 * \param [in]  output  the MirOutput to query
 
305
 * \returns     Physical height of the connected display, in mm.
 
306
 */
 
307
int mir_output_get_physical_height_mm(MirOutput const* output);
 
308
 
 
309
/**
 
310
 * Get the power state of a connected display.
 
311
 *
 
312
 * It is undefined which power state is returned for an output which is not
 
313
 * connected.
 
314
 *
 
315
 * \param [in]  output  The MirOutput to query
 
316
 * \returns     The power state of the display connected to output.
 
317
 */
 
318
MirPowerMode mir_output_get_power_mode(MirOutput const* output);
 
319
 
 
320
/**
 
321
 * Get the orientation of a display.
 
322
 *
 
323
 * \param [in]  output  The MirOutput to query
 
324
 * \returns     The orientation of output
 
325
 */
 
326
MirOrientation mir_output_get_orientation(MirOutput const* output);
 
327
 
 
328
/**
 
329
 * Get the scale-factor of a display
 
330
 *
 
331
 * The scale-factor specifies the conversion between logical pixels and physical pixels on this output.
 
332
 *
 
333
 * A surface with dimensions 200×100 on an output with scale-factor 2.0 will display 400x200 pixels
 
334
 * on this output, will display 300x150 pixels on an output with scale-factor 1.5, and so on.
 
335
 *
 
336
 * Where this calculation would result in a fractional number of pixels the floor is used, so a surface with
 
337
 * dimensions 101x100 on an output with scale-factor of 1.5 will display 151x150 pixels, not 152x150.
 
338
 *
 
339
 * \param [in]  output  The MirOutput to query
 
340
 * \returns     The scale-factor of this monitor
 
341
 */
 
342
float mir_output_get_scale_factor(MirOutput const* output);
 
343
 
 
344
/**
 
345
 * Get the form-factor of a connected output.
 
346
 *
 
347
 * This call succeeds even if the output is not connected, but may return nonsense values.
 
348
 *
 
349
 * \param [in]  output  The MirOutput to query
 
350
 * \returns     The form factor of this output
 
351
 */
 
352
MirFormFactor mir_output_get_form_factor(MirOutput const* output);
 
353
 
 
354
/**
 
355
 * Get the width, in pixels, of a MirOutputMode
 
356
 *
 
357
 * \note    This is unaffected by the orientation of the output
 
358
 *
 
359
 * \param [in] mode    The MirOutputMode to query
 
360
 * \returns     The width, in pixels, of mode.
 
361
 */
 
362
int mir_output_mode_get_width(MirOutputMode const* mode);
 
363
 
 
364
/** Get the height, in pixels, of a MirOutputMode
 
365
 *
 
366
 * \note    This is unaffected by the orientation of the output
 
367
 *
 
368
 * \param [in] mode    The MirOutputMode to query
 
369
 * \returns     The height, in pixels, of mode.
 
370
 */
 
371
int mir_output_mode_get_height(MirOutputMode const* mode);
 
372
 
 
373
/** Get the refresh rate, in Hz, of a MirOutputMode
 
374
 *
 
375
 * \param [in]  mode    The MirOutputMode to query
 
376
 * \returns     The refresh rate, in Hz, of mode
 
377
 */
 
378
double mir_output_mode_get_refresh_rate(MirOutputMode const* mode);
 
379
 
 
380
/**@}*/
 
381
 
 
382
#ifdef __cplusplus
 
383
}
 
384
#endif
 
385
 
 
386
#endif //MIR_TOOLKIT_MIR_DISPLAY_CONFIGURATION_H_