Chapter 4 - Graphics Operations

The TMS340 Graphics Library supports the drawing of a variety of 
two-dimensional geometric objects such as points, lines, polygons, ellipses, 
arcs, pie-slice wedges, and polygons.

Geometric objects can be rendered in a variety of styles. Filled primitives 
such as polygons and ellipses can be filled with either a solid color or a 
two-dimensional area-fill pattern. Vector primitives that produce 1-pixel-thick 
lines and arcs can be drawn either in a single color or with a one-dimensional 
line-style pattern. A rectangular drawing pen (or brush) is available for 
producing thicker lines and arcs; the area swept out by the pen is filled with 
either a solid color or an area-fill pattern.

The library follows a set of strict conventions in order to make the behavior 
of the drawing functions (library functions that produce graphics output) 
predictable in all cases. These conventions cover the following:

- The naming of the functions

- The mapping of x-y coordinates onto the screen (a display surface 
   addressed as a two-dimensional array of pixels)

- Defining the paths followed by vector primitives such as lines and arcs

- Defining the pixels covered by area-fill primitives such as polygons 
   and ellipses

The library supports a variety of methods for combining source and destination 
pixel values during drawing operations. Pixels are combined according to how 
the user configures the library's plane mask, transparency attribute, and 
pixel-processing operation code.

All graphics output is automatically clipped either to the screen or to a 
rectangular clipping window located within the screen limits.

4.1 Graphics-Function Naming Conventions

A set of conventions has been adopted for naming graphics functions in the 
Extended Primitives Library that draw geometric objects such as lines and 
ellipses. Each object can be rendered in a variety of styles, and the rendering 
style also is reflected in the function name. The name assigned to the function 
is a concatenation of a modifier (such as rect for rectangle) denoting a 
geometric type and another modifier (such as fill ) designating a rendering 
style. For example, the fill_rect function fills a rectangle with a solid 
color.

Table 4-1 is a list of the geometric types supported by the library. The left
column specifies the function-name modifier corresponding to each type.

Table 4-1. Geometric Types

Function Name	Geometric Type

line		A straight line

oval		An ellipse in standard position (major and minor axes aligned 
		with the x-y 
		coordinate axes)

ovalarc		An arc from an ellipse in standard position

point		A single point

polygon		A filled region bounded by a series of connected straight edges

polyline	A series of connected straight lines

piearc		A pie-slice-shaped wedge bounded by an arc (from an ellipse in 
		standard 
		position) and two straight edges (connecting the ends of the 
		arc to the center 
		of the ellipse)

rect		A rectangle with vertical and horizontal sides

seed		A pixel of a particular color designating a connected region of 
		pixels of the same color

Table 4-2 is a list of the graphics rendering styles supported by the library. 
The left column specifies the function-name modifier corresponding to each 
style.

Table 4-2. Rendering Styles

Function Name		Rendering Style

draw		Draws a line, arc, or outline a single pixel thick with the 
		current foreground color.

styled 		Similar to "draw" except that the line, arc, or outline is 
		drawn with a repeating 32-bit
		line-style pattern that is rendered in the
		current foreground and background colors.
		Alternately, background pixels in the pattern are skipped.

pen		Traces a line or curve with a rectangular drawing pen, and 
		fills the area swept 
		out by the pen with the current foreground color.

patnpen 	Similar to "pen" except that the area swept out by the
		pen is filled with a
		16-by-16 area-fill pattern in the current foreground and 
		background colors.

fill		Fills the interior of an object with the current foreground 
		color.

patnfill	Similar to "fill" except that the object is filled with
		a 16-by-16 area-fill 
		pattern in the current foreground and background colors.

frame		Fills a frame with the current foreground color. The area 
		enclosed by the frame is not modified.

patnframe	Similar to "frame" except that the frame is filled with
		a 16-by-16 area-fill 
		pattern in the current foreground and background colors.

Not all combinations of geometric type and rendering style are available in the 
library. Table 4-3 is a checklist indicating which combinations are supported.

Table 4-3. Checklist of Available Geometric Types and Rendering Styles

				Rendering Style	

Geometric  draw   styled   pen	patnpen  fill  patnfill  frame	patnframe
Type

line	    X	    X	    X	    X

oval	    X	    X			    X	    X	    X	    X

ovalarc     X	    X	    X	    X

piearc	    X	    X	    X	    X	    X	    X

point	    X		    X	    X

polygon 				     X	     X

polylin     X		    X	    X

rect	    X				    X	    X	    X	    X

seed					    X	    X

4.2 Coordinate Systems

Figure 4-1 shows the conventions used by the library to map x-y coordinates 
onto the screen.

