isa/mutter
1
0
Fork 0
mirror of https://github.com/brl/mutter.git synced 2024-11-26 18:11:05 -05:00
Code Issues Packages Projects Releases Wiki Activity
db4fb91fe3
mutter/cogl-texture.h
Emmanuele Bassi c56d5b1468 [cogl] Remove max_waste argument from Texture ctors 
The CoglTexture constructors expose the "max-waste" argument for
controlling the maximum amount of wasted areas for slicing or,
if set to -1, disables slicing.

Slicing is really relevant only for large images that are never
repeated, so it's a useful feature only in controlled use cases.
Specifying the amount of wasted area is, on the other hand, just
a way to mess up this feature; 99% the times, you either pull this
number out of thin air, hoping it's right, or you try to do the
right thing and you choose the wrong number anyway.

Instead, we can use the CoglTextureFlags to control whether the
texture should not be sliced (useful for Clutter-GST and for the
texture-from-pixmap actors) and provide a reasonable value for
enabling the slicing ourself. At some point, we might even
provide a way to change the default at compile time or at run time,
for particular platforms.

Since max_waste is gone, the :tile-waste property of ClutterTexture
becomes read-only, and it proxies the cogl_texture_get_max_waste()
function.

Inside Clutter, the only cases where the max_waste argument was
not set to -1 are in the Pango glyph cache (which is a POT texture
anyway) and inside the test cases where we want to force slicing;
for the latter we can create larger textures that will be bigger than
the threshold we set.

Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>
Signed-off-by: Robert Bragg <robert@linux.intel.com>
Signed-off-by: Neil Roberts <neil@linux.intel.com>
2009-05-23 19:35:19 +01:00

532 lines
20 KiB
C
Raw Blame History

