[Indigo]<Imager>System>Imager.mesa!47

Imager.mesa

This interface is the public expression of the client view of the procedures, structures, etc.
for making images on all devices. At this level (client), only operations which affect only the client world are allowed. Therefore, updates to the viewers or device parameters go through lower level interfaces. There are two "tracks" for many operations: a "Fast Track" for efficient operations, using integers, and a "General Track" for more general operations, using floating point.

Last Edited by:

Crow, June 17, 1983 6:50 pm

Wyatt, February 23, 1983 12:09 pm

Plass, March 14, 1983 2:13 pm

DIRECTORY

ImagerBasic USING [Vec, IntVec, Rectangle, IntRectangle, Context, ImagingDevice,

InteractiveImagingDevice, Procs, DeviceProcs, Path, SampledSource,

SourceRecord, StrokeEnds, PixelArray, RGBValue, AISFile, Visibility];

Imager: CEDAR DEFINITIONS

= BEGIN

Basic Numbers and Shapes

Rectangle: TYPE = ImagerBasic.Rectangle; -- RECORD [x, y, w, h: REAL]

IntRectangle: TYPE = ImagerBasic.IntRectangle; -- RECORD [x, y, w, h: INTEGER]

Vec: TYPE = ImagerBasic.Vec; -- RECORD [x, y: REAL]

IntVec: TYPE = ImagerBasic.IntVec; -- RECORD [x, y: INTEGER]

Context (interface designed - fcc)

Context: TYPE = REF ContextRep; -- Holds the imager state

ContextRep: TYPE = RECORD [

procs: ImagerInternalDefs.Procs,

data: REF ANY

];

Making a new context, clients would not generally use these procedures directly

CreateContext: PROC [device: ImagingDevice] RETURNS [Context];

Called by the viewers package, or other utilities, to set up a context. Returns NIL if unable to create the context.

DestroyContext: PROC [context: Context];

Remove all traces of the given context, clean up VM.

Save/Restore

Inclusions: TYPE = { all, allButCP, clientOnly, viewerOnly };

Should be set representing all possible entries in context record

Mark: TYPE[1];

nullMark: Mark ← NULL; -- default mark indicating "use most recent save"

Save: PROC [context: Context, what: Inclusions] RETURNS [Mark];

Note the current state of the display context, and return a mark value which can later be passed to Restore.

Restore: PROC [context: Context, mark: Mark ← nullMark];

Restore the state of the display context to its condition prior to the call on Save that returned the given mark. Defaulting the mark means restore to the most recent Save.

Clear, Next Page, etc.

NewFrame: PROC [context: Context]; -- who keeps the background color??

If printer or InterPress, start new page; if double-buffering, display newly completed image; otherwise clear inside context.

Transformations (implemented - fcc)

These calls, for clients, automatically concatenate to the current client transform.

General Track

Translate: PROC [context: Context, dx, dy: REAL];

Rotate: PROC [context: Context, degrees: REAL];

Scale: PROC [context: Context, sx, sy: REAL];

Fast Track

IntTranslate: PROC [context: Context, dx, dy: INTEGER];

IntRotate: PROC [context: Context, degrees: INTEGER]; -- Fast if a multiple of 90

IntScale: PROC [context: Context, sx, sy: INTEGER]; -- Fast for mirror transforms

ResetTransform: PROC [context: Context]; -- reset to identity

Clipping (fast track implemented - fcc)

These routines allow the definition and testing of client clipping paths. Clipping paths are assumed to be glued to the viewer once defined. Subsequent changes in the client transform do not effect previously defined clipping paths. Testing and clipping operations are always done in device coordinates. Therefore items to be clipped must first be transformed.

Visibility: TYPE = ImagerBasic.Visibility; -- {visible, partlyVisible, invisible}

General Track

SetClipArea: PROC [context: Context, area: Path];

Establishes clipped area

ConcatArea: PROC [context: Context, area: Path, exclude: BOOLEAN ← FALSE];

