[_CDMiwok_01_]<bonsai2.0>cedar>release>Imager>Imager.mesa!1

Imager.mesa

Michael Plass, October 25, 1991 1:13 pm PDT

Doug Wyatt, January 19, 1987 5:55:40 pm PST

Imager is the standard Cedar interface for creating two-dimensional images; it allows images to be specified in a way that is independent of the imaging device. Imager operations can be directed to various displays and printers, or to an Interpress master.

DIRECTORY

ImagerBox USING [Box, Rectangle],

ImagerColor USING [Color, ColorOperator, ConstantColor, SampledColor, Structure, SpecialColor],

ImagerError USING [ErrorDesc],

ImagerFont USING [Font, XChar, XStringProc],

ImagerPath USING [Outline, PathProc, Trajectory],

ImagerPixel USING [PixelMap],

ImagerPixelArray USING [PixelArray],

ImagerSample USING [SampleMap],

ImagerTransformation USING [ScanMode, Transformation],

Prop USING [PropList],

Rope USING [ROPE, XROPE],

SF USING [Vec, zeroVec],

Vector2 USING [VEC];

Imager: CEDAR DEFINITIONS

~ BEGIN

VEC: TYPE ~ Vector2.VEC; -- RECORD [x, y: REAL]

zeroVEC: VEC ~ [0.0, 0.0];

Rectangle: TYPE ~ ImagerBox.Rectangle; -- RECORD [x, y, w, h: REAL]

Transformation: TYPE ~ ImagerTransformation.Transformation;

PathProc: TYPE ~ ImagerPath.PathProc;

Trajectory: TYPE ~ ImagerPath.Trajectory;

Outline: TYPE ~ ImagerPath.Outline;

PixelArray: TYPE ~ ImagerPixelArray.PixelArray;

SampleMap: TYPE ~ ImagerSample.SampleMap;

PixelMap: TYPE ~ ImagerPixel.PixelMap;

ScanMode: TYPE ~ ImagerTransformation.ScanMode;

defaultScanMode: ScanMode ~ [slow: down, fast: right];

Color: TYPE ~ ImagerColor.Color;

ConstantColor: TYPE ~ ImagerColor.ConstantColor;

SampledColor: TYPE ~ ImagerColor.SampledColor;

SpecialColor: TYPE ~ ImagerColor.SpecialColor;

Structure: TYPE ~ ImagerColor.Structure;

ColorOperator: TYPE ~ ImagerColor.ColorOperator;

Font: TYPE ~ ImagerFont.Font;

XChar: TYPE ~ ImagerFont.XChar;

XStringProc: TYPE ~ ImagerFont.XStringProc;

ROPE: TYPE ~ Rope.ROPE;

XROPE: TYPE ~ Rope.XROPE;

Contexts and Imager State

Context: TYPE ~ REF ContextRep;

ContextRep: TYPE ~ RECORD [

class: REF ClassRep, -- operations for the context class

state: REF StateRep, -- context state, if standard representation

data: REF, -- instance data (class-dependent type)

propList: Prop.PropList ¬ NIL -- instance property list

];

ClassRep: TYPE; -- ImagerPrivate.ClassRep

StateRep: TYPE; -- ImagerState.StateRep

Error: VAR ERROR [error: ImagerError.ErrorDesc];

Warning: VAR SIGNAL [error: ImagerError.ErrorDesc];

SetWarn: PROC [context: Context, warn: BOOL];

The Warning signal may always be resumed; clients may disable and enable the occurence of Warning signals by using SetWarn. The warn/no warn state is subject to DoSave, and warnings are initially disabled.

GetClass: PROC [context: Context] RETURNS [ATOM];

Returns an ATOM that identifies the context class.

PutProp: PROC [context: Context, key: REF, val: REF];

GetProp: PROC [context: Context, key: REF] RETURNS [val: REF];

Operations on context.propList; propList is saved and restored by DoSave and DoSaveAll.

DoSave: PROC [context: Context, action: PROC];

DoSaveAll: PROC [context: Context, action: PROC];

These save imager variables, call the action procedure, then restore imager variables.

DoSave restores all but the current position and correctMeasure.

DoSaveAll restores everything.

Transformations and Current Position

metersPerInch: REAL ~ 0.0254;

metersPerPoint: REAL ~ 0.0003514598;

metersPerMica: REAL ~ 0.00001;

pointsPerInch: REAL ~ 72.27;

pointsPerMica: REAL ~ 0.028452756;

micasPerInch: REAL ~ 2540.0;

micasPerPoint: REAL ~ 35.14598;

inchesPerPoint: REAL ~ 0.013837;

inchesPerMica: REAL ~ 0.00039370079;

Handy conversion factors.

