Archon::Utilities::PixelFormat Struct Reference

Supports any number of channels (color components. More...

#include <archon/util/pixel_format.H>

Collaboration diagram for Archon::Utilities::PixelFormat:

[legend]List of all members.

Public Types
typedef uintmax_t	MaxInt
enum	FormatType { direct, packed, tight }
	There are three major categories of pixel formats. More...
enum	WordType {   std_char, std_short, std_int, std_long,   std_max_int, std_float, std_double, std_long_double,   custom_int, custom_float }
	Interpret image data as a sequence of words of this type. More...
enum	ColorScheme {   implied, custom, luminance, rgb,   hsv }
	Implied:. More...
Public Member Functions
PixelFormat	getExpandedFormat () const throw (UnsupportedWordTypeException, InconsistencyException)
PixelFormat	getReducedFormat () const throw (UnsupportedWordTypeException, InconsistencyException)
	A normalized or canonicalized format.
string	toString () const
	Get a tring representation of this pixel format.
bool	operator== (const PixelFormat &f) const
	PixelFormat ()
Public Attributes
FormatType	formatType
int	pixelSize
	For direct and packed formats this is the number of words per pixel.
WordType	wordType
int	bitsPerWord
	For custom_int and custom_float word types this specifies the desired number of bits per word.
bool	mostSignificantBitsFirst
	This flag selects the bit order that applies to your image data.
vector< Channel >	channelLayout
	A description of each channel in canonical (decoded) order.
ColorScheme	colorScheme
bool	hasAlphaChannel
	Set to true if your pixel data contains an alpha channel.
Classes
struct	Channel
	Describes a single channel. More...
struct	InconsistencyException
	Thrown when comflicting attributes are detected during expansion. More...
struct	UnsupportedWordTypeException
	Thrown when attempting to use pixel formats with word types that are not supported by your platform / architecture. More...

---

Detailed Description

Supports any number of channels (color components.

)

Channel order

The pixel format describes how to decode pixel data into a sequence of one or more channels. If there are more than one channel it must also describe how to decode them into the connonical order applying to the relevant color scheme. For custom color schemes the cannonical order is defined by you. Otherwise they are as follows:

   l     Luminance (trivial)
   rgb   Red, Green, Blue
   hsv   Hue, Saturation, Value

If the pixel data contains an alpha channel, that channel must always be last in decoded pixel.

Todo:

Make a formal format for string representation of pixel formats and a parser.

Definition at line 61 of file pixel_format.H.

---

Member Enumeration Documentation

enum Archon::Utilities::PixelFormat::ColorScheme

Implied:. Channels Color scheme Has alpha channel ------------------------------------------------------ 1 -> Luminance no 2 -> Luminance yes 3 -> Red, Green, Blue no 4 -> Red, Green, Blue yes 5 (>4) -> Custom no Enumerator: implied  Color scheme and alpha channel precense is implied from number of channels. custom  Custom color scheme. luminance  Luminance (grayscale). rgb  Red, Green, Blue. hsv  Hue, Saturation, Value. Definition at line 301 of file pixel_format.H.

enum Archon::Utilities::PixelFormat::FormatType

There are three major categories of pixel formats. Enumerator: direct  Every channel is aligned to a word boundary. (direct_int8_l) packed  Every pixel is aligned to a word boundary. (packed_int32_rgba8) tight  No word alignment - allows multiple pixels per word (tight_int8_l1). Definition at line 91 of file pixel_format.H.

enum Archon::Utilities::PixelFormat::WordType

Interpret image data as a sequence of words of this type. The formation of words from bytes in the image buffer is affected by the chosen byte order. For 'custom_int' and 'custom_float' types the actual word type is inferred from the value of bitsPerWord. Floating point word types can only be used with direct formats. See also: ByteOrder Enumerator: std_char  Characters (number of bits is platform dependant). std_short  Low precision integer numbers (number of bits is platform dependant). std_int  Normal precision integer numbers (number of bits is platform dependant). std_long  High precision integer numbers (number of bits is platform dependant). std_max_int  Ultra precision integer numbers (number of bits is platform dependant). std_float  Low precision floating point numbers (number of bits is platform dependant). std_double  Normal precision floating point numbers (number of bits is platform dependant). std_long_double  High precision floating point number (number of bits is platform dependant). custom_int  Custom precision integer number (number of bits is determined by bitsPerWord). custom_float  Custom precision floating point number (number of bits is determined by bitsPerWord). Definition at line 142 of file pixel_format.H.

---

Member Function Documentation

PixelFormat Archon::Utilities::PixelFormat::getExpandedFormat (   )  const throw (UnsupportedWordTypeException, InconsistencyException)

If an inconsistency is detected among the specified attributes this method will fail. Returns: A consistent pixel format with all implied attributes set to inferred values. Exceptions: UnsupportedWordTypeException  If the specified custom word type is not supported on this platform (CPU architecture). InconsistencyException  If an inconsistency is detected among the specified attributes. Definition at line 95 of file pixel_format.C. References bitsPerWord, channelLayout, colorScheme, custom, custom_float, custom_int, direct, formatType, hasAlphaChannel, hsv, implied, luminance, mostSignificantBitsFirst, Archon::Utilities::PixelFormat::Channel::offset, packed, pixelSize, rgb, tight, Archon::Utilities::Text::toString(), Archon::Utilities::PixelFormat::Channel::width, and wordType. Referenced by getReducedFormat(), and toString().

PixelFormat Archon::Utilities::PixelFormat::getReducedFormat (   )  const throw (UnsupportedWordTypeException, InconsistencyException)

A normalized or canonicalized format. Return a pixel format where no redundant attributes are specified Definition at line 352 of file pixel_format.C. References channelLayout, colorScheme, custom_float, custom_int, getExpandedFormat(), hasAlphaChannel, implied, pixelSize, and wordType. Referenced by toString().

string Archon::Utilities::PixelFormat::toString (   )  const

Get a tring representation of this pixel format. foramt = format_type '_' word_type '_' channel_layout '_' bit_order foramt_type = 'direct' | 'packed' | 'tight' word_type = 'char' | 'short' | 'int' | 'long' | 'max_int' | 'float' | 'double' | 'long double' | 'int' word_size (custom sized integer) | 'float' word_size (custom sized float) channel_layout = chort_custom_layout (N custom channels in canonical order: IMPLIES TIGHT FORMAT WHEN FORMAT IS UNSPECIFIED) | simple_channel_layout IMPLIES DIRECT FORMAT WHEN FORMAT IS UNSPECIFIED | cumplex_channel_layout IMPLIES DIRECT FORMAT WHEN FORMAT IS UNSPECIFIED bit_order = 'lsb' (least significant bits first - default) | 'msb' (most significant bits first) simple_channel_layout = simple_field | simple_field simple_channel_layout simple_field = standard_channel bit_width | standard_channel (implied field width) complex_channel_layout = complex_field | complex_field '_' complex_channel_layout complex_field = complex_field_type bit_width | complex_field_type (implied field width) | short_unused_field complex_field_type = standard_channel (standard channel) | channel_index 'c' (custom channel) | 'z' (unused field) short_unused_field = bit_width standard_channel = 'l' | 'a' | 'r' | 'g' | 'b' | 'h' | 's' | 'v' short_custom_layout = pixel_size | pixel_size 'a' (with alpha channel) The format string is not case sensitive. Returns: A string describing this pixel format. Definition at line 396 of file pixel_format.C. References bitsPerWord, channelLayout, colorScheme, custom, custom_float, custom_int, direct, formatType, getExpandedFormat(), getReducedFormat(), hasAlphaChannel, hsv, implied, luminance, mostSignificantBitsFirst, n, packed, pixelSize, rgb, tight, Archon::Utilities::Text::toString(), and wordType.

---

Member Data Documentation

int Archon::Utilities::PixelFormat::bitsPerWord

For custom_int and custom_float word types this specifies the desired number of bits per word. If zero 'custom_int' will be interpreted as 'int' and 'custom_float' as 'double'. For any other word type this attribute must either be zero or match the actual number of bits of the selected word type. Definition at line 166 of file pixel_format.H. Referenced by getExpandedFormat(), Archon::Utilities::ImageData::ImageData(), operator==(), and toString().

vector<Channel> Archon::Utilities::PixelFormat::channelLayout

A description of each channel in canonical (decoded) order. If empty the channel layout is implied. Definition at line 284 of file pixel_format.H. Referenced by getExpandedFormat(), getReducedFormat(), Archon::Utilities::ImageData::ImageData(), operator==(), and toString().

bool Archon::Utilities::PixelFormat::hasAlphaChannel

Set to true if your pixel data contains an alpha channel. If colorScheme == implied then the apparent state of this flag is ignored and the actual state of this flag will be inferred. Definition at line 319 of file pixel_format.H. Referenced by getExpandedFormat(), getReducedFormat(), operator==(), and toString().

bool Archon::Utilities::PixelFormat::mostSignificantBitsFirst

This flag selects the bit order that applies to your image data. Set this flag if you considder the most significant bit of a word to be the first bit in that word. Clear it if the first bit is the least significant bit instead. This flag affects pixel encoding/decoding in the following ways: If a channel in a direct format has a bit-width W which is less than the bit-width of a word, then by default the W least significant bits of the word are used. When setting this flag it causes the W most significant bits to be used instead. Order of channels within a word: If a pixel format has multiple channels and two channels A and B of a single pixel fall within a single word and A is before B in the canonical order (decoded order) then by default A uses bits of lesser significance than those used by B (least significant bits first.) When setting this flag A uses bits of greater significance than those used by B (most significant bits first.) Order of pixels within a word: If two pixels A and B fall within a single word and A is before B when decoded, then by default A uses uses bits of lesser significance than those used by B (least significant bits first.) When setting this flag A uses bits of greater significance than those used by B (most significant bits first.) The following is an example of the default bit ordering (least significant bits first) using a tight format with channels red, green and blue each using three bits (r0 is the least significant bit of the red channel) and the canonical channel order being as listed (red comes before green when decoded) and a word size of 8 bits (w0 is the least significant bit of the word): | pixel offset 0 | pixel offset 1 | | | | |r0 r1 r2|g0 g1 g2|b0 b1 b2|r0 r1 r2|g0 g1 g2|b0 b1 b2|... | | | | | | | ---------------------------------------------------------- | | | |w0 w1 w2 w3 w4 w5 w6 w7|w0 w1 w2 w3 w4 w5 w6 w7|......... | | | | word offset 0 | word offset 1 | The next example is like the previous one except that the bit ordering is now reversed (most significant bits first): | pixel offset 0 | pixel offset 1 | | | | |r2 r1 r0|g2 g1 g0|b2 b1 b0|r2 r1 r0|g2 g1 g0|b2 b1 b0|... | | | | | | | ---------------------------------------------------------- | | | |w7 w6 w5 w4 w3 w2 w1 w0|w7 w6 w5 w4 w3 w2 w1 w0|......... | | | | word offset 0 | word offset 1 | Note: The bit order never affect decoding of individual component values, That is, when a number of consecutive bits inside a word make up a channel value, the most significant bit in the decoded channel value will always correspond to the most significant bit in the word. Definition at line 250 of file pixel_format.H. Referenced by getExpandedFormat(), Archon::Utilities::ImageData::ImageData(), operator==(), and toString().

int Archon::Utilities::PixelFormat::pixelSize

For direct and packed formats this is the number of words per pixel. For tight format, this is the number of bits per pixel. If zero the actual pixel size is inferred. Note: This value determines the distance in bits/words between memory consecutive pixels. Therefore this value may be greater than the actual number of bits/words used by a pixel. Definition at line 126 of file pixel_format.H. Referenced by getExpandedFormat(), getReducedFormat(), Archon::Utilities::ImageData::ImageData(), operator==(), and toString().

---

The documentation for this struct was generated from the following files:

• archon/util/pixel_format.H
• archon/util/pixel_format.C

---