Modifies old clipping region by supplied area. Exclude sets clipping outside path rather than inside.

TestArea: PROC [context: Context, area: Path] RETURNS [Visibility];

Enables use of "DoWithoutClipping" if returns visible

TestPoint: PROC [context: Context, point: Vec] RETURNS [BOOLEAN]; -- true if visible

ClipArea: PROC [context: Context, area: Path] RETURNS [Path];

Returns subarea which lies entirely inside clipping area

Fast Track

SetClipIntRectangle: PROC [context: Context, area: IntRectangle];

ConcatIntRectangle: PROC [context: Context, area: IntRectangle];

TestIntRectangle: PROC [context: Context, area: IntRectangle] RETURNS [Visibility];

Enables use of "DoWithoutClipping" if returns visible

TestIntPoint: PROC [context: Context, point: IntVec] RETURNS [BOOLEAN];

ClipIntRectangle: PROC [context: Context, area: IntRectangle] RETURNS [IntRectangle];

Returns a subrectangle which lies entirely inside clipping area. Not recommended for use with nonconvex clipping paths.

DoWithoutClipping: PROC [context: Context, callBack: PROC[Context]];

For clients who are able to use the tests above to verify that no clipping is needed. Each call must be preceded by a successful call to TestArea or TestIntRectangle. The client assumes liability for garbaged displays.

Devices (interface under construction - fcc)

ImagingDevice: TYPE = ImagerBasic.ImagingDevice;

ATOM; -- eg. $LF, $CRT8, $CRT24, $PD, $IP, etc.

InteractiveImagingDevice: TYPE = ImagerBasic.InteractiveImagingDevice;

RegisterDevice: PROC [name: ImagingDevice, procs: ImagerBasic.DeviceProcs];

EnumerateRegisteredDevices: PROC [] RETURNS [LIST OF ImagingDevice];

SetDevice: PROC [context: Context, device: ImagingDevice];

This affects only the device transforms, clipping, etc.

GetDevice: PROC [context: Context] RETURNS [ImagingDevice];

