isa/mutter
1
0
Fork 0
mirror of https://github.com/brl/mutter.git synced 2024-12-03 05:10:40 -05:00
Code Issues Packages Projects Releases Wiki Activity
5fa0ee9569
mutter/cogl/cogl-atlas-texture.h

241 lines
8.6 KiB
C
Raw Normal View History

Expose CoglAtlasTexture api This exposes the CoglAtlasTexture api, making the following public: cogl_atlas_texture_new_with_size cogl_atlas_texture_new_from_file cogl_atlas_texture_new_from_data cogl_atlas_texture_new_from_bitmap The plan is to remove auto-texture apis like cogl_texture_new_from_file since they are a bit too magic, but that means we need an explicit way for users to allocate texture that will go in the atlas. Although the _new_from_file() api is arguably redundant since you can use _bitmap_new_from_file() followed by _atlas_texture_new_from_bitmap() we don't want to loose any of the convenience that cogl_texture_new_from_file() had. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit fe515e6063ba4c3ddb5cd00d2c8527d9a6336a12) Conflicts: cogl/Makefile.am
2013-06-07 20:58:05 -04:00
/*
* Cogl
*
* An object oriented GL/GLES Abstraction/Utility Layer
*
* Copyright (C) 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
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* 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/>.
*
*
*/
#if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION)
#error "Only <cogl/cogl.h> can be included directly."
#endif
#ifndef _COGL_ATLAS_TEXTURE_H_
#define _COGL_ATLAS_TEXTURE_H_
#include <cogl/cogl-context.h>
COGL_BEGIN_DECLS
/**
* SECTION:cogl-atlas-texture
* @short_description: Functions for managing textures in Cogl's global
* set of texture atlases
*
* A texture atlas is a texture that contains many smaller images that
* an application is interested in. These are packed together as a way
* of optimizing drawing with those images by avoiding the costs of
* repeatedly telling the hardware to change what texture it should
* sample from. This can enable more geometry to be batched together
* into few draw calls.
*
* Each #CoglContext has an shared, pool of texture atlases that are
* are managed by Cogl.
*
* This api lets applications upload texture data into one of Cogl's
* shared texture atlases using a high-level #CoglAtlasTexture which
* represents a sub-region of one of these atlases.
*
* <note>A #CoglAtlasTexture is a high-level meta texture which has
* some limitations to be aware of. Please see the documentation for
* #CoglMetaTexture for more details.</note>
*/
typedef struct _CoglAtlasTexture CoglAtlasTexture;
#define COGL_ATLAS_TEXTURE(tex) ((CoglAtlasTexture *) tex)
/**
* cogl_atlas_texture_new_with_size:
* @ctx: A #CoglContext
* @width: The width of your atlased texture.
* @height: The height of your atlased texture.
*
* Creates a #CoglAtlasTexture with a given @width and @height. A
* #CoglAtlasTexture represents a sub-region within one of Cogl's
* shared texture atlases.
*
* The storage for the texture is not allocated before this function
* returns. You can call cogl_texture_allocate() to explicitly
* allocate the underlying storage or let Cogl automatically allocate
* storage lazily.
*
introduce texture loaders to make allocations lazy This introduces the internal idea of texture loaders that track the state for loading and allocating a texture. This defers a lot more work until the texture is allocated. There are several intentions to this change: - provides a means for extending how textures are allocated without requiring all the parameters to be supplied in a single _texture_new() function call. - allow us to remove the internal_format argument from all _texture_new() apis since using CoglPixelFormat is bad way of expressing the internal format constraints because it is too specific. For now the internal_format arguments haven't actually been removed but this patch does introduce replacement apis for controlling the internal format: cogl_texture_set_components() lets you specify what components your texture needs when it is allocated. cogl_texture_set_premultiplied() lets you specify whether a texture data should be interpreted as premultiplied or not. - Enable us to support asynchronous texture loading + allocation in the future. Of note, the _new_from_data() texture constructors all continue to allocate textures immediately so that existing code doesn't need to be adapted to manage the lifetime of the data being uploaded. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 6a83de9ef4210f380a31f410797447b365a8d02c) Note: Compared to the original patch, the ->premultipled state for textures isn't forced to be %TRUE in _cogl_texture_init since that effectively ignores the users explicitly given internal_format which was a mistake and on master that change should have been made in the patch that followed. The gtk-doc comments for cogl_texture_set_premultiplied() and cogl_texture_set_components() have also been updated in-line with this fix.
2013-06-23 11:18:18 -04:00
* The texture is still configurable until it has been allocated so
* for example you can influence the internal format of the texture
* using cogl_texture_set_components() and
* cogl_texture_set_premultiplied().
*
remove internal_format and redundant error arguments Texture allocation is now consistently handled lazily such that the internal format can now be controlled using cogl_texture_set_components() and cogl_texture_set_premultiplied() before allocating the texture with cogl_texture_allocate(). This means that the internal_format arguments to texture constructors are now redundant and since most of the texture constructors now can't ever fail the error arguments are also redundant. This now means we no longer use CoglPixelFormat in the public api for describing the internal format of textures which had been bad solution originally due to how specific CoglPixelFormat is which is missleading when we don't support such explicit control over the internal format. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 99a53c82e9ab0a1e5ee35941bf83dc334b1fbe87) Note: there are numerous API changes for functions currently marked as 'unstable' which we don't think are in use by anyone depending on a stable 1.x api. Compared to the original patch though this avoids changing the cogl_texture_rectangle_new_with_size() api which we know is used by Mutter.
2013-07-01 20:48:54 -04:00
* <note>Allocate call can fail if Cogl considers the internal
* format to be incompatible with the format of its internal
Expose CoglAtlasTexture api This exposes the CoglAtlasTexture api, making the following public: cogl_atlas_texture_new_with_size cogl_atlas_texture_new_from_file cogl_atlas_texture_new_from_data cogl_atlas_texture_new_from_bitmap The plan is to remove auto-texture apis like cogl_texture_new_from_file since they are a bit too magic, but that means we need an explicit way for users to allocate texture that will go in the atlas. Although the _new_from_file() api is arguably redundant since you can use _bitmap_new_from_file() followed by _atlas_texture_new_from_bitmap() we don't want to loose any of the convenience that cogl_texture_new_from_file() had. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit fe515e6063ba4c3ddb5cd00d2c8527d9a6336a12) Conflicts: cogl/Makefile.am
2013-06-07 20:58:05 -04:00
* atlases.</note>
*
* <note>The returned #CoglAtlasTexture is a high-level meta-texture
* with some limitations. See the documentation for #CoglMetaTexture
* for more details.</note>
*
remove internal_format and redundant error arguments Texture allocation is now consistently handled lazily such that the internal format can now be controlled using cogl_texture_set_components() and cogl_texture_set_premultiplied() before allocating the texture with cogl_texture_allocate(). This means that the internal_format arguments to texture constructors are now redundant and since most of the texture constructors now can't ever fail the error arguments are also redundant. This now means we no longer use CoglPixelFormat in the public api for describing the internal format of textures which had been bad solution originally due to how specific CoglPixelFormat is which is missleading when we don't support such explicit control over the internal format. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 99a53c82e9ab0a1e5ee35941bf83dc334b1fbe87) Note: there are numerous API changes for functions currently marked as 'unstable' which we don't think are in use by anyone depending on a stable 1.x api. Compared to the original patch though this avoids changing the cogl_texture_rectangle_new_with_size() api which we know is used by Mutter.
2013-07-01 20:48:54 -04:00
* Returns: (transfer full): A new #CoglAtlasTexture object.
Expose CoglAtlasTexture api This exposes the CoglAtlasTexture api, making the following public: cogl_atlas_texture_new_with_size cogl_atlas_texture_new_from_file cogl_atlas_texture_new_from_data cogl_atlas_texture_new_from_bitmap The plan is to remove auto-texture apis like cogl_texture_new_from_file since they are a bit too magic, but that means we need an explicit way for users to allocate texture that will go in the atlas. Although the _new_from_file() api is arguably redundant since you can use _bitmap_new_from_file() followed by _atlas_texture_new_from_bitmap() we don't want to loose any of the convenience that cogl_texture_new_from_file() had. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit fe515e6063ba4c3ddb5cd00d2c8527d9a6336a12) Conflicts: cogl/Makefile.am
2013-06-07 20:58:05 -04:00
* Since: 1.16
* Stability: unstable
*/
CoglAtlasTexture *
cogl_atlas_texture_new_with_size (CoglContext *ctx,
int width,
remove internal_format and redundant error arguments Texture allocation is now consistently handled lazily such that the internal format can now be controlled using cogl_texture_set_components() and cogl_texture_set_premultiplied() before allocating the texture with cogl_texture_allocate(). This means that the internal_format arguments to texture constructors are now redundant and since most of the texture constructors now can't ever fail the error arguments are also redundant. This now means we no longer use CoglPixelFormat in the public api for describing the internal format of textures which had been bad solution originally due to how specific CoglPixelFormat is which is missleading when we don't support such explicit control over the internal format. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 99a53c82e9ab0a1e5ee35941bf83dc334b1fbe87) Note: there are numerous API changes for functions currently marked as 'unstable' which we don't think are in use by anyone depending on a stable 1.x api. Compared to the original patch though this avoids changing the cogl_texture_rectangle_new_with_size() api which we know is used by Mutter.
2013-07-01 20:48:54 -04:00
int height);
Expose CoglAtlasTexture api This exposes the CoglAtlasTexture api, making the following public: cogl_atlas_texture_new_with_size cogl_atlas_texture_new_from_file cogl_atlas_texture_new_from_data cogl_atlas_texture_new_from_bitmap The plan is to remove auto-texture apis like cogl_texture_new_from_file since they are a bit too magic, but that means we need an explicit way for users to allocate texture that will go in the atlas. Although the _new_from_file() api is arguably redundant since you can use _bitmap_new_from_file() followed by _atlas_texture_new_from_bitmap() we don't want to loose any of the convenience that cogl_texture_new_from_file() had. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit fe515e6063ba4c3ddb5cd00d2c8527d9a6336a12) Conflicts: cogl/Makefile.am
2013-06-07 20:58:05 -04:00
/**
* cogl_atlas_texture_new_from_file:
* @ctx: A #CoglContext
* @filename: the file to load
remove internal_format and redundant error arguments Texture allocation is now consistently handled lazily such that the internal format can now be controlled using cogl_texture_set_components() and cogl_texture_set_premultiplied() before allocating the texture with cogl_texture_allocate(). This means that the internal_format arguments to texture constructors are now redundant and since most of the texture constructors now can't ever fail the error arguments are also redundant. This now means we no longer use CoglPixelFormat in the public api for describing the internal format of textures which had been bad solution originally due to how specific CoglPixelFormat is which is missleading when we don't support such explicit control over the internal format. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 99a53c82e9ab0a1e5ee35941bf83dc334b1fbe87) Note: there are numerous API changes for functions currently marked as 'unstable' which we don't think are in use by anyone depending on a stable 1.x api. Compared to the original patch though this avoids changing the cogl_texture_rectangle_new_with_size() api which we know is used by Mutter.
2013-07-01 20:48:54 -04:00
* @error: A #CoglError to catch exceptional errors or %NULL
Expose CoglAtlasTexture api This exposes the CoglAtlasTexture api, making the following public: cogl_atlas_texture_new_with_size cogl_atlas_texture_new_from_file cogl_atlas_texture_new_from_data cogl_atlas_texture_new_from_bitmap The plan is to remove auto-texture apis like cogl_texture_new_from_file since they are a bit too magic, but that means we need an explicit way for users to allocate texture that will go in the atlas. Although the _new_from_file() api is arguably redundant since you can use _bitmap_new_from_file() followed by _atlas_texture_new_from_bitmap() we don't want to loose any of the convenience that cogl_texture_new_from_file() had. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit fe515e6063ba4c3ddb5cd00d2c8527d9a6336a12) Conflicts: cogl/Makefile.am
2013-06-07 20:58:05 -04:00
*
* Creates a #CoglAtlasTexture from an image file. A #CoglAtlasTexture
* represents a sub-region within one of Cogl's shared texture
* atlases.
*
introduce texture loaders to make allocations lazy This introduces the internal idea of texture loaders that track the state for loading and allocating a texture. This defers a lot more work until the texture is allocated. There are several intentions to this change: - provides a means for extending how textures are allocated without requiring all the parameters to be supplied in a single _texture_new() function call. - allow us to remove the internal_format argument from all _texture_new() apis since using CoglPixelFormat is bad way of expressing the internal format constraints because it is too specific. For now the internal_format arguments haven't actually been removed but this patch does introduce replacement apis for controlling the internal format: cogl_texture_set_components() lets you specify what components your texture needs when it is allocated. cogl_texture_set_premultiplied() lets you specify whether a texture data should be interpreted as premultiplied or not. - Enable us to support asynchronous texture loading + allocation in the future. Of note, the _new_from_data() texture constructors all continue to allocate textures immediately so that existing code doesn't need to be adapted to manage the lifetime of the data being uploaded. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 6a83de9ef4210f380a31f410797447b365a8d02c) Note: Compared to the original patch, the ->premultipled state for textures isn't forced to be %TRUE in _cogl_texture_init since that effectively ignores the users explicitly given internal_format which was a mistake and on master that change should have been made in the patch that followed. The gtk-doc comments for cogl_texture_set_premultiplied() and cogl_texture_set_components() have also been updated in-line with this fix.
2013-06-23 11:18:18 -04:00
* The storage for the texture is not allocated before this function
* returns. You can call cogl_texture_allocate() to explicitly
* allocate the underlying storage or let Cogl automatically allocate
* storage lazily.
*
* The texture is still configurable until it has been allocated so
* for example you can influence the internal format of the texture
* using cogl_texture_set_components() and
* cogl_texture_set_premultiplied().
*
remove internal_format and redundant error arguments Texture allocation is now consistently handled lazily such that the internal format can now be controlled using cogl_texture_set_components() and cogl_texture_set_premultiplied() before allocating the texture with cogl_texture_allocate(). This means that the internal_format arguments to texture constructors are now redundant and since most of the texture constructors now can't ever fail the error arguments are also redundant. This now means we no longer use CoglPixelFormat in the public api for describing the internal format of textures which had been bad solution originally due to how specific CoglPixelFormat is which is missleading when we don't support such explicit control over the internal format. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 99a53c82e9ab0a1e5ee35941bf83dc334b1fbe87) Note: there are numerous API changes for functions currently marked as 'unstable' which we don't think are in use by anyone depending on a stable 1.x api. Compared to the original patch though this avoids changing the cogl_texture_rectangle_new_with_size() api which we know is used by Mutter.
2013-07-01 20:48:54 -04:00
* <note>Allocate call can fail if Cogl considers the internal
* format to be incompatible with the format of its internal
Expose CoglAtlasTexture api This exposes the CoglAtlasTexture api, making the following public: cogl_atlas_texture_new_with_size cogl_atlas_texture_new_from_file cogl_atlas_texture_new_from_data cogl_atlas_texture_new_from_bitmap The plan is to remove auto-texture apis like cogl_texture_new_from_file since they are a bit too magic, but that means we need an explicit way for users to allocate texture that will go in the atlas. Although the _new_from_file() api is arguably redundant since you can use _bitmap_new_from_file() followed by _atlas_texture_new_from_bitmap() we don't want to loose any of the convenience that cogl_texture_new_from_file() had. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit fe515e6063ba4c3ddb5cd00d2c8527d9a6336a12) Conflicts: cogl/Makefile.am
2013-06-07 20:58:05 -04:00
* atlases.</note>
*
* <note>The returned #CoglAtlasTexture is a high-level meta-texture
* with some limitations. See the documentation for #CoglMetaTexture
* for more details.</note>
*
atlas-texture: add missing transfer annontations Reviewed-by: Robert Bragg <robert@linux.intel.com>
2013-09-03 10:27:55 -04:00
* Return value: (transfer full): A new #CoglAtlasTexture object or
* %NULL on failure and @error will be updated.
Expose CoglAtlasTexture api This exposes the CoglAtlasTexture api, making the following public: cogl_atlas_texture_new_with_size cogl_atlas_texture_new_from_file cogl_atlas_texture_new_from_data cogl_atlas_texture_new_from_bitmap The plan is to remove auto-texture apis like cogl_texture_new_from_file since they are a bit too magic, but that means we need an explicit way for users to allocate texture that will go in the atlas. Although the _new_from_file() api is arguably redundant since you can use _bitmap_new_from_file() followed by _atlas_texture_new_from_bitmap() we don't want to loose any of the convenience that cogl_texture_new_from_file() had. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit fe515e6063ba4c3ddb5cd00d2c8527d9a6336a12) Conflicts: cogl/Makefile.am
2013-06-07 20:58:05 -04:00
* Since: 1.16
* Stability: unstable
*/
CoglAtlasTexture *
cogl_atlas_texture_new_from_file (CoglContext *ctx,
const char *filename,
CoglError **error);
/**
* cogl_atlas_texture_new_from_data:
* @ctx: A #CoglContext
* @width: width of texture in pixels
* @height: height of texture in pixels
* @format: the #CoglPixelFormat the buffer is stored in in RAM
* @rowstride: the memory offset in bytes between the start of each
* row in @data. A value of 0 will make Cogl automatically
* calculate @rowstride from @width and @format.
* @data: pointer to the memory region where the source buffer resides
* @error: A #CoglError to catch exceptional errors or %NULL
*
* Creates a new #CoglAtlasTexture texture based on data residing in
* memory. A #CoglAtlasTexture represents a sub-region within one of
* Cogl's shared texture atlases.
*
introduce texture loaders to make allocations lazy This introduces the internal idea of texture loaders that track the state for loading and allocating a texture. This defers a lot more work until the texture is allocated. There are several intentions to this change: - provides a means for extending how textures are allocated without requiring all the parameters to be supplied in a single _texture_new() function call. - allow us to remove the internal_format argument from all _texture_new() apis since using CoglPixelFormat is bad way of expressing the internal format constraints because it is too specific. For now the internal_format arguments haven't actually been removed but this patch does introduce replacement apis for controlling the internal format: cogl_texture_set_components() lets you specify what components your texture needs when it is allocated. cogl_texture_set_premultiplied() lets you specify whether a texture data should be interpreted as premultiplied or not. - Enable us to support asynchronous texture loading + allocation in the future. Of note, the _new_from_data() texture constructors all continue to allocate textures immediately so that existing code doesn't need to be adapted to manage the lifetime of the data being uploaded. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 6a83de9ef4210f380a31f410797447b365a8d02c) Note: Compared to the original patch, the ->premultipled state for textures isn't forced to be %TRUE in _cogl_texture_init since that effectively ignores the users explicitly given internal_format which was a mistake and on master that change should have been made in the patch that followed. The gtk-doc comments for cogl_texture_set_premultiplied() and cogl_texture_set_components() have also been updated in-line with this fix.
2013-06-23 11:18:18 -04:00
* <note>This api will always immediately allocate GPU memory for the
* texture and upload the given data so that the @data pointer does
* not need to remain valid once this function returns. This means it
* is not possible to configure the texture before it is allocated. If
* you do need to configure the texture before allocation (to specify
* constraints on the internal format for example) then you can
* instead create a #CoglBitmap for your data and use
* cogl_atlas_texture_new_from_bitmap() or use
* cogl_atlas_texture_new_with_size() and then upload data using
* cogl_texture_set_data()</note>
*
remove internal_format and redundant error arguments Texture allocation is now consistently handled lazily such that the internal format can now be controlled using cogl_texture_set_components() and cogl_texture_set_premultiplied() before allocating the texture with cogl_texture_allocate(). This means that the internal_format arguments to texture constructors are now redundant and since most of the texture constructors now can't ever fail the error arguments are also redundant. This now means we no longer use CoglPixelFormat in the public api for describing the internal format of textures which had been bad solution originally due to how specific CoglPixelFormat is which is missleading when we don't support such explicit control over the internal format. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 99a53c82e9ab0a1e5ee35941bf83dc334b1fbe87) Note: there are numerous API changes for functions currently marked as 'unstable' which we don't think are in use by anyone depending on a stable 1.x api. Compared to the original patch though this avoids changing the cogl_texture_rectangle_new_with_size() api which we know is used by Mutter.
2013-07-01 20:48:54 -04:00
* <note>Allocate call can fail if Cogl considers the internal
* format to be incompatible with the format of its internal
Expose CoglAtlasTexture api This exposes the CoglAtlasTexture api, making the following public: cogl_atlas_texture_new_with_size cogl_atlas_texture_new_from_file cogl_atlas_texture_new_from_data cogl_atlas_texture_new_from_bitmap The plan is to remove auto-texture apis like cogl_texture_new_from_file since they are a bit too magic, but that means we need an explicit way for users to allocate texture that will go in the atlas. Although the _new_from_file() api is arguably redundant since you can use _bitmap_new_from_file() followed by _atlas_texture_new_from_bitmap() we don't want to loose any of the convenience that cogl_texture_new_from_file() had. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit fe515e6063ba4c3ddb5cd00d2c8527d9a6336a12) Conflicts: cogl/Makefile.am
2013-06-07 20:58:05 -04:00
* atlases.</note>
*
* <note>The returned #CoglAtlasTexture is a high-level
* meta-texture with some limitations. See the documentation for
* #CoglMetaTexture for more details.</note>
*
atlas-texture: add missing transfer annontations Reviewed-by: Robert Bragg <robert@linux.intel.com>
2013-09-03 10:27:55 -04:00
* Return value: (transfer full): A new #CoglAtlasTexture object or
* %NULL on failure and @error will be updated.
Expose CoglAtlasTexture api This exposes the CoglAtlasTexture api, making the following public: cogl_atlas_texture_new_with_size cogl_atlas_texture_new_from_file cogl_atlas_texture_new_from_data cogl_atlas_texture_new_from_bitmap The plan is to remove auto-texture apis like cogl_texture_new_from_file since they are a bit too magic, but that means we need an explicit way for users to allocate texture that will go in the atlas. Although the _new_from_file() api is arguably redundant since you can use _bitmap_new_from_file() followed by _atlas_texture_new_from_bitmap() we don't want to loose any of the convenience that cogl_texture_new_from_file() had. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit fe515e6063ba4c3ddb5cd00d2c8527d9a6336a12) Conflicts: cogl/Makefile.am
2013-06-07 20:58:05 -04:00
* Since: 1.16
* Stability: unstable
*/
CoglAtlasTexture *
cogl_atlas_texture_new_from_data (CoglContext *ctx,
int width,
int height,
CoglPixelFormat format,
int rowstride,
const uint8_t *data,
CoglError **error);
/**
* cogl_atlas_texture_new_from_bitmap:
remove internal_format and redundant error arguments Texture allocation is now consistently handled lazily such that the internal format can now be controlled using cogl_texture_set_components() and cogl_texture_set_premultiplied() before allocating the texture with cogl_texture_allocate(). This means that the internal_format arguments to texture constructors are now redundant and since most of the texture constructors now can't ever fail the error arguments are also redundant. This now means we no longer use CoglPixelFormat in the public api for describing the internal format of textures which had been bad solution originally due to how specific CoglPixelFormat is which is missleading when we don't support such explicit control over the internal format. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 99a53c82e9ab0a1e5ee35941bf83dc334b1fbe87) Note: there are numerous API changes for functions currently marked as 'unstable' which we don't think are in use by anyone depending on a stable 1.x api. Compared to the original patch though this avoids changing the cogl_texture_rectangle_new_with_size() api which we know is used by Mutter.
2013-07-01 20:48:54 -04:00
* @bitmap: A #CoglBitmap
Expose CoglAtlasTexture api This exposes the CoglAtlasTexture api, making the following public: cogl_atlas_texture_new_with_size cogl_atlas_texture_new_from_file cogl_atlas_texture_new_from_data cogl_atlas_texture_new_from_bitmap The plan is to remove auto-texture apis like cogl_texture_new_from_file since they are a bit too magic, but that means we need an explicit way for users to allocate texture that will go in the atlas. Although the _new_from_file() api is arguably redundant since you can use _bitmap_new_from_file() followed by _atlas_texture_new_from_bitmap() we don't want to loose any of the convenience that cogl_texture_new_from_file() had. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit fe515e6063ba4c3ddb5cd00d2c8527d9a6336a12) Conflicts: cogl/Makefile.am
2013-06-07 20:58:05 -04:00
*
* Creates a new #CoglAtlasTexture texture based on data residing in a
* @bitmap. A #CoglAtlasTexture represents a sub-region within one of
* Cogl's shared texture atlases.
*
introduce texture loaders to make allocations lazy This introduces the internal idea of texture loaders that track the state for loading and allocating a texture. This defers a lot more work until the texture is allocated. There are several intentions to this change: - provides a means for extending how textures are allocated without requiring all the parameters to be supplied in a single _texture_new() function call. - allow us to remove the internal_format argument from all _texture_new() apis since using CoglPixelFormat is bad way of expressing the internal format constraints because it is too specific. For now the internal_format arguments haven't actually been removed but this patch does introduce replacement apis for controlling the internal format: cogl_texture_set_components() lets you specify what components your texture needs when it is allocated. cogl_texture_set_premultiplied() lets you specify whether a texture data should be interpreted as premultiplied or not. - Enable us to support asynchronous texture loading + allocation in the future. Of note, the _new_from_data() texture constructors all continue to allocate textures immediately so that existing code doesn't need to be adapted to manage the lifetime of the data being uploaded. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 6a83de9ef4210f380a31f410797447b365a8d02c) Note: Compared to the original patch, the ->premultipled state for textures isn't forced to be %TRUE in _cogl_texture_init since that effectively ignores the users explicitly given internal_format which was a mistake and on master that change should have been made in the patch that followed. The gtk-doc comments for cogl_texture_set_premultiplied() and cogl_texture_set_components() have also been updated in-line with this fix.
2013-06-23 11:18:18 -04:00
* The storage for the texture is not allocated before this function
* returns. You can call cogl_texture_allocate() to explicitly
* allocate the underlying storage or preferably let Cogl
* automatically allocate storage lazily when it may know more about
* how the texture is being used and can optimize how it is allocated.
*
* The texture is still configurable until it has been allocated so
* for example you can influence the internal format of the texture
* using cogl_texture_set_components() and
* cogl_texture_set_premultiplied().
*
remove internal_format and redundant error arguments Texture allocation is now consistently handled lazily such that the internal format can now be controlled using cogl_texture_set_components() and cogl_texture_set_premultiplied() before allocating the texture with cogl_texture_allocate(). This means that the internal_format arguments to texture constructors are now redundant and since most of the texture constructors now can't ever fail the error arguments are also redundant. This now means we no longer use CoglPixelFormat in the public api for describing the internal format of textures which had been bad solution originally due to how specific CoglPixelFormat is which is missleading when we don't support such explicit control over the internal format. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 99a53c82e9ab0a1e5ee35941bf83dc334b1fbe87) Note: there are numerous API changes for functions currently marked as 'unstable' which we don't think are in use by anyone depending on a stable 1.x api. Compared to the original patch though this avoids changing the cogl_texture_rectangle_new_with_size() api which we know is used by Mutter.
2013-07-01 20:48:54 -04:00
* <note>Allocate call can fail if Cogl considers the internal
* format to be incompatible with the format of its internal
Expose CoglAtlasTexture api This exposes the CoglAtlasTexture api, making the following public: cogl_atlas_texture_new_with_size cogl_atlas_texture_new_from_file cogl_atlas_texture_new_from_data cogl_atlas_texture_new_from_bitmap The plan is to remove auto-texture apis like cogl_texture_new_from_file since they are a bit too magic, but that means we need an explicit way for users to allocate texture that will go in the atlas. Although the _new_from_file() api is arguably redundant since you can use _bitmap_new_from_file() followed by _atlas_texture_new_from_bitmap() we don't want to loose any of the convenience that cogl_texture_new_from_file() had. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit fe515e6063ba4c3ddb5cd00d2c8527d9a6336a12) Conflicts: cogl/Makefile.am
2013-06-07 20:58:05 -04:00
* atlases.</note>
*
* <note>The returned #CoglAtlasTexture is a high-level meta-texture
* with some limitations. See the documentation for #CoglMetaTexture
* for more details.</note>
*
remove internal_format and redundant error arguments Texture allocation is now consistently handled lazily such that the internal format can now be controlled using cogl_texture_set_components() and cogl_texture_set_premultiplied() before allocating the texture with cogl_texture_allocate(). This means that the internal_format arguments to texture constructors are now redundant and since most of the texture constructors now can't ever fail the error arguments are also redundant. This now means we no longer use CoglPixelFormat in the public api for describing the internal format of textures which had been bad solution originally due to how specific CoglPixelFormat is which is missleading when we don't support such explicit control over the internal format. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 99a53c82e9ab0a1e5ee35941bf83dc334b1fbe87) Note: there are numerous API changes for functions currently marked as 'unstable' which we don't think are in use by anyone depending on a stable 1.x api. Compared to the original patch though this avoids changing the cogl_texture_rectangle_new_with_size() api which we know is used by Mutter.
2013-07-01 20:48:54 -04:00
* Returns: (transfer full): A new #CoglAtlasTexture object.
Expose CoglAtlasTexture api This exposes the CoglAtlasTexture api, making the following public: cogl_atlas_texture_new_with_size cogl_atlas_texture_new_from_file cogl_atlas_texture_new_from_data cogl_atlas_texture_new_from_bitmap The plan is to remove auto-texture apis like cogl_texture_new_from_file since they are a bit too magic, but that means we need an explicit way for users to allocate texture that will go in the atlas. Although the _new_from_file() api is arguably redundant since you can use _bitmap_new_from_file() followed by _atlas_texture_new_from_bitmap() we don't want to loose any of the convenience that cogl_texture_new_from_file() had. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit fe515e6063ba4c3ddb5cd00d2c8527d9a6336a12) Conflicts: cogl/Makefile.am
2013-06-07 20:58:05 -04:00
* Since: 1.16
* Stability: unstable
*/
CoglAtlasTexture *
remove internal_format and redundant error arguments Texture allocation is now consistently handled lazily such that the internal format can now be controlled using cogl_texture_set_components() and cogl_texture_set_premultiplied() before allocating the texture with cogl_texture_allocate(). This means that the internal_format arguments to texture constructors are now redundant and since most of the texture constructors now can't ever fail the error arguments are also redundant. This now means we no longer use CoglPixelFormat in the public api for describing the internal format of textures which had been bad solution originally due to how specific CoglPixelFormat is which is missleading when we don't support such explicit control over the internal format. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 99a53c82e9ab0a1e5ee35941bf83dc334b1fbe87) Note: there are numerous API changes for functions currently marked as 'unstable' which we don't think are in use by anyone depending on a stable 1.x api. Compared to the original patch though this avoids changing the cogl_texture_rectangle_new_with_size() api which we know is used by Mutter.
2013-07-01 20:48:54 -04:00
cogl_atlas_texture_new_from_bitmap (CoglBitmap *bmp);
Expose CoglAtlasTexture api This exposes the CoglAtlasTexture api, making the following public: cogl_atlas_texture_new_with_size cogl_atlas_texture_new_from_file cogl_atlas_texture_new_from_data cogl_atlas_texture_new_from_bitmap The plan is to remove auto-texture apis like cogl_texture_new_from_file since they are a bit too magic, but that means we need an explicit way for users to allocate texture that will go in the atlas. Although the _new_from_file() api is arguably redundant since you can use _bitmap_new_from_file() followed by _atlas_texture_new_from_bitmap() we don't want to loose any of the convenience that cogl_texture_new_from_file() had. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit fe515e6063ba4c3ddb5cd00d2c8527d9a6336a12) Conflicts: cogl/Makefile.am
2013-06-07 20:58:05 -04:00
atlas-texture: use COGL_TEXTURE_DEFINE macro It was an oversight when making the CoglAtlasTexture api public that we continued to use the COGL_TEXTURE_INTERNAL_DEFINE macro. This updates the code to now use COGL_TEXTURE_DEFINE which means the cogl_is_atlas_texture() function will now be exported in the public api. Reviewed-by: Neil Roberts <neil@linux.intel.com> Reviewed-by: Lionel Landwerlin <llandwerlin@gmail.com> (cherry picked from commit ecbe209f48be80fe45b48f92b277a2aee08d5704)
2013-09-06 13:18:52 -04:00
/**
* cogl_is_atlas_texture:
* @object: a #CoglObject
*
* Checks whether the given object references a #CoglAtlasTexture
*
* Return value: %TRUE if the passed object represents an atlas
* texture and %FALSE otherwise
*
* Since: 1.16
* Stability: Unstable
*/
CoglBool
cogl_is_atlas_texture (void *object);
Expose CoglAtlasTexture api This exposes the CoglAtlasTexture api, making the following public: cogl_atlas_texture_new_with_size cogl_atlas_texture_new_from_file cogl_atlas_texture_new_from_data cogl_atlas_texture_new_from_bitmap The plan is to remove auto-texture apis like cogl_texture_new_from_file since they are a bit too magic, but that means we need an explicit way for users to allocate texture that will go in the atlas. Although the _new_from_file() api is arguably redundant since you can use _bitmap_new_from_file() followed by _atlas_texture_new_from_bitmap() we don't want to loose any of the convenience that cogl_texture_new_from_file() had. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit fe515e6063ba4c3ddb5cd00d2c8527d9a6336a12) Conflicts: cogl/Makefile.am
2013-06-07 20:58:05 -04:00
COGL_END_DECLS
#endif /* _COGL_ATLAS_TEXTURE_H_ */
Reference in New Issue Copy Permalink