From: KOSU_MATSB@routh.kosufy.lu.se
Newsgroups: fj.mail-lists.x-window
Subject: Announcing: TGIFCRTL (RTL to make TGIF files).
Date: 10 Sep 92 04:56:26 GMT
Distribution: fj
Organization: Workstation Div., Supermicro Systems Group, Sony Corporation

Date: Wed, 9 Sep 92 11:41:41 -0400
Message-Id: <9209091541.AA23755@expo.lcs.mit.edu>

ANNOUNCING:

                                TGIFCRTL
          a Run-Time Library in C to produce TGIF object files.

                                 Ver 1.1

AUTHOR:
    Mats Bergstr"om, University of Lund, Sweden.
    mats.bergstrom@kosufy.lu.se



ABSTRACT:
    In many types of plots, machine created data is essential, yet the
    need for free hand editing is needed. TGIFCRTL is a small and simple
    run-time library written in ANSI-C to create plots readable by the
    TGIF programme. The programme TGIF is an interactive X-windows based
    drawing programme created by William Chia-Wei Cheng. 



LOCATION:
    TGIFCRTL has been made available for anonymous ftp by William Cheng
    on the locations:

        cs.ucla.edu:/pub/tgif/TGIFCRTL/*
        rye.cs.ucla.edu:/pub/tgif/TGIFCRTL/*



CONTENTS:
    TGIFCRTL.h          Header file for the library. (507 lines).
    TGIFCRTL.c          Source code. (874 lines).
    TGIFCRTL.license    License. *READ*IT*!
    TGIFCRTL.README     This file.
    TGIFCRTL-TEST.c     Simple test file.



COMPILATION:
    Try Your favourite C-compiler:
        "cc -c TGIFCRTL.c" on Un*x like machines
        "CC TGIFCRTL" and "GCC TGIFCRTL" works on VMS.

    The library compiles successfully under the following circumstances:

    VAX/VMS V5.4-1        VAX C V3.0-031  (with \STANDARD=PORTABLE option)
    VAX/VMS V5.4-1        GNU GCC V2.2.2  (both with C an C++ options)
    ULTRIX V4.2 (Rev. 96) ULTRIX RISC C

    There should be no problem in compiling this library under UNIX.



HISTORY:
    The TGIFCRTL was created after a number of frustrated and unsuccessful
    attempts to import claimed encapsulated PostScript files, created by
    various WYSIWYG PC tools, into LaTeX documents. As i had good
    experience with TGIF and the object files describing pictures used by
    TGIF are (fairly) simple ASCII text files, the TGIFCRTL was written as
    a solution to the problem. William Cheng answered may of my questions
    in a friendly, prompt and most enlightening way. I don't think i would
    have been able to finish it in twice the time without his help,
    *Thanks*!!!



KNOWN PROBLEMS:
    Since TGIFCRTL does not involve any X-window routines, the text
    bounding boxes are faked. The same is true with a few other text
    attributes. This is no problem _as_long_as_the_file_is_read_by_TGIF_ 
    since TGIF will recalculate these attributes. PRTGIF, however,
    *relies* on these values and may not perform correct. The solution is
    to read the file with TGIF, write it back immediately and then use
    PRTGIF (or even faster: print from within TGIF ;-).

    The page space upon which TGIFCRTL plots is restricted to the
    smallest common size of A4 and it's American cousin covers.

    If a polyline of polygon have vertices too close on a (supposed) 
    smooth curve it may look crooked since the resolution is 5/mm (256/"),
    either recalculate with longer distances or delete points by hand.

    Please bare in mind that i wrote this in my spare time, THERE IS NO
    WARRANTY WHAT SO EVER (read the license!).
    If You find a bug, please drop me a note describing the problem.
    I'll try to correct it, if and when i can find time for a next version.


USAGE:
    The library supports all TGIF objects *except* arcs (will come in next
    version though). In addition to these a special MARKER object can be
    drawn. This is a composed object used for marking a position on a
    curve etc. Currently there are two types of markers available: CIRCLE
    and SQUARE. 

    The graphical objects are divided into four classes: open (polyline), 
    closed (box, oval, rcbox), text and marker. Each of these have a 
    separate graphic state. The graphic state determines line width, line 
    type, fill pattern, text font, marker type etc., for an object to be 
    written on the output file. The header file "TGIFCRTL.h" defines 
    macros for each of the possible parameter values in the "TRset_xxx" 
    functions. If a parameter value is replace by the macro "IGNORE" the 
    corresponding parameter is ignored and not set.

    The library sets no restriction in number of output files open 
    simultaneously.

    The library functions may be divided into three types:
    i,   Basic functions such as open and close an output file.
    ii,  Control functions to set graphic states and transformation.
    iv,  Drawing functions to draw objects.

    All function identifiers use the prefix "TR" (for TgifcRtl) and all
    but "TRopen" have "TR_FILE *tp" as first argument.



LIST OF FUNCTIONS:
    TRopen                  Open a new output file.
    TRclose                 Close an output file.
    TRerr                   Report Error status (not fully implemented).

    TRset_htrans            Set horizontal transformation.
    TRset_vtrans            Set vertical transformation.
    TRhtrans                Return horiz. paper coordinate.
    TRvtrans                Return vert. paper coordinate.
    TRhmm                   Transform x to x horizonal mm's
    TRvmm                   Transform x to x vertical mm's
    TRhdot                  Transform x to horizonal dots
    TRvdot                  Transform x to vertical dots

    TRset_default           Set default graphics states and 
    TRset_open_line         Set graphic state for open shapes.
    TRset_open_fill         Set graphic state for open shapes.
    TRset_open_arrow        Set graphic state for open shapes.
    TRset_closed_line       Set Graphic state for closed shapes.
    TRset_closed_fill       Set Graphic state for closed shapes.
    TRset_closed_rc         Set Graphic state for closed shapes.
    TRset_text_text         Set graphic state for text.
    TRset_text_fill         Set graphic state for text.
    TRset_mark_mark         Set Graphic state for Markers.
    TRset_mark_line         Set Graphic state for Markers.  
    TRset_mark_fill         Set Graphic state for Markers.
    TRset_mark_arrow        Set Graphic state for Markers.
    TRset_mark_text         Set Graphic state for Markers.
    TRset_lock              Objects are locked.
    TRset_unlock            Objects are unlocked.
    TRpush                  Push/Pop the current graphics state
    TRpop                   on the graphics stack.

    TRpolyline              Write a poly line.
    TRpolygon               Write a polygon         
    TRoval                  Write oval.     
    TRbox                   Write box.      
    TRrcbox                 Write rounded-corner box.
    TRtext                  Write text.
    TRline                  Draw a single line element
    TRmark                  Draw a marker at position.
    TRpolymark              Mark may positions.

    TRgroup_begin           Begin a group object.
    TRgroup_end             End a group object.


			Sincerely/Mats Bergstr"om.
 -----------------------------------  -----------------------------------
 Mats Bergstrvm                       mats.bergstrom@kosufy.lu.se
 Div of Cosmic and Subatomic Physics  kosu_matsb@130.235.92.17
 Department of Physics                ROUTH::KOSU_MATSB (ROUTH::=57412::)
 University of Lund                   Phone: (+46)104767
 SWEDEN.                              Fax:   (+46)104709
 -----------------------------------  -----------------------------------