Introduction to CTM Introduction to CTM Introduction to CTM
There are man pages for the following CTM calls:
⊕ ctm_alloc_pv.man
⊕ ctm_find_color.man
⊕ ctm_inc_use_count.man
⊕ ctm_inq_curr_color_map.man
⊕ ctm_intro.man
⊕ ctm_mark_read_only.man
⊕ ctm_release_pv.man
⊕ ctm_set_curr_color_map.man
Each routine description contains
⊕ An abstract of the routine's function
⊕ he order of the routine parameters
⊕ A brief description of each parameter
⊕ A description of the routine's function and use
If the parameter can be declared using a predefined data type, the
description contains the phrase "in XXX format", where XXX is the prede-
fined data type. Pascal and C programmers, look for this phrase to
determine how to declare a parameter.
FORTRAN programmers, look for the phrase that describes the data type in
atomic terms, such as "This parameter is a 2-byte integer."
We've listed all the CTM data types in alphabetical order. If you are
writing CTM programs in Pascal, then all CTM data types are predefined in
the /sys/ins/ctm.ins.pas file. If you are writing CTM programs in C,
then most of the CTM data types are predefined in the
/usr/apollo/include/ctm.h file. However, the CTM set data types are not
predefined; C CTM programmers must learn to simulate these data types.
If you are writing CTM programs in FORTRAN, then none of the CTM data
types are predefined; you must learn how to simulate all CTM data types.
The individual descriptions of each CTM data type explain how to simulate
the type in FORTRAN (or C if necessary). In addition, you may find the
following general notes to be useful.
Pascal supports set variables, but C and FORTRAN do not. However, C and
FORTRAN programmers can simulate Pascal set variables. If the base type
of the Pascal set contains 16 or fewer members, you can simulate the set
by declaring a 2-byte integer. If the base type of the set contains
17-32 members, you can simulate the set by declaring a 4-byte integer.
If the base type of the set contains more than 32 members, then you must
use the special set emulation functions to simulate the set. For full
details on set simulation, see the Programming With General Systems Calls
manual.
Data Types
ctm$allocoptionst
A small set type for specifying a set of pixel values to the CTM.
Though defined as a small set, arguments of type
ctm$allocoptionst may currently take only a single value and the
elements of the set are mutually exclusive. Therefore, arguments of
this type can take one of the following values:
ctm$contiguous
Contiguous pixel values.
| Two Examples of 5 Contiguous Pixel Values |
| from the Default 4-Plane Color Map |
||
| Pixel Value | Color Value | Visible |
||| Color |
|decimal | binary | red | green | blue | |
|||||
| 2 | 0010 | 0 255 0 | green |
| 3 | 0011 | 0 0 255 | blue |
| 4 | 0100 | 0 255 255 | cyan |
| 5 | 0101 | 255 255 0 | yellow |
| 6 | 0110 | 255 0 255 | magenta |
|||||
| 10 | 1010 | 255 255 230 | off white |
| 11 | 1011 | 210 20 0 | dark red |
| 12 | 1100 | 255 255 230 | off yellow |
| 13 | 1101 | 60 60 200 | dark blue |
| 14 | 1110 | 240 240 170 | off white |
|||||
ctm$zeroonly
Pixel values with 0s in a specified plane or bit position.
| Pixel Values with Only 0s in Plane 2 |
| from the Default 4-Plane Color Map |
||
| Pixel Value | Color Value | Visible |
||| Color |
|decimal | binary | red | green | blue | |
|||||
| 0 | 0000 | 0 0 0 | black |
| 1 | 0001 | 255 0 0 | red |
| 4 | 0100 | 0 255 255 | cyan |
| 5 | 0101 | 255 255 0 | yellow |
| 8 | 1000 | 240 255 190 | off white |
| 9 | 1001 | 30 155 0 | dark green |
| 12 | 1100 | 255 255 230 | off yellow |
| 13 | 1101 | 60 60 200 | dark blue |
|||||
ctm$oneonly
Pixel values with 1s in a specified plane or bit position.
| Pixel Values with Only 1s in Plane 2 |
| from the Default 4-Plane Color Map |
||
| Pixel Value | Color Value | Visible |
||| Color |
|decimal | binary | red | green | blue | |
|||||
| 2 | 0010 | 0 255 0 | green |
| 3 | 0011 | 0 0 255 | blue |
| 6 | 0110 | 255 0 255 | magenta |
| 7 | 0111 | 255 255 255 | white |
| 10 | 1010 | 255 255 230 | off white |
| 11 | 1011 | 210 20 0 | dark red |
| 14 | 1110 | 240 240 170 | off white |
| 15 | 1111 | 150 90 0 | brown |
|||||
ctm$both
Pairs of pixel values that differ only in a specified plane;
that is, pixel value pairs that differ in only one bit.
| Five Pixel Value Pairs |
| Differing Only in Plane 3 |
| from the Default 4-Plane Color Map |
||
| Pixel Value | Color Value | Visible |
||| Color |
|decimal | binary | red | green | blue | |
|||||
| 0 | 0000 | 0 0 0 | black |
| 4 | 0100 | 0 255 255 | cyan |
|||||
| 1 | 0001 | 255 0 0 | red |
| 5 | 0101 | 255 255 0 | yellow |
|||||
| 3 | 0011 | 0 0 255 | blue |
| 7 | 0111 | 255 255 255 | white |
|||||
| 9 | 1001 | 30 155 0 | dark green |
| 13 | 1101 | 60 60 200 | dark blue |
|||||
| 10 | 1010 | 255 255 230 | off white |
| 14 | 1110 | 240 240 170 | off white |
|||||
ctm$colormapoptionst
This is a predefined set of 2-byte integers in Pascal. C and FOR-
TRAN do not support set types, but you can simulate this type by
declaring a short int variable in C or an INTEGER*2 variable in FOR-
TRAN. This type contains the current CTM color map options. It is
used for devices with multiple color maps. This set currently has
one member:
ctm$setdisplaycolormap
Set the display (GPR) color map to the current CTM color
map.
ctm$pixelvaluevectort
An array of type gpr$pixelvaluet; that is, an array of indexes
into the color map or array of pixel values.
Errors
ctm$badunit
Returned by ctm$inqcurrcolormap and ctm$setcurrcolormap when
a requested display unit is not in the valid range.
ctm$cant
The CTM can't supply a requested pixel value because the color map
is full. Try using ctm$findcolor to locate a needed color that is
already allocated, or use ctm$releasepv to free up the needed
color table entries.
ctm$invalidcolormapid
Returned by ctm$setcurrcolormap when you specify a color map ID
outside of the valid range (currently 0-7).
ctm$colormapnotinstalled
Returned by ctm$findcolor when you have set the current color map
for CTM but have not set that color map for GPR.
ctm$nospace
The CTM was unable to allocate enough memory for its internal use.
ctm$notallocated
Returned by ctm$releasepv, ctm$incusecount, or
ctm$markreadonly when a requested pixel value was not allocated
to the calling process. A process must allocate entries in the
color map with ctm$allocpv or ctm$findcolor before using them
with other CTM calls.