Class: TPixelBuffer

Declaration: PixelBuffer.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TGModifiableImage

Inherited By:

None.

Purpose:

TPixelBuffer is an abstract base class representing a rectangular array of attributes stored as pixels. Derived classes allow for different quantization trade-offs, attributes, and memory organizations. Each derived class encapsulates the knowledge of how to allocate, manage, stream, translate, and modify its pixel data. All subsystems of the Graphics system use the polymorphic access mechanisms, enabling anyone to extend the types of pixel buffers that are rendered into or copied from. The commonality that exists between all of the various flavors of pixel buffers are: (1) mechanisms for polymorphic management, (2) the specification of the relationship between discrete and continuous space, (3) the characterization of color capabilities for use in accurate color reproduction, (4) mechanisms for pixel memory alteration in the form of Get and SetPixel, specialized blitloops tailored for scan converting clients, BitBlt, and CopyImage, (5) mechanisms to supply clients with variants of the specialized blitloops which match a key formed from the combination of client supplied attributes, (6) polymorphic queries regarding traits or stored attributes, (7) mechanisms which allow clients to polymorphically create, maintain, and query pixel buffer caches, and (8) mechanisms which allow clients to polymorphically create and maintain correlated back buffers. Pixel buffers must provide a way to specify the visual appearance of rendered primitives. This includes support for the specification of properties such as color, patterns, transfer modes, color matching, and dithering. These properties serve three purposes: (1) specification of a desired color at a given pixel, (2) specification of an interaction between that pixel and the current destination pixel, (3) specification of hints that state a preference for a given time or quality trade-off. For a given pixel buffer, there exists a subroutine that will set pixels to the state specified by these attributes. These subroutines are commonly referred to as blitloops. There are two requirements for these blitloops: (1) different rendering pipelines require blitloops with different semantics, (2) different appearance attributes require that blitloops use different algorithms to achieve the desired result. For each blitloop (for each specialized way a client needs to modify pixel memory) an abstract base painter class is created with a corresponding Create function in the Pixel buffer. All painters returned from a specific Create function are derived classes of a specific painter base class. The choice of which painter derived class to return should be driven by the second requirement. Each pixel buffer is expected to know about a few standard pixel buffer types. These types are TAlpha8Gray8PixelBuffer, TA8R8G8B8PixelBuffer, and TL12A12B12PixelBuffer. This default behavior allows the CopyImage engine to stream pixels from a pixel buffer of unknown organization into one of the three standard forms.

Instantiation:

Abstract base class; do not allocate.

Deriving Classes:

Provided classes include TChunkyPixelBuffer and TVideoPixelBuffer. Classes deriving from TPixelBuffer should override CreateMatchingStreamers.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPixelBuffer::~TPixelBuffer

virtual ~ TPixelBuffer ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPixelBuffer::AlignRectToMemoryBoundary

virtual void AlignRectToMemoryBoundary (TLongRect & rect) const

Interface Category:

API.

Purpose:

Aligns the specified rectangle to a long integer memory boundary.

Calling Context:

Call this function directly.

Parameters:

TLongRect & rect -The rectangle to be aligned.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPixelBuffer::CreateMatchingStreamers

virtual void CreateMatchingStreamers (TPixelStreamReader * & reader, TPixelStreamWriter * & writer, const TGImage & sourceImage, const TTransferMode * transferMode, const TGrafState & grafState, const TGrafMatrix * deviceXform)

Interface Category:

API.

Purpose:

Negotiates a pixel format that the source pixel buffer can read and the destination pixel buffer can write. If the format is successfully agreed upon, both streamers are created and returned to the caller. The source pixel buffer creates the pixel stream reader, and destination pixel buffer creates the pixel stream writer.

Calling Context:

Call this function directly.

Parameters:

TPixelStreamReader * & reader -The pixel stream reader created by this function.
TPixelStreamWriter * & writer -The pixel stream writer created by this function.
const TGImage & sourceImage -The image from which the pixels will be read.
const TTransferMode * transferMode -The transfer mode with which to initialize the new pixel stream reader and writer.
const TGrafState & grafState -The grafstate with which to initialize the new pixel stream reader and writer.
const TGrafMatrix * deviceXform -The graf matrix with which to initialize the new pixel stream reader and writer.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Classes deriving from TPixelBuffer should override this member function to take advantage of knowing their own storage format.

Member Function: TPixelBuffer::CreatePainterMaker

virtual TPainterMaker * CreatePainterMaker (TGrafDeviceCache * deviceCache) const

Interface Category:

API.

Purpose:

Creates a new TPainterMaker for the specified device cache.

Calling Context:

Call this function directly.

Parameters:

TGrafDeviceCache * deviceCache -The device cache.

Return Value:

Returns the newly created TPainterMaker object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPixelBuffer::CreateBackBuffer

virtual TPixelBuffer* CreateBackBuffer(const TLongRect& area, bool trimmedToBounds =true, TMemoryHeap* pixelMemoryHeap =NIL, TMemoryHeap* pixelBufferHeap =NIL ) const;