Figure 4-1. Screen Coordinates and Drawing Coordinates

The screen coordinate system maps the pixels on the display surface to x and y 
coordinates. By convention, the screen origin is located in the top left corner 
of the screen. The x axis is horizontal, and x increases from left to right. 
The y axis is vertical, and y increases from top to bottom.

A drawing coordinate system is also defined. All drawing operations (both 
graphics and text output) take place relative to the drawing origin. Unlike the 
screen origin, which remains fixed, the drawing origin can be moved relative to 
the screen. The directions of the x and y axes match those of the screen 
coordinate system.

The drawing origin is aligned with the screen origin immediately after  
initialization of the graphics environment by the set_config function. The 
drawing origin may be displaced in x and y from the screen origin by means of a 
call to the set_draw_origin function. All subsequent drawing operations are 
specified relative to the new drawing origin.While Fig4-1 shows the drawing ori-
gin lying within the boundaries of the screen, the origin may also be moved to a
position above, below or to the side of the screen. Only objects that are drawn
on the screen and within the clipping window (to be described) will be visible.

Figure 4-2 is a close-up of several pixels in the vicinity of the drawing 
origin that 
illustrates the relationship of the pixels on the screen to the coordinate grid 
lines. Each vertical or horizontal grid line corresponds to an integer x or y 
coordinate value. Centered within each square of the grid is a pixel, drawn as 
a circle.

The draw and styled functions within the library (refer to Table 4-2) identify a
pixel by the integer x-y coordinates at the top left corner of its grid square.
For instance, the pixel designated by the function call

	draw_point(2, 1);

is, in fact, centered at (2.5, 1.5) and is darkened in Figure 4-2.

Figure 4-2. Mapping of Pixels to Coordinate Grid

The graphics library represents x-y coordinates as 16-bit signed integers. 
Valid coordinate values are limited to the range -16384 to +16383. Restricting 
the values to this range provides one guard bit to protect against overflow 
during 16-bit arithmetic operations.

4.3 Area-Filling Conventions

The fill, frame, and pen functions within the library designate a pixel as 
being part of a filled region if the center of the pixel falls within the 
boundary of that region.

Figure 4-3 shows an example of a filled region - a rectangle of width 5 and 
height 3. The top left corner
of the rectangle is located at coordinates (4, 2). The function
call to fill this particular rectangle is

	fill_rect(5, 3, 4, 2);

The pixels selected to fill the rectangle are indicated in the figure.

Figure 4-3. A Filled Rectangle

 

As a second example, a filled polygon is shown in . The five straight edges of 
the polygon separate the interior of the polygon, which is filled, from the 
exterior. (This figure was drawn using the fill_polygon function.)

Figure 4-4. A Filled Polygon

By convention, a pixel is considered to be part of the interior if its center 
falls within the boundary of the polygon. If the center falls precisely on a 
boundary, the pixel is inside if and only if the polygon interior is 
immediately to its right (x-increasing direction). Pixels with centers along a 
horizontal edge are a special case and are inside if and only if the polygon 
interior is immediately below (y-increasing direction).

The names of graphics functions that follow the area-filling conventions 
described in this section include the modifiers fill, pen, or frame.

4.4 Vector-Drawing Conventions

Mathematically ideal points, lines, and arcs are defined to be infinitely thin. 
Since these figures contain no area, they would be invisible if drawn using the 
conventions described above for filled areas. A different set of conventions 
must be used to make points, lines and arcs visible. These are referred to as 
vector-drawing conventions to distinguish them from the area-filling 
conventions. Vector-drawing conventions apply to all library functions whose 
names include the modifiers draw or styled.

The vector-drawing conventions associate the point specified by the integer 
coordinate pair (x, y) with the pixel that lies just to the lower right of this 
point; that is, the pixel whose center lies at coordinates (x+1/2, y+1/2). For 
example, the function call

	draw_point(2, 1);

draws the pixel centered at (2.5, 1.5), as shown in Figure 4-2.

As a second example, the polygon from Figure 4-4 is shown again in Figure 4-5, 
but this time it is 
outlined rather than filled. (This figure was drawn using the draw_polyline 
function.) The integer coordinate points selected to represent the edges of the 
polygon are indicated as small black dots. The pixel to the lower right of each 
point is turned on to represent the edge of the polygon.

Figure 4-5. An Outlined Polygon

A line or arc drawn using the vector-drawing conventions consists of a thin, 
but connected set of pixels selected to follow the ideal line or arc as closely 
as possible. Each pixel is horizontally, vertically, or diagonally adjacent to 
its neighbor on either side, with no holes or gaps in between. The resulting 
line or arc is only a single pixel in thickness.