/*
* Cogl
*
* An object oriented GL/GLES Abstraction/Utility Layer
*
* Copyright (C) 2007,2008,2009 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.
*/
#if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
#error "Only <cogl/cogl.h> can be included directly."
#endif
#ifndef __COGL_TEXTURE_H__
#define __COGL_TEXTURE_H__
#include <cogl/cogl-types.h>
G_BEGIN_DECLS
/**
* SECTION:cogl-texture
* @short_description: Fuctions for creating and manipulating textures
*
* COGL allows creating and manipulating GL textures using a uniform
* API that tries to hide all the various complexities of creating,
* loading and manipulating textures.
*/
#define COGL_TEXTURE_MAX_WASTE 127
/**
* cogl_texture_new_with_size:
* @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 COGL texture with the specified dimensions and pixel format.
*
* Return value: a #CoglHandle to the newly created texture or
* %COGL_INVALID_HANDLE on failure
*
* Since: 0.8
*/
CoglHandle cogl_texture_new_with_size (guint width,
guint height,
CoglTextureFlags flags,
CoglPixelFormat internal_format);
/**
* cogl_texture_new_from_file:
* @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
* @error: return location for a #GError or %NULL
*
* Creates a COGL texture from an image file.
*
* Return value: a #CoglHandle to the newly created texture or
* %COGL_INVALID_HANDLE on failure
*
* Since: 0.8
*/
CoglHandle cogl_texture_new_from_file (const gchar *filename,
CoglTextureFlags flags,
CoglPixelFormat internal_format,
GError **error);
/**
* cogl_texture_new_from_data:
* @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
* @rowstride: the memory offset in bytes between the starts of
* scanlines in @data
* @data: pointer the memory region where the source buffer resides
*
* Creates a new COGL texture based on data residing in memory.
*
* Return value: a #CoglHandle to the newly created texture or
* %COGL_INVALID_HANDLE on failure
*
* Since: 0.8
*/
CoglHandle cogl_texture_new_from_data (guint width,
guint height,
CoglTextureFlags flags,
CoglPixelFormat format,
CoglPixelFormat internal_format,
guint rowstride,
const guchar *data);
/**
* cogl_texture_new_from_foreign:
* @gl_handle: opengl target type of foreign texture
* @gl_target: opengl handle of foreign texture.
* @width: width of foreign texture
* @height: height of foreign texture.
* @x_pot_waste: maximum horizontal waste.
* @y_pot_waste: maximum vertical waste.
* @format: format of the foreign texture.
*
* Creates a COGL texture based on an existing OpenGL texture; the
* width, height and format are passed along since it is not possible
* to query this from a handle with GLES 1.0.
*
* Return value: a #CoglHandle to the newly created texture or
* %COGL_INVALID_HANDLE on failure
*
* Since: 0.8
*/
CoglHandle cogl_texture_new_from_foreign (GLuint gl_handle,
GLenum gl_target,
GLuint width,
GLuint height,
GLuint x_pot_waste,
GLuint y_pot_waste,
CoglPixelFormat format);
/**
* cogl_texture_new_from_bitmap:
* @bmp_handle: A CoglBitmap handle
* @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 COGL texture from a CoglBitmap.
*
* Return value: a #CoglHandle to the newly created texture or
* %COGL_INVALID_HANDLE on failure
*
* Since: 1.0
*/
CoglHandle cogl_texture_new_from_bitmap (CoglHandle bmp_handle,
CoglTextureFlags flags,
CoglPixelFormat internal_format);
/**
* cogl_is_texture:
* @handle: A CoglHandle
*
* Gets whether the given handle references an existing texture object.
*
* Returns: %TRUE if the handle references a texture,
* %FALSE otherwise
*/
gboolean cogl_is_texture (CoglHandle handle);
/**
* cogl_texture_get_width:
* @handle: a #CoglHandle for a texture.
*
* Query the width of a cogl texture.
*
* Returns: the width of the GPU side texture in pixels:
*/
guint cogl_texture_get_width (CoglHandle handle);
/**
* cogl_texture_get_height:
* @handle: a #CoglHandle for a texture.
*
* Query the height of a cogl texture.
*
* Returns: the height of the GPU side texture in pixels:
*/
guint cogl_texture_get_height (CoglHandle handle);
/**
* cogl_texture_get_format:
* @handle: a #CoglHandle for a texture.
*
* Query the #CoglPixelFormat of a cogl texture.
*
* Returns: the #CoglPixelFormat of the GPU side texture.
*/
CoglPixelFormat cogl_texture_get_format (CoglHandle handle);
/**
* cogl_texture_get_rowstride:
* @handle: a #CoglHandle for a texture.
*
* Query the rowstride of a cogl texture.
*
* Returns: the offset in bytes between each consequetive row of pixels.
*/
guint cogl_texture_get_rowstride (CoglHandle handle);
/**
* cogl_texture_get_max_waste:
* @handle: a #CoglHandle for a texture.
*
* Query the maximum wasted (unused) pixels in one dimension of a GPU side
* texture.
*
* Returns: the maximum waste.
*/
gint cogl_texture_get_max_waste (CoglHandle handle);
/**
* CoglTextureFilter:
* @COGL_TEXTURE_FILTER_NEAREST: Measuring in manhatten distance from the,
* current pixel center, use the nearest texture
* texel.
* @COGL_TEXTURE_FILTER_LINEAR: Use the weighted average of the 4 texels
* nearest the current pixel center.
* @COGL_TEXTURE_FILTER_NEAREST_MIPMAP_NEAREST: Select the mimap level whose
* texel size most closely matches
* the current pixel, and use the
* COGL_TEXTURE_FILTER_NEAREST
* criterion.
* @COGL_TEXTURE_FILTER_LINEAR_MIPMAP_NEAREST: Select the mimap level whose
* texel size most closely matches
* the current pixel, and use the
* COGL_TEXTURE_FILTER_LINEAR
* criterion.
* @COGL_TEXTURE_FILTER_NEAREST_MIPMAP_LINEAR: Select the two mimap levels
* whose texel size most closely
* matches the current pixel, use
* the COGL_TEXTURE_FILTER_NEAREST
* criterion on each one and take
* their weighted average.
* @COGL_TEXTURE_FILTER_LINEAR_MIPMAP_LINEAR: Select the two mimap levels
* whose texel size most closely
* matches the current pixel, use
* the COGL_TEXTURE_FILTER_LINEAR
* criterion on each one and take
* their weighted average.
*
* Texture filtering is used whenever the current pixel maps either to more
* than one texture element (texel) or less than one. These filter enums
* correspond to different strategies used to come up with a pixel color, by
* possibly referring to multiple neighbouring texels and taking a weighted
* average or simply using the nearest texel.
*/
typedef enum _CoglTextureFilter
{
COGL_TEXTURE_FILTER_NEAREST = GL_NEAREST,
COGL_TEXTURE_FILTER_LINEAR = GL_LINEAR,
COGL_TEXTURE_FILTER_NEAREST_MIPMAP_NEAREST = GL_NEAREST_MIPMAP_NEAREST,
COGL_TEXTURE_FILTER_LINEAR_MIPMAP_NEAREST = GL_LINEAR_MIPMAP_NEAREST,
COGL_TEXTURE_FILTER_NEAREST_MIPMAP_LINEAR = GL_NEAREST_MIPMAP_LINEAR,
COGL_TEXTURE_FILTER_LINEAR_MIPMAP_LINEAR = GL_LINEAR_MIPMAP_LINEAR
} CoglTextureFilter;
/**
* cogl_texture_get_min_filter:
* @handle: a #CoglHandle for a texture.
*
* Query the currently set downscaling filter for a cogl texture.
*
* Returns: the current downscaling filter for a cogl texture.
*/
CoglTextureFilter cogl_texture_get_min_filter (CoglHandle handle);
/**
* cogl_texture_get_mag_filter:
* @handle: a #CoglHandle for a texture.
*
* Query the currently set downscaling filter for a cogl texture.
*
* Returns: the current downscaling filter for a cogl texture.
*/
CoglTextureFilter cogl_texture_get_mag_filter (CoglHandle handle);
/**
* cogl_texture_is_sliced:
* @handle: a #CoglHandle for a texture.
*
* Query if a texture is sliced (stored as multiple GPU side tecture
* objects).
*
* Returns: %TRUE if the texture is sliced, %FALSE if the texture
* is stored as a single GPU texture.
*/
gboolean cogl_texture_is_sliced (CoglHandle handle);
/**
* cogl_texture_get_gl_texture:
* @handle: a #CoglHandle for a texture.
* @out_gl_handle: pointer to return location for the textures GL handle, or
* NULL.
* @out_gl_target: pointer to return location for the GL target type, or NULL.
*
* Query the GL handles for a GPU side texture through it's #CoglHandle,
* if the texture is spliced the data for the first sub texture will be
* queried.
*
* Returns: %TRUE if the handle was successfully retrieved %FALSE
* if the handle was invalid.
*/
gboolean cogl_texture_get_gl_texture (CoglHandle handle,
GLuint *out_gl_handle,
GLenum *out_gl_target);
/**
* cogl_texture_get_data:
* @handle: a #CoglHandle for a texture.
* @format: the #CoglPixelFormat to store the texture as.
* @rowstride: the rowstride of @data or retrieved from texture if none is
* specified.
* @data: memory location to write contents of buffer, or %NULL if we're
* only querying the data size through the return value.
*
* Copy the pixel data from a cogl texture to system memory.
*
* Returns: the size of the texture data in bytes (or 0 if the texture
* is not valid.)
*/
gint cogl_texture_get_data (CoglHandle handle,
CoglPixelFormat format,
guint rowstride,
guchar *data);
/**
* cogl_texture_set_filters:
* @handle: a #CoglHandle.
* @min_filter: the filter used when scaling the texture down.
* @mag_filter: the filter used when magnifying the texture.
*
* Changes the decimation and interpolation filters used when the texture is
* drawn at other scales than 100%.
*/
void cogl_texture_set_filters (CoglHandle handle,
CoglTextureFilter min_filter,
CoglTextureFilter mag_filter);
/**
* cogl_texture_set_region:
* @handle: a #CoglHandle.
* @src_x: upper left coordinate to use from source data.
* @src_y: upper left coordinate to use from source data.
* @dst_x: upper left destination horizontal coordinate.
* @dst_y: upper left destination vertical coordinate.
* @dst_width: width of destination region to write.
* @dst_height: height of destination region to write.
* @width: width of source data buffer.
* @height: height of source data buffer.
* @format: the #CoglPixelFormat used in the source buffer.
* @rowstride: rowstride of source buffer (computed from width if none
* specified)
* @data: the actual pixel data.
*
* Sets the pixels in a rectangular subregion of @handle from an in-memory
* buffer containing pixel data.
*
* Returns: %TRUE if the subregion upload was successful, otherwise %FALSE.
*/
gboolean cogl_texture_set_region (CoglHandle handle,
gint src_x,
gint src_y,
gint dst_x,
gint dst_y,
guint dst_width,
guint dst_height,
gint width,
gint height,
CoglPixelFormat format,
guint rowstride,
const guchar *data);
/**
* cogl_texture_ref:
* @handle: a @CoglHandle.
*
* Increment the reference count for a cogl texture.
*
* Returns: the @handle.
*/
CoglHandle cogl_texture_ref (CoglHandle handle);
/**
* cogl_texture_unref:
* @handle: a @CoglHandle.
*
* Deccrement the reference count for a cogl texture.
*/
void cogl_texture_unref (CoglHandle handle);
/**
* cogl_rectangle_with_texture_coords:
* @x1: x coordinate upper left on screen.
* @y1: y coordinate upper left on screen.
* @x2: x coordinate lower right on screen.
* @y2: y coordinate lower right on screen.
* @tx1: x part of texture coordinate to use for upper left pixel
* @ty1: y part of texture coordinate to use for upper left pixel
* @tx2: x part of texture coordinate to use for lower right pixel
* @ty2: y part of texture coordinate to use for left pixel
*
* Draw a rectangle using the current material and supply texture coordinates
* to be used for the first texture layer of the material. To draw the entire
* texture pass in @tx1=0.0 @ty1=0.0 @tx2=1.0 @ty2=1.0.
*
* Since 1.0
*/
void cogl_rectangle_with_texture_coords (float x1,
float y1,
float x2,
float y2,
float tx1,
float ty1,
float tx2,
float ty2);
/**
* cogl_rectangle_with_multitexture_coords:
* @x1: x coordinate upper left on screen.
* @y1: y coordinate upper left on screen.
* @x2: x coordinate lower right on screen.
* @y2: y coordinate lower right on screen.
* @tex_coords: An array containing groups of 4 float values:
* [tx1, ty1, tx2, ty2] that are interpreted as two texture coordinates; one
* for the upper left texel, and one for the lower right texel. Each value
* should be between 0.0 and 1.0, where the coordinate (0.0, 0.0) represents
* the top left of the texture, and (1.0, 1.0) the bottom right.
* @tex_coords_len: The length of the tex_coords array. (e.g. for one layer
* and one group of texture coordinates, this would be 4)
*
* This function draws a rectangle using the current source material to
* texture or fill with. As a material may contain multiple texture layers
* this interface lets you supply texture coordinates for each layer of the
* material.
*
* The first pair of coordinates are for the first layer (with the smallest
* layer index) and if you supply less texture coordinates than there are
* layers in the current source material then default texture coordinates
* (0.0, 0.0, 1.0, 1.0) are generated.
*
* Since 1.0
*/
void cogl_rectangle_with_multitexture_coords (float x1,
float y1,
float x2,
float y2,
const float *tex_coords,
gint tex_coords_len);
/**
* cogl_rectangles_with_texture_coords:
* @verts: an array of vertices
* @n_rects: number of rectangles to draw
*
* Draws a series of rectangles in the same way that
* cogl_rectangle_with_texture_coords() does. In some situations it can give a
* significant performance boost to use this function rather than
* calling cogl_rectangle_with_texture_coords() separately for each rectangle.
*
* @verts should point to an array of #float<!-- -->s with
* @n_rects * 8 elements. Each group of 8 values corresponds to the
* parameters x1, y1, x2, y2, tx1, ty1, tx2 and ty2 and have the same
* meaning as in cogl_rectangle_with_texture_coords().
*
* Since: 0.8.6
*/
void cogl_rectangles_with_texture_coords (const float *verts,
guint n_rects);
/**
* cogl_rectangles:
* @verts: an array of vertices
* @n_rects: number of rectangles to draw
*
* Draws a series of rectangles in the same way that
* cogl_rectangle() does. In some situations it can give a
* significant performance boost to use this function rather than
* calling cogl_rectangle() separately for each rectangle.
*
* @verts should point to an array of #float<!-- -->s with
* @n_rects * 4 elements. Each group of 4 values corresponds to the
* parameters x1, y1, x2, and y2, and have the same
* meaning as in cogl_rectangle().
*
* Since: 1.0
*/
void cogl_rectangles (const float *verts,
guint n_rects);
/**
* cogl_polygon:
* @vertices: An array of #CoglTextureVertex structs
* @n_vertices: The length of the vertices array
* @use_color: %TRUE if the color member of #CoglTextureVertex should be used
*
* Draws a convex polygon using the current source material to fill / texture
* with according to the texture coordinates passed.
*
* If @use_color is %TRUE then the color will be changed for each vertex using
* the value specified in the color member of #CoglTextureVertex. This can be
* used for example to make the texture fade out by setting the alpha value of
* the color.
*
* All of the texture coordinates must be in the range [0,1] and repeating the
* texture is not supported.
*
* Because of the way this function is implemented it will currently only work
* if either the texture is not sliced or the backend is not OpenGL ES and the
* minifying and magnifying functions are both set to CGL_NEAREST.
*
* Since 1.0
*/
void cogl_polygon (CoglTextureVertex *vertices,
guint n_vertices,
gboolean use_color);
G_END_DECLS
#endif /* __COGL_TEXTURE_H__ */
Reference in New Issue View Git Blame Copy Permalink