From 0010f8380a826c39c53553bb084ad1d95c76f015 Mon Sep 17 00:00:00 2001 From: Pekka Paalanen Date: Thu, 19 Sep 2019 13:22:58 +0300 Subject: [PATCH] gl-renderer: document display_create Some of this is a little convoluted to figure out from the code. Signed-off-by: Pekka Paalanen --- libweston/renderer-gl/gl-renderer.h | 36 +++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/libweston/renderer-gl/gl-renderer.h b/libweston/renderer-gl/gl-renderer.h index a9187be8..545533e4 100644 --- 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,