From 757916f17a78e91c0af206e03e32b17f3a061542 Mon Sep 17 00:00:00 2001
From: Robert Bragg <robert@linux.intel.com>
Date: Tue, 1 Nov 2011 19:05:32 +0000
Subject: [PATCH] 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>
---
 cogl/cogl-texture.h | 41 +++++++++++++++++++++++++++++++++--------
 1 file changed, 33 insertions(+), 8 deletions(-)

diff --git a/cogl/cogl-texture.h b/cogl/cogl-texture.h
index ba5418812..ed947de9a 100644
--- a/cogl/cogl-texture.h
+++ b/cogl/cogl-texture.h
@@ -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,