ConcatT: PROC [context: Context, m: Transformation];

Premultiplies the current transformation by m.

ScaleT: PROC [context: Context, s: REAL];

Scales the current transformation by s.

Equivalent to ConcatT[context, ImagerTransformation.Scale[s]].

Scale2T: PROC [context: Context, s: VEC];

Equivalent to ConcatT[context, ImagerTransformation.Scale2[s]].

RotateT: PROC [context: Context, a: REAL];

Equivalent to ConcatT[context, ImagerTransformation.Rotate[a]].

Angle a is in degrees counterclockwise.

TranslateT: PROC [context: Context, t: VEC];

Equivalent to ConcatT[context, ImagerTransformation.Translate[t]].

Move: PROC [context: Context];

Translates the origin to the current position.

Trans: PROC [context: Context];

Translates the origin to the grid point nearest the current position.

SetXY: PROC [context: Context, p: VEC];

SetXYI: PROC [context: Context, x, y: INTEGER];

Sets the current position.

SetXYRel: PROC [context: Context, v: VEC];

SetXYRelI: PROC [context: Context, x, y: INTEGER];

Adds a relative displacement to the current position.

SetXRel: PROC [context: Context, x: REAL];

SetXRelI: PROC [context: Context, x: INTEGER];

Equivalent to SetXYRel[context, x, 0]

SetYRel: PROC [context: Context, y: REAL];

SetYRelI: PROC [context: Context, y: INTEGER];

Equivalent to SetXYRel[context, 0, y]

Text and Spacing Correction

FindFontScaled: PROC [name: ROPE, s: REAL] RETURNS [Font];

Equivalent to ImagerFont.FindScaled[name, s].

SetFont: PROC [context: Context, font: Font];

Sets the font for subsequent Show operations.

SetAmplifySpace: PROC [context: Context, amplifySpace: REAL];

