Class: TRasterScanOrder

Declaration: Paginator.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TScanOrder

Inherited By:

TScanOrderDownLeft TScanOrderDownRight TScanOrderLeftDown TScanOrderLeftUp TScanOrderRightDown TScanOrderRightUp TScanOrderUpLeft TScanOrderUpRight

Purpose:

TScanOrder is a general ordering class. TRasterScanOrder is a derived class that provides ordering in one of several raster directions. (A raster is the pattern that an electron beam traces as it paints an image on CRT displays, like your TV set.) This class provides eight possible raster scans. Given the coordinate of at least one item in a 2-D array or grid, the class provides the next (or previous) logical item in the sequence. It also provides a mapping of sequential numbers to and from the set of coordinates in the grid.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This is a specific derived class of TScanOrder and is not intended to be derived.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TRasterScanOrder::TRasterScanOrder

TRasterScanOrder ()
TRasterScanOrder (const TRasterScanOrder &)
TRasterScanOrder (ERasterOrder)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.
Constructor for a specific enumerated scan order.

Calling Context:

Called by the stream-in operators and derived classes.
Called to copy an object.
Constructs a raster scan order with the order specified by the enumeration.

Parameters:

Takes no parameters.
const TRasterScanOrder & -The object to copy.
ERasterOrder -The scan direction specified by an enumerated constant.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRasterScanOrder::~TRasterScanOrder

virtual ~ TRasterScanOrder ()

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: TRasterScanOrder::ReverseOrder

virtual void ReverseOrder ()

Interface Category:

API.

Purpose:

Dynamically reverses the order of the scan.

Calling Context:

Called directly to reverse the direction of the scan order. RightDown becomes LeftUp. A subsequent call reverts to the original order.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Reversing the order of a raster scan order changes its class type behaviorally. While it still remains a TRasterScanOrder, a TScanOrderRightDown behaves like a TScanOrderLeftUp.

Member Function: TRasterScanOrder::SwapRowColOrder

virtual void SwapRowColOrder ()

Interface Category:

API.

Purpose:

Dynamically changes the order of the scan order swapping the columns for the rows and vice versa. The structure of the scan is not changed, only the order.

Calling Context:

Called directly to swap the row order for the column order. RightDown becomes DownRight.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Swapping row and column order changes the class type behaviorally. For example, while this class would still remain a TRasterScanOrder, a TScanOrderRightDown would behave like a TScanOrderDownRight.

Member Function: TRasterScanOrder::RotateOrder90

virtual void RotateOrder90 (long n)

Interface Category:

API.

Purpose:

Rotates the scan order 90 degrees clockwise times the value of the integer argument. The structure of the scan is not changed, only the order.

Calling Context:

Called directly to change the scan order. RightDown becomes DownLeft.

Parameters:

long n -Used as a multiplier of 90 degrees to specify how far to rotate the scan order.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Rotating the order of a raster scan order changes its class type behaviorally. While it still remains a TRasterScanOrder, a TScanOrderRightDown behaves like a TScanOrderDownLeft.

Member Function: TRasterScanOrder::Next

virtual bool Next (const TULongPair & grid, TULongPair & inOut) const
virtual bool Next (const TULongRect & bounds, TULongPair & inOut) const

Interface Category:

API.

Purpose:

Given a grid with the top-left corner at the origin, and some coordinate in the grid, the next grid coordinate can be calculated.
Given a rectangle within the grid, and some coordinate within the rectangle, the next grid coordinate within the rectangle can be calculated.

Calling Context:

Called directly to obtain the next coordinate in the scan sequence.
Called directly to obtain the next coordinate in the scan sequence bounded by a rectangle within the grid.

Parameters:

const TULongPair & grid -Specifies the grid in which the next parameter is desired.
TULongPair & inOut -The current coordinate within the grid. The desired output is the coordinate for the next position in sequence as dictated by the scan order.
const TULongRect & bounds -Specifies a bounds rectangle instead of a grid. The next position is calculated the same way except that the next position is constrained to remain within the rectangle.
TULongPair & inOut -The current coordinate within the rectangle (or out of it for that matter), in which is returned the coordinate for the next position in the sequence as dictated by the scan order and adjusted to remain within the bounds rectangle.

