From: Pekka Paalanen <pekka.paalanen@collabora.com>
Date: Thu, 19 Sep 2019 11:25:53 +0000 (+0300)
Subject: gl-renderer: document output_window_create
X-Git-Tag: upstream/9.0.0~360
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=53b7fd70b833608fecd0e7f079ccd8c2f4bd0ebf;p=platform%2Fupstream%2Fweston.git

gl-renderer: document output_window_create

Even if it is internal, it is a non-trivial interface and deserves
documentation.

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 545533e4..9aac993a 100644
--- a/libweston/renderer-gl/gl-renderer.h
+++ b/libweston/renderer-gl/gl-renderer.h
@@ -102,6 +102,33 @@ struct gl_renderer_interface {
 			      const uint32_t *drm_formats,
 			      unsigned drm_formats_count);
 
+	/**
+	 * Attach GL-renderer to the output with a native window
+	 *
+	 * \param output The output to create a rendering surface for.
+	 * \param window_for_legacy Native window handle for
+	 * eglCreateWindowSurface().
+	 * \param window_for_platform Native window handle for
+	 * eglCreatePlatformWindowSurface().
+	 * \param drm_formats Array of DRM pixel formats that are acceptable.
+	 * \param drm_formats_count The drm_formats array length.
+	 * \return 0 on success, -1 on failure.
+	 *
+	 * This function creates the renderer data structures needed to repaint
+	 * the output. The repaint results will be directed to the given native
+	 * window.
+	 *
+	 * If EGL_EXT_platform_base is supported then \c window_for_platform is
+	 * used, otherwise \c window_for_legacy is used. This is because the
+	 * handle on X11 platform is different between the two.
+	 *
+	 * The first format in drm_formats that matches any EGLConfig
+	 * determines which EGLConfig is chosen. See \c display_create about
+	 * how the matching works and the possible limitations.
+	 *
+	 * This function should be used only if \c display_create was called
+	 * with \c EGL_WINDOW_BIT in \c egl_surface_type.
+	 */
 	int (*output_window_create)(struct weston_output *output,
 				    EGLNativeWindowType window_for_legacy,
 				    void *window_for_platform,