Interface Category:

API.

Purpose:

Creates a new pixel buffer that is a clone of this area.

Calling Context:

Call this function directly.

Parameters:

const TLongRect & area -The bounding area to be copied.
bool trimmedToBounds =true -A Boolean, which, if true (the default), causes the bounding area to be trimmed to the size of the raster bounds.
TMemoryHeap* pixelMemoryHeap =NIL -An optional memory heap pointer specifying which heap to get the new memory from.
TMemoryHeap* pixelBufferHeap =NIL -An optional memory heap pointer specifying which heap to create the actual TPixelBuffer object in.

Return Value:

Returns a pointer to a TPixelBuffer that was created for the area specified.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TPixelBuffer. The caller is responsible for deleting this memory.

Member Function: TPixelBuffer::operator>>=

virtual TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream to which the object streams itself out.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPixelBuffer::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The stream from which the object streams itself in.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPixelBuffer::CreateSpanPainter

virtual TSpanPainter * CreateSpanPainter (const TGrafState & grafState, const TGrafMatrix * deviceXform, const TLongRect & bounds, const TPaint & paint, const TTransferMode * transferMode)

Interface Category:

API.

Purpose:

Creates a new TSpanPainter initialized with the specified parameters. Filling and framing scan converted primitives are basic operations of a graphics system. Four specific mechanisms are required to support this type of client. Because these operations can be used in conjunction to alter the pixel memory, they are member functions of the same painter base class--TSpanPainter. These member functions are the (1) filling of spans, (2) filling of rectangular blocks, (3) filling of blended spans, and (4) filling an individual pixel that is blended with a color from an abutting edge. The TSpanPainter object which implements the above-mentioned operations is acquired through this function.

Calling Context:

Call this function directly.

Parameters:

const TGrafState & grafState -The grafstate with which to initialize the new span painter.
const TGrafMatrix * deviceXform -The graf matrix with which to initialize the new span painter.
const TLongRect & bounds -The bounding rectangle with which to initialize the new span painter.
const TPaint & paint -The paint type with which to initialize the new span painter.
const TTransferMode * transferMode -The transfer mode with which to initialize the new span painter.

Return Value:

Returns the newly created span painter object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The caller is responsible for destroying the span painter object created by this function.

Member Function: TPixelBuffer::CreateHairlinePainter

virtual THairlinePainter * CreateHairlinePainter (const TGrafState & grafState, const TGrafMatrix * deviceXform, const TLongRect & bounds, const TPaint & paint)

Interface Category:

API.

Purpose:

Creates a new THairlinePainter initialized with the specified parameters. THairlinePainter provides a specialized mechanism for drawing thin lines or hairlines. Hairlines are defined as lines drawn at the finest resolution of the pixel buffer. With raster devices this is a single pixel wide line. Hairlines are rendered as the result of lines, polylines, framed polygons, curves, and 3-D wireframes being drawn with the Hairline attribute turned on in the TGrafBundle. The end points of the hairline are specified with fractional precision. This object is acquired through this function.

Calling Context:

Call this function directly.

Parameters:

const TGrafState & grafState -The grafstate with which to initialize the new hairline painter.
const TGrafMatrix * deviceXform -The graf matrix with which to initialize the new hairline painter.
const TLongRect & bounds -The bounding rectangle with which to initialize the new hairline painter.
const TPaint & paint -The paint type with which to initialize the new hairline painter.

Return Value:

Returns the newly created hairline painter object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The caller is responsible for destroying the hairline painter object created by this function.

Member Function: TPixelBuffer::CreateGlyphPainter

virtual TBitmapGlyphPainter * CreateGlyphPainter (const TGrafState & grafState, const TGrafMatrix * deviceXform, const TLongRect & bounds, const TPaint & paint, const TTransferMode * transferMode)

Interface Category:

API.

Purpose:

Creates a new TGlyphPainter initialized with the specified parameters. Clients such as TFramebuffer::RenderGlyphRun request bitmaps or grayscale pixelmap forms of a given TFont from the TFontServer. The TFontServer asks the appropriate TFontHandler to take the high level contour description of a glyph and produce a bitmap or grayscale pixelmap. Once the TFramebuffer has the result, an efficient member function to composite the bitmap or pixelmap onto a TPixelBuffer is required. In the case of bitmaps, the proper object to ask for is a TGlyphPainter. TGlyphPainter contains the member functions necessary to render the bitmap form of glyphs. These bitmaps act as opaque mattes through which the user-supplied paint is composited. The first of these functions is PaintSmallGlyph that accepts a destination origin in the dstx and dsty arguments, as well as a TGlyphPixmap. This function is for unclipped glyphs. The next and final function is an overloaded PaintSmallGlyph. It takes an additional argument that is a rectangular clip area in the destination. This object is acquired through this function.

Calling Context:

Call this function directly.

