Merge lp:~vanvugt/mir/one-for-robert-ancell into lp:mir

[Daniel van Vugt]

Document the awkward (but improving) situation of "supported"
pixel formats. For Robert Ancell.

[Robert Ancell (robert-ancell)]

Quite a bit wordier than is ideal but a definite improvement on the current situation.

review: Approve

[lp:~vanvugt/mir/one-for-robert-ancell]

2794. By Daniel van Vugt on 2015-07-29

Less wordy

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:2793
http://jenkins.qa.ubuntu.com/job/mir-ci/4434/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-android-vivid-i386-build/3338
    SUCCESS: http://s-jenkins.ubuntu-ci:8080/job/mir-clang-ts-wily-amd64-build/191
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-clang-wily-amd64-build/863
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-vivid-touch/3286
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-wily-amd64-ci/583
        deb: http://jenkins.qa.ubuntu.com/job/mir-wily-amd64-ci/583/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-builder-vivid-armhf/3286
        deb: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-builder-vivid-armhf/3286/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-runner-mako/6082
    SUCCESS: http://s-jenkins.ubuntu-ci:8080/job/touch-flash-device/22187

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/4434/rebuild

review: Approve (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:2794
http://jenkins.qa.ubuntu.com/job/mir-ci/4436/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-android-vivid-i386-build/3341
    SUCCESS: http://s-jenkins.ubuntu-ci:8080/job/mir-clang-ts-wily-amd64-build/194
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-clang-wily-amd64-build/866
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-vivid-touch/3289
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-wily-amd64-ci/585
        deb: http://jenkins.qa.ubuntu.com/job/mir-wily-amd64-ci/585/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-builder-vivid-armhf/3289
        deb: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-builder-vivid-armhf/3289/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-runner-mako/6085
    SUCCESS: http://s-jenkins.ubuntu-ci:8080/job/touch-flash-device/22190

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/4436/rebuild

review: Approve (continuous-integration)

[Alan Griffiths (alan-griffiths)]

OK

review: Approve

=== modified file 'include/client/mir_toolkit/mir_connection.h'
--- include/client/mir_toolkit/mir_connection.h	2015-07-25 08:10:48 +0000
+++ include/client/mir_toolkit/mir_connection.h	2015-07-29 09:35:42 +0000
@@ -200,6 +200,14 @@
  *   \param [out] formats           List of valid formats to create surfaces with
  *   \param [in]  formats_size      size of formats list
  *   \param [out] num_valid_formats number 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.
  */
 void mir_connection_get_available_surface_formats(
     MirConnection* connection, MirPixelFormat* formats,