gl-renderer: document display_create

Some of this is a little convoluted to figure out from the code.

Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>

diff --git a/libweston/renderer-gl/gl-renderer.h b/libweston/renderer-gl/gl-renderer.h
index a9187be8cc786aab94814dbe0d5f158ae855aaa7..545533e49873f02b15e52e9fd054ea4bf1820526 100644 (file)
--- a/libweston/renderer-gl/gl-renderer.h
+++ b/libweston/renderer-gl/gl-renderer.h
@@ -59,6 +59,42 @@ enum gl_renderer_border_side {
 };
 
 struct gl_renderer_interface {
+       /**
+        * Initialize GL-renderer with the given EGL platform and native display
+        *
+        * \param ec The weston_compositor where to initialize.
+        * \param platform The EGL platform identifier.
+        * \param native_display The native display corresponding to the given
+        * EGL platform.
+        * \param egl_surface_type EGL_SURFACE_TYPE bits for the base EGLConfig.
+        * \param drm_formats Array of DRM pixel formats that are acceptable
+        * for the base EGLConfig.
+        * \param drm_formats_count The drm_formats array length.
+        * \return 0 on success, -1 on failure.
+        *
+        * This function creates an EGLDisplay and initializes it. It also
+        * creates the GL ES context and sets it up. It attempts GL ES 3.0
+        * and falls back to GL ES 2.0 if 3.0 is not supported.
+        *
+        * If \c platform is zero or EGL_EXT_platform_base is not supported,
+        * choosing the platform is left for the EGL implementation. Otherwise
+        * the given platform is used explicitly if the EGL implementation
+        * advertises it. Without the advertisement this function fails.
+        *
+        * If neither EGL_KHR_no_config_context or EGL_MESA_configless_context
+        * are supported, the arguments egl_surface_type, drm_formats, and
+        * drm_formats_count are used to find a so called base EGLConfig. The
+        * GL context is created with the base EGLConfig, and outputs will be
+        * required to use the same config as well. If one or both of the
+        * extensions are supported, these arguments are unused, and each
+        * output can use a different EGLConfig (pixel format).
+        *
+        * The first format in drm_formats that matches any EGLConfig
+        * determines which EGLConfig is chosen. On EGL GBM platform, the
+        * pixel format must match exactly. On other platforms, it is enough
+        * that each R, G, B, A channel has the same number of bits as in the
+        * DRM format.
+        */
        int (*display_create)(struct weston_compositor *ec,
                              EGLenum platform,
                              void *native_display,