CGM_TOOLS(1NCARG)

📦 version 6.6.2, in epel 9, fedora 43, fedora 44

okay bestie, sit down, hydrate, because we're about to read the CGM_TOOLS(1NCARG) page together — that's the NCAR GRAPHICS manual, and it's all about Computer Graphics Metafile operations. no cap, this is the whole lore 💖

✨ 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 🎀

like, here's the whole vibe check, verbatim, don't touch a character 💅

#include <cgm_tools.h>

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 🌸

okay so first thing, the arguments, because everything else builds on these 🫶

The argument cgm_fd is a valid file descriptor that was created for reading or writing — whichever is appropriate — by CGM_open. Now listen, because the reading/writing split is a whole thing:

  • CGM_read, CGM_directory, CGM_getInstr and CGM_flushGetInstr need a file descriptor that's open for reading.
  • CGM_write, CGM_getInstr, CGM_flushGetInstr and CGM_flushOutputInstr need a Cgm_fd that's open for writing. (yes, CGM_getInstr and CGM_flushGetInstr are in both lists, that's just how it is, iykyk 😌)
  • CGM_close and CGM_lseek will happily take any valid Cgm_fd. periodt.

The size argument is the CGM record size, in bytes. For an NCAR CGM this value is 1440. memorize it, it comes back a lot 🔥

buf is a pointer to user allocated memory of size size. That storage gets used for buffering input and output of CGM_read and CGM_write respectively. it's giving "you bring the bucket, I'll bring the water" 💧

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, bestie, hands off 🙈. A set of convenience macros is provided for exactly this purpose in cgm_tools.h.

The start, num and target arguments are how you address frame numbers in a metafile you're editing with one of these: CGM_copyFrames, CGM_deleteFrames, CGM_readFrames, CGM_moveFrames, CGM_writeFrames and CGM_mergeFrames. So:

  • start is the first frame in a sequence of num frame(s) that you're performing the editing operation on.
  • target is similar to start and is used by commands that need two frame addresses, like copy.
  • Addressing begins at zero. zero-indexed girlies rise up ✨

👑 CGM_open

This one is modeled after the unix open command, iconic honestly. It opens a CGM for reading or writing as specified by the flags argument and returns 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

Deletes a file descriptor. It's 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. And where does that size come from? It was set at the creation of cgm_fd by CGM_open 💫

  • It returns the number of bytes successfully read.
  • A zero is returned on EOF.
  • A negative number means an error happened 😭

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 you provided when cgm_fd was created. write returns the number of bytes successfully written. A negative return number means 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

Creates a table of contents for the metafile referenced by cgm_fd, and returns a pointer to this table of type Directory. What's inside, you ask? The contents of the directory include:

  • number of metafiles
  • number of frames
  • record offset for each frame
  • frame length in records
  • optional frame description
  • 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

Frees the memory allocated to a directory created by CGM_directory or CGM_initMetaEdit. be a good citizen, free your stuff 🧚

👑 CGM_printDirectory

Prints the contents of the directory pointed to by dir to the standard output.

👑 CGM_getInstr

Fetch the next instruction in the 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, we handle that, you're welcome 💅 The fields of the Instr are as described in cgm_tools.h.

now the part you actually need to remember:

The maximum allowable data length returned in a single invocation is 32760 bytes. The CGM standard allows up to 32767 bytes to be stored in a single instruction — but 32767 is <em>not</em> 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 up to the same limit. And so on... CGM_getInstr requires a valid Cgm_fd open for reading. For a description on CGM see the ANSI standard.

👑 CGM_getInstr (flush edition) — CGM_flushGetInstr

Flush the input buffer used by CGM_getInstr. CGM_getInstr buffers the contents of the CGM and only performs actual reads as necessary. If you desire anything other than sequential read access to a CGM, it becomes necessary to flush the input buffer before reading from a new location. no skipping around without flushing, bestie 🙈

👑 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. So if you want 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. You 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. and that's the tea ☕😭

👑 CGM_initMetaEdit

Initialize a metafile for editing. This is the initialization routine for the higher level editing routines in this package: CGM_copyFrames, CGM_deleteFrames, 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 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 💀 so save first, bestie.

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 you wanted 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. bye bye frames 👋

💅 CGM_mergeFrames

Okay so this one takes the frame sitting at bottom and straight up overwrites it with the union of the frame at bottom and the frame at top. What does that actually feel like? It's the same as drawing the top frame right on top of the bottom frame. It is not a union in the true sense of the word, bestie — do not come for me, that's just what the docs say. 🌸

  • Works out? You get a pointer to the current directory back. ✨
  • Flops? You get a NULL pointer. 💀

🦋 CGM_moveFrames

Moving day! This moves a block of num frames from the edit file, starting with frame start, over to the spot currently occupied by frame target.

  • All good → pointer to the current directory. 🫶
  • Not all good → NULL pointer. 😭

🎀 CGM_readFrames

Reads num frames from metafile file, starting with frame start, and inserts those frames at address target in the edit file. Like importing but make it CGM. 💖

  • Success → pointer to the current directory, iconic.
  • Error → NULL pointer, tragic.

🧚 CGM_validCGM

Is this file a valid NCAR CGM or is it lying to you? That's the whole vibe check. 👑

It runs a few simple diagnostics to try and figure out whether a given file is in the NCAR CGM format. Heads up though — these tests are not rigorous, and it is conceivable that the info you get back is incorrect. So like, trust but verify, fr fr.

  • 1 → valid NCAR CGM ✅
  • 0 → not a NCAR CGM ❌
  • -1 → an error happened, and the global variable errno gets set accordingly. 🚨

🌈 CGM_writeFile

Writes the entire contents of the current edit file out to file. That's it, that's the function.

Returns the integer 1 on success and a negative number on failure. Periodt.

🔥 CGM_writeFrames

Writes a block of num frames starting with frame start to file. The source frames come from the edit file.

⚠️ Note time, and this one matters: 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. So if a file foo contains n frames that are read into an editing session with a file goo, and then those same frames get written out to a file zoid, zoid may or may not be the same as the original foo. No cap. 🙈

Returns the integer 1 on success and a negative number on failure.

🍓 CGM_appendFrames

Appends a block of num frames starting with frame start to file. Key detail: file must already exist and must already be a valid NCAR CGM. No creating files out of thin air, bestie. 💅

Returns the integer 1 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 than one metafile stored in them are not guaranteed to work. Yeah. That's the whole bug. 🫠
  • Should not have to explicitly flush the output buffer for CGM_getInstr. This should be handled automatically when the file is closed. (Currently: not handled. Rude.)

Copyright (C) 1987-2009 University Corporation for Atmospheric Research

The use of this Software is governed by a License Agreement.

And that's a wrap on the whole page, my love! 🎀 This beauty is an NCARG joint, dated January 1993, and it lives in section 1NCARG as CGM_TOOLS — go forth and manipulate those metafiles responsibly. Mwah. 💋

📦 where this page comes from