CGM
Name
CGM_open,
CGM_close,
CGM_lseek,
CGM_read,
CGM_write,
CGM_directory,
CGM_freeDirectory,
CGM_printDirectory,
CGM_getInstr,
CGM_flushGetInstr,
CGM_putInstr,
CGM_flushOutputInstr,
CGM_initMetaEdit,
CGM_termMetaEdit,
CGM_copyFrames,
CGM_deleteFrames,
CGM_mergeFrames
CGM_moveFrames,
CGM_readFrames,
CGM_valid,
CGM_writeFile,
CGM_writeFrames,
CGM_appendFrames - Computer Graphics Metafile operations
Syntax
#include
Cgm_fd CGM_open(metafile, size, flags, mode)
char *metafile;
unsigned size;
int flags;
int mode;
int CGM_close(cgm_fd)
Cgm_fd cgm_fd;
int CGM_lseek(cgm_fd, offset)
Cgm_fd cgm_fd;
int offset;
int CGM_read(cgm_fd, buf)
Cgm_fd cgm_fd;
unsigned char *buf;
int CGM_write(cgm_fd, buf)
Cgm_fd cgm_fd;
unsigned char *buf;
Directory *CGM_directory(cgm_fd)
Cgm_fd cgm_fd;
void CGM_freeDirectory(dir)
Directory *dir;
void CGM_printDirectory(dir)
Directory *dir;
int CGM_getInstr(cgm_fd, instr)
Cgm_fd cgm_fd;
Instr *instr;
void CGM_flushGetInstr(cgm_fd)
Cgm_fd cgm_fd;
int CGM_putInstr(cgm_fd, instr)
Cgm_fd cgm_fd;
Instr *instr;
int CGM_flushOutputInstr(cgm_fd)
Cgm_fd cgm_fd;
Directory *CGM_initMetaEdit (metafile, size)
char *metafile;
unsigned int size;
int CGM_termMetaEdit()
Directory *CGM_copyFrames(start, num, target )
unsigned int start;
int num;
unsigned int target;
Directory *CGM_deleteFrames(start, num)
unsigned int start,
num;
Directory *CGM_mergeFrames(bottom, top)
unsigned bottom, top;
Directory *CGM_moveFrames (start, num, target)
unsigned int start, num, target;
Directory *CGM_readFrames(metafile, start, num, target, size)
char *metafile;
unsigned int start;
int num;
unsigned int target, size;
int *CGM_validCGM(metafile)
char *metafile;
int CGM_writeFile(metafile)
char *metafile;
int CGM_writeFrames(metafile, start, num)
char *metafile;
unsigned start, num;
int CGM_appendFrames(metafile, start, num)
char *metafile;
unsigned start, num;
Description
The argument cgm_fd refers to a valid file descriptor created
for reading or writing, as appropriate by
CGM_open. CGM_read,
CGM_directory, CGM_getInstr and
CGM_flushGetInstr require a file descriptor open for
reading. CGM_write,
CGM_getInstr,CGM_flushGetInstr and
CGM_flushOutputInstr require a Cgm_fd open
for writing. CGM_close and CGM_lseek
will accept any valid Cgm_fd.
The size argument refers to the CGM record size in bytes.
For an NCAR CGM this value is 1440.
buf is a pointer to user allocated memory of size
size. This storage will be used for buffering input and
output of CGM_read and CGM_write
respectively.
The dir argument is a pointer to a Directory
structure created with CGM_directory or
CGM_initMetaEdit. dir is a private resource
that should NOT be directly modified by the user. A set of
convenience macros is provided for this purpose in
cgm_tools.h.
The start, num and target arguments are
used to address frame numbers in a metafile being edited with one of
the commands: CGM_copyFrames,
CGM_deleteFrames, CGM_readFrames,
CGM_moveFrames, CGM_writeFrames and
CGM_mergeFrames. The start argument is the
first frame in a sequence of num frame(s) to perform the
editing operation on. target is similar to start and
is used by commands that require two frame addresses such as
copy. Addressing begins at zero.
- CGM_open
- This command is modeled after the unix open command. It
will open a CGM for reading or writing as specified by the
flags argument and return a Cgm_fd file
descriptor. The flags and open parameters are passed
directly on to the system open command. For a detailed
explanation of these two arguments see open(2).
- CGM_close
- Delete a file descriptor. The inverse of
CGM_open. See close(2).
- CGM_read
- CGM_read attempts to read size bytes
from the object referenced through the descriptor
cgm_fd. size is set at the creation of
cgm_fd by
CGM_open. CGM_read returns the
number of bytes successfully read. A zero is returned on EOF and a
negative number implies an error occurred. The unix system call
read is called by CGM_read. See read(2).
- CGM_write
- Attempts to write a single record of size bytes from
buf from the object referenced by cgm_edit where
size is the record size parameter provided at the creation of
cgm_fd. write returns the number of bytes
successfully written. A negative return number implies an error
occurred. The unix system call write is called by
CGM_write. See write(2).
- CGM_lseek
- Advance the file pointer of cgm_fd to offset
bytes. Upon successful completion the current file pointer offset is
returned. A negative return value is an error. The unix system call
lseek is called by CGM_lseek. See lseek(2).
- CGM_directory
- Create a table of contents for the metafile referenced by
cgm_fd. Return a pointer to this table of type
Directory. The contents of the directory include number of
metafiles, number of frames, record offset for each frame, frame
length in records, optional frame description and metafile
status. These fields are meant to be read only and should only be
referenced by the convenience macros provided in cgm_tools.h. A NULL
pointer is returned on failure.
- CGM_freeDirectory
- Free memory allocated to a directory created by
CGM_directory or CGM_initMetaEdit.
- CGM_printDirectory
- Print the contents of a directory pointed to by dir to the
standard output.
- CGM_getInstr,
- Fetch the next instruction in file referenced by cgm_edit and
convert it into a usable format pointed to by instr.
CGM_getInstr provides an interface to the metafile
for extracting CGM elements. The user need not be concerned with the
binary format of the metafile. The fields of the Instr are as
described in cgm_tools.h. The user should note that the
maximum allowable data length returned in a single invocation is 32760
bytes. The CGM standard allows upto 32767 bytes to be stored in a
single instruction. But 32767 is not a nice number to work
with. Should the data length of a CGM instruction exceed 32760 bytes,
indicated by the boolean more flag, the next invocation of
CGM_getInstr will return the remaining data upto the
same limit. And so on... CGMgetInstr\R requires a
valid Cgm_fd open for reading. For a description on CGM see
the ANSI standard.
- CGM_flushGetInstr
- Flush the input buffer used by
CGM_getInstr\fR. CGM_getInstr buffers the contents of
the CGM and only performs actual reads as necessary. If the user
desires other then sequential read access to a CGM it becomes
necessary to flush the input buffer before reading from a new
location.
- CGM_putInstr
- The analog to CGM_getInstr. This function buffers CGM
instructions to be written to a CGM referenced by
cgm_fd. Again the user need not be concerned with the binary
format of the file. Writes are performed sequentially in record size
size as specified during the creation of cgm_fd. The
same data length constraints that are placed on
CGM_getInstr hold for
CGM_putInstr. If the user wants to output
instructions with a data length greater than 32760 bytes then the data
must be broken up into blocks no greater than this size. The user must
also set the boolean more flag in the
Instr. cgm_fd must be a valid file descriptor open
for writing. For a description of the fields of the Instr see
the file cgm_tools.h.
- CGM_flushOutputInstr
- Flush the output buffer used by CGM_putInstr for the
file referenced by cgm_fd. It is necessary to explicitly
flush the output buffer used by CGM_putInstr before
the file is closed or any random access is performed. Otherwise not
all CGM elements will actually get written.
- CGM_initMetaEdit
- Initialize a metafile for editing. This is the initialization routine
for the higher level editing routines contained in this package:
CGM_copyFrames, CGM_deleteFrames\fR,
CGM_readFrames, CGM_moveFrames,
CGM_writeFile, CGM_writeFrames, and
CGM_mergeFrames. These routines only work on one
metafile at a time (the one named in
CGM_initMetaEdit. Invoking this routine for a second
time without explicitly saving any changes will have the effect of
loading a new file and discarding all changes made in the previous
file. CGM_initMetaEdit and all proceeding editing
functions that make changes to the file return a
pointer to a Directory as a convenience that allows the user
to examine the state of the file. The contents of the directory are
private and should NOT be changed by the user. A set of macros is
provided in cgm_tools.h to be used for retrieving the
directory's contents. Note: no changes are actually
made to the edit file unless it is explicitly overwritten with either
CGM_writeFile or CGM_writeFrames.
- CGM_termMetaEdit
- Terminate the editing session started with
CGM_initMetaEdit. This routine should be called
after any editing changes have been saved, if desired to save them,
and before exiting the editing session.
CGM_termMetaEdit frees valuable resources.
- CGM_copyFrames
- Copy num frames beginning with start to the frame
addressed by target. If target is already occupied
then the source frames are inserted in its place while the target
frame, and all proceeding frames, are
advanced. CGM_copy operates on the file initialized
by CGM_initMetaEdit (the edit file). On successful
completion a pointer to the current directory is returned. On error a
NULL pointer is returned.
- CGM_deleteFrames
- Delete num frames from the edit file starting with frame
start. On successful completion a pointer to the current
directory is returned. On error a NULL pointer is returned.
- CGM_mergeFrames
- Overwrite the contents of frame addressed bottom with the
union of the frame at location bottom and the frame at
location top. The effect of this command is equivalent to
drawing the top frame on top of the bottom frame. It
is not a union in the true sense of the word. On successful
completion a pointer to the current directory is returned. On error a
NULL pointer is returned.
- CGM_moveFrames
- Move a block of num frames from the edit file starting with
with frame start to the position occupied by frame
target On successful completion a pointer to the current
directory is returned. On error a NULL pointer is returned.
- CGM_readFrames
- Read num frames from metafile file starting with
frame start. Insert the frames at address target in
the edit file. On successful completion a pointer to the current
directory is returned. On error a NULL pointer is returned.
- CGM_validCGM
- Determine whether a file is a valid NCAR CGM or not. This function
performs a few simple diagnostics in an effort to determine whether a
given file is in the NCAR CGM format. The tests performed are not
rigorous and it is conceivable that the information retrieved is
incorrect. A return of 1 indicates a valid NCAR CGM. A return of 0
indicates the file is not a NCAR CGM. A return of -1 indicates an
error occurred and the global variable `errno' is set accordingly.
- CGM_writeFile
- Write the entire contents of the current edit file to
file. CGM_writeFile returns the integer one
on success and a negative number on failure.
- CGM_writeFrames
- Write a block of num frames starting with frame
start to file. The source frames come from the edit
file. Note: CGM frames are contained in a wrapper made up of CGM
delimiter elements. The file created by
CGM_writeFrames will use the wrapper
provided by the current edit file. Thus if a file foo
contains n frames that are read into an editing
session with a file goo and then these same frames are
written out to a file zoid, zoid may or may not be
the same as the original foo.
CGM_writeFrames returns the integer one on success
and a negative number on failure.
- CGM_appendFrames
- Append a block of num frames starting with frame
start to file. file must already exist and
be a valid NCAR CGM. CGM_appendFrames returns the
integer one on success and a negative number on failure.
See also
ANSI X3.122 Computer Graphics Metafile for the Storage and
Transfer of Picture Description Information.
Bugs
CGMs with more the one metafile stored in the are not guaranteed to work.
Should not have to explicitly flush the output buffer for
CGM_getInstr. This should be handled automatically when the
file is closed.
Copyright
Copyright © 1987-1999
University Corporation for Atmospheric Research
The use of this
software and documentation is governed by a License Agreement.