Return Value:

Returns true if there is a next coordinate that remains in the grid; false if there is no next coordinate.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRasterScanOrder::Previous

virtual bool Previous (const TULongPair & grid, TULongPair & inOut) const
virtual bool Previous (const TULongRect & bounds, TULongPair & inOut) const

Interface Category:

API.

Purpose:

Given a grid with the top-left corner at the origin, and some coordinate in the grid, the previous grid coordinate can be calculated.
Given a rectangle within the grid, and some coordinate within the rectangle, the previous grid coordinate within the rectangle can be calculated.

Calling Context:

Called directly to obtain the previous coordinate in the scan sequence.
Called directly to obtain the previous coordinate in the scan sequence bounded by a rectangle within the grid.

Parameters:

const TULongPair & grid -Specifies the grid in which the previous position is desired.
TULongPair & inOut -The current coordinate within the grid. The desired output is the coordinate for the previous position in sequence as dictated by the scan order.
const TULongRect & bounds -Specifies a bounds rectangle instead of a grid. The previous position is calculated the same way as with the grid except that the previous position is constrained to remain within the rectangle.
TULongPair & inOut -This is the current coordinate within the rectangle (or out of it for that matter), in which is returned the coordinate for the previous position in the sequence as dictated by the scan order and adjusted to remain within the bounds rectangle.

Return Value:

Returns true if the coordinate previous to this coordinate exists and is still in the grid; false if the previous coordinate does not exist or is outside the grid.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRasterScanOrder::ItemToCoordinate

virtual TULongPair ItemToCoordinate (const TULongPair & grid, unsigned long item) const

Interface Category:

API.

Purpose:

Converts an item number to a grid coordinate.

Calling Context:

Called directly to convert an item number in the sequence to a grid coordinate.

Parameters:

const TULongPair & grid -The target grid used to convert item numbers to grid coordinates.
unsigned long item -The item number for which the coordinate is desired.

Return Value:

Returns the coordinate for the input item number.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRasterScanOrder::CoordinateToItem

virtual unsigned long CoordinateToItem (const TULongPair & grid, const TULongPair & in) const

Interface Category:

API.

Purpose:

Converts a coordinate within the grid to an item number.

Calling Context:

Called directly to convert a grid coordinate to an item number.

Parameters:

const TULongPair & grid -The target grid used to convert coordinate positions to item numbers.
const TULongPair & in -The coordinate for which the item number is desired.

Return Value:

Returns the item number for the specified coordinate.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRasterScanOrder::CreateOrderedRegion

virtual TPrimitiveRegion * CreateOrderedRegion (const TULongPair & grid, unsigned long from, unsigned long to) const

Interface Category:

API.

Purpose:

Creates a primitive region over the grid representing, in the scan order, all the items in the grid between from and to inclusive. The shape of the region is highly dependent on the order.

Calling Context:

Called directly to create a range representing the required items in the proper sequence. Because the scan order creates the range, clients do not need to know anything about the order.

Parameters:

const TULongPair & grid -The target grid.
unsigned long from -The beginning item number that marks a boundary position in the grid for constructing the region.
unsigned long to -The ending item number that marks the other boundary position in the grid for constructing the region.

Return Value:

Returns the primitive region.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRasterScanOrder::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called by collections and directly to obtain a hash value for an object of this class.

Parameters:

Takes no parameters.

Return Value:

The hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRasterScanOrder::operator=

TRasterScanOrder & operator =(const TRasterScanOrder &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TRasterScanOrder & -The object to be copied.

Return Value:

A reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRasterScanOrder::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called directly to stream in data.

Parameters:

TStream & fromWhere -The stream the object is streamed in from.

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: TRasterScanOrder::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called directly to stream out data.

Parameters:

TStream & toWhere -The stream the object is streamed out to.

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.

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