[gtk/wip/otte/float-textures: 8/10] gdk: Deprecate gdk_cairo_draw_from_gl()

[Benjamin Otte <otte src gnome org>]

commit 88f84d9abef5b21bc9b09656a5520dd3d3681528
Author: Benjamin Otte <otte redhat com>
Date:   Sun Sep 12 00:10:10 2021 +0200

    gdk: Deprecate gdk_cairo_draw_from_gl()
    
    It's broken with various pixel formats and OpenGL ES, it's hard to
    understand what everything does, and gdk_texture_download() can be used
    instead.

 gdk/gdkcairo.h | 2 +-
 gdk/gdkgl.c    | 8 +++++++-
 2 files changed, 8 insertions(+), 2 deletions(-)
---
diff --git a/gdk/gdkcairo.h b/gdk/gdkcairo.h
index 40ab46baf6..f2dfa3177e 100644
--- a/gdk/gdkcairo.h
+++ b/gdk/gdkcairo.h
@@ -50,7 +50,7 @@ cairo_region_t *
            gdk_cairo_region_create_from_surface
                                         (cairo_surface_t      *surface);
 
-GDK_AVAILABLE_IN_ALL
+GDK_DEPRECATED_IN_4_6_FOR(gdk_gl_texture_new)
 void       gdk_cairo_draw_from_gl (cairo_t              *cr,
                                    GdkSurface            *surface,
                                    int                   source,
diff --git a/gdk/gdkgl.c b/gdk/gdkgl.c
index 4e57853afb..b22446e30f 100644
--- a/gdk/gdkgl.c
+++ b/gdk/gdkgl.c
@@ -301,7 +301,7 @@ gdk_gl_texture_quads (GdkGLContext *paint_context,
  * @width: The width of the region to draw
  * @height: The height of the region to draw
  *
- * The main way to draw GL content in GTK.
+ * The main way to not draw GL content in GTK.
  *
  * It takes a render buffer ID (@source_type == GL_RENDERBUFFER) or a texture
  * id (@source_type == GL_TEXTURE) and draws it onto @cr with an OVER operation,
@@ -319,6 +319,12 @@ gdk_gl_texture_quads (GdkGLContext *paint_context,
  * with alpha components, so make sure you use GL_TEXTURE if using alpha.
  *
  * Calling this may change the current GL context.
+ *
+ * Deprecated: 4.6: The function is overly complex and produces broken output
+ *   in various combinations of arguments. If you want to draw with GL textures
+ *   in GTK, use [method Gdk GLTexture new]; if you want to use that texture in
+ *   Cairo, use [method@Gdk.Texture.download] to download the data into a Cairo
+ *   image surface.
  */
 void
 gdk_cairo_draw_from_gl (cairo_t              *cr,