egl: document which driver hooks are only required by extensions

Signed-off-by: Eric Engestrom <eric@engestrom.ch>
Reviewed-by: Frank Binns <frank.binns@imgtec.com>
Reviewed-by: Emil Velikov <emil.velikov@collabora.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/6130>

docs/egl.rst

@@ -128,6 +128,8 @@ succeeded (as per EGL spec).
 
 A driver _could_ implement all the other EGL API functions, but several of
 them are only needed for extensions, like ``eglSwapBuffersWithDamageEXT()``.
+See ``src/egl/main/egldriver.h`` to see which driver hooks are only
+required by extensions.
 
 Bootstrapping
 ~~~~~~~~~~~~~

src/egl/main/egldriver.h

@@ -117,6 +117,8 @@ struct _egl_driver
    EGLBoolean (*SwapBuffers)(_EGLDisplay *disp, _EGLSurface *draw);
    EGLBoolean (*CopyBuffers)(_EGLDisplay *disp, _EGLSurface *surface,
                              void *native_pixmap_target);
+
+   /* for EGL_KHR_partial_update */
    EGLBoolean (*SetDamageRegion)(_EGLDisplay *disp, _EGLSurface *surface,
                                  EGLint *rects, EGLint n_rects);
 
@@ -127,45 +129,61 @@ struct _egl_driver
    /* this function may be called from multiple threads at the same time */
    _EGLProc (*GetProcAddress)(const char *procname);
 
+   /* for EGL_KHR_image_base */
    _EGLImage *(*CreateImageKHR)(_EGLDisplay *disp, _EGLContext *ctx,
                                 EGLenum target, EGLClientBuffer buffer,
                                 const EGLint *attr_list);
    EGLBoolean (*DestroyImageKHR)(_EGLDisplay *disp, _EGLImage *image);
 
+   /* for EGL_KHR_reusable_sync/EGL_KHR_fence_sync */
    _EGLSync *(*CreateSyncKHR)(_EGLDisplay *disp, EGLenum type,
                               const EGLAttrib *attrib_list);
    EGLBoolean (*DestroySyncKHR)(_EGLDisplay *disp, _EGLSync *sync);
    EGLint (*ClientWaitSyncKHR)(_EGLDisplay *disp, _EGLSync *sync,
                                EGLint flags, EGLTime timeout);
    EGLint (*WaitSyncKHR)(_EGLDisplay *disp, _EGLSync *sync);
+   /* for EGL_KHR_reusable_sync */
    EGLBoolean (*SignalSyncKHR)(_EGLDisplay *disp, _EGLSync *sync, EGLenum mode);
+
+   /* for EGL_ANDROID_native_fence_sync */
    EGLint (*DupNativeFenceFDANDROID)(_EGLDisplay *disp, _EGLSync *sync);
 
+   /* for EGL_NOK_swap_region */
    EGLBoolean (*SwapBuffersRegionNOK)(_EGLDisplay *disp, _EGLSurface *surf,
                                       EGLint numRects, const EGLint *rects);
 
+   /* for EGL_MESA_drm_image */
    _EGLImage *(*CreateDRMImageMESA)(_EGLDisplay *disp, const EGLint *attr_list);
    EGLBoolean (*ExportDRMImageMESA)(_EGLDisplay *disp, _EGLImage *img,
                                     EGLint *name, EGLint *handle,
                                     EGLint *stride);
 
+   /* for EGL_WL_bind_wayland_display */
    EGLBoolean (*BindWaylandDisplayWL)(_EGLDisplay *disp, struct wl_display *display);
    EGLBoolean (*UnbindWaylandDisplayWL)(_EGLDisplay *disp, struct wl_display *display);
    EGLBoolean (*QueryWaylandBufferWL)(_EGLDisplay *displ, struct wl_resource *buffer,
                                       EGLint attribute, EGLint *value);
+
+   /* for EGL_WL_create_wayland_buffer_from_image */
    struct wl_buffer *(*CreateWaylandBufferFromImageWL)(_EGLDisplay *disp, _EGLImage *img);
 
+   /* for EGL_EXT_swap_buffers_with_damage */
    EGLBoolean (*SwapBuffersWithDamageEXT)(_EGLDisplay *disp, _EGLSurface *surface,
                                           const EGLint *rects, EGLint n_rects);
 
+   /* for EGL_NV_post_sub_buffer */
    EGLBoolean (*PostSubBufferNV)(_EGLDisplay *disp, _EGLSurface *surface,
                                  EGLint x, EGLint y, EGLint width, EGLint height);
 
+   /* for EGL_EXT_buffer_age/EGL_KHR_partial_update */
    EGLint (*QueryBufferAge)(_EGLDisplay *disp, _EGLSurface *surface);
+
+   /* for EGL_CHROMIUM_sync_control */
    EGLBoolean (*GetSyncValuesCHROMIUM)(_EGLDisplay *disp, _EGLSurface *surface,
                                        EGLuint64KHR *ust, EGLuint64KHR *msc,
                                        EGLuint64KHR *sbc);
 
+   /* for EGL_MESA_image_dma_buf_export */
    EGLBoolean (*ExportDMABUFImageQueryMESA)(_EGLDisplay *disp, _EGLImage *img,
                                             EGLint *fourcc, EGLint *nplanes,
                                             EGLuint64KHR *modifiers);
@@ -173,15 +191,18 @@ struct _egl_driver
                                        EGLint *fds, EGLint *strides,
                                        EGLint *offsets);
 
+   /* for EGL_MESA_query_driver */
    const char *(*QueryDriverName)(_EGLDisplay *disp);
    char *(*QueryDriverConfig)(_EGLDisplay *disp);
 
+   /* for OpenGL-OpenCL interop; see include/GL/mesa_glinterop.h */
    int (*GLInteropQueryDeviceInfo)(_EGLDisplay *disp, _EGLContext *ctx,
                                    struct mesa_glinterop_device_info *out);
    int (*GLInteropExportObject)(_EGLDisplay *disp, _EGLContext *ctx,
                                 struct mesa_glinterop_export_in *in,
                                 struct mesa_glinterop_export_out *out);
 
+   /* for EGL_EXT_image_dma_buf_import_modifiers */
    EGLBoolean (*QueryDmaBufFormatsEXT)(_EGLDisplay *disp,
                                        EGLint max_formats, EGLint *formats,
                                        EGLint *num_formats);
@@ -190,6 +211,7 @@ struct _egl_driver
                                          EGLBoolean *external_only,
                                          EGLint *num_modifiers);
 
+   /* for EGL_ANDROID_blob_cache */
    void (*SetBlobCacheFuncsANDROID)(_EGLDisplay *disp,
                                     EGLSetBlobFuncANDROID set,
                                     EGLGetBlobFuncANDROID get);