Pixrect line padding

[Mark Smith]

In sun-spots digest v8n229 david at sun.com (David DiGiacomo) writes:

> In article <3789 at brazos.Rice.edu> canon!laukee at nsfnet-relay.ac.uk (David
> Lau-Kee) writes:
>
> >X-Sun-Spots-Digest: Volume 8, Issue 217, message 12 of 23
> >My 4.0.3 documentation says
> >that for pixrects of width > 16 scan lines are padded out to a 32 bit
> >boundary.
> 
> Read the documentation carefully -- this is describing pixrects created by
> mem_create().  The minimum padding requirement is still 16 bits.
> 
> >This means that MPR_LINEBITPAD ought to be 32, and that the
> >mpr_linebytes macro (which will take your *actual* width and depth and
> >return the number of bytes you need to hold a whole line) gets it wrong
> >(unless your bitmap happens to be < 16 bits wide or a multiple of 32!).
> 
> Not really.  We couldn't change MPR_LINEBITPAD without breaking everyone's
> mpr_static() declarations etc.  All the pixrect code is still capable of
> handling 16 bit padded pixrects, but on SPARC systems they're much less
> efficient.  It's better to use 32 bit padded pixrects if you can.
> 
> P.S. Whenever you want to access the data in a memory pixrect, look at
> md_linebytes instead of assuming a particular padding algorithm.

This last minute entry looks like a clear contender for the hotly
contested 1989 Blame The Victim award.

In the Memory Pixrects chapter of the Pixrect Reference Manual:

    The mpr_linebytes macro computes the bytes per line of a primary memory
    pixrect given its width in pixels and the bits per pixel. This includes
    the padding to word bounds. It is useful for incrementing pixel addresses
    in the y direction or calculating line padding in the bitmap.

Next comes the definition of mpr_linebytes, which is *wrong* because it has
the number 15 hardcoded. Next comes a helpful example with the description:

    Note how the mpr_linebytes macro is used to find the number of bytes
    used to hold a line of a memory pixrect.

Well, it isn't, and it doesn't. I would suggest that given the incorrect
documentation, your suggestion to "read the documentation carefully" is
pretty nervy, especially coming from a Sun address.

As for "look at md_linebytes instead of assuming a particular padding
algorithm", I think most people would reasonably assume that using a
provided macro should be safer than accessing a data structure member
directly. It might also be reasonable to assume that a macro lovingly
described in the Memory Pixrects chapter, which starts with the characters
"mpr_", would work with memory pixrects. I guess it's just there to pad
out the manual to page boundaries...

+-----------------------------------+------------------------------+
|            Mark Smith             | tel:  +44 483 574 325        |
| Canon Research Centre Europe Ltd. | fax:  +44 483 574 360        |
|     19 Frederick Sanger Road      +------------------------------+
|       Surrey Research Park        | inet: smith at canon.co.uk      |
|   Guildford Surrey UK  GU2 5YD    | uucp: ukc!uos-ee!canon!smith |
+-----------------------------------+------------------------------+