4.5 Rectangular Drawing Pen

The graphics functions that follow the vector-drawing conventions above can 
draw only lines and arcs that are a single pixel in thickness. To draw lines 
and arcs of arbitrary thickness, a logical pen (or brush) is defined. Library 
functions that use the pen include the modifier pen as part of their names.

The drawing pen is rectangular, and its position is defined by the integer 
coordinates at its top left corner. When a pen of  integer width w and height h 
draws a point at (x, y), the rectangle's top left corner lies at (x, y), and 
its bottom right corner lies at (x+w, y+h). The rectangular area covered by the 
pen is filled either with a solid color or with an area-fill pattern, depending 
on the function called.

Figure 4-6 shows a line from (1, 4) to (7, 1) drawn by a pen of width 1 and 
height 2. The pen is initially positioned
at the bottom left of the figure, with its top left
corner at (1, 4). As the pen moves along the line, the pen is always located 
with its top left corner touching the ideal line. The area swept out by the pen 
as it traverses the line from start to end is filled according to the 
area-filling conventions described previously. The pixels interior to the line 
are indicated in the figure.

Figure 4-6. A Line Drawn by a Pen

When the pen's width and height are both 1, a line or arc drawn by the pen is 
similar in appearance to one drawn using the vector-drawing conventions 
discussed previously. The pen, however, conforms to the area-filling 
conventions, and a pen function can track the perimeter of a filled figure more 
faithfully than the corresponding vector-drawing function can.

For instance, consider an ellipse defined by some width w, height h, and 
top-left-corner coordinates (x, y). The ellipse is filled by the function call

	fill_oval(w, h, x, y);

If the filled ellipse is outlined by calling draw_oval, which is a 
vector-drawing function, with the same arguments, the outline may not conform 
to the edge of the filled area, and gaps may appear between the filled area and 
the outline. Calling the pen_oval function with the same arguments, however, 
draws an outline that follows the edge of the filled area precisely, remaining 
flush to the ellipse at all points along the perimeter.

4.6 Area-Fill Patterns

Graphics functions that include the modifier patn as part of their names fill 
geometric figures with a two-dimensional pattern rather than a solid color. 
Currently, the only area-fill patterns supported are two-color patterns that 
are 16 pixels wide by 16 pixels high.

The tiling of patterns to the screen is currently fixed relative to the top 
left corner of the screen. In other words, changing the drawing origin causes 
no shift in the mapping of the pattern to the screen, although the geometric 
objects filled with the pattern are themselves positioned relative to the 
drawing origin. The screen-relative x and y coordinate values at the top left 
corner of each instance of the pattern are multiples of 16.

Before an area on the screen is filled with a particular pattern, the pattern 
must be installed by calling the set_patn function. The pattern is specified as 
a 16-by-16 bit map, as shown in , and is stored in memory as an array of 256 
contiguous bits. The bits within a pattern bit map are listed in left-to-right 
order within a row, and the rows are listed in top-to-bottom order. For 
instance, the top row in the figure contains bits 0 (left) to 15 (right); bit 
255 is located in the bottom right corner. The shaded squares in  represent to 
1s in the source bit map, and white squares represent to 0s. When a pattern is 
drawn to the screen, screen pixels corresponding to 1s in the bit map are 
replaced by the foreground color, and 0s by the background color.

Figure 4-7. A 16-by-16 Area-Fill Pattern

4.7 Line-Style Patterns

Graphics functions that include the modifier styled as part of their names draw 
lines and arcs using a line-style pattern. A line-style pattern is a 
1-dimensional pattern of two colors. The pattern controls the color of each 
successive pixel output to the screen as a line or arc is drawn.

The line-style pattern is specified as a 32-bit mask containing a repeating 
pattern of 1s and 0s. The pattern bits are consumed in the order 0,1,...,31, 
where 0 is the LSB. If the line is more than 32 pixels long, the pattern is 
repeated modulo 32 as the line is drawn. A bit value of 1 in the pattern mask 
means that the corresponding pixel is drawn in the foreground color, while a 0 
means that the pixel is drawn in the background color. As an option, background 
pixels can be skipped over rather than drawn.

When a line-style pattern function such as styled_line is called, either a new 
pattern mask is specified, or an old one is reused. The latter option supports 
the drawing of continuous patterns across a series of connecting lines. After a 
styled_line has been used to draw a line n pixels in length, the original 
pattern has been rotated left (n-1) modulo 32 bits. The rotated pattern is 
always saved by the function before returning. The saved pattern is ready to be 
used as the pattern for a second line that continues from the end point of the 
first line. The last pixel plotted in the first line is identical to the first 
pixel in the second line.

