texture-rectangle: Make new_from_foreign api public

This adds a new public cogl_texture_rectangle_new_from_foreign()
function so that we can look at removing the generic
cogl_texture_new_from_foreign().

Reviewed-by: Neil Roberts <neil@linux.intel.com>

(cherry picked from commit af02792b336bb492c5bd11afc34a5dcd417503f6)

cogl/cogl-texture-rectangle.c

@@ -294,29 +294,35 @@ cogl_texture_rectangle_new_from_bitmap (CoglBitmap *bmp,
 }
 
 CoglTextureRectangle *
-_cogl_texture_rectangle_new_from_foreign (GLuint gl_handle,
-                                          GLuint width,
-                                          GLuint height,
-                                          CoglPixelFormat format)
+cogl_texture_rectangle_new_from_foreign (CoglContext *ctx,
+                                         unsigned int gl_handle,
+                                         int width,
+                                         int height,
+                                         CoglPixelFormat format,
+                                         GError **error)
 {
   /* NOTE: width, height and internal format are not queriable
    * in GLES, hence such a function prototype.
    */
 
-  GLenum                gl_error      = 0;
-  GLint                 gl_compressed = GL_FALSE;
-  GLenum                gl_int_format = 0;
+  GLenum gl_error = 0;
+  GLint gl_compressed = GL_FALSE;
+  GLenum gl_int_format = 0;
   CoglTextureRectangle *tex_rect;
 
-  _COGL_GET_CONTEXT (ctx, NULL);
+  /* Assert that it is a valid GL texture object */
+  g_return_val_if_fail (ctx->glIsTexture (gl_handle), NULL);
 
   if (!ctx->texture_driver->allows_foreign_gl_target (ctx,
                                                       GL_TEXTURE_RECTANGLE_ARB))
-    return NULL;
-
-  /* Make sure it is a valid GL texture object */
-  if (!ctx->glIsTexture (gl_handle))
-    return NULL;
+    {
+      g_set_error (error,
+                   COGL_ERROR,
+                   COGL_ERROR_UNSUPPORTED,
+                   "Foreign GL_TEXTURE_RECTANGLE textures are not "
+                   "supported by your system");
+      return NULL;
+    }
 
   /* Make sure binding succeeds */
   while ((gl_error = ctx->glGetError ()) != GL_NO_ERROR)
@@ -324,7 +330,13 @@ _cogl_texture_rectangle_new_from_foreign (GLuint gl_handle,
 
   _cogl_bind_gl_texture_transient (GL_TEXTURE_RECTANGLE_ARB, gl_handle, TRUE);
   if (ctx->glGetError () != GL_NO_ERROR)
-    return NULL;
+    {
+      g_set_error (error,
+                   COGL_ERROR,
+                   COGL_ERROR_UNSUPPORTED,
+                   "Failed to bind foreign GL_TEXTURE_RECTANGLE texture");
+      return NULL;
+    }
 
   /* Obtain texture parameters */
 
@@ -348,7 +360,13 @@ _cogl_texture_rectangle_new_from_foreign (GLuint gl_handle,
       if (!ctx->driver_vtable->pixel_format_from_gl_internal (ctx,
                                                               gl_int_format,
                                                               &format))
-        return NULL;
+        {
+          g_set_error (error,
+                       COGL_ERROR,
+                       COGL_ERROR_UNSUPPORTED,
+                       "Unsupported internal format for foreign texture");
+          return NULL;
+        }
     }
   else
 #endif
@@ -370,12 +388,17 @@ _cogl_texture_rectangle_new_from_foreign (GLuint gl_handle,
    */
 
   /* Validate width and height */
-  if (width <= 0 || height <= 0)
-    return NULL;
+  g_return_val_if_fail (width > 0 && height > 0, NULL);
 
   /* Compressed texture images not supported */
   if (gl_compressed == GL_TRUE)
-    return NULL;
+    {
+      g_set_error (error,
+                   COGL_ERROR,
+                   COGL_ERROR_UNSUPPORTED,
+                   "Compressed foreign textures aren't currently supported");
+      return NULL;
+    }
 
   /* Create new texture */
   tex_rect = _cogl_texture_rectangle_create_base (ctx, width, height, format);

cogl/cogl-texture-rectangle.h

@@ -89,6 +89,12 @@ cogl_is_texture_rectangle (void *object);
  * the GPU can sample from directly unlike high-level textures such
  * as #CoglTexture2DSliced and #CoglAtlasTexture.
  *
+ * <note>Unlike for #CoglTexture2D textures, coordinates for
+ * #CoglTextureRectangle textures should not be normalized. So instead
+ * of using the coordinate (1, 1) to sample the bottom right corner of
+ * a rectangle texture you would use (@width, @height) where @width
+ * and @height are the width and height of the texture.</note>
+ *
  * <note>If you want to sample from a rectangle texture from GLSL you
  * should use the sampler2DRect sampler type.</note>
  *
@@ -124,6 +130,12 @@ cogl_texture_rectangle_new_with_size (CoglContext *ctx,
  * directly unlike high-level textures such as #CoglTexture2DSliced
  * and #CoglAtlasTexture.
  *
+ * <note>Unlike for #CoglTexture2D textures, coordinates for
+ * #CoglTextureRectangle textures should not be normalized. So instead
+ * of using the coordinate (1, 1) to sample the bottom right corner of
+ * a rectangle texture you would use (@width, @height) where @width
+ * and @height are the width and height of the texture.</note>
+ *
  * <note>If you want to sample from a rectangle texture from GLSL you
  * should use the sampler2DRect sampler type.</note>
  *
@@ -142,6 +154,51 @@ cogl_texture_rectangle_new_from_bitmap (CoglBitmap *bitmap,
                                         CoglPixelFormat internal_format,
                                         GError **error);
 
+/**
+ * cogl_texture_rectangle_new_from_foreign:
+ * @ctx: A #CoglContext
+ * @gl_handle: A GL handle for a GL_TEXTURE_RECTANGLE texture object
+ * @width: Width of the foreign GL texture
+ * @height: Height of the foreign GL texture
+ * @internal_format: The format of the texture
+ * @error: A #GError for exceptions
+ *
+ * Wraps an existing GL_TEXTURE_RECTANGLE texture object as a
+ * #CoglTextureRectangle.  This can be used for integrating Cogl with
+ * software using OpenGL directly.
+ *
+ * <note>Unlike for #CoglTexture2D textures, coordinates for
+ * #CoglTextureRectangle textures should not be normalized. So instead
+ * of using the coordinate (1, 1) to sample the bottom right corner of
+ * a rectangle texture you would use (@width, @height) where @width
+ * and @height are the width and height of the texture.</note>
+ *
+ * <note>The results are undefined for passing an invalid @gl_handle
+ * or if @width or @height don't have the correct texture
+ * geometry.</note>
+ *
+ * <note>If you want to sample from a rectangle texture from GLSL you
+ * should use the sampler2DRect sampler type.</note>
+ *
+ * <note>Applications wanting to use #CoglTextureRectangle should
+ * first check for the %COGL_FEATURE_ID_TEXTURE_RECTANGLE feature
+ * using cogl_has_feature().</note>
+
+ * Returns: A newly allocated #CoglTextureRectangle, or if Cogl could
+ *          not validate the @gl_handle in some way (perhaps because
+ *          of an unsupported format) it will return %NULL and set
+ *          @error.
+ *
+
+ */
+CoglTextureRectangle *
+cogl_texture_rectangle_new_from_foreign (CoglContext *ctx,
+                                         unsigned int gl_handle,
+                                         int width,
+                                         int height,
+                                         CoglPixelFormat format,
+                                         GError **error);
+
 G_END_DECLS
 
 #endif /* __COGL_TEXURE_RECTANGLE_H */

cogl/cogl-texture.c

@@ -503,10 +503,13 @@ cogl_texture_new_from_foreign (GLuint           gl_handle,
           return NULL;
         }
 
-      texture_rectangle = _cogl_texture_rectangle_new_from_foreign (gl_handle,
-                                                                    width,
-                                                                    height,
-                                                                    format);
+      texture_rectangle = cogl_texture_rectangle_new_from_foreign (ctx,
+                                                                   gl_handle,
+                                                                   width,
+                                                                   height,
+                                                                   format,
+                                                                   NULL);
+
       /* CoglTextureRectangle textures work with non-normalized
        * coordinates, but the semantics for this function that people
        * depend on are that all returned texture works with normalized