Fonts (awaiting M. Plass' attentions)

Font: TYPE = REF; -- Will be more concrete when the new font interface is done.

Affects current font, stroke width, strokends

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

GetFont: PROC [context: Context] RETURNS [font: Font];

Sources (interface designed - fcc)

A Source is a specification for coloring the Euclidean plane. There are three levels of complexity: (1) a constant color, (2) color from an array of samples (which can be used to tile the plane), and (3) color described by a procedure with arguments x and y. A "Color" can be (1) an uninterpreted value (the interpretation is device-dependent, or deferred), or (2) a tristimulus value (RGB). Various procedures provide transformations from common color spaces to RGB. Each device provides a transformation from RGB to a device-dependent representation. Thus there could be a standard 8-bit device with a standard color map for interpreting RGB (perhaps with dithering) and then an uninterpreted 8-bit device with a (possibly dynamic) color map.

SourceRecord: TYPE = ImagerBasic.SourceRecord;

RGBValue: TYPE = ImagerBasic.RGBValue;

AISFile: TYPE = ImagerBasic.AISFile;

PixelArray: TYPE = ImagerBasic.PixelArray;

SampledSource: TYPE = ImagerBasic.SampledSource;

Affects current color, source of sampled imagery

SetSource: PROC [context: Context, source: SourceRecord];

GetSource: PROC [context: Context] RETURNS [SourceRecord];

SourceFromColor: PROC [context: Context, color: RGBValue] RETURNS [SourceRecord];

SourceFromImage: PROC [context: Context] RETURNS [SourceRecord];

SourceFromAIS: PROC [file: AISFile] RETURNS [SourceRecord];

Paths (Skeleton made - fcc)

Path: TYPE = ImagerBasic.Path;

PathFromIntRectangle: PROC [area: IntRectangle] RETURNS [Path];

Masks (fast track partially implemented - fcc)

These procedures take the current source and apply it to those pixels which lie inside an area defined by the mask parameter (stroke, area, or pixelmask). The defined area is treated as a stencil which is conceptually superposed over the page while the color or image is applied.

StrokeEnds: TYPE = ImagerBasic.StrokeEnds; -- {butt, square, round}

(1) "Butt" ends are squared off at the endpoint coordinate.

(2) "Square" ends are extended by half the stroke width before squaring.

(3) "Round" ends have semicircular caps at the ends.

MaskStroke: PROC [context: Context, path: Path];

Form a stencil of "width" thickness around a spine defined by "path".

Connected path segments will be mitered together. The client's path expansion scheme determines whether the path is open or closed.

MaskFill: PROC [context: Context, path: Path];

Use the path to outline an area to be filled with the source

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

Use the supplied pixel array as the stencil. The origin of the pixel array will be placed at the origin of the client space. The samples will be assumed to be placed at one unit intervals in the client space.

Fast Track. The width of lines, etc. is device dependent, approximately .1% page height.

Sets current position

MoveTo: PROC [context: Context, p: IntVec] = INLINE { Imager.SetIntCP[context, p] };

DrawTo: PROC [context: Context, p: IntVec];

Draw line using source for color

DrawPath: PROC [context: Context, path: Path];

Draw whole path using source for color

FillRectangle: PROC [context: Context, area: IntRectangle];

Fill rectangular area with source

Characters (awaiting M. Plass' attentions)

Use the font interface to obtain FONTs and their metrics.

Affects current position.

SetCP: PROC [context: Context, cp: Vec];

GetCP: PROC [context: Context, cp: Vec];

SetIntCP: PROC [context: Context, cp: IntVec];

GetIntCP: PROC [context: Context, cp: IntVec];

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

MaskCharacters: PROC [

context: Context,

characters: REF, -- may be a Rope.ROPE or a REF TEXT, for non-cedar probably a LONG STRING

start: INT ← 0,

length: INT ← LAST[INT]

];

Uses the DeviceWidth of each character for positioning.

MaskCharSeq: PROC [

context: Context, length: NAT,

charPtr: LONG POINTER TO CHAR, charIncrement: NAT,

deltaXptr: LONG POINTER TO INTEGER, deltaXincrement: NAT,

deltaYptr: LONG POINTER TO INTEGER, deltaYincrement: NAT

];

Displays a batch of characters, with all positioning provided by the client. Use this where speed is important.

Interactive graphics (interface designed - fcc)

These operations may not work on all devices, will no-op on noninteractive devices.

Interactive: PROC [context: Context] RETURNS [BOOLEAN]

= INLINE {RETURN [context.interactive]};

If true, the interactive operations should work.

General Track

HiliteArea: PROC [context: Context, area: Path]; -- Invert on LF, device dependent

Fast Track

HiliteIntRectangle: PROC [context: Context, area: IntRectangle];

MoveIntRectangle: PROC [context: Context, source: IntRectangle, destination: IntVec];

Client's way to use BitBlt

GetPixelArray: PROC [context: Context, source: IntRectangle, image: PixelArray ← NIL] RETURNS [PixelArray];

PutPixelArray: PROC [context: Context, destination: IntRectangle, image: PixelArray];

These use uninterpreted Pixel Arrays, clip to rectangle. Handy for rubber-stamping, etc.)

StartDoubleBuffering: PROC [context: Context];

StopDoubleBuffering: PROC [context: Context];

Maintain shadow pixel array on the side for building images, use with "NewFrame".

Implementer private data

Procs: TYPE = ImagerBasic.Procs;

DefaultProcs: PROC RETURNS [Procs];

ProcsRec: PUBLIC TYPE = RECORD [

CreateContext: PROC [imagingDevice: ImagingDevice] RETURNS [Context],

DestroyContext: PROC [context: Context],

Save: PROC [context: Context, what: Inclusions] RETURNS [Mark],

Restore: PROC [context: Context, mark: Mark],

NewFrame: PROC [context: Context],

Translate: PROC [context: Context, dx, dy: REAL],

Rotate: PROC [context: Context, degrees: REAL],

Scale: PROC [context: Context, sx, sy: REAL],

IntTranslate: PROC [context: Context, dx, dy: INTEGER],

IntRotate: PROC [context: Context, degrees: INTEGER],

IntScale: PROC [context: Context, x, y: INTEGER],

ResetTransform: PROC [context: Context],

SetClipArea: PROC [context: Context, area: Path],

ConcatArea: PROC [context: Context, area: Path, exclude: BOOLEAN ← FALSE],

TestArea: PROC [context: Context, area: Path] RETURNS [Visibility],

TestPoint: PROC [context: Context, point: Vec] RETURNS [BOOLEAN],

ClipArea: PROC [context: Context, area: Path] RETURNS [Path],

SetClipRectangle: PROC [context: Context, area: IntRectangle],

ConcatRectangle: PROC [context: Context, area: IntRectangle],

TestRectangle: PROC [context: Context, area: IntRectangle] RETURNS [Visibility],

TestIntPoint: PROC [context: Context, point: IntVec] RETURNS [BOOLEAN],

ClipRectangle: PROC [context: Context, area: IntRectangle] RETURNS [IntRectangle],

DoWithoutClipping: PROC [context: Context, callBack: PROC[Context]],

RegisterDevice: PROC [name: ATOM, procs: ImagerBasic.DeviceProcs],

EnumerateRegisteredDevices: PROC [] RETURNS [LIST OF ATOM],

SetDevice: PROC [context: Context, device: ImagingDevice],

GetDevice: PROC [context: Context] RETURNS [ImagingDevice],

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

GetFont: PROC [context: Context] RETURNS [font: Font],

SetSource: PROC [context: Context, source: SourceRecord],

GetSource: PROC [context: Context] RETURNS [source: SourceRecord],

SourceFromColor: PROC [color: RGBValue] RETURNS [source: SourceRecord],

SourceFromImage: PROC [context: Context] RETURNS [source: SourceRecord],

SourceFromAIS: PROC [file: AISFile] RETURNS [source: SourceRecord],

PathFromIntRectangle: PROC [area: IntRectangle] RETURNS [Path],

MaskStroke: PROC [context: Context, path: Path],

MaskFill: PROC [context: Context, path: Path],

MaskPixel: PROC [context: Context, pixelArray: PixelArray],

MoveTo: PROC [context: Context, p: IntVec],

DrawTo: PROC [context: Context, p: IntVec],

DrawPath: PROC [context: Context, path: Path],

FillRectangle: PROC [context: Context, r: Rectangle],

SetCP: PROC [context: Context, cp: Vec],

GetCP: PROC [context: Context, cp: Vec],

SetIntCP: PROC [context: Context, cp: IntVec],

GetIntCP: PROC [context: Context, cp: IntVec],

MaskChar: PROC [context: Context, char: CHAR],

MaskCharacters: PROC [context: Context, characters: REF, start: INT ← 0, length: INT ← LAST[INT]],

MaskCharSeq: PROC [context: Context, length: NAT, charPtr: LONG POINTER TO CHAR, charIncrement: NAT, deltaXptr: LONG POINTER TO INTEGER, deltaXincrement: NAT, deltaYptr: LONG POINTER TO INTEGER, deltaYincrement: NAT],

Interactive: PROC [context: Context] RETURNS [BOOLEAN],

InvertArea: PROC [context: Context, area: Path],

InvertIntRectangle: PROC [context: Context, area: IntRectangle],

MoveIntRectangle: PROC [context: Context, source: IntRectangle, destination: IntVec],

GetPixelArray: PROC [context: Context, source: IntRectangle, image: PixelArray ← NIL] RETURNS [PixelArray],

PutPixelArray: PROC [context: Context, destination: IntRectangle, image: PixelArray],

StartDoubleBuffering: PROC [context: Context],

StopDoubleBuffering: PROC [context: Context]

];

END.