For example, three connected styled lines are shown in . Darkened pixels 
correspond to 1s in the line-style mask, and white pixels correspond to 0s. The 
lines in the  are drawn by the following three function calls:

	styled_line(2, 1, 7, 1, 1, 0xF3F3F3F3);
	styled_line(7, 1, 10, 4, 3, 0);
	styled_line(10, 4, 10, 8, 3, 0);

The first call loads the line-style mask 0xF3F3F3F3, and draws a line from (2, 
1) to (7, 1). The last two calls reuse the mask loaded by the first call and 
draw lines from (7, 1) to (10, 4) to (10, 8).

Figure 4-8. Three Connected Styled Lines

4.8 Operations on Pixels

Drawing (or graphics output) operations consist of replacing one or more pixels 
on the screen with new pixel values. By default, a specified source pixel 
simply replaces a designated destination pixel. The graphics library, however, 
provides several optional methods for processing the source and destination 
pixel values to determine the final pixel value written to the screen.

- Transparency is a pixel attribute that, when enabled, permits objects 
  written onto the screen to have transparent regions through which the 
  original background pixels are preserved.

- The plane mask specifies which bits within pixels can be modified 
  during pixel operations.

- Boolean and arithmetic pixel-processing operations specify how source 
  and destination pixel values are combined.

These three methods for processing pixels can be used independently or in 
conjunction with each other. Transparency, plane masking, and pixel processing 
are orthogonal in the sense that they can be used in any combination, and each 
is controlled independently of the other two. These attributes affect all 
drawing operations, including those that involve text, geometric objects, and 
pixel arrays.

Immediately following initialization of the drawing environment by the 
set_config function, the following defaults are in effect:

- Transparency is disabled (all pixels are opaque).

- The plane mask is 0 (all bits within pixels can be modified).

- The pixel-processing operation is replace (the source pixel value 
  simply replaces the destination pixel).

Transparency, plane masking, and pixel processing are described individually 
below. Refer to the user's guides for the TMS34010 and TMS34020 for additional 
information.

4.8.1 Transparency

Pixel transparency is useful in applications involving text, area-fill 
patterns, and pixel arrays in which only the shapes, and not the extraneous 
pixels surrounding them, are to be drawn to the screen. When a rectangular 
pixel array containing a shape is written to the screen, the pixel transparency 
attribute can be enabled to avoid modifying destination pixels in the 
rectangular region surrounding the shape. In effect, the source pixels 
surrounding the shape are treated as though they are transparent rather than 
opaque.

The library's default transparency mode is enabled and disabled by calls to the 
transp_on and transp_off functions. In TMS34020-based systems, additional
transparency modes may be selected by means of the set_transp function. Only 
the default mode is available in TMS34010-based systems. Refer to the TMS34020 
User's Guide for information on the additional modes.

When transparency is enabled in the default mode, a pixel that has a value of 0 
is considered to be transparent, and it will not overwrite a destination pixel. 
The check for a 0-valued pixel is applied not to the source pixel value, but to 
the pixel value resulting from pixel processing and plane masking. In the case 
of pixel processing operations such as AND, MIN, and replace, a source pixel 
value of 0 ensures that the result of the operation will be a transparent 
pixel, regardless of the destination pixel value.

4.8.2 Plane Mask

The plane mask specifies which bits within a pixel are protected from 
modification, and affects all operations on pixels. The plane mask has the same 
number of bits as a pixel in the display memory. A value of 1 in a particular 
plane mask bit means that the corresponding bit in a pixel is protected from 
modification. Pixel bits corresponding to 0s in the plane mask can be modified.

The plane mask allows the bits within the pixels on the screen to be 
manipulated as bit planes (or color planes) that can be modified independently 
of other planes. A useful way to think of planes is as laminations or layers 
parallel to the display surface. The number of planes is the same as the number 
of bits in a pixel.

For example, at 4 bits per pixel, three contiguous planes can be dedicated to 
8-color graphics, while the fourth is used to overlay text in a single color. 
The plane mask permits the text layer to be manipulated independently of the 
graphics layers, and vice versa.

During a write to a pixel in memory, the 1s in the plane mask designate which 
bits in the pixel are write-protected; only pixel bits corresponding to 0s in 
the plane mask are modified. During a pixel read, 1s designate which bits 
within a pixel are always read as 0, regardless of their values in memory; only 
pixel bits corresponding to 0s in the plane mask are read as they appear in 
memory.

The plane mask can be modified by means of a call to the library's set_pmask 
function.

4.8.3 Pixel-Processing Operations

