exodus@uop.UUCP (Freddy Kreuger) (10/10/87)
#! /bin/sh
# This is a shell archive. Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file". To overwrite existing
# files, type "sh file -c". You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g.. If this archive is complete, you
# will see the following message at the end:
# "End of archive 1 (of 2)."
# Contents: gem10.asc gem9.asc
# Wrapped by exodus@uop on Thu Oct 8 16:49:37 1987
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f gem10.asc -a "${1}" != "-c" ; then
echo shar: Will not over-write existing file \"gem10.asc\"
else
echo shar: Extracting \"gem10.asc\" \(12387 characters\)
sed "s/^X//" >gem10.asc <<'END_OF_gem10.asc'
X *PROFESSIONAL GEM*
X by Tim Oren
X Column #10 - VDI Graphics: Text Output
X
X This issue of ST PRO GEM concludes the two column series on
XVDI with a look at simple VDI text output, and ways to optimize
Xits speed. There is also a Feedback section. You may find the
Xassociated download file under the name GMCL10.C in DL3 of the
XATARI16 SIG (PCS-58).
X
X To keep the size of this first discussion of text within
Xreason, I am going to restrict it to use of the mono-spaced system
Xfont in its default size and orientation. Discussion of
Xalternate and proportionally spaced fonts, baseline rotation, and
Xcharacter scaling will become a later article in this series.
X
X DEFINITIONS. This article makes use of some terminology
Xwhich may be unfamiliar if you have not used digital typefaces. A
Xmono-spaced font is one in which each character occupies an
Xidentically wide space on the screen. A proportional font has
Xcharacters which occupy different widths. For instance, an 'l'
Xwould probably be narrower than a 'w'.
X
X Text may be "justified" right, left, or center. This means
Xthat the right character, left character, or center position of
Xthe text string is constrained to a given location. In common
Xusage, a page of text is "ragged right" if its lines are left
Xjustified only. The text page is "fully justified", "justified"
Xor (ambiguously) "right justified" if BOTH the left and right
Xcharacters are contrained to fixed columns. Full justification is
Xproduced by inserting extra blank characters in the case of a
Xmono-spaced font, or by adding extra pixel columns in the case of
Xproportional output.
X
X A text character (in a monospaced font) is written inside a
Xstandard sized cell or box. Vertically, the cell extends from the
X"top line" down to the "bottom line". If there are one or more
Xblank lines at the top or bottom, they are called "leading" and
Xare used to separate lines of text. The characters themselves
Xalways fall between the "ascent line", which is the highest line
Xreached by characters such as 'd' and 'l', and the "descent line",
Xwhich is the lowest line in characters like 'q' and 'g'. Other
Xlocations of interest are the "half line", which is the top of
Xcharacters like 'a' or 'n', and the "base line", which is the
Xbottom of characters which do not have descenders.
X
X Before plunging into the Attribute Functions for text, you
Xshould note that the writing mode (vswr_mode) and clipping
Xrectangle (vs_clip) attributes discussed in the last column (#9)
Xalso pertain to text. Since much of the discussion of text
Xoptimization will center on these attributes, you may want to
Xreview them.
X
X TEXT ATTRIBUTES. The writing color for graphics text is set
Xwith the command:
X
X vst_color(vdi_handle, color);
X
XVdi_handle is always the handle returned from graf_handle() at
Xapplication startup. Color is a word value between 0 and 15 which
Xdesignates the output color index. As discussed in previous
Xcolumns, the actual color which appears is dependent on the
Xcurrent palette settings. In applications such as word and
Xoutline processors it is important that characters and their
Xbackground provide good contrast to avoid eyestrain. In these
Xsituations, you may want to use the setPalette and/or setColor
XXBIOS functions to force the palette to a known state before
Xstarting the application.
X
X You can choose a variety of special output effects for your
Xtext with the call:
X
X vst_effects(vdi_handle, effects);
X
XEffects is a single flag word, with the bits having the following
Xsignificance:
X
X 0 - Thicken
X 1 - Lighten
X 2 - Skew
X 3 - Underline
X 4 - Outline
X 5 - Shadow
X
XIn each case, turning the bit on selects the effect. Otherwise,
Xthe effect is off. Any number of multiple effects may be
Xselected, but the result may not always be pleasing or legible.
X
X The "thicken" effect widens the character strokes by one
Xpixel, resulting in the appearance of boldface type. The
X"lighten" effect superimposes a half-tone dither on the character.
XThis mode is useful for indicating non-selectable text items, but
Xis not legible enough for other purposes.
X
X The skew effect shifts the rows of the character the right,
Xwith the greatest displacement at the top. This results in the
Xappearance of italic text. You should be aware that the VDI does
Xnot compensate for this effect. This means that a skewed italic
Xcharacter which is immediately followed by a normal blank will be
Xoverstruck, and part of the top of the character will disappear.
XLikewise, a skewed character written to the left of an existing
Xnormal character will overstrike part of it. There is a related
Xbug in the VDI clipping logic which may cause some parts of a
Xskewed character not to be redrawn if they fall at the edge of a
Xclipping rectangle, even though they should fall within the
Xregion.
X
X The outline effect produces output which is a one pixel
X"halo" around the normal character. The shadow effect attempts to
Xcreate a "drop shadow" to the side of the character. These
Xeffects should be used very sparingly with default sized fonts.
XThey often result in illegible output.
X
X When graphics text is written, a screen coordinate must be
Xspecified for the output. The relationship of the text to the
Xscreen point is determined by the call:
X
X vst_alignment(vdi_handle, hin, vin, &hout, &vout);
X
XHin and vin are each words, with values specifying the desired
Xhorizontal and vertical alignment, respectively. Hout and vout
Xreceive the actual values set by the VDI. If they differ from the
Xrequested values, an error has occurred.
X
X Hin may be set to zero for left justification, one for center
Xjustification, or two for right justification. The coordinate
Xgiven when text is written becomes the "anchor point" as described
Xin the definitions above. The default justification is left.
X
X Vin determines what reference line of the text is positioned
Xat the output coordinate. The selection values are:
X
X 0 - baseline (default)
X 1 - half line
X 2 - ascent line
X 3 - bottom line
X 4 - descent line
X 5 - top line
X
X A common combination of alignments is left (0) and top line
X(5). This mode guarantees that all text output will lie to the
Xright and below the output coordinate. This corresponds with the
XAES object and GRECT coordinate systems.
X
X Finally, the call to do the actual output is:
X
X v_gtext(vdi_handle, x, y, string);
X
XX and y define the screen coordinate to be used as the alignment
Xpoint. String is a pointer to a null terminated string, which
Xmust be total eighty characters or less, exclusive of the null.
XThis limit is imposed by the size of the intin[] array in the VDI
Xbinding. Be warned that it is NOT checked in the standard
Xbinding! Exceeding it may cause memory to be overwritten.
X
X One Inquire Function is useful with text output. The call
X
X vqt_attributes(vdi_handle, attrib);
X
Xreads back the current attribute settings into the 10 word array
Xattrib[]. The main items of interest are attrib[6] through
Xattrib[9], which contain the width and height of characters, and
Xthe width and height of the character cell in the current font.
XYou should rely on this function to obtain size information,
Xrather than using the output of the graf_handle() function. On
Xthe ST, graf_handle() always returns sizes for the monochrome mode
Xsystem font, which will be incorrect in the color screen modes.
X
X Attrib[1] will contain the current graphics text color as set
Xby vst_color(). Attrib[3] and [4] contain the horizontal and
Xvertical alignment settings, respectively. Attrib[5] contains the
Xcurrent writing mode, as set by vswr_mode().
X
X OPTIMIZATION. The most common complaint about using bit maps
Xfor character output is lack of speed. This section suggests ways
Xto speed things up. By adopting all of these methods, you can
Xrealize an improvement of two to three times in speed.
X
X BYTE ALIGNMENT. Since writing graphic text is essentially a
Xbit-blit operation, characters which have "fringes", that is, do
Xnot align evenly with byte boundaries, will suffer performance
Xpenalities. The default system fonts in all resolutions of the ST
Xare a multiple of eight pixels wide, so the problem reduces to
Xassuring that each characters starts at a byte boundary in the
Xscreen bit map. This will be true if the horizontal pixel address
Xof the left edge of the character is evenly divisible by eight.
X
X Obviously, byte alignment is easiest to enforce when the
Xhorizontal justification is right or left. Doing so with centered
Xtext is possible, but requires adding padding blanks to odd length
Xstrings.
X
X When writing text within windows, it is helpful to assure
Xthat the edges of the window working area are byte aligned. There
Xis a section of code in the download which shows a technique for
Xconverting a user requested window position and/or size to its
Xworking dimensions, byte-aligning the width and horizontal
Xposition, and computing the adjusted external window coordinates.
X
X WRITING MODE. The fastest text output mode is replace. All
Xother modes require reading in the target raster area and merging
Xit with the new information. You may find that you must use
Xtransparent or reverse transparent mode, for instance, to use or
Xpreserve an underlying background color other than white. In this
Xcase, you can still do some optimization by filling in the
Xbackground color for the entire string with a v_bar() call, rather
Xthan doing it one character cell at a time.
X
X CLIPPING. VDI output always proceeds faster when the
Xclipping rectangle is turned off, and text output is no exception.
XRemember that you may only do this if you are drawing into a
Xdialog box, or into the interior of a window which you know is on
Xtop. (You can use the WM_TOPPED and WM_NEWTOP messages for
Xkeeping track of the top window, or use the WF_TOP wind_get() call
Xto find the current top.) In both of these cases, you will know
Xthe width of the drawing area, and you can truncate the output
Xstring to fit exactly, rather than setting the clipping rectangle.
XFor this to work, you must have used the byte alignment technique
Xto assure that the width of the writing area is a multiple of
Xeight.
X
X BINDINGS. The normal binding for v_gtext() is inefficient.
XIt copies the string which you supply character-by-character into
Xintin[] before it calls the VDI itself. In many cases, it will be
Xmore efficient for your application to place characters directly
Xinto intin[] and make the VDI trap call directly. To give you a
Xstart, the code for the standard v_gtext() binding has been
Xincluded in the download. When setting up intin[], be sure not to
Xload more than 80 characters, or you will probably crash the
Xsystem!
X
X MOVING TEXT. When performing text editing on the screen, you
Xshould avoid rewriting the string under edit whenever possible.
XIt is always more efficient to use the raster operations to move a
Xstring to the right or left, assuming that you have obeyed the
Xbyte alignment rule. If you are deleting characters, blit the
Xunchanged part of the screen to the left, and overstrike the last
Xcharacter in the string with a blank. If inserting characters,
Xblit the trailing portion of the string to the right before
Xwriting in the new character.
X
X THAT'S IT FOR NOW. This concludes the two article series on
Xsimple VDI output. Future columns may explore more complex VDI
Xtopics such as proportional text. If there is something you would
Xlike to see, please use the Online Feedback to let me know!
XMeanwhile, the next column will give out the locations of some of
Xthe "hooks" and "trapdoors" built into the AES object structure,
Xincluding how to set up user-defined AES drawing objects.
END_OF_gem10.asc
if test 12387 -ne `wc -c <gem10.asc`; then
echo shar: \"gem10.asc\" unpacked with wrong size!
fi
# end of overwriting check
fi
if test -f gem9.asc -a "${1}" != "-c" ; then
echo shar: Will not over-write existing file \"gem9.asc\"
else
echo shar: Extracting \"gem9.asc\" \(20502 characters\)
sed "s/^X//" >gem9.asc <<'END_OF_gem9.asc'
X *PROFESSIONAL GEM*
X By Tim Oren
X Column #9 - VDI Graphics: Lines and Solids
X
X This issue of ST PRO GEM is the first in a series of two
Xwhich will explore the fundamentals of VDI graphics output. In
Xthis installment, we will take a look at the commands necessary to
Xoutput simple graphics such as lines, squares and circles as well
Xas more complex figures such as polygons. The following episode
Xwill take a first look at graphics text output, with an emphasis
Xon ways to optimize its drawing speed. It will also include
Xanother installment of ONLINE Feedback. As usual, there is a
Xdownload with this column. You should find it under the name
XGEMCL9.C in DL3 of ATARI16 (PCS-58).
X
X A BIT OF HISTORY
X
X One of the reasons that the VDI can be confusing is that
Xdrawing anything at all, even a simple line, can involve setting
Xaround four different VDI parameters before making the draw call!
X(Given the state of the GEM documents, just FINDING them can be
Xfun!) Looking backwards a bit sheds some light on why the VDI is
Xstructured this way, and also gives us a framework for organizing
Xa discussion of graphics output.
X
X The GEM VDI closely follows the so-called GKS standard, which
Xdefines capabilities and calling sequences for a standardized
Xgraphic input/output system. GKS is itself an evolution from an
Xearly system called "Core". Both of these standards were born in
Xthe days when pen plotters, vectored graphics displays, and
Xminicomputers were the latest items. So, if you wonder why
Xsetting the drawing pen color is a separate command, just think
Xback a few years when it actually meant what it says! (The
Xcynical may choose instead to ponder the benefits of
Xstandardization.)
X
X When doing VDI output, it helps if you pretend that the
Xdisplay screen really is a plotter or some other separate device,
Xwhich has its own internal parameters which you can set up and
Xread back. The class of VDI commands called Attribute Functions
Xlet you set the parameters. Output Functions cause the "device"
Xto actually draw someone once it is configured. The Inquire
XFunctions let you read back the parameters if necessary.
X
X There are two parameters which are relevant no matter what
Xtype of object you are trying to draw. They are the writing mode
Xand the clipping rectangle. The writing mode is similar to that
Xdiscussed in the column on raster operations. It determines what
Xeffect the figure you are drawing will have on data already on the
Xscreen. The writing mode is set with the call:
X
X vswr_mode(vdi_handle, mode);
X
X (Vdi_handle, here and below, is the handle obtained from
Xgraf_handle at the beginning of the program. Mode is a word which
Xmay be one of:
X
X 1 - Replace Mode
X 2 - Transparent Mode
X 3 - XOR mode
X 4 - Reverse Transparent Mode
X
X In replace mode, whatever is on the screen is overwritten.
XIf you are writing characters, this means the background of each
Xcharacter cell will be erased.
X
X In transparent mode, only the pixels directly under the
X"positive" part of the image, that is, where 1-bits are being
Xwritten, will be changed. When writing characters, the background
Xof the cell will be left intact.
X
X In XOR mode, an exclusive or is performed between the screen
Xcontents and what is being written. The effect is to reverse the
Ximage under areas where a 1-bit occurs.
X
X Reverse transparent is like transparent, but with a "reverse
Xcolor scheme". That is, only places where a 0-bit is to be
Xput are changed to the current writing color. When you
Xwrite characters in reverse transparent (over white), the effect
Xis reverse video.
X
X The other common parameter is the clipping rectangle. It
Xdefines the area on the screen where the VDI is permitted to draw.
XAny output which would fall outside of this area is ignored; it is
Xeffectively a null operation. The clip rectangle is set with the
Xcall:
X
X vs_clip(vdi_handle, flag, pxy);
X
X Pxy is a four-word array. Pxy[0] and pxy[1] are the X and Y
Xscreen coordinates, respectively, of one corner of your clipping
Xrectangle. Pxy[2] and pxy[3] are the coordinates of the
Xdiagonally opposite corner of the rectangle. (When working with
Xthe AES, use of a GRECT to define the clip is often more
Xconvenient. The routine set_clip() in the download does this.)
X
X Flag is set to TRUE if clipping is to be used. If you set it
Xto FALSE, the entire screen is assumed to be fair game.
X
X Normally, you should walk the rectangle list for the current
Xwindow to obtain your clipping rectangles. (See ST PRO GEM #2 for
Xmore details.) However, turning off the clip speeds up all output
Xoperations, particularly text. You may do this ONLY when you are
Xabsolutely certain that the figure you are drawing will not extend
Xout of the top-most window, or out of a dialog.
X
X THE LINE FORMS ON THE LEFT
X
X The VDI line drawing operations include polyline, arc,
Xelliptical arc, and rounded rectangle. I'll first look at the
XAttribute Functions for line drawing, then go through the drawing
Xprimitives themselves.
X
X The most common used line attributes are color and width.
XThe color is set with:
X
X vsl_color(vdi_handle, color);
X
X where color is one of the standard VDI color indices, ranging
Xfrom zero to 15. (As discussed in column #6, the color which
Xactually appears will depend on the pallette setting of your ST.)
X
X The line width may only be set to ODD positive values, for
Xreasons of symmetry. If you try to set an even value, the VDI
Xwill take the next lower odd value. The call is:
X
X vsl_width(vdi_handle, width);
X
X The two less used line parameters are the end style and
Xpattern. With the end style you can cause the output line to
Xhave rounded ends or arrowhead ends. The call is:
X
X vsl_ends(vdi_handle, begin_style, end_style);
X
X Begin_style and end_style are each words which may have the
Xvalues zero for square ends (the default), one for arrowed ends,
Xor two for rounded ends. They determine the styles for the
Xstarting and finishing ends of the line, respectively.
X
X The line pattern attribute can select dotted or dashed lines
Xas well as more complicated patterns. Before continuing, you
Xshould note one warning: VDI line output DOES NOT compensate for
Xpixel aspect ratio. That is, the dashes on a line will look twice
Xas long drawn vertically on a medium-res ST screen as they do when
Xdrawn horizontally. The command for setting the pattern is:
X
X vsl_type(vdi_handle, style);
X
X Style is a word with a value between 1 and 7. The styles
Xselected are:
X
X 1 - Solid (the default)
X 2 - Long Dash
X 3 - Dot
X 4 - Dash, Dot
X 5 - Dash
X 6 - Dash, Dot, Dot
X 7 - (User defined style)
X
X The user defined style is determined by a 16-bit pattern
Xsupplied by the application. A one bit in the pattern turns a
Xpixel on, a zero bit leaves it off. The pattern is cycled through
Xrepeatedly, using the high bit first. To use a custom style, you
Xmust make the call:
X
X vsl_udsty(vdi_handle, pattern);
X
X before doing vsl_type().
X
X As I mentioned above, the line type Output Functions
Xavailable are polyline, circular and ellliptical arc, and rounded
Xrectangle. Each has its own calling sequence. The call for a
Xpolyline is:
X
X v_pline(vdi_handle, points, pxy);
X
X Points tells how many vertices will appear on the polyline. For
Xinstance, a straight line has two vertices: the end and the
Xbeginning. A closed square would have five, with the first and
Xlast identical. (There is no requirement that the figure
Xdescribed be closed.)
X
X The pxy array contains the X and Y raster coordinates for the
Xvertices, with a total of 2 * points entries. Pxy[0] and pxy[1]
Xare the first X-Y pair, and so on.
X
X If you happen to be using the XOR drawing mode, remember that
Xdrawing twice at a point is equivalent to no drawing at all.
XTherefore, for a figure to appear closed in XOR mode, the final
Xstroke should actually stop one pixel short of the origin of the
Xfigure.
X
X You may notice that in the GEM VDI manual the rounded
Xrectangle and arc commands are referred to as GDPs (Generalized
XDrawing Primitives). This denotation is historical in nature, and
Xhas no effect unless you are writing your own VDI bindings.
X
X The rounded rectangle is nice to use for customized buttons
Xin windows and dialogs. It gives a "softer" look to the screen
Xthan the standard square objects. The drawing command is:
X
X v_rbox(vdi_handle, pxy);
X
X Pxy is a four word array giving opposite corners of the
Xrectangle, just as for the vs_clip() call. The corner rounding
Xoccurs within the confines of this rectangle. Nothing will
Xprotrude unless you specify a line thickness greater than one.
XThe corner rounding is approximately circular; there is no user
Xcontrol over the degree or shape of rounding.
X
X Both the arc and elliptical arc commands use a curious method
Xof specifying angles. The units are tenths of degrees, so an
Xentire circle is 3600 units. The count starts at ninety degrees
Xright of vertical, and proceeds counterclockwise. This means that
X"3 o'clock" is 0 units, "noon" is 900 units, "9 o'clock" is 1800
Xunits, and 2700 units is at "half-past". 3600 units take you back
Xto "3 o'clock".
X
X The command for drawing a circular arc is:
X
X v_arc(vdi_handle, x, y, radius, begin, end);
X
X X and y specify the raster coordinates of the center of the
Xcircle. Radius specifies the distance from center to all points
Xon the arc. Begin and end are angles given in units as described
Xabove, both with values between 0 and 3600. The drawing of the
Xarc ALWAYS proceeds counterclockwise, in the direction of
Xincreasing arc number. So values of 0 and 900 for begin and end
Xwould draw a quarter circle from "three o'clock" to "noon".
XReversing the values would draw the other three quarters of the
Xcircle.
X
X A v_arc() command which specifies a "full turn" is the
Xfastest way to draw a complete circle on the screen. Be warned,
Xhowever, that the circle drawing algorithm used in the VDI seems
Xto have some serious shortcomings at small radii! You can
Xexperiment with the CIRCLE primitive in ST Logo, which uses
Xv_arc(), to see what I mean.
X
X Notice that if you want an arc to strike one or more given
Xpoints on the screen, then you are in for some trigonometry. If
Xyour math is a bit rusty, I highly recommend the book "A
XProgrammer's Geometry", by Bowyer and Woodwark, published by
XButterworths (London, Boston, Toronto).
X
X Finally, the elliptical arc is generated with:
X
X v_ellarc(vdi_handle, x, y, xrad, yrad, begin, end);
X
X X, y, begin, and end are just as before. Xrad and yrad give the
Xhorizontal and vertical radii of the defining ellipse. This means
Xthat the distance of the arc from center will be yrad pixels at
X"noon" and "half-past", and it will be xrad pixels at "3 and 9
Xo'clock". Again, the arc is always drawn counterclockwise.
X
X There are a number of approaches to keeping the VDI's
Xattributes "in sync" with the actual output operations. Probably
Xthe LEAST efficient is to use the Inquire Functions to determine
Xthe current attributes. For this reason, I have omitted a
Xdiscussion of these calls from this column.
X
X Another idea is to keep a local copy of all significant
Xattributes, use a test-before-set method to minimize the number of
XAttribute Functions which need to be called. This puts a burden
Xon the programmer to be sure that the local attribute variables
Xare correctly maintained. Failure to do so may result in obscure
Xdrawing bugs. If your application employs user defined AES
Xobjects, you must be very careful because GEM might call your draw
Xcode in the middle of a VDI operation (particularly if the user
Xdefined objects are in the menu).
X
X Always setting the attributes is a simplistic method, but
Xoften proves most effective. The routines pl_perim() and
Xrr_perim() in the download exhibit this approach. Modification
Xfor other primitives is straightforward. This style is most
Xuseful when drawing operations are scattered throughout the
Xprogram, so that keeping track of the current attribute status is
Xdifficult. Although inherently inefficient, the difference is not
Xvery noticable if the drawing operation requested is itself time
Xconsuming.
X
X In many applications, such as data graphing programs or
X"Draw" packages, the output operations are centralized, forming
Xthe primary functionality of the code. In this case, it is both
Xeasy and efficient to keep track of attribute status between
Xsuccessive drawing operations.
X
X SOLIDS
X
X There are a wider variety of VDI calls for drawing solid
Xfigures. They include rectangle or bar, disk, pie, ellipse,
Xelliptical pie, filled rounded rectangle, and filled polygonal
Xarea. Of course, filled figure calls also have their own set of
Xattributes which you will need to set.
X
X The fill color index determines what pen color will be used
Xto draw the solid. It is set with:
X
X vsf_color(vdi_handle, color);
X
X Color is just the same as for line drawing. A solid may or
Xmay not have a visible border. This is determined with the call:
X
X vsf_perimeter(vdi_handle, vis);
X
X Vis is a Boolean. If it is true, the figure will be given a
Xsolid one pixel outline in the current fill color index. This is
Xoften useful to improve the appearance of solids drawn with a
Xdithered fill pattern. If vis is false, then no outline is drawn.
X
X There are two parameters which together determine the pattern
Xused to fill your figure. They are called interior style and
Xinterior index. The style determines the general type of fill,
Xand the index is used to select a particular pattern if necessary.
XThe style is set with the command:
X
X vsf_interior(vdi_handle, style);
X
X where style is a value from zero through four. Zero selects a
Xhollow style: the fill is performed in color zero, which is
Xusually white. Style one selects a solid fill with the current
Xfill color. A style of two is called "pattern" and a three is
Xcalled "hatch", which are terms somewhat suggestive of the options
Xwhich can then be selected using the interior index. Style four
Xselects the user defined pattern, which is described below.
X
X The interior index is only significant for styles two and
Xthree. To set it, use:
X
X vsf_style(vdi_handle, index);
X
X (Be careful here: it is very easy to confuse this call with the
Xone above due to the unfortunate choice of name.) The index
Xselects the actual drawing pattern. The GEM VDI manual shows fill
Xpatterns corresponding to index values from 1 to 24 under style 2,
Xand from 1 to 12 under style 3. However, some of these are
Ximplemented differently on the ST. Rather than try to describe
Xthem all here, I would suggest that you experiment. You can do so
Xeasily in ST Logo by opening the Graphics Settings dialog and
Xplaying with the style and index values there.
X
X The user defined style gives you some interesting options for
Xmulti-color fills. It is set with:
X
X vsf_udpat(vdi_handle, pattern, planes);
X
X Planes determines the number of color planes in the pattern
Xwhich you supply. It is set to one if you are setting a
Xmonochrome pattern. (Remember, monochrome is not necessarily
Xblack). It may be set to higher values on color systems: two for
XST medium-res mode, or four for low-res mode. If you use a number
Xlower than four under low-res, the other planes are zero filled.
X
X The pattern parameter is an array of words which is a
Xmultiple of 16 words long. The pattern determined is 16 by 16
Xpixels, with each word forming one row of the pattern. The rows
Xare arranged top to bottom, with the most significant bit to the
Xleft. If you have selected a multi-plane pattern, the entire
Xfirst plane is stored, then the second, and so on.
X
X Note that to use a multi-plane pattern, you set the writing
Xmode to replace using vswr_mode(). Since the each plane can be
Xdifferent, you can produce multi-colored patterns. If you use a
Xwriting color other than black, some of the planes may
X"disappear".
X
X Most of the solids Output Functions have analogous line
Xdrawing commands. The polyline command corresponds to the filled
Xarea primitive. The filled area routine is:
X
X v_fillarea(vdi_handle, count, pxy);
X
X Count and pxy are just the same as for v_pline(). If the
Xpolygon defined by pxy is not closed, then the VDI will force
Xclosure with a straight line from the last to the first point.
XThe polygon may be concave or self-intersecting. If perimeter
Xshow is on, the area will be outlined.
X
X One note of caution is necessary for both v_fillarea() and
Xv_pline(). There is a limit on the number of points which may be
Xstored in pxy[]. This limit occurs because the contents of pxy[]
Xare copied to the intin[] binding array before the VDI is called.
XYou can determine the maximum number of vertices by checking
Xintout[14] after using the extended inquire function vq_extnd().
X
X For reasons unknown to this writer, there are TWO different
Xfilled rectangle commands in the VDI. The first is
X
X vr_recfl(vdi_handle, pxy);
X
X Pxy is a four word array defining two opposite corners of the
Xrectangle, just as in vs_clip(). Vr_recfl() uses the fill
Xattribute settings, except that it NEVER draws a perimeter.
X
X The other rectangle routine is v_bar(), with exactly the same
Xarguments as vr_recfl(). The only difference is that the
Xperimeter setting IS respected. These two routines are the
Xfastest way to produce a solid rectangle using the VDI. They may
Xbe used in XOR mode with a BLACK fill color to quickly invert an
Xarea of the screen. You can improve the speed even further by
Xturning off the clip (if possible), and byte aligning the left and
Xright edges of the rectangle.
X
X Separate commands are provided for solid circle and ellipse.
XThe circle call is:
X
X v_circle(vdi_handle, x, y, radius);
X
X and the ellipse command is:
X
X v_ellipse(vdi_handle, x, y, xrad, yrad);
X
X All of the parameters are identical to those given above for
Xv_arc() and v_ellarc(). The solid analogue of an arc is a "pie
Xslice". The VDI pie commands are:
X
X v_pieslice(vdi_handle, x, y, radius, begin, end);
X
X for a slice from a circular pie, and
X
X v_ellpie(vdi_handle, x, y, xrad, yrad, begin, end);
X
X for a slice from a "squashed" pie. Again, the parameters are
Xidentical to those in v_arc() and v_ellarc(). The units and
Xdrawing order of angles are also the same. The final solids
XOutput Function is:
X
X v_rfbox(vdi_handle, pxy);
X
X which draws a filled rounded rectangle. The pxy array defines
Xtwo two opposite corners of the bounding box, as shown for
Xvs_clip().
X
X The issues involved in correctly setting the VDI attributes
Xfor a fill operation are identical to those in drawing lines. For
Xthose who want to employ the "always set" method, I have again
Xincluded two skeleton routines in the download, which can be
Xmodified as desired.
X
X TO BE CONTINUED
X
X This concludes the first part of our expedition through basic
XVDI operations. The next issue will tackle the problems of
Xdrawing bit mapped text at a reasonable speed. This first pass
Xwill not attempt to tackle alternate or proportional fonts, or
Xalternate font sizes. Instead, I will concentrate on techniques
Xfor squeezing greater performance out of the standard monospaced
Xsystem fonts.
END_OF_gem9.asc
if test 20502 -ne `wc -c <gem9.asc`; then
echo shar: \"gem9.asc\" unpacked with wrong size!
fi
# end of overwriting check
fi
echo shar: End of archive 1 \(of 2\).
cp /dev/null ark1isdone
MISSING=""
for I in 1 2 ; do
if test ! -f ark${I}isdone ; then
MISSING="${MISSING} ${I}"
fi
done
if test "${MISSING}" = "" ; then
echo You have unpacked both archives.
rm -f ark[1-9]isdone
else
echo You still need to unpack the following archives:
echo " " ${MISSING}
fi
## End of shell archive.
exit 0