sungmg/mutter-performance-source
1
0
Fork 0
Code Activity

doc: deprecate cogl_texture_get_rowstride()

Browse source 
This documents that cogl_texture_get_rowstride() is deprecated (or
rather it was a mistake that the api was ever published) and also
clarifies the rowstride argument documentation for
cogl_texture_get_data() to explain how it's automatically calculated
when 0 is passed to help avoid misleading people into thinking that
cogl_texture_get_rowstride() is an appropriate way to get a valid
rowstride for that.

Reviewed-by: Neil Roberts <neil@linux.intel.com>
This commit is contained in:
Robert Bragg 2011-11-01 19:05:32 +00:00
parent a1b682e051
commit 757916f17a
1 changed files with 33 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
cogl/cogl-texture.h
View file

@ -261,9 +261,29 @@ cogl_texture_get_format (CoglTexture *texture);
* cogl_texture_get_rowstride:
* @texture a #CoglTexture pointer.
*
* Queries the rowstride of a cogl texture.
* Determines the bytes-per-pixel for the #CoglPixelFormat retrieved
* from cogl_texture_get_format() and multiplies that by the texture's
* width.
*
* Return value: the offset in bytes between each consequetive row of pixels
* <note>It's very unlikely that anyone would need to use this API to
* query the internal rowstride of a #CoglTexture which can just be
* considered an implementation detail. Actually it's not even useful
* internally since underlying drivers are free to use a different
* format</note>
*
* </note>This API is only here for backwards compatibility and
* shouldn't be used in new code. In particular please don't be
* mislead to pass the returned value to cogl_texture_get_data() for
* the rowstride, since you should be passing the rowstride you desire
* for your destination buffer not the rowstride of the source
* texture.</note>
*
* Return value: The bytes-per-pixel for the current format
* multiplied by the texture's width
*
* Deprecated: 1.10: There's no replacement for the API but there's
* also no known need for API either. It was just
* a mistake that it was ever published.
*/
unsigned int
cogl_texture_get_rowstride (CoglTexture *texture);
@ -318,15 +338,20 @@ cogl_texture_get_gl_texture (CoglTexture *texture,
* cogl_texture_get_data:
* @texture a #CoglTexture pointer.
* @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.
* @rowstride: the rowstride of @data in bytes or pass 0 to calculate
* from the bytes-per-pixel of @format multiplied by the
* @texture width.
* @data: memory location to write the @texture's contents, or %NULL
* to only query the data size through the return value.
*
* Copies the pixel data from a cogl texture to system memory.
*
* Return value: the size of the texture data in bytes, or 0 if the texture
* is not valid
* <note>Don't pass the value of cogl_texture_get_rowstride() as the
* @rowstride argument, the rowstride should be the rowstride you
* want for the destination @data buffer not the rowstride of the
* source texture</note>
*
* Return value: the size of the texture data in bytes
*/
int
cogl_texture_get_data (CoglTexture *texture,