During drawing operations, source and destination pixels are combined according 
to a specified Boolean or arithmetic operation and written back to the 
destination pixel. The library supports 16 Boolean pixel-processing operations 
(or "raster ops") and 6 arithmetic operations. The Booleans are performed in 
bitwise fashion on operand pixels, while the arithmetic operations treat pixels 
as unsigned integers.

 A 5-bit PPOP code specifies one of the 22 pixel-processing operations, as 
shown in Table 4-4 and Table 4-5. Legal PPOP codes are in the range 0 to 21.
As shown in the two tables, codes
for Boolean operations are in the range 0 to 15, and codes for
arithmetic operations are in the range 16 to 21.

Table 4-4. Boolean Pixel-Processing Operation Codes

PPOP Code			Description

0			replace destination with source

1			source AND destination

2			source AND NOT destination

3			set destination to all 0s

4			source OR NOT destination

5			source EQU destination

6			NOT destination

7			source NOR destination

8			source OR destination

9			destination (no change)

10			source XOR destination

11			NOT source AND destination

12			set destination to all 1s

13			NOT source OR destination

14			source NAND destination

15			NOT source

Table 4-5. Arithmetic Pixel-Processing Operation Codes

PPOP Code			Description

16			source plus destination (with overflow)

17			source plus destination (with saturation)

18			destination minus source (with overflow)

19			destination minus source (with saturation)

20			MAX(source, destination)

21			MIN(source, destination)

The result of an arithmetic pixel-processing operation is undefined at screen 
pixel sizes of 1 and 2 bits on the TMS34010, and at a pixel size of 1 bit on 
the TMS34020.

The PPOP code can be altered with a call to the set_ppop function.

4.9 Clipping Window

The graphics output produced by the library's drawing functions is always 
confined to the interior of a rectangular clipping window that occupies all or 
a portion of the screen. All library drawing functions automatically inhibit 
attempted writes to pixels outside this window.

The width, height, and position of the clipping window can be modified by a 
call to the set_clip_rect function. The function call

	set_clip_rect(w, h, x, y);

defines the window to be a rectangle of width w and height h whose top left 
corner lies at coordinates (x, y). The x-y coordinates are specified relative 
to the drawing origin in effect at the time the function is called. The four 
sides of the clipping window are parallel to the x and y axes. If a clipping 
rectangle is specified that lies partially outside the screen boundaries, the 
set_clip_rect function automatically trims the window to the limits of the 
screen.

The default clipping window covers the entire screen. This default is in effect 
immediately following initialization of the drawing environment by the 
set_config function.

4.10 Pixel-Size Independence

The TMS34010 can support pixel sizes of 1, 2, 4, 8, and 16 bits, and the 
TMS34020 can support pixel sizes of 1, 2, 4, 8, 16, and 32 bits. Any particular 
TMS340 graphics processor-based display hardware system, however, may support 
only a subset of the pixel sizes that the processor itself can handle. Possible 
hardware limitations include the amount of video RAM in the system and the 
pixel sizes supported by the color palette device.

With the exception of the handful of system-dependent functions described in 
subsection , the graphics library functions are written to be independent of 
the pixel size. The library achieves pixel-size independence by taking 
advantage of special graphics hardware internal to the TMS34010 and TMS34020 
processor chips. Changing the pixel size in software is not much more difficult 
than loading the processor's PSIZE (pixel size) register with a new value.

Application programs based on the graphics library are potentially able to 
execute on display systems that support a variety of pixel sizes. Ideally, an 
application program should be flexible enough to take advantage of the large 
number of colors available in systems with large pixel sizes, yet also run 
satisfactorily in systems that are limited to small pixel sizes. In practice, 
this ideal may be difficult to achieve.

For instance, an application written to run on a 1-bit-per-pixel display should 
be able to run with little modification at 2, 4, 8, 16, or 32 bits per pixel. 
This is achieved, however, by restricting the application's choice of colors to 
black and white, regardless of the number of colors supported by the display 
hardware.

At the other end of the spectrum, consider an application that is written to 
control a true color display with 8 bits of red, green, and blue intensity per 
pixel. The application writer may be able to stretch the program to reasonably 
accommodate pixel sizes of 16 or even 8 bits per pixel, although at some loss 
in image quality. This can be done by using certain well-known halftoning or 
ordered-dithering algorithms to simulate a larger palette of colors. The 
application is unlikely, however, to run satisfactorily on a 1-bit-per-pixel 
display.

To summarize, the graphics library's high degree of pixel-size independence 
represents a powerful and useful feature. This does not automatically guarantee 
that all applications that call the library will not themselves contain 
inherent color dependencies.

