Ambiguous description of vgWritePixels/vgReadPixels

Hi,

The OpenVG spec

“OpenVG Specification
Version 1.0.1
Version 1.0 - August 1, 2005
Amended January 26, 2007”

reads (page 128): “The vgReadPixels function allows pixel data to be copied …”.

Together with the code sample (“The code … is equivalent to the code …”, p. 129), where ‘data’ is not allocated before use, this sentence may be somewhat misleading to the conclusion that it allows direct access to the pixel data. Especially because vgGetPixels is described in active voice: “The vgGetPixels function retrieves pixel data …”. Shouldn’t it therefore be “The vgReadPixels function copies pixel data from the drawing surface…”?

vgWritePixels is similar.

Of course it is clear what the function does if one reads the whole description. Sorry for nitpicking but a spec should be as unambiguous as possible, shouldn’t it?

Oh there’s much more ambiguous and confusing stuff than that in the spec - trust me. The worst offenders are mainly things to do with blending, precision, the version string [in version 1.0.1], and fill rules.

The vgReadPixel() thing is not too bad though - I mean the function takes as an argument the pointer it wants the data put in. Since this pointer is not passed by reference, modifying it to point to the actual drawing surface is impossible (besides - being able to get a pointer to the actual framebuffer is not something that is considered normal behavior now-a-days).