[Cogl] [PATCH] format: Tidy up the definition of CoglPixelFormat

[Neil Roberts]

Robert Bragg <robert at sixbynine.org> writes:

> +/**
> + * COGL_BITWISE_BIT:
> + *
> + * A flag that can be masked with a #CoglPixelFormat to determine if
> + * the format should be accessed with bitwise operations or does the
> + * layout of the format depend on the endianness of the CPU.
> + */
> +#define COGL_BITWISE_BIT        (1 << 5)

I think it would be worth making this a bit more clear. Saying ‘the
layout of the format depends on the endianness of the CPU’ is ambiguous
depending on whether you mean the layout in memory is endianness
dependant or whether the layout within the word is endianness dependant.

Maybe something like this would be better:

“A flag that can be masked with a #CoglPixelFormat to determine if the
 format should be accessed with bitwise operations. If the flag is set
 then all of the bytes representing a pixel should interpreted as a
 single integer stored in the native endianness of the CPU. The order of
 the components in the name of the format represent the bits within that
 integer in order of decreasing significance. For example, the bytes for
 a pixel in the format RGB_565 should be interpreted as a 16-bit
 integer, with the red component in the most significant 5 bits, green
 in the next 6 bits and so on.

 If the flag is not set then each component is byte aligned and is
 stored in order of increasing memory addresses. For example, in
 RGB_888, there are 24 bits per pixel with the red component stored in
 the byte with the lowest address and so on.”

Otherwise looks good to me.

Reviewed-by: Neil Roberts <neil at linux.intel.com>

- Neil