[cairo] Images with stride == width?

[Behdad Esfahbod]

Soeren Sandmann wrote:

>>> 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.

Makes sense.

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

Comments 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

How about, "the smallest appropriate stride..."?

>   * 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.

Well, the whole point of introducing new API for stride handling was to not
have to put the actual requirements in the API contract.  How about
documenting that multiples of sizeof(int) are always valid strides?

behdad