CtBasic.mesa
Copyright Ó 1985, 1992 by Xerox Corporation. All rights reserved.
Bloomenthal, July 3, 1992 1:23 pm PDT
Andrew Glassner November 14, 1990 3:14 pm PST
DIRECTORY G2dBasic, Imager, ImagerPixel, ImagerSample, SF;
CtBasic: CEDAR DEFINITIONS
IMPORTS
~ BEGIN
Types
IntegerPair:  TYPE ~ G2dBasic.IntegerPair;  -- RECORD [x, y: INTEGER ¬ 0]
RealPair:   TYPE ~ G2dBasic.Pair;    -- RECORD [x, y: REAL ¬ 0.0]
Context:   TYPE ~ Imager.Context;
Rectangle:  TYPE ~ Imager.Rectangle;   -- RECORD [x, y, w, h: REAL]
PixelMap:   TYPE ~ ImagerPixel.PixelMap;
SampleBuffer: TYPE ~ ImagerSample.SampleBuffer;
SampleMap:  TYPE ~ ImagerSample.SampleMap;
Box:    TYPE ~ SF.Box;      -- RECORD [min, max: Vec ¬ [0, 0]]
Vec:    TYPE ~ SF.Vec;      -- RECORD [s, f: INTEGER]
RGB:    TYPE ~ RECORD [r, g, b: BYTE ¬ 0];
Channel:   TYPE ~ RECORD [
type:      ATOM ¬ NIL,   -- use of channel
map:      SampleMap ¬ NIL-- channel image
];
SampleMaps:  TYPE ~ REF SampleMapsRep;
SampleMapsRep: TYPE ~ RECORD [
x, y, w, h:    NAT ¬ 0,    -- the box, derived from the sample maps
box:      Box ¬ [[0,0], [0,0]], -- read only: dimensions of maps
size:      Vec ¬ [0, 0],   -- read only: size of maps
bpp:      NAT ¬ 8,    -- bits per pixel: 8, 24 or other
nChannels:    NAT ¬ 0,    -- number of sample maps
element:     SEQUENCE maxLength: NAT OF Channel
];
Similar to ImagerPixel.PixelMap, but more descriptive.
The client may set element.type (see Create[] or SampleMapsfromPixelMap[] for defaults).
PixelArray:  TYPE ~ REF PixelArrayRep;
PixelArrayRep: TYPE ~ RECORD [
bpp:      NAT ¬ 8,    -- bits per pixel
x, y, w, h:    NAT ¬ 0,    -- dimensions of array
box:      Box ¬ [[0,0], [0,0]], -- read only: dimensions of maps
size:      Vec ¬ [0, 0],   -- read only: size of maps
element:     SEQUENCE maxLength: NAT OF SampleBuffer
];
An array of pixels, each accessed more quickly than via a SampleMap.
Elements are stored by row, then column; that is, pixelArray[y][x].
Miscellany
GetBpp: PROC RETURNS [NAT];
Return the bits per pixel for the current hardware device.
Sample Maps Operations
SampleMapsFromPixelMap: PROC [pixelMap: PixelMap] RETURNS [SampleMaps];
Convert pixelMap to SampleMaps with nchannels = samplesPerPixel.
for nChannels = 1, the type of the single map is $BW.
for nChannels = 3, the types of the three maps are $Red, $Green, $Blue.
for other nChannels, the types are $Unknown.
SampleMapsFromMaps: PROC [map1, map2, map3: SampleMap] RETURNS [SampleMaps];
Create SampleMaps from the three maps.
CreateMaps: PROC [bpp: NAT, x, y, w, h: NAT, allocateMaps: BOOL ¬ TRUE]
RETURNS [SampleMaps];
Create the appropriate sample maps of the given size.
CopyOfMaps: PROC [maps: SampleMaps, x, y, w, h: NAT] RETURNS [SampleMaps];
Create the a new SampleMaps of the given size; nChannels, maps, bpp are same as input.
ClipMaps: PROC [maps: SampleMaps, x, y, w, h: NAT];
Equivalent to ReIndexMaps[maps, [0, 0], BoxFromXYWH[x, y, w, h]].
MoveMaps: PROC [maps: SampleMaps, srcMin, dstMin, size: Vec];
Move samples in maps; from srcMin to dstMin, for a size of size.
ShiftMaps: PROC [maps: SampleMaps, delta: Vec] RETURNS [SampleMaps];
Shift the maps by delta.
FillMaps: PROC [maps: SampleMaps, bw, r, g, b: CARDINAL ¬ 0];
Fill the appropriate pixel maps (if 8 bpp, fill with bw, else with r, g, b).
CopyMaps: PROC [src, dst: SampleMaps];
Copy src to dst through the intersection of their boxes.
CopyClippedMaps: PROC [src, dst: SampleMaps, srcBox, dstBox: Box];
Clip the src and translate it to upper left of the clipped dst.
ReIndexMaps: PUBLIC PROC [maps: SampleMaps, delta: Vec ¬ [0, 0], box: Box ¬ SF.maxBox];
Set box, size, x, y, w, and h of maps, and clip the maps to box; see ImagerSample.ReIndex.
ReleaseDescriptors: PROC [maps: SampleMaps];
Release the descriptors of the maps to ImagerSample pool. Unsafe to use maps after this call.
8 Bit Operations
ValueProc: TYPE ~ PROC [x, y: INTEGER, clientData: REF ¬ NIL] RETURNS [value: BYTE];
FillBWMap: PROC [map: SampleMap, color: CARDINAL];
Fill the pixel map with color.
PutBWPixel: PROC [map: SampleMap, x, y: INTEGER, value: CARDINAL];
Write value to (x, y).
GetBWPixel: PROC [map: SampleMap, x, y: INTEGER] RETURNS [CARDINAL];
Read from (x, y) the 8 or 16 bit value.
PutBWBox: PROC [map: SampleMap, x0, y0, x1, y1: INTEGER, value: CARDINAL];
Fill the box with value.
PutBWLine: PROC [map: SampleMap, x0, y0, x1, y1: INTEGER, value: CARDINAL];
Draw a one pixel wide line from (x0, y0) to (x1, y1).
PutBWScanLine: PROC [map: SampleMap, y: INTEGER, proc: ValueProc, clientData: REF ¬ NIL];
Write scanline-y to the 8 or 16 bit color display; buffers the line to improve efficiency.
PutBWFrame: PROC [map: SampleMap, proc: ValueProc, clientData: REF ¬ NIL];
Write entire frame to the 8 or 16 bit color display; buffers each line to improve efficiency.
This is approximately 3 times faster than calling PutPixel[] for each pixel.
24 Bit Operations
RGBProc: TYPE ~ PROC [x, y: INTEGER, clientData: REF ¬ NIL] RETURNS [rgb: RGB];
FillRGBMap: PROC [maps: SampleMaps, rgb: RGB];
Fill maps with r, g, b; no-op if maps is not 24 bpp.
PutRGBPixel: PROC [maps: SampleMaps, x, y: INTEGER, rgb: RGB];
Write to (x, y) the 24 bit r, g, b value; no-op if maps is not 24 bpp.
GetRGBPixel: PROC [maps: SampleMaps, x, y: INTEGER] RETURNS [RGB];
Read from (x, y) the 24 bit r, g, b value; no-op if maps is not 24 bpp.
PutRGBBox: PROC [maps: SampleMaps, x0, y0, x1, y1: INTEGER, rgb: RGB];
Fill the box with the r, g, b values. No-op if maps is not 24 bpp.
PutRGBLine: PROC [maps: SampleMaps, x0, y0, x1, y1: INTEGER, rgb: RGB];
Draw a one pixel wide line from (x0, y0) to (x1, y1). No-op if maps is not 24 bpp.
PutRGBScanLine: PROC [maps: SampleMaps, y: INTEGER, proc: RGBProc, clientData: REF ¬ NIL];
Write scanline-y to the 24 bit color display; buffers the line to improve efficiency.
No-op if maps is not 24 bpp.
PutRGBFrame: PROC [maps: SampleMaps, proc: RGBProc, clientData: REF ¬ NIL];
Write entire frame to the 24 bit color display; buffers each line to improve efficiency.
No-op if maps is not 24 bpp.
This is approximately 3 times faster than calling PutRGBPixel[] for each pixel.
Pixel Array Operations
InitializePixelArray: PROC [box: Box, bpp: NAT ¬ 8] RETURNS [PixelArray];
Return an empty pixel array dimensioned to box.
AllocatePixelArray: PROC [box: Box, bpp: NAT ¬ 8] RETURNS [PixelArray];
Return a pixel array dimensioned to box, and allocate the internal buffers.
PixelArrayFromSampleMap: PROC [map: SampleMap] RETURNS [PixelArray];
Return a pixel array equivalent to the input sample map.
SampleMapFromPixelArray: PROC [pa: PixelArray] RETURNS [SampleMap];
Return a sample map equivalent to the pixel array.
TransferPixelArrayToMap: PROC [pa: PixelArray, map: SampleMap];
Write the contents of pa into map.
PixelArrayBoxToMap: PROC [pa: PixelArray, map: SampleMap, x1, y1, x2, y2: INTEGER];
Write the contents of pa into map for the given region.
BoxFromPixelArray: PROC [pa: PixelArray] RETURNS [Box];
Return the box describing the pixel array.
DoToPixelArray: PROC [
pa: PixelArray,
proc: ValueProc,
map: SampleMap ¬ NIL,
clientData: REF ¬ NIL];
Perform proc on pa's pixels; if map is not NIL, then update map at same time.
IntersectionOfPixelArrays: PROC [pa1, pa2, pa3, pa4: PixelArray ¬ NIL] RETURNS [Box];
Return the intersection of two pixel arrays.
SetPixelArrayRange: PROC [pa: PixelArray, box: Box];
Redefine the range (x, y, w, h) of the pixel array.
CopyPixelArray: PROC [in: PixelArray] RETURNS [copy: PixelArray];
Create a copy of the pixel array.
Box/Rectangle Operations
BoxFromXYWH: PROC [x, y, w, h: INTEGER] RETURNS [Box];
Box conversion.
XYWHFromBox: PROC [box: Box] RETURNS [x, y, w, h: INTEGER];
Box conversion.
RectangleFromXYs: PROC [x0, y0, x1, y1: INTEGER] RETURNS [Rectangle];
Return a rectangle given its limits (no right/left or top/bottom ordering presumed).
BoxFromRectangle: PROC [rectangle: Rectangle] RETURNS [Box];
A convenience conversion procedure.
Imager Context Operations
DoWithSampleMapsFromContext: PROC [context: Context, action: PROC [maps: SampleMaps]];
Apply action to sample maps obtained from context; usually called from a Viewer PaintProc.
action should not perform any Imager operations on context (Imager operations should be
performed, instead, on a context obtained from ContextFromSampleMaps[]).
The origin of maps is at the upper left.
ContextFromSampleMaps: PROC [maps: SampleMaps, ignoreColormap: BOOL ¬ FALSE]
RETURNS [Context];
Create a context sized as maps and with a backing raster from maps.
The origin of the context is at the lower left.
TransformContextToMap: PROC [context: Context, map: SampleMap];
Transform a presumed unit (±1, ±1) context to coincide with map.
Coordinate System Transformations
PairFromMapCoords: PROC [x, y: INTEGER, map: SampleMap, fit: BOOL ¬ TRUE]
RETURNS [RealPair];
Given the sample map coordinates, return the coordinates in a [-1..1] space.
If fit, then stretch map to fit [-1..1], else clip map to square before transforming.
MapCoordsFromPair: PROC [pair: RealPair, map: SampleMap, fit: BOOL ¬ TRUE]
RETURNS [IntegerPair];
Given coordinates in a [-1..1] space, return the sample map coordinates.
If fit, then stretch map to fit [-1..1], else clip map to square before transforming.
END.