Class TLinearDDA

TLinearDDA

Support

Supported from 5.0

Description

Linear digital differential analyser.

This is used to calculate the pixels which most closely approximate a specified straight line, or when scaling a bitmap. Note that a line is infinitely thin, and can only be approximated by pixels with real width and height.

Functions are provided for:

• pixel line traversing

• jumping to a rectangle or co-ordinate

Defined in TLinearDDA:
Construct(), ECenter, ELeft, JumpToRect(), JumpToXCoord(), JumpToYCoord(), NextStep(), SingleScanline(), SingleStep(), TLineMode, TLinearDDA()

See also:

• Using the TLinearDDA

TLinearDDA();

Description

Constructs the default linear DDA.

No start or end point is defined for the line.

TLinearDDA(const TLinearDDA& aLine);

Description

Copy constructs a linear DDA from the specified linear DDA.

Parameters

const TLinearDDA& aLine The linear DDA to be copied.

void Construct(const TPoint& aStart,const TPoint& aFinish,TLineMode aMode=ECenter);

Description

Constructs a linear DDA, setting the start and end points of the line.

Parameters

const TPoint& aStart The start point of the line. const TPoint& aFinish The end point of the line. TLineMode aMode The mode of the line; defaults to centred.

Description

To draw the pixels in a pixel line, or to do bitmap scaling, the pixel line must be traversed from the start point to the end point. The pixel positions given during the traverse can then be used for the actual drawing operation.

The pixel line may be traversed in three ways:

• one pixel at a time

• one scan line at a time

• one step of pixels at a time

These three methods must not be mixed together. Only one traversing function should be employed for each instance of TLinearDDA.

The functions return true when the last pixel in the line has been reached. Care must be taken not to call a function after it has returned true, because the result is undefined.

Returning true when the last pixel has been reached is also useful to line drawing functions that do not want to draw the last pixel of a line.

TBool SingleStep(TPoint& aPosition);

Description

Gets the pixel co-ordinates of the next pixel on the pixel line.

The function is called repeatedly until the whole line has been traversed.

Parameters

TPoint& aPosition On entry to the first call, this can be a reference to any point. On return from the first call, this is the position of the first pixel in the line, as specified during construction of this object. On return from subsequent calls, this is the position of subsequent pixels in the line, as calculated by the function. On return from the final call, this is the position of the last pixel in the line, as specified during construction of this object.

Return value

TBool True, when the position of the last pixel is returned; false, otherwise.

TBool SingleScanline(TPoint& aStartPosition,TPoint& aEndPosition);

Description

Gets the start and end pixel co-ordinates that define the next scan line.

The best line that joins the start and end points is formed from all the scan lines returned by this function.

The function is called repeatedly until the position of all scanlines has been returned.

The start and end points passed to the constructor of this object define the boundaries of the line. Successive scan lines move from the start point to the end point.

Parameters

TPoint& aStartPosition On entry to the first call, this can be a reference to any point. On return from the first call, this is the position of the pixel that defines the leftmost position of the first scan line. On return from subsequent calls, this is the position of the pixel that defines the leftmost position of the next scan line. On return from the final call, either this or aEndPosition is set to the end point, as specified during construction. TPoint& aEndPosition On entry to the first call, this can be a reference to any point. On return from the first call, this is the position of the pixel that defines the rightmost position of the first scan line. On return from subsequent calls, this is the position of the pixel that defines the rightmost position of the next scan line. On return from the final call, either this or aStartPosition is set to the end point, as specified during construction.

Return value

TBool True, when the position of the last scan line includes the end point; false, otherwise.

TBool NextStep(TPoint& aPosition);

Description

Gets the pixel co-ordinates of the start of the next scan line.

The best line that joins the start and end points is formed from all the scan lines returned by this function.

The function is called repeatedly until the start position of all scanlines has been returned.

The start and end points passed to the constructor of this object define the boundaries of the line. Successive scan lines move from the start point to the end point.

Parameters

TPoint& aPosition On entry to the first call, this can be a reference to any point. On return from the first call, this is the position of the pixel that defines the leftmost position of the first scan line. On return from subsequent calls, this is the position of the pixel that defines the leftmost position of the next scan line. On return from the final call, this is the position of the last pixel in the line, as specified during construction.

Return value

TBool True, when the position of the last pixel is returned; false, otherwise.

Description

In order to speed up the operation of a linear DDA, there are member functions for jumping.

A jump can be made in three ways:

• to an x co-ordinate

• to a y co-ordinate

• to a rectangle

True is returned by subsequent calls to the stepping functions if the line:

• does not cross the co-ordinate or reach the rectangle

• has not been constructed

• has been run to completion

void JumpToXCoord(const TInt aXCoord,TInt& aYCoord);

Description

Jumps to x co-ordinate.

The other co-ordinate of the intersection is returned through a reference argument. After a jump call, the line is ready to continue through calls to the stepping functions.

This function accelerates the Linear DDA stepping functions (e.g. SingleStep()) making them return false when they reach the specified co-ordinate. If the line does not cross the co-ordinate, has not been constructed, has been run to completion or the intersection is the end point of the line then the stepping functions will return true.

Parameters

const TInt aXCoord x co-ordinate to jump to TInt& aYCoord On return, this parameter holds the y co-ordinate which corresponds to the specified x co-ordinate

void JumpToYCoord(TInt& aXCoord,const TInt aYCoord);

Description

Jumps to a y co-ordinate.

The other co-ordinate of the intersection is returned through a reference argument. After a jump call, the line is ready to continue through calls to the stepping functions.

This function accelerates the Linear DDA stepping functions (e.g. SingleStep()) making them return false when they reach the specified co-ordinate. If the line does not cross the co-ordinate, has not been constructed, has been run to completion or the intersection is the end point of the line then they will return true.

Parameters

TInt& aXCoord On return, this parameter holds the x co-ordinate which corresponds to the specified y co-ordinate. const TInt aYCoord y co-ordinate to jump to

void JumpToRect(const TRect& aRect);

Description

Jumps to start of a clipping rectangle.

This will accelerate the linear DDA to the vicinity of the specified rectangle. It is NOT guaranteed to reach the rectangle, but will reduce co-ordinates that are 1000's out to co-ordinates that are 10's out. Because of this, failure to intersect the rectangle may not be detected. If it is, or the line has not been constructed or has been run to completion, then a subsequent call to the stepping functions returns true.

Parameters

const TRect& aRect The rectangle to be jumped to.

TLineMode

Description

LDDA Line mode.

ECenter Centres scan-lines in the pixel line ELeft Starts at the beginning of a complete scan line. Used for bitmap scaling.