778 lines
210 KiB
Plaintext
778 lines
210 KiB
Plaintext
Copyright (c) 1986 Xerox Corporation. All rights reserved.
|
||
|
||
2
|
||
|
||
27.17 Implementation of Image Streams
|
||
1
|
||
|
||
Interlisp does all image creation through a set of functions and data structures for device-independent graphics, known popularly as DIG. DIG is implemented through the use of a special type of stream, known as an image stream.
|
||
An image stream, by convention, is any stream that has its IMAGEOPS field (described in detail below) set to a vector of meaningful graphical operations. Using image streams, you can write programs that draw and print on an output stream without regard to the underlying device, be it a window, a disk, or a printer.
|
||
To define a new image stream type, it is necessary to put information on the variable IMAGESTREAMTYPES:
|
||
IMAGESTREAMTYPES [Variable]
|
||
1
|
||
|
||
This variable describes how to create a stream for a given image stream type. The value of IMAGESTREAMTYPES is an association list, indexed by the image stream type (e.g., DISPLAY, INTERPRESS, etc.). The format of a single association list item is:
|
||
(IMAGETYPE
|
||
(OPENSTREAM OPENSTREAMFN)
|
||
(FONTCREATE FONTCREATEFN)
|
||
(FONTSAVAILABLE FONTSAVAILABLEFN))
|
||
OPENSTREAMFN, FONTCREATEFN, and FONTSAVAILABLEFN are "image stream methods," device-dependent functions used to implement generic image stream operations. For Interpress image streams, the association list entry is:
|
||
(INTERPRESS
|
||
(OPENSTREAM OPENIPSTREAM)
|
||
(FONTCREATE \CREATEINTERPRESSFONT)
|
||
(FONTSAVAILABLE \SEARCHINTERPRESSFONTS))
|
||
1
|
||
|
||
(OPENSTREAMFN FILE OPTIONS) [Image Stream Method]
|
||
1
|
||
|
||
FILE is the file name as it was passed to OPENIMAGESTREAM, and OPTIONS is the OPTIONS property list passed to OPENIMAGESTREAM. The result must be a stream of the appropriate image type.
|
||
1
|
||
|
||
(FONTCREATEFN FAMILY SIZE FACE ROTATION DEVICE) [Image Stream Method]
|
||
1
|
||
|
||
FAMILY is the family name for the font, e.g., MODERN. SIZE is the body size of the font, in printer's points. FACE is a three-element list describing the weight, slope, and expansion of the face desired, e.g., (MEDIUM ITALIC EXPANDED). ROTATION is how much the font is to be rotated from the normal orientation, in minutes of arc. For example, to print a landscape page, fonts have the rotation 5400 (90 degrees). The function's result must be a FONTDESCRIPTOR with the fields filled in appropriately.
|
||
1
|
||
|
||
(FONTSAVAILABLEFN FAMILY SIZE FACE ROTATION DEVICE) [Image Stream Method]
|
||
1
|
||
|
||
This function returns a list of all fonts agreeing with the FAMILY, SIZE, FACE, and ROTATION arguments; any of them may be wild-carded (i.e., equal to *, which means any value is acceptable). Each element of the list should be a quintuple of the form (FAMILY SIZE FACE ROTATION DEVICE).
|
||
Where the function looks is an implementation decision: the FONTSAVAILABLEFN for the display device looks at DISPLAYFONTDIRECTORIES, the Interpress code looks on INTERPRESSFONTDIRECTORIES, and implementors of new devices should feel free to introduce new search path variables.
|
||
1
|
||
|
||
As indicated above, image streams use a field that no other stream uses: IMAGEOPS. IMAGEOPS is an instance of the IMAGEOPS data type and contains a vector of the stream's graphical methods. The methods contained in the IMAGEOPS object can make arbitrary use of the stream's IMAGEDATA field, which is provided for their use, and may contain any data needed.
|
||
The IMAGEOPS data type has the following fields:
|
||
IMAGETYPE [IMAGEOPS Field]
|
||
1
|
||
|
||
Value is the name of an image type. Monochrome display streams have an IMAGETYPE of DISPLAY; color display streams are identified as (COLOR DISPLAY). The IMAGETYPE field is informational and can be set to anything you choose.
|
||
1
|
||
|
||
IMFONTCREATE [IMAGEOPS Field]
|
||
1
|
||
|
||
Value is the device name to pass to FONTCREATE when fonts are created for the stream.
|
||
1
|
||
|
||
The remaining fields are all image stream methods, whose value should be a device-dependent function that implements the generic operation. Most methods are called by a similarly-named function, e.g. the function DRAWLINE calls the IMDRAWLINE method. All coordinates that refer to points in a display device's space are measured in the device's units. (The IMSCALE method provides access to a device's scale.) For arguments that have defaults (such as the BRUSH argument of DRAWCURVE), the default is substituted for the NIL argument before it is passed to the image stream method. Therefore, image stream methods do not have to handle defaults.
|
||
(IMCLOSEFN STREAM) [Image Stream Method]
|
||
1
|
||
|
||
Called before a stream is closed with CLOSEF. This method should flush buffers, write header or trailer information, etc.
|
||
1
|
||
|
||
(IMDRAWLINE STREAM X1 Y1 X2 Y2 WIDTH OPERATION COLOR DASHING) [Image Stream Method]
|
||
1
|
||
|
||
Draws a line of width WIDTH from (X1, Y1) to (X2, Y2). See DRAWLINE, ("DRAWLINE" . Function).
|
||
1
|
||
|
||
(IMDRAWCURVE STREAM KNOTS CLOSED BRUSH DASHING) [Image Stream Method]
|
||
1
|
||
|
||
Draws a curve through KNOTS. See DRAWCURVE, ("DRAWCURVE" . Function).
|
||
1
|
||
|
||
(IMDRAWCIRCLE STREAM CENTERX CENTERY RADIUS BRUSH DASHING) [Image Stream Method]
|
||
1
|
||
|
||
Draws a circle of radius RADIUS around (CENTERX, CENTERY). See DRAWCIRCLE, ("DRAWCIRCLE" . Function).
|
||
1
|
||
|
||
(IMDRAWELLIPSE STREAM CENTERX CENTERY SEMIMINORRADIUS SEMIMAJORRADIUS ORIENTATION BRUSH DASHING) [Image Stream Method]
|
||
1
|
||
|
||
Draws an ellipse around (CENTERX, CENTERY). See DRAWELLIPSE, ("DRAWELLIPSE" . Function).
|
||
1
|
||
|
||
(IMFILLPOLYGON STREAM POINTS TEXTURE) [Image Stream Method]
|
||
1
|
||
|
||
Fills in the polygon outlined by POINTS on the image stream STREAM, using the texture TEXTURE. See FILLPOLYGON, ("FILLPOLYGON" . Function).
|
||
1
|
||
|
||
(IMFILLCIRCLE STREAM CENTERX CENTERY RADIUS TEXTURE) [Image Stream Method]
|
||
1
|
||
|
||
Draws a circle filled with texture TEXTURE around (CENTERX, CENTERY). See FILLCIRCLE, ("FILLCIRCLE" . Function).
|
||
1
|
||
|
||
(IMBLTSHADE TEXTURE STREAM DESTINATIONLEFT DESTINATIONBOTTOM WIDTH HEIGHT OPERATION CLIPPINGREGION) [Image Stream Method]
|
||
1
|
||
|
||
The texture-source case of BITBLT (("BITBLT" . Function)). DESTINATIONLEFT, DESTINATIONBOTTOM, WIDTH, HEIGHT, and CLIPPINGREGION are measured in STREAM's units. This method is invoked by the functions BITBLT and BLTSHADE (("BLTSHADE" . Function)).
|
||
1
|
||
|
||
(IMBITBLT SOURCEBITMAP SOERCELEFT SOURCEBOTTOM STREAM DESTINATIONLEFT DESTINATIONBOTTOM WIDTH HEIGHT SOURCETYPE OPERATION TEXTURE CLIPPINGREGION CLIPPEDSOURCELEFT CLIPPEDSOURCEBOTTOM SCALE) [Image Stream Method]
|
||
1
|
||
|
||
Contains the bit-map-source cases of BITBLT (("BITBLT" . Function)). SOURCELEFT, SOURCEBOTTOM, CLIPPEDSOURCELEFT, CLIPPEDSOURCEBOTTOM, WIDTH, and HEIGHT are measured in pixels; DESTINATIONLEFT, DESTINATIONBOTTOM, and CLIPPINGREGION are in the units of the destination stream.
|
||
1
|
||
|
||
(IMSCALEDBITBLT SOURCEBITMAP SOURCELEFT SOURCEBOTTOM STREAM DESTINATIONLEFT DESTINATIONBOTTOM WIDTH HEIGHT SOURCETYPE OPERATION TEXTURE CLIPPINGREGION CLIPPEDSOURCELEFT CLIPPEDSOURCEBOTTOM SCALE) [Image Stream Method]
|
||
1
|
||
|
||
A scaled version of IMBITBLT. Each pixel in SOURCEBITMAP is replicated SCALE times in the X and Y directions; currently, SCALE must be an integer.
|
||
1
|
||
|
||
(IMMOVETO STREAM X Y) [Image Stream Method]
|
||
1
|
||
|
||
Moves to (X,Y). This method is invoked by the function MOVETO (("MOVETO" . Function)). If IMMOVETO is not supplied, a default method composed of calls to the IMXPOSITION and IMYPOSITION methods is used.
|
||
1
|
||
|
||
(IMSTRINGWIDTH STREAM STR RDTBL) [Image Stream Method]
|
||
1
|
||
|
||
Returns the width of string STR in STREAM's units, using STREAM's current font. This is envoked when STRINGWIDTH (("STRINGWIDTH" . Function)) is passed a stream as its FONT argument. If IMSTRINGWIDTH is not supplied, it defaults to calling STRINGWIDTH on the default font of STREAM.
|
||
1
|
||
|
||
(IMCHARWIDTH STREAM CHARCODE) [Image Stream Method]
|
||
1
|
||
|
||
Returns the width of character CHARCODE in STREAM's units, using STREAM's current font. This is invoked when CHARWIDTH (("CHARWIDTH" . Function)) is passed a stream as its FONT argument. If IMCHARWIDTH is not supplied, it defaults to calling CHARWIDTH on the default font of STREAM.
|
||
1
|
||
|
||
(IMCHARWIDTHY STREAM CHARCODE) [Image Stream Method]
|
||
1
|
||
|
||
Returns the Y componant of the width of character CHARCODE in STREAM's units, using STREAM's current font. This is envoked when CHARWIDTHY (("CHARWIDTHY" . Function)) is passed a stream as its FONT argument. If IMCHARWIDTHY is not supplied, it defaults to calling CHARWIDTHY on the default font of STREAM.
|
||
1
|
||
|
||
(IMBITMAPSIZE STREAM BITMAP DIMENSION) [Image Stream Method]
|
||
1
|
||
|
||
Returns the size that BITMAP will be when BITBLTed to STREAM, in STREAM's units. DIMENSION can be one of WIDTH, HEIGHT, or NIL, in which case the dotted pair (WIDTH . HEIGHT) will be returned.
|
||
This is envoked by BITMAPIMAGESIZE (("BITMAPIMAGESIZE" . Function)). If IMBITMAPSIZE is not supplied, it defaults to a method that multiplies the bitmap height and width by the scale of STREAM.
|
||
1
|
||
|
||
(IMNEWPAGE STREAM) [Image Stream Method]
|
||
1
|
||
|
||
Causes a new page to be started. The X position is set to the left margin, and the Y position is set to the top margin plus the linefeed. If not supplied, defaults to (\OUTCHAR STREAM (CHARCODE ^L)). Envoked by DSPNEWPAGE (("DSPNEWPAGE" . Function)).
|
||
1
|
||
|
||
(IMTERPRI STREAM) [Image Stream Method]
|
||
1
|
||
|
||
Causes a new line to be started. The X position is set to the left margin, and the Y position is set to the current Y position plus the linefeed. If not supplied, defaults to (\OUTCHAR STREAM (CHARCODE EOL)). Envoked by TERPRI (("TERPRI" . Function)).
|
||
1
|
||
|
||
(IMRESET STREAM) [Image Stream Method]
|
||
1
|
||
|
||
Resets the X and Y position of STREAM. The X coordinate is set to its left margin; the Y coordinate is set to the top of the clipping region minus the font ascent. Envoked by DSPRESET, ("DSPRESET" . Function).
|
||
1
|
||
|
||
The following methods all have corresponding DSPxx functions (e.g., IMYPOSITION corresponds to DSPYPOSITION) that invoke them. They also have the property of returning their previous value; when called with NIL they return the old value without changing it.
|
||
(IMCLIPPINGREGION STREAM REGION) [Image Stream Method]
|
||
1
|
||
|
||
Sets a new clipping region on STREAM.
|
||
1
|
||
|
||
(IMXPOSITION STREAM XPOSITION) [Image Stream Method]
|
||
1
|
||
|
||
Sets the X-position on STREAM.
|
||
1
|
||
|
||
(IMYPOSITION STREAM YPOSITION) [Image Stream Method]
|
||
1
|
||
|
||
Sets a new Y-position on STREAM.
|
||
1
|
||
|
||
(IMFONT STREAM FONT) [Image Stream Method]
|
||
1
|
||
|
||
Sets STREAM's font to be FONT.
|
||
1
|
||
|
||
(IMLEFTMARGIN STREAM LEFTMARGIN) [Image Stream Method]
|
||
1
|
||
|
||
Sets STREAM's left margin to be LEFTMARGIN. The left margin is defined as the X-position set after the new line.
|
||
1
|
||
|
||
(IMRIGHTMARGIN STREAM RIGHTMARGIN) [Image Stream Method]
|
||
1
|
||
|
||
Sets STREAM's right margin to be RIGHTMARGIN. The right margin is defined as the maximum X-position at which characters are printed; printing beyond it causes a new line.
|
||
1
|
||
|
||
(IMTOPMARGIN STREAM YPOSITION) [Image Stream Method]
|
||
1
|
||
|
||
Sets STREAM's top margin (the Y-position of the tops of characters that is set after a new page) to be YPOSITION.
|
||
1
|
||
|
||
(IMBOTTOMMARGIN STREAM YPOSITION) [Image Stream Method]
|
||
1
|
||
|
||
Sets STREAM's bottom margin (the Y-position beyond which any printing causes a new page) to be YPOSITION.
|
||
1
|
||
|
||
(IMLINEFEED STREAM DELTA) [Image Stream Method]
|
||
1
|
||
|
||
Sets STREAM's line feed distance (distance to move vertically after a new line) to be DELTA.
|
||
1
|
||
|
||
(IMSCALE STREAM SCALE) [Image Stream Method]
|
||
1
|
||
|
||
Returns the number of device points per screen point (a screen point being ~1/72 inch). SCALE is ignored.
|
||
1
|
||
|
||
(IMSPACEFACTOR STREAM FACTOR) [Image Stream Method]
|
||
1
|
||
|
||
Sets the amount by which to multiply the natural width of all following space characters on STREAM; this can be used for the justification of text. The default value is 1. For example, if the natural width of a space in STREAM's current font is 12 units, and the space factor is set to two, spaces appear 24 units wide. The values returned by STRINGWIDTH and CHARWIDTH are also affected.
|
||
1
|
||
|
||
(IMOPERATION STREAM OPERATION) [Image Stream Method]
|
||
1
|
||
|
||
Sets the default BITBLT OPERATION argument (see ("OPERATION" . BITBLTargument)).
|
||
1
|
||
|
||
(IMBACKCOLOR STREAM COLOR) [Image Stream Method]
|
||
1
|
||
|
||
Sets the background color of STREAM.
|
||
1
|
||
|
||
(IMCOLOR STREAM COLOR) [Image Stream Method]
|
||
1
|
||
|
||
Sets the default color of STREAM.
|
||
1
|
||
|
||
In addition to the IMAGEOPS methods described above, there are two other important methods, which are contained in the stream itself. These fields can be installed using a form like (replace (STREAM OUTCHARFN) of STREAM with (FUNCTION MYOUTCHARFN)). Note: You need to have loaded the Interlisp-D system declarations to manipulate the fields of STREAMs. The declarations can be loaded by loading the Lisp Library package SYSEDIT.
|
||
(STRMBOUTFN STREAM CHARCODE) [Stream Method]
|
||
1
|
||
|
||
The function called by BOUT.
|
||
1
|
||
|
||
(OUTCHARFN STREAM CHARCODE) [Stream Method]
|
||
1
|
||
|
||
The function that is called to output a single byte. This is like STRMBOUTFN, except for being one level higher: it is intended for text output. Hence, this function should convert (CHARCODE EOL) into the stream's actual end-of-line sequence and should adjust the stream's CHARPOSITION appropriately before invoking the stream's STRMBOUTFN (by calling BOUT) to actually put the character. Defaults to \FILEOUTCHARFN, which is probably incorrect for an image stream.
|
||
1
|
||
|
||
|