[cairo] Images with stride == width?

[Soeren Sandmann]

Behdad Esfahbod <behdad at behdad.org> writes:

> Vladimir Vukicevic wrote:
> > On 1/20/09 11:20 AM, Behdad Esfahbod wrote:
> >> Strides not multiple of 4 never worked.  We just formalized it so you
> >> get an
> >> error message that makes sense, instead of NO_MEMORY or memory
> >> corruption in
> >> pixman.
> > 
> > Sure, but it sounds like the stride now has to be exactly width * 4?
> 
> The code in cairo_image_surface_create_for_data() doesn't agree:

And this will hopefully continue to be the case, because we should
certainly support the usecase of having one big image from which bits
and pieces are copied out of.

So I suggest changing the documentation to reflect reality. See the
patch below.


Soren



diff --git a/src/cairo-image-surface.c b/src/cairo-image-surface.c
index 234a6f9..ae9cc75 100644
--- a/src/cairo-image-surface.c
+++ b/src/cairo-image-surface.c
@@ -408,7 +408,7 @@ _cairo_image_surface_create_with_content (cairo_content_t	content,
  *						  stride);
  * </programlisting></informalexample>
  *
- * Return value: the appropriate stride to use given the desired
+ * Return value: an appropriate stride to use given the desired
  * format and width, or -1 if either the format is invalid or the width
  * too large.
  *
@@ -442,9 +442,7 @@ slim_hidden_def (cairo_format_stride_for_width);
  * @width: the width of the image to be stored in the buffer
  * @height: the height of the image to be stored in the buffer
  * @stride: the number of bytes between the start of rows in the
- *     buffer as allocated. This value should always be computed by
- *     cairo_format_stride_for_width() before allocating the data
- *     buffer.
+ *     buffer as allocated. This value must always be a multiple of 4.
  *
  * Creates an image surface for the provided pixel data. The output
  * buffer must be kept around until the #cairo_surface_t is destroyed
@@ -453,14 +451,13 @@ slim_hidden_def (cairo_format_stride_for_width);
  * must explicitly clear the buffer, using, for example,
  * cairo_rectangle() and cairo_fill() if you want it cleared.
  *
- * Note that the stride may be larger than
- * width*bytes_per_pixel to provide proper alignment for each pixel
- * and row. This alignment is required to allow high-performance rendering
- * within cairo. The correct way to obtain a legal stride value is to
- * call cairo_format_stride_for_width() with the desired format and
- * maximum image width value, and the use the resulting stride value
- * to allocate the data and to create the image surface. See
- * cairo_format_stride_for_width() for example code.
+ * The stride must always be a multiple of 4. This alignment is required to
+ * allow high-performance rendering within cairo. One way to obtain a legal
+ * stride value is to call cairo_format_stride_for_width() with the desired
+ * format and maximum image width value, and then use the resulting stride
+ * value to allocate the data and to create the image surface. See
+ * cairo_format_stride_for_width() for example code. Note that it is allowed
+ * for the stride to be negative.
  *
  * Return value: a pointer to the newly created surface. The caller
  * owns the surface and should call cairo_surface_destroy() when done