[cogl] Remove cogl-auto-texture apis

From: Robert Bragg <rbragg src gnome org>
To: commits-list gnome org
Cc:
Subject: [cogl] Remove cogl-auto-texture apis
Date: Thu, 11 Jul 2013 21:02:47 +0000 (UTC)
commit 8d24270567ad135fee75491a9477e8ff053066c4
Author: Robert Bragg <robert linux intel com>
Date:   Sat Jun 8 19:02:43 2013 +0100

    Remove cogl-auto-texture apis
    
    This removes the automagic texture constructors including:
    cogl_texture_new_with_size
    cogl_texture_new_from_file
    cogl_texture_new_from_bitmap
    cogl_texture_new_from_data
    cogl_texture_gl_new_from_foreign
    
    The same convenience can instead be found by using the more specific
    apis such as cogl_texture_2d_new_with_size/from_file but the advantage
    should be that it's clearer what kind of texture you will end up with
    and what special considerations you must be mindful of with any
    particular texture that you allocate. This way applications will also be
    less likely to hammer the texture-atlas with very large images that may
    not be appropriate for the atlas and also avoid extra work migrating
    images out of the atlas when choosing to use mipmapping.
    
    Another nice side affect is that the #CoglTexture api is now just an
    interface for handling operations common to all of the different texture
    types in Cogl instead of a combination of constructor apis and interface
    apis.
    
    The CoglTextureFlags type is also removed by this patch a corresponding
    references to the type in the documentation since these flags were only
    used with the auto-texture apis.
    
    Reviewed-by: Neil Roberts <neil linux intel com>

 cogl/Makefile.am         |    1 -
 cogl/cogl-auto-texture.c |  332 ----------------------------------------------
 cogl/cogl-primitive.h    |  136 +++++++++----------
 cogl/cogl-texture.h      |  171 ++----------------------
 cogl/cogl-types.h        |   23 ---
 cogl/cogl.symbols        |    5 -
 6 files changed, 76 insertions(+), 592 deletions(-)
---
diff --git a/cogl/Makefile.am b/cogl/Makefile.am
index 3c8149f..1161987 100644
--- a/cogl/Makefile.am
+++ b/cogl/Makefile.am
@@ -296,7 +296,6 @@ cogl_sources_c = \
        $(srcdir)/cogl-texture-driver.h                 \
        $(srcdir)/cogl-sub-texture.c                    \
        $(srcdir)/cogl-texture.c                        \
-       $(srcdir)/cogl-auto-texture.c                   \
        $(srcdir)/cogl-texture-2d.c                     \
        $(srcdir)/cogl-texture-2d-sliced.c              \
        $(srcdir)/cogl-texture-3d.c                     \
