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
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].
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.
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.