On Mon, 28 Jan 2008 00:51:13 -0500, Behdad Esfahbod wrote:

...

int cairo_image_surface_stride_for_width (cairo_format_t format, int width);

I marginally prefer cairo_format_stride_for_width() as a name.

Oh, I might like that. I came up with the first name before I realized that a format was needed here.

...

And also documenting cairo_image_surface_create_for_data that the stride value passed to it should always come from calling the function above.

Humm, not sure how limiting that would be. Do you mean it should be the stride_for_width() of the actual image width,

"stride_for_width() of the actual image width" is what I intended.

                                          or the stride for some

(any) width? I mean, say I want to create a cairo surface for a subsurface of a larger buffer. The width passed to cairo may be way smaller than the width used for stride computation.

So you might have noticed that I dropped the suggestion in the documentation for cairo_image_surface_create_for_data that playing games with stride is a good way to generate sub-surfaces. More on that below.

Also while at this, how does this work for:

• 64-bit machines? Is the requirement still just 32? Guess yes.

Yes. The requirement comes from the fact that all of pixman is currently in terms of uint32_t. But, yes, the existence of 64-bit architectures is exactly why we want to be able to "upgrade" the alignment constraints in the future. Hence the newly required function call.

• Machines that do not allow unaligned access. Do we also require

that data be aligned properly?

Right. And this is why the sub-surface thing is a problem.

I tried to address this in the new documentation for cairo_image_surface_create_for_data by stealing language from malloc. What I'm trying to say there is that the data pointer needs to be properly aligned for the current platform. Take a look at the wording I used and see if you can improve it at all.

-Carl