diff --git a/cogl/cogl-primitive.h b/cogl/cogl-primitive.h
index 7e47c14..983a118 100644
--- a/cogl/cogl-primitive.h
+++ b/cogl/cogl-primitive.h
@@ -268,15 +268,14 @@ cogl_primitive_new_with_attributes (CoglVerticesMode mode,
  * #CoglPrimitive <structfield>n_vertices</structfield> property as if
  * cogl_primitive_set_n_vertices() were called. This property defines
  * the number of vertices to read when drawing.
-
- * <note>The primitive API doesn't support drawing with sliced
- * textures (since switching between slices implies changing state and
- * so that implies multiple primitives need to be submitted). You
- * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
- * might be used while drawing with this API. If your hardware doesn't
- * support non-power of two textures (For example you are using GLES
- * 1.1) then you will need to make sure your assets are resized to a
- * power-of-two size (though they don't have to be square)</note>
+ *
+ * <note>The primitive API doesn't support drawing with high-level
+ * meta texture types such as #CoglTexture2DSliced or
+ * #CoglAtlasTexture so you need to ensure that only low-level
+ * textures that can be directly sampled by a GPU such as
+ * #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D are
+ * associated with the layers of any pipeline used while drawing a
+ * primitive.</note>
  *
  * Return value: A newly allocated #CoglPrimitive with a reference of
  * 1. This can be freed using cogl_object_unref().
@@ -321,15 +320,14 @@ cogl_primitive_new_p2 (CoglContext *context,
  * #CoglPrimitive <structfield>n_vertices</structfield> property as if
  * cogl_primitive_set_n_vertices() were called. This property defines
  * the number of vertices to read when drawing.
-
- * <note>The primitive API doesn't support drawing with sliced
- * textures (since switching between slices implies changing state and
- * so that implies multiple primitives need to be submitted). You
- * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
- * might be used while drawing with this API. If your hardware doesn't
- * support non-power of two textures (For example you are using GLES
- * 1.1) then you will need to make sure your assets are resized to a
- * power-of-two size (though they don't have to be square)</note>
+ *
+ * <note>The primitive API doesn't support drawing with high-level
+ * meta texture types such as #CoglTexture2DSliced or
+ * #CoglAtlasTexture so you need to ensure that only low-level
+ * textures that can be directly sampled by a GPU such as
+ * #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D are
+ * associated with the layers of any pipeline used while drawing a
+ * primitive.</note>
  *
  * Return value: A newly allocated #CoglPrimitive with a reference of
  * 1. This can be freed using cogl_object_unref().
@@ -376,15 +374,14 @@ cogl_primitive_new_p3 (CoglContext *context,
  * #CoglPrimitive <structfield>n_vertices</structfield> property as if
  * cogl_primitive_set_n_vertices() were called. This property defines
  * the number of vertices to read when drawing.
-
- * <note>The primitive API doesn't support drawing with sliced
- * textures (since switching between slices implies changing state and
- * so that implies multiple primitives need to be submitted). You
- * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
- * might be used while drawing with this API. If your hardware doesn't
- * support non-power of two textures (For example you are using GLES
- * 1.1) then you will need to make sure your assets are resized to a
- * power-of-two size (though they don't have to be square)</note>
+ *
+ * <note>The primitive API doesn't support drawing with high-level
+ * meta texture types such as #CoglTexture2DSliced or
+ * #CoglAtlasTexture so you need to ensure that only low-level
+ * textures that can be directly sampled by a GPU such as
+ * #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D are
+ * associated with the layers of any pipeline used while drawing a
+ * primitive.</note>
  *
  * Return value: A newly allocated #CoglPrimitive with a reference of
  * 1. This can be freed using cogl_object_unref().
@@ -431,15 +428,14 @@ cogl_primitive_new_p2c4 (CoglContext *context,
  * #CoglPrimitive <structfield>n_vertices</structfield> property as if
  * cogl_primitive_set_n_vertices() were called. This property defines
  * the number of vertices to read when drawing.
-
- * <note>The primitive API doesn't support drawing with sliced
- * textures (since switching between slices implies changing state and
- * so that implies multiple primitives need to be submitted). You
- * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
- * might be used while drawing with this API. If your hardware doesn't
- * support non-power of two textures (For example you are using GLES
- * 1.1) then you will need to make sure your assets are resized to a
- * power-of-two size (though they don't have to be square)</note>
+ *
+ * <note>The primitive API doesn't support drawing with high-level
+ * meta texture types such as #CoglTexture2DSliced or
+ * #CoglAtlasTexture so you need to ensure that only low-level
+ * textures that can be directly sampled by a GPU such as
+ * #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D are
+ * associated with the layers of any pipeline used while drawing a
+ * primitive.</note>
  *
  * Return value: A newly allocated #CoglPrimitive with a reference of
  * 1. This can be freed using cogl_object_unref().
@@ -486,15 +482,14 @@ cogl_primitive_new_p3c4 (CoglContext *context,
  * #CoglPrimitive <structfield>n_vertices</structfield> property as if
  * cogl_primitive_set_n_vertices() were called. This property defines
  * the number of vertices to read when drawing.
-
- * <note>The primitive API doesn't support drawing with sliced
- * textures (since switching between slices implies changing state and
- * so that implies multiple primitives need to be submitted). You
- * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
- * might be used while drawing with this API. If your hardware doesn't
- * support non-power of two textures (For example you are using GLES
- * 1.1) then you will need to make sure your assets are resized to a
- * power-of-two size (though they don't have to be square)</note>
+ *
+ * <note>The primitive API doesn't support drawing with high-level
+ * meta texture types such as #CoglTexture2DSliced or
+ * #CoglAtlasTexture so you need to ensure that only low-level
+ * textures that can be directly sampled by a GPU such as
+ * #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D are
+ * associated with the layers of any pipeline used while drawing a
+ * primitive.</note>
  *
  * Return value: A newly allocated #CoglPrimitive with a reference of
  * 1. This can be freed using cogl_object_unref().
@@ -541,15 +536,14 @@ cogl_primitive_new_p2t2 (CoglContext *context,
  * #CoglPrimitive <structfield>n_vertices</structfield> property as if
  * cogl_primitive_set_n_vertices() were called. This property defines
  * the number of vertices to read when drawing.
-
- * <note>The primitive API doesn't support drawing with sliced
- * textures (since switching between slices implies changing state and
- * so that implies multiple primitives need to be submitted). You
- * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
- * might be used while drawing with this API. If your hardware doesn't
- * support non-power of two textures (For example you are using GLES
- * 1.1) then you will need to make sure your assets are resized to a
- * power-of-two size (though they don't have to be square)</note>
+ *
+ * <note>The primitive API doesn't support drawing with high-level
+ * meta texture types such as #CoglTexture2DSliced or
+ * #CoglAtlasTexture so you need to ensure that only low-level
+ * textures that can be directly sampled by a GPU such as
+ * #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D are
+ * associated with the layers of any pipeline used while drawing a
+ * primitive.</note>
  *
  * Return value: A newly allocated #CoglPrimitive with a reference of
  * 1. This can be freed using cogl_object_unref().
@@ -596,15 +590,14 @@ cogl_primitive_new_p3t2 (CoglContext *context,
  * #CoglPrimitive <structfield>n_vertices</structfield> property as if
  * cogl_primitive_set_n_vertices() were called. This property defines
  * the number of vertices to read when drawing.
-
- * <note>The primitive API doesn't support drawing with sliced
- * textures (since switching between slices implies changing state and
- * so that implies multiple primitives need to be submitted). You
- * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
- * might be used while drawing with this API. If your hardware doesn't
- * support non-power of two textures (For example you are using GLES
- * 1.1) then you will need to make sure your assets are resized to a
- * power-of-two size (though they don't have to be square)</note>
+ *
+ * <note>The primitive API doesn't support drawing with high-level
+ * meta texture types such as #CoglTexture2DSliced or
+ * #CoglAtlasTexture so you need to ensure that only low-level
+ * textures that can be directly sampled by a GPU such as
+ * #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D are
+ * associated with the layers of any pipeline used while drawing a
+ * primitive.</note>
  *
  * Return value: A newly allocated #CoglPrimitive with a reference of
  * 1. This can be freed using cogl_object_unref().
@@ -651,15 +644,14 @@ cogl_primitive_new_p2t2c4 (CoglContext *context,
  * #CoglPrimitive <structfield>n_vertices</structfield> property as if
  * cogl_primitive_set_n_vertices() were called. This property defines
  * the number of vertices to read when drawing.
-
- * <note>The primitive API doesn't support drawing with sliced
- * textures (since switching between slices implies changing state and
- * so that implies multiple primitives need to be submitted). You
- * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
- * might be used while drawing with this API. If your hardware doesn't
- * support non-power of two textures (For example you are using GLES
- * 1.1) then you will need to make sure your assets are resized to a
- * power-of-two size (though they don't have to be square)</note>
+ *
+ * <note>The primitive API doesn't support drawing with high-level
+ * meta texture types such as #CoglTexture2DSliced or
+ * #CoglAtlasTexture so you need to ensure that only low-level
+ * textures that can be directly sampled by a GPU such as
+ * #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D are
+ * associated with the layers of any pipeline used while drawing a
+ * primitive.</note>
  *
  * Return value: A newly allocated #CoglPrimitive with a reference of
  * 1. This can be freed using cogl_object_unref().
diff --git a/cogl/cogl-texture.h b/cogl/cogl-texture.h
index 74fb252..a3cd0cf 100644
--- a/cogl/cogl-texture.h
+++ b/cogl/cogl-texture.h
@@ -3,7 +3,7 @@
  *
  * An object oriented GL/GLES Abstraction/Utility Layer
  *
- * Copyright (C) 2007,2008,2009,2010 Intel Corporation.
+ * Copyright (C) 2007,2008,2009,2010,2011,2012,2013 Intel Corporation.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -16,7 +16,8 @@
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General Public
- * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>.
  *
  *
  */
@@ -43,11 +44,15 @@ COGL_BEGIN_DECLS
 
 /**
  * SECTION:cogl-texture
- * @short_description: Functions for creating and manipulating textures
- *
- * Cogl allows creating and manipulating textures using a uniform
- * API that tries to hide all the various complexities of creating,
- * loading and manipulating textures.
+ * @short_description: Common interface for manipulating textures
+ *
+ * Cogl provides several different types of textures such as
+ * #CoglTexture2D, #CoglTexture3D, #CoglTextureRectangle,
+ * #CoglTexture2DSliced, #CoglAtlasTexture, #CoglSubTexture and
+ * #CoglTexturePixmapX11 that each have specific apis for creating
+ * and manipulating them, but there are a number of common operations
+ * that can be applied to any of these texture types which are handled
+ * via this #CoglTexture interface.
  */
 
 #define COGL_TEXTURE(X) ((CoglTexture *)X)
@@ -102,158 +107,6 @@ typedef enum {
 uint32_t cogl_texture_error_domain (void);
 
 /**
- * cogl_texture_new_with_size:
- * @context: A #CoglContext
- * @width: width of texture in pixels.
- * @height: height of texture in pixels.
- * @flags: Optional flags for the texture, or %COGL_TEXTURE_NONE
- * @internal_format: the #CoglPixelFormat to use for the GPU storage of the
- *    texture.
- *
- * Creates a new #CoglTexture with the specified dimensions and pixel format.
- *
- * The storage for the texture is not necesarily created before this
- * function returns. The storage can be explicitly allocated using
- * cogl_texture_allocate() or preferably you can let Cogl
- * automatically allocate the storage lazily when uploading data when
- * Cogl may know more about how the texture will be used and can
- * optimize how it is allocated.
- *
- * Return value: A newly created #CoglTexture
- *
- * Since: 0.8
- */
-CoglTexture *
-cogl_texture_new_with_size (CoglContext *ctx,
-                            int width,
-                            int height,
-                            CoglTextureFlags flags,
-                            CoglPixelFormat internal_format);
-
-/**
- * cogl_texture_new_from_file:
- * @context: A #CoglContext
- * @filename: the file to load
- * @flags: Optional flags for the texture, or %COGL_TEXTURE_NONE
- * @internal_format: the #CoglPixelFormat to use for the GPU storage of the
- *    texture. If %COGL_PIXEL_FORMAT_ANY is given then a premultiplied
- *    format similar to the format of the source data will be used. The
- *    default blending equations of Cogl expect premultiplied color data;
- *    the main use of passing a non-premultiplied format here is if you
- *    have non-premultiplied source data and are going to adjust the blend
- *    mode (see cogl_material_set_blend()) or use the data for something
- *    other than straight blending.
- * @error: A #CoglError to catch exceptional errors or %NULL
- *
- * Creates a #CoglTexture from an image file.
- *
- * Return value: A newly created #CoglTexture or %NULL on failure
- *
- * Since: 0.8
- */
-CoglTexture *
-cogl_texture_new_from_file (CoglContext *context,
-                            const char *filename,
-                            CoglTextureFlags flags,
-                            CoglPixelFormat internal_format,
-                            CoglError **error);
-
-/**
- * cogl_texture_new_from_data:
- * @context: A #CoglContext
- * @width: width of texture in pixels
- * @height: height of texture in pixels
- * @flags: Optional flags for the texture, or %COGL_TEXTURE_NONE
- * @format: the #CoglPixelFormat the buffer is stored in in RAM
- * @internal_format: the #CoglPixelFormat that will be used for storing
- *    the buffer on the GPU. If COGL_PIXEL_FORMAT_ANY is given then a
- *    premultiplied format similar to the format of the source data will
- *    be used. The default blending equations of Cogl expect premultiplied
- *    color data; the main use of passing a non-premultiplied format here
- *    is if you have non-premultiplied source data and are going to adjust
- *    the blend mode (see cogl_material_set_blend()) or use the data for
- *    something other than straight blending.
- * @rowstride: the memory offset in bytes between the starts of
- *    scanlines in @data
- * @data: pointer the memory region where the source buffer resides
- * @error: A #CoglError to catch exceptional errors or %NULL
- *
- * Creates a new #CoglTexture based on data residing in memory.
- *
- * Return value: A newly created #CoglTexture or %NULL on failure
- *
- * Since: 0.8
- */
-CoglTexture *
-cogl_texture_new_from_data (CoglContext *ctx,
-                            int width,
-                            int height,
-                            CoglTextureFlags flags,
-                            CoglPixelFormat format,
-                            CoglPixelFormat internal_format,
-                            int rowstride,
-                            const uint8_t *data,
-                            CoglError **error);
-
-/**
- * cogl_texture_gl_new_from_foreign:
- * @context: A #CoglContext
- * @gl_handle: opengl handle of foreign texture.
- * @gl_target: opengl target type of foreign texture
- * @width: width of foreign texture
- * @height: height of foreign texture.
- * @x_pot_waste: horizontal waste on the right hand edge of the texture.
- * @y_pot_waste: vertical waste on the bottom edge of the texture.
- * @format: format of the foreign texture.
- * @error: A #CoglError to catch exceptional errors or %NULL
- *
- * Creates a #CoglTexture based on an existing OpenGL texture; the
- * width, height and format are passed along since it is not always
- * possible to query these from OpenGL.
- *
- * The waste arguments allow you to create a Cogl texture that maps to
- * a region smaller than the real OpenGL texture. For instance if your
- * hardware only supports power-of-two textures you may load a
- * non-power-of-two image into a larger power-of-two texture and use
- * the waste arguments to tell Cogl which region should be mapped to
- * the texture coordinate range [0:1].
- *
- * Return value: A newly created #CoglTexture or %NULL on failure
- *
- * Since: 0.8
- */
-CoglTexture *
-cogl_texture_gl_new_from_foreign (CoglContext *context,
-                                  unsigned int gl_handle,
-                                  unsigned int gl_target,
-                                  int width,
-                                  int height,
-                                  int x_pot_waste,
-                                  int y_pot_waste,
-                                  CoglPixelFormat format,
-                                  CoglError **error);
-
-/**
- * cogl_texture_new_from_bitmap:
- * @bitmap: A #CoglBitmap pointer
- * @flags: Optional flags for the texture, or %COGL_TEXTURE_NONE
- * @internal_format: the #CoglPixelFormat to use for the GPU storage of the
- * texture
- * @error: A #CoglError to catch exceptional errors or %NULL
- *
- * Creates a #CoglTexture from a #CoglBitmap.
- *
- * Return value: A newly created #CoglTexture or %NULL on failure
- *
- * Since: 1.0
- */
-CoglTexture *
-cogl_texture_new_from_bitmap (CoglBitmap *bitmap,
-                              CoglTextureFlags flags,
-                              CoglPixelFormat internal_format,
-                              CoglError **error);
-
-/**
  * cogl_is_texture:
  * @object: A #CoglObject pointer
  *
diff --git a/cogl/cogl-types.h b/cogl/cogl-types.h
index 943dbc8..384ba96 100644
--- a/cogl/cogl-types.h
+++ b/cogl/cogl-types.h
@@ -384,29 +384,6 @@ struct _CoglColor
 COGL_STRUCT_SIZE_ASSERT (CoglColor, 16);
 
 /**
- * CoglTextureFlags:
- * @COGL_TEXTURE_NONE: No flags specified
- * @COGL_TEXTURE_NO_AUTO_MIPMAP: Disables the automatic generation of
- *   the mipmap pyramid from the base level image whenever it is
- *   updated. The mipmaps are only generated when the texture is
- *   rendered with a mipmap filter so it should be free to leave out
- *   this flag when using other filtering modes
- * @COGL_TEXTURE_NO_SLICING: Disables the slicing of the texture
- * @COGL_TEXTURE_NO_ATLAS: Disables the insertion of the texture inside
- *   the texture atlas used by Cogl
- *
- * Flags to pass to the cogl_texture_new_* family of functions.
- *
- * Since: 1.0
- */
-typedef enum {
-  COGL_TEXTURE_NONE           = 0,
-  COGL_TEXTURE_NO_AUTO_MIPMAP = 1 << 0,
-  COGL_TEXTURE_NO_SLICING     = 1 << 1,
-  COGL_TEXTURE_NO_ATLAS       = 1 << 2
-} CoglTextureFlags;
-
-/**
  * COGL_BLEND_STRING_ERROR:
  *
  * #CoglError domain for blend string parser errors
diff --git a/cogl/cogl.symbols b/cogl/cogl.symbols
index 89a2bd8..20109b8 100644
--- a/cogl/cogl.symbols
+++ b/cogl/cogl.symbols
@@ -549,11 +549,6 @@ cogl_texture_get_gl_texture
 cogl_texture_get_height
 cogl_texture_get_width
 cogl_texture_is_sliced
-cogl_texture_new_from_bitmap
-cogl_texture_new_from_data
-cogl_texture_new_from_file
-cogl_texture_new_from_foreign
-cogl_texture_new_with_size
 #ifdef COGL_HAS_X11
 cogl_texture_pixmap_x11_error_domain
 cogl_texture_pixmap_x11_is_using_tfp_extension
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]