Sets the scale factor for widths of `amplified' characters.

Show: PROC [context: Context, string: XStringProc, xrel: BOOL ¬ FALSE];

Shows a string of characters in the current font, starting at the current position.

If xrel~TRUE, every other char means SetXRel[context, char.code-128].

ShowAndFixedXRel: PROC [context: Context, string: XStringProc, x: REAL];

Does SetXRel[context, x] between characters.

ShowBackward: PROC [context: Context, string: XStringProc];

Shows the string, reversing the sense of the character escapements.

ShowChar: PROC [context: Context, char: CHAR];

Shows an 8-bit character (in Character Set 0).

ShowXChar: PROC [context: Context, char: XChar];

Shows a 16-bit Xerox Character Code.

ShowXRope: PROC [context: Context, rope: XROPE,
start: INT ¬ 0, len: INT ¬ INT.LAST, xrel: BOOL ¬ FALSE];

Shows extended characters from an XROPE; does not use Xerox String Encoding

ShowRope: PROC [context: Context, rope: ROPE,
start: INT ¬ 0, len: INT ¬ INT.LAST, xrel: BOOL ¬ FALSE];

Shows characters from a ROPE, using the Xerox String Encoding.

ShowText: PROC [context: Context, text: REF READONLY TEXT,
start: NAT ¬ 0, len: NAT ¬ NAT.LAST, xrel: BOOL ¬ FALSE];

Shows characters from a REF TEXT, using the Xerox String Encoding.

StartUnderline: PROC [context: Context];

Remembers the starting x position for an underline.

MaskUnderline: PROC [context: Context, dy, h: REAL];

MaskUnderlineI: PROC [context: Context, dy, h: INTEGER];

Draws an underline from the StartUnderline point to the current position.

The underline's top is dy below the current position; its height is h.

Example: StartUnderline[ctx]; ShowRope[ctx, "underlined"]; MaskUnderline[ctx, 3, 1];

CorrectMask: PROC [context: Context];

CorrectSpace: PROC [context: Context, v: VEC];

Note "correction space" opportunities for Correct; see Correct, below.

Usually, font characters call these implicitly within Show.

Space: PROC [context: Context, x: REAL];

SpaceI: PROC [context: Context, x: INTEGER];

Use Space rather than SetXRel to make correctable spaces inside Correct.

Equivalent to { SetXRel[ctx, x]; CorrectSpace[ctx, [x, 0]] }.

SetCorrectMeasure: PROC [context: Context, v: VEC];

Sets the expected line measure for subsequent Correct operations.

SetCorrectTolerance: PROC [context: Context, v: VEC];

Sets the line measure tolerance for subsequent Correct operations.

SetCorrectShrink: PROC [context: Context, correctShrink: REAL];

Sets the allowable fraction of space shrink for subsequent Correct operations.

Correct: PROC [context: Context, action: PROC];

Ensures reasonable spacing of text (or other masks) even if the imager approximates fonts.

Like DoSave[context, action], but adjusts "correction space" if necessary to ensure that the net change in current position is within correctTolerance of correctMeasure.

Note that Correct may (or may not) invoke action twice.

See the Interpress Standard, section 4.10, and the Introduction to Interpress, section 10.

DontCorrect: PROC [context: Context, action: PROC, saveCP: BOOL ¬ FALSE];

Disables correction, calls action, then restores correction state.

If saveCP~TRUE, also saves and restores current position.

For relevant examples, see the Introduction to Interpress, section 10.6.

Color and Pixel Arrays

SetColor: PROC [context: Context, color: Color];

Sets the current color.

MakeGray: PROC [f: REAL] RETURNS [ConstantColor];

Returns a constant gray; f is the fraction of absorptance, from 0 (white) to 1 (black).

black: READONLY ConstantColor; -- MakeGray[1]

white: READONLY ConstantColor; -- MakeGray[0]

SetGray: PROC [context: Context, f: REAL];

Equivalent to SetColor[context, MakeGray[f]]

SetSampledColor: PROC [context: Context, pa: PixelArray,
m: Transformation ¬ NIL, colorOperator: ColorOperator];

Equivalent to SetColor[context, MakeSampledColor[pa, Concat[m, T], colorOperator].

Better than direct use of MakeSampledColor, since you don't need to know T.

SetSampledBlack: PROC [context: Context, pa: PixelArray,
m: Transformation ¬ NIL, clear: BOOL ¬ FALSE];

Equivalent to SetColor[context, MakeSampledBlack[pa, Concat[m, T], clear].

Better than direct use of MakeSampledBlack, since you don't need to know T.

DrawSampledColor: PROC [context: Context, pa: PixelArray, colorOperator: ColorOperator,
m: Transformation ¬ NIL, position: VEC ¬ zeroVEC];

Convenience procedure to draw a sampled image from a PixelArray. The contents of the PixelArray are displayed through a rectangular mask.

m is normally a Scale for sizing the image, but may be more general.

position may be used to position the image in client coordinates.

DrawPixels: PROC [context: Context, pixelMap: PixelMap, colorOperator: ColorOperator, referencePoint: SF.Vec ¬ SF.zeroVec, scanMode: ScanMode ¬ defaultScanMode,
position: VEC ¬ zeroVEC];

Convenience procedure to draw a sampled image from a mutable buffer without first having to construct a PixelArray. The contents of the PixelMap are displayed with referencePoint in the PixelMap at the specified position in client coordinates, and the orientation in accordance with scanMode.

DrawBitmap: PROC [context: Context, bitmap: SampleMap,
referencePoint: SF.Vec ¬ SF.zeroVec, scanMode: ScanMode ¬ defaultScanMode,
position: VEC ¬ zeroVEC];

Convenience procedure to draw a bitmap from a mutable buffer without first having to construct a PixelArray. The contents of the bitmap are displayed with referencePoint in the bitmap at the specified position in client coordinates, and the orientation in accordance with scanMode. One bits produce black, zero bits produce white.

Masks and Clipping

MaskFill: PROC [context: Context, path: PathProc, oddWrap: BOOL ¬ FALSE];

Fills with the current color the interior of the region outlined by the specified path.

Closes each trajectory in the path with a straight line, if necessary.

If oddWrap~FALSE, the mask includes all points with nonzero winding number.

If oddWrap~TRUE, the mask includes all points with odd winding number.

MaskFillTrajectory: PROC [context: Context, trajectory: Trajectory, oddWrap: BOOL ¬ FALSE];

Fills the region described by a Trajectory.

MaskFillOutline: PROC [context: Context, outline: Outline];

Fills the region described by an Outline.

MaskRectangle: PROC [context: Context, r: Rectangle];

MaskRectangleI: PROC [context: Context, x, y, w, h: INTEGER];

Fills the rectangle [x, y], [x+w, y], [x+w, y+h], [x, y+h].

Box: TYPE ~ ImagerBox.Box; -- RECORD [xmin, ymin, xmax, ymax: REAL]

MaskBox: PROC [context: Context, box: Box];

Fills the rectangle [xmin, ymin], [xmax, ymin], [xmax, ymax], [xmin, ymax].

A convenience for former users of Graphics.DrawBox.

SetStrokeWidth: PROC [context: Context, strokeWidth: REAL];

Establishes the width for subsequent strokes.

StrokeEnd: TYPE ~ MACHINE DEPENDENT { square, butt, round, (15) };

square: square off each end after extending the stroke by half strokeWidth

butt: square off each end flush with the endpoint

round: round each end with a semicircular cap of strokeWidth diameter

SetStrokeEnd: PROC [context: Context, strokeEnd: StrokeEnd];

Establishes the endpoint style for subsequent strokes.

StrokeJoint: TYPE ~ MACHINE DEPENDENT { miter, bevel, round, (15) };

miter: extend segment sides until they meet (acute angles make long, sharp corners)

bevel: cut corner with a line segment

round: join segments in a circle of strokeWidth diameter

SetStrokeJoint: PROC [context: Context, strokeJoint: StrokeJoint];

Establishes the joint style for subsequent strokes.

MaskStroke: PROC [context: Context, path: PathProc, closed: BOOL ¬ FALSE];

Fills with the current color a stroke whose centerline is the specified path.

The current strokeWidth and strokeJoint determine the stroke's width and joint style.

If closed~FALSE, the current strokeEnd determines the stroke's endpoint style.

If closed~TRUE, each trajectory is closed, if necessary, with a straight line.

MaskStrokeTrajectory: PROC [context: Context, trajectory: Trajectory, closed: BOOL ¬ FALSE];

Fills a stroke along a trajectory.

MaskVector: PROC [context: Context, p1, p2: VEC];

MaskVectorI: PROC [context: Context, x1, y1, x2, y2: INTEGER];

Fills a stroke along the line joining p1 and p2.

MaskDashedStroke: PROC [context: Context, path: PathProc,
patternLen: NAT, pattern: PROC [NAT] RETURNS [REAL], offset, length: REAL];

MaskDashedStrokeTrajectory: PROC [context: Context, trajectory: Trajectory,
patternLen: NAT, pattern: PROC [NAT] RETURNS [REAL], offset, length: REAL];

MaskPixel: PROC [context: Context, pa: PixelArray];

Uses a pixel array as a mask; pa must have one bit per pixel.

MaskBitmap: PROC [context: Context, bitmap: SampleMap, referencePoint: SF.Vec ¬ SF.zeroVec,
scanMode: ScanMode ¬ defaultScanMode, position: VEC ¬ zeroVEC];

The referencePoint of the SampleMap (which must have one bit per sample) is placed at the specified position in client coordinates. The ScanMode controls the orientation of the bitmap with respect to the client coordinate system.

SetPriorityImportant: PROC [context: Context, priorityImportant: BOOL];

If priorityImportant~TRUE, subsequent Mask operations will retain correct priority order.

SetNoImage: PROC [context: Context, noImage: BOOL];

If noImage~TRUE, subsequent Mask operations will not change the output.

Clip: PROC [context: Context, path: PathProc, oddWrap, exclude: BOOL ¬ FALSE];

Clips subsequent masks to the interior of a region described (as for MaskFill) by a path.

If exclude~TRUE, clips to the exterior of the region instead of the interior.

This region is itself clipped by any clipping region previously in force.

ClipOutline: PROC [context: Context, outline: Outline, exclude: BOOL ¬ FALSE];

Clips to an outline.

ClipRectangle: PROC [context: Context, r: Rectangle, exclude: BOOL ¬ FALSE];

ClipRectangleI: PROC [context: Context, x, y, w, h: INTEGER, exclude: BOOL ¬ FALSE];

Clips to the rectangle [x, y], [x+w, y], [x+w, y+h], [x, y+h].

Other Utilities

DoIfVisible: PROC [context: Context, r: Rectangle, action: PROC];

Calls action if the rectangle specified by r might be visible.

DoWithBuffer: PROC [context: Context, action: PROC, x, y, w, h: INTEGER, backgroundColor: Color ¬ NIL];

Equivalent to clipping to the given rectangle [x, y, w, h] and then calling action, all under a DoSaveAll. Will buffer the output where possible. If backgroundColor#NIL, the rectangle will be filled with the color before action is called.

Image Objects

Object: TYPE ~ REF ObjectRep;

ObjectRep: TYPE ~ RECORD [draw: PROC [self: Object, context: Context], clip: Rectangle, data: REF];

An object represents a picture that is expected to be drawn repeatedly. The draw proc should execute precisely the same sequence of Imager calls every time it is called. The rendering of the object is clipped to the given rectangle.

DrawObject: PROC [context: Context, object: Object, position: VEC ¬ zeroVEC, interactive: BOOL ¬ FALSE];

The semantics are to execute TranslateT[context, position]; object.draw[object, context] under a DoSaveAll, i.e., the object is drawn with its origin at the specified position.

If interactive, certain implementations may cache partial results to speed subsequent renderings, and may make some approximations to the image to make this more feasible (such as moving the origin to the nearest grid point and altering the phase of dither patterns). Use this when the object is expected to be drawn many times with only the translation being different.

END.