mirror of
https://github.com/brl/mutter.git
synced 2024-11-25 09:30:45 -05:00
doc: deprecate cogl_texture_get_rowstride()
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:
parent
a1b682e051
commit
757916f17a
@ -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,
|
||||
|
Loading…
Reference in New Issue
Block a user