df21e20f65
Although we use GLib internally in Cogl we would rather not leak GLib api through Cogl's own api, except through explicitly namespaced cogl_glib_ / cogl_gtype_ feature apis. One of the benefits we see to not leaking GLib through Cogl's public API is that documentation for Cogl won't need to first introduce the Glib API to newcomers, thus hopefully lowering the barrier to learning Cogl. This patch provides a Cogl specific typedef for reporting runtime errors which by no coincidence matches the typedef for GError exactly. If Cogl is built with --enable-glib (default) then developers can even safely assume that a CoglError is a GError under the hood. This patch also enforces a consistent policy for when NULL is passed as an error argument and an error is thrown. In this case we log the error and abort the application, instead of silently ignoring it. In common cases where nothing has been implemented to handle a particular error and/or where applications are just printing the error and aborting themselves then this saves some typing. This also seems more consistent with language based exceptions which usually cause a program to abort if they are not explicitly caught (which passing a non-NULL error signifies in this case) Since this policy for NULL error pointers is stricter than the standard GError convention, there is a clear note in the documentation to warn developers that are used to using the GError api. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit b068d5ea09ab32c37e8c965fc8582c85d1b2db46) Note: Since we can't change the Cogl 1.x api the patch was changed to not rename _error_quark() functions to be _error_domain() functions and although it's a bit ugly, instead of providing our own CoglError type that's compatible with GError we simply #define CoglError to GError unless Cogl is built with glib disabled. Note: this patch does technically introduce an API break since it drops the cogl_error_get_type() symbol generated by glib-mkenum (Since the CoglError enum was replaced by a CoglSystemError enum) but for now we are assuming that this will not affect anyone currently using the Cogl API. If this does turn out to be a problem in practice then we would be able to fix this my manually copying an implementation of cogl_error_get_type() generated by glib-mkenum into a compatibility source file and we could also define the original COGL_ERROR_ enums for compatibility too. Note: another minor concern with cherry-picking this patch to the 1.14 branch is that an api scanner would be lead to believe that some APIs have changed, and for example the gobject-introspection parser which understands the semantics of GError will not understand the semantics of CoglError. We expect most people that have tried to use gobject-introspection with Cogl already understand though that it is not well suited to generating bindings of the Cogl api anyway and we aren't aware or anyone depending on such bindings for apis involving GErrors. (GnomeShell only makes very-very minimal use of Cogl via the gjs bindings for the cogl_rectangle and cogl_color apis.) The main reason we have cherry-picked this patch to the 1.14 branch even given the above concerns is that without it it would become very awkward for us to cherry-pick other beneficial patches from master.
185 lines
6.9 KiB
C
185 lines
6.9 KiB
C
/*
|
||
* Cogl
|
||
*
|
||
* An object oriented GL/GLES Abstraction/Utility Layer
|
||
*
|
||
* Copyright (C) 2010 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, write to the
|
||
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
||
* Boston, MA 02111-1307, USA.
|
||
*
|
||
* Authors:
|
||
* Neil Roberts <neil@linux.intel.com>
|
||
*/
|
||
|
||
#if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION)
|
||
#error "Only <cogl/cogl.h> can be included directly."
|
||
#endif
|
||
|
||
#ifndef __COGL_TEXTURE_3D_H
|
||
#define __COGL_TEXTURE_3D_H
|
||
|
||
#include <glib.h>
|
||
|
||
G_BEGIN_DECLS
|
||
|
||
/**
|
||
* SECTION:cogl-texture-3d
|
||
* @short_description: Fuctions for creating and manipulating 3D textures
|
||
*
|
||
* These functions allow 3D textures to be used. 3D textures can be
|
||
* thought of as layers of 2D images arranged into a cuboid
|
||
* shape. When choosing a texel from the texture, Cogl will take into
|
||
* account the 'r' texture coordinate to select one of the images.
|
||
*/
|
||
|
||
typedef struct _CoglTexture3D CoglTexture3D;
|
||
|
||
#define COGL_TEXTURE_3D(X) ((CoglTexture3D *)X)
|
||
|
||
/**
|
||
* cogl_texture_3d_new_with_size:
|
||
* @context: a #CoglContext
|
||
* @width: width of the texture in pixels.
|
||
* @height: height of the texture in pixels.
|
||
* @depth: depth of the texture in pixels.
|
||
* @internal_format: the #CoglPixelFormat to use for the GPU
|
||
* storage of the texture.
|
||
* @error: A CoglError return location.
|
||
*
|
||
* Creates a new Cogl 3D texture with the specified dimensions and
|
||
* pixel format.
|
||
*
|
||
* Note that this function will throw a #CoglError if
|
||
* %COGL_FEATURE_TEXTURE_3D is not advertised. It can also fail if the
|
||
* requested dimensions are not supported by the GPU.
|
||
*
|
||
* Return value: a new #CoglTexture3D object or
|
||
* %NULL on failure and an exception will be returned
|
||
* in @error.
|
||
* Since: 1.10
|
||
* Stability: Unstable
|
||
*/
|
||
CoglTexture3D *
|
||
cogl_texture_3d_new_with_size (CoglContext *context,
|
||
int width,
|
||
int height,
|
||
int depth,
|
||
CoglPixelFormat internal_format,
|
||
CoglError **error);
|
||
|
||
/**
|
||
* cogl_texture_3d_new_from_data:
|
||
* @context: a #CoglContext
|
||
* @width: width of the texture in pixels.
|
||
* @height: height of the texture in pixels.
|
||
* @depth: depth of the texture in pixels.
|
||
* @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_pipeline_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 or 0 to infer it from the width and format
|
||
* @image_stride: the number of bytes from one image to the next. This
|
||
* can be used to add padding between the images in a similar way
|
||
* that the rowstride can be used to add padding between
|
||
* rows. Alternatively 0 can be passed to infer the @image_stride
|
||
* from the @height.
|
||
* @data: pointer the memory region where the source buffer resides
|
||
* @error: A CoglError return location.
|
||
*
|
||
* Creates a new 3D texture and initializes it with @data. The data is
|
||
* assumed to be packed array of @depth images. There can be padding
|
||
* between the images using @image_stride.
|
||
*
|
||
* Note that this function will throw a #CoglError if
|
||
* %COGL_FEATURE_TEXTURE_3D is not advertised. It can also fail if the
|
||
* requested dimensions are not supported by the GPU.
|
||
*
|
||
* Return value: the newly created #CoglTexture3D or %NULL if
|
||
* there was an error an an exception will be returned
|
||
* through @error.
|
||
* Since: 1.10
|
||
* Stability: Unstable
|
||
*/
|
||
CoglTexture3D *
|
||
cogl_texture_3d_new_from_data (CoglContext *context,
|
||
int width,
|
||
int height,
|
||
int depth,
|
||
CoglPixelFormat format,
|
||
CoglPixelFormat internal_format,
|
||
int rowstride,
|
||
int image_stride,
|
||
const uint8_t *data,
|
||
CoglError **error);
|
||
|
||
/**
|
||
* cogl_texture_3d_new_from_bitmap:
|
||
* @bitmap: A #CoglBitmap object.
|
||
* @height: height of the texture in pixels.
|
||
* @depth: depth of the texture in pixels.
|
||
* @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_pipeline_set_blend()) or use the data for
|
||
* something other than straight blending.
|
||
* @error: A CoglError return location.
|
||
*
|
||
* Creates a new 3D texture and initializes it with the images in
|
||
* @bitmap. The images are assumed to be packed together after one
|
||
* another in the increasing y axis. The height of individual image is
|
||
* given as @height and the number of images is given in @depth. The
|
||
* actual height of the bitmap can be larger than @height × @depth. In
|
||
* this case it assumes there is padding between the images.
|
||
*
|
||
* Return value: the newly created texture or %NULL if
|
||
* there was an error.
|
||
* Since: 2.0
|
||
* Stability: unstable
|
||
*/
|
||
CoglTexture3D *
|
||
cogl_texture_3d_new_from_bitmap (CoglBitmap *bitmap,
|
||
unsigned int height,
|
||
unsigned int depth,
|
||
CoglPixelFormat internal_format,
|
||
CoglError **error);
|
||
|
||
/**
|
||
* cogl_is_texture_3d:
|
||
* @object: a #CoglObject
|
||
*
|
||
* Checks whether the given object references a #CoglTexture3D
|
||
*
|
||
* Return value: %TRUE if the passed object represents a 3D texture
|
||
* and %FALSE otherwise
|
||
*
|
||
* Since: 1.4
|
||
* Stability: Unstable
|
||
*/
|
||
CoglBool
|
||
cogl_is_texture_3d (void *object);
|
||
|
||
G_END_DECLS
|
||
|
||
#endif /* __COGL_TEXTURE_3D_H */
|