Parameters:

const TGrafState & grafState -The grafstate with which to initialize the new glyph painter.
const TGrafMatrix * deviceXform -The graf matrix with which to initialize the new glyph painter.
const TLongRect & bounds -The bounding rectangle with which to initialize the new glyph painter.
const TPaint & paint -The paint type with which to initialize the new glyph painter.
const TTransferMode * transferMode -The transfer mode with which to initialize the new glyph painter.

Return Value:

Returns the newly created glyph painter object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The caller is responsible for destroying the glyph painter object created by this function.

Member Function: TPixelBuffer::CreateNativePixelWriter

virtual TPixelStreamWriter * CreateNativePixelWriter () const

Interface Category:

API.

Purpose:

Creates a pixel stream writer native to the storage format of the pixel buffer. This pixel stream writer can write pixel information in the native storage format for this pixel buffer.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the newly created pixel writer object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The caller is responsible for destroying the pixel writer created by this function..

Member Function: TPixelBuffer::CreatePixelWriter

virtual TPixelStreamWriter * CreatePixelWriter (const TPixelLayout & sourcePixelLayout, const TTransferMode * transferMode, const TGrafState & grafState, const TGrafMatrix * deviceXform)

Interface Category:

API.

Purpose:

Creates a pixel stream writer according to the specified parameters.

Calling Context:

Call this function directly.

Parameters:

const TPixelLayout & sourcePixelLayout -The pixel layout format that the new pixel writer must be able to write.
const TTransferMode * transferMode -The transfer mode with which to initialize the new pixel stream writer.
const TGrafState & grafState -The grafstate with which to initialize the new pixel stream writer.
const TGrafMatrix * deviceXform -The graf matrix with which to initialize the new pixel stream writer.

Return Value:

Returns the newly created pixel writer object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The caller is responsible for destroying the object created by this function.

Member Function: TPixelBuffer::CreateA8G8PixelWriter

virtual TPixelStreamWriter * CreateA8G8PixelWriter (const TTransferMode * transferMode, const TGrafState & grafState, const TGrafMatrix * deviceXform)

Interface Category:

API.

Purpose:

Creates a pixel stream writer for writing 8-bit alpha 8-bit gray images. All pixel buffers are required to know how to write the A8G8 format. This default behavior allows the CopyImage engine to stream pixels from a pixel buffer of unknown organization into one of the three standard forms.

Calling Context:

Call this function directly.

Parameters:

const TTransferMode * transferMode -The transfer mode with which to initialize the new pixel stream writer.
const TGrafState & grafState -The grafstate with which to initialize the new pixel stream writer.
const TGrafMatrix * deviceXform -The graf matrix with which to initialize the new pixel stream writer.

Return Value:

Returns the newly created pixel writer object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The caller is responsible for destroying the pixel writer created by this function.

Member Function: TPixelBuffer::CreateA8R8G8B8PixelWriter

virtual TPixelStreamWriter * CreateA8R8G8B8PixelWriter (const TTransferMode * transferMode, const TGrafState & grafState, const TGrafMatrix * deviceXform)

Interface Category:

API.

Purpose:

Creates a pixel stream writer for writing 8-bit alpha, 8-bit red, 8-bit green, and 8-bit blue images. All pixel buffers are required to know how to write the A8R8G8B8 format. This default behavior allows the CopyImage engine to stream pixels from a pixel buffer of unknown organization into one of the three standard forms.

Calling Context:

Call this function directly.

Parameters:

const TTransferMode * transferMode -The transfer mode with which to initialize the new pixel stream writer.
const TGrafState & grafState -The grafstate with which to initialize the new pixel stream writer.
const TGrafMatrix * deviceXform -The graf matrix with which to initialize the new pixel stream writer.

Return Value:

Returns the newly created pixel writer object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The caller is responsible for destroying the pixel writer created by this function.

Member Function: TPixelBuffer::TPixelBuffer

TPixelBuffer ()
TPixelBuffer (const TLongRect & bounds, TGPoint dpi =TGImage :: k72DPI, EOrientation orientation =kIdentity)
TPixelBuffer (const TPixelBuffer &)

Interface Category:

API.

Purpose:

Default constructor. This is a protected constructor.
Creates a new pixel buffer initialized with the specified parameters. This is a protected constructor.
Copy constructor. This is a protected constructor.

Calling Context:

Called by the stream-in operators. You can also call this function directly.
Call this function directly.
Called to copy an object. You can also call this function directly.

Parameters:

Takes no parameters.
const TLongRect & bounds -The bounding rectangle for the pixel buffer in pixel space.
TGPoint dpi =TGImage :: k72DPI -The image with which to initialize the new pixel buffer.
EOrientation orientation =kIdentity -The orientation for the initial image.
const TPixelBuffer & -The object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPixelBuffer::operator=

const TPixelBuffer & operator =(const TPixelBuffer & source)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement.

Parameters:

const TPixelBuffer & source -The object to be copied.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.