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.
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.
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.
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.
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.
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.
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..
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.
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.
Click the icon to mail questions or corrections about this material to Taligent personnel.