Simtel MSDOS 1992 September/Simtel20_Sept92.cdr/msdos/graphics/grafxlib.arc/GRAFSEC2.TEX

Text File | 1987-09-01 | 15KB | 526 lines

\manpage intro(2)

\manname
    intro --- introduction to halo emulation library
\mandscr
    The halo emulation library is a collection of routines that
    emulate some of the most frequently used routines of the
    popular HALO graphics library. It was written to assist in
    converting HALO programs to the Grafix library.

    To use the halo functions, you should include the
    file \bfwd halo.h at the start of your program and
    link with the graphics library as usual.

    Most of these functions are fairly straightforward; however,
    there are a few things you should be aware of. First of
    all, and probably most important, all the parameters to all
    the halo routines must be passed by reference, i.e., you must pass
    pointers to the desired arguments to the graphics routines, not
    the arguments themselves. Second, the halo routines
    remember one point, called the graphics cursor, and
    a color, called the current drawing color. The halo
    drawing routines use these values instead of explicitly
    passed parameters in many instances. They may be set with
    the \itnc movabs , \itnc movrel , and \itwd setcolor functions.
    And third, the halo drawing routines always take
    world coordinates, never device coordinates (as is
    possible in the original HALO library).
\manex
\vinput grafex2.c
\manpend

\manpage box(2)

\manname
    box --- draw a rectangular box
\mansyn
    void box(x1, y1, x2, y2)

    float *x1, *y1, *x2, *y2;
\mandscr
    The \itwd box function draws the rectangular box defined by the points
    \itpnt (*x1, *y1) and \itpnt (*x2, *y2) (in world coordinates)
    in the current drawing buffer with the current drawing color.
    If xor mode is on, the rectangle is logically xor'ed with the
    existing data in the buffer.
\mansee
    g_box(1).
\manpend

\manpage cir(2)

\manname
    cir --- draw a circle
\mansyn
    void cir(r)

    float *r;
\mandscr
    The \itwd g_cir function draws a circle centered on the current
    graphics cursor with radius~\itwd r (in world coordinates).
    The circle is drawn in the current drawing buffer with the current
    drawing color. If xor mode is
    on, the circle is logically xor'ed with the existing data in the
    buffer. The radius is taken to be half of the horizontal diameter
    of the circle, in world coordinates.
\mansee
    g_circle(1).
\manpend

\manpage coordinates(2)

\manname
    coordinates --- coordinate systems used
\mandscr
    The halo routines utilize three different coordinate
    systems: device, normalized device, and world. The following
    sections explain these coordinate systems and their
    interrelationships.

\manhead Device coordinates\par

    The first and simplest coordinate system is device coordinates.
    In device coordinates, the origin is at the upper left
    corner of the screen and the axes are scaled in pixels.
    Thus in the four-color mode of the CGA, for example,
    device coordinates range from (0, 0) to (319, 199).
    All the graphics routines listed in section 1 of this manual
    use device coordinates.
    Device coordinates are always expressed as integers.

\vskip\baselineskip
\centerline{\vbox{%
  \hbox to 4in{(0, 0)\hfill (319, 0)}%
  \smallskip
  \hrule width4in
  \hbox to 4in{\vrule height3in
               \hfill
               \vbox to 3in{\vfill\hbox{Device coordinates}\vfill}%
               \hfill
               \vrule height3in}%
  \hrule width4in
  \smallskip
  \hbox to 4in{(0, 199)\hfill (319, 199)}%
}}
\bigskip

\manhead Normalized device coordinates\par

    In normalized device coordinates, the origin is still the
    upper left corner of the screen, but the point (1.0, 1.0)
    is fixed at the lower right corner. This allows one to specify
    coordinates without knowing the physical size of the screen.
    Normalized device coordinates are always expressed as floats.

\vskip\baselineskip
\centerline{\vbox{%
  \hbox to 4in{(0.0, 0.0)\hfill (1.0, 0.0)}%
  \smallskip
  \hrule width4in
  \hbox to 4in{\vrule height3in
               \hfill
               \vbox to 3in{\vfill\hbox{Normalized device coordinates}\vfill}%
               \hfill
               \vrule height3in}%
  \hrule width4in
  \smallskip
  \hbox to 4in{(0.0, 1.0)\hfill (1.0, 1.0)}%
}}
\bigskip

\manhead World coordinates\par

    In world coordinates you can set up a coordinate system
    with an arbitrary offset and scale. For example, if you
    want to have the x coordinates range from $-100$ to $+100$
    and the y coordinates range from $-50$ to $+50$, you would
    call the \itwd setworld function as follows:
\mancodebeg
      x1 = -100.0;        /* lower left corner */
      y1 = -50.0;
      x2 = 100.0;        /* upper right corner */
      y2 = 50.0;
      setworld(&x1, &y1, &x2, &y2);
\mancodeend
    This sequence results in the following situation:

\vskip\baselineskip
\centerline{\vbox{%
  \hbox to 4in{($-$100.0, 50.0)\hfill (100.0, 50.0)}%
  \smallskip
  \hrule width4in
  \hbox to 4in{\vrule height3in
               \hfill
               \vbox to 3in{\vfill\hbox{World coordinates}\vfill}%
               \hfill
               \vrule height3in}%
  \hrule width4in
  \smallskip
  \hbox to 4in{($-$100.0, $-$50.0)\hfill (100.0, $-$50.0)}%
}}
\bigskip

\manhead Coordinate transformations\par

    The following routines are available for converting points
    from one coordinate system to another:
{\obeylines
      mapdton --- convert device to normalized device coordinates
      mapdtow --- convert device to world coordinates
      mapntod --- convert normalized device to device coordinates
      mapntow --- convert normalized device to world coordinates
      mapwtod --- convert world to device coordinates
      mapwton --- convert world to normalized device coordinates
}

\manhead Viewports\par

    Viewports allow one to draw only on a portion of the screen.
    For example, if we wanted the same coordinate system as
    we had in the last example but we wanted to use only the
    upper left corner of the screen, we could use:
\mancodebeg
      x1 = 0.0;   /* upper left corner of viewport in NDC */
      y1 = 0.0;
      x2 = 0.5;   /* lower right corner of viewport in NDC */
      y2 = 0.5;
      c = -1;     /* no border or clearing */
      setviewport(&x1, &y1, &x2, &y2, &c, &c);

      x1 = -100.0;  /* lower left corner */
      y1 = -50.0;
      x2 = 100.0;   /* upper right corner */
      y2 = 50.0;
      setworld(&x1, &y1, &x2, &y2);
\mancodeend
    This results in the following:

\vskip\baselineskip
\centerline{\vbox{%
  \hbox to 4in{($-$100.0, 50.0)\hfill \hbox to 2in{(100.0, 50.0)\hfill}}%
  \smallskip
  \hrule width 4in
  \hbox to 4in{%
    \vrule height 3in
    \vbox to 3in{%
      \hbox to 2in{%
        \hfill
        \vbox to 1.5in{%
          \vfill
          \hbox{\hfill Viewport\hfill}%
          \vfill
        }%
        \hfill
        \vrule height 1.5in
      }%
      \hrule width 2in
      \smallskip
      \hbox to 2in{($-$100.0, $-$50.0)\hfill}%
      \vfill
    }%
    \vbox to 3in{%
      \vskip 1.5in
      \smallskip
      \hbox{(100.0, $-$50.0)\hfill}%
      \vfill
    }%
    \hfill
    \vrule height 3in
  }%
  \hrule width 4in
}}
\bigskip

    Note that the viewport corners are specified using normalized
    device coordinates.
\mansee
    mapdton(2),
    mapdtow(2), mapntod(2), mapntow(2), mapwtod(2),
    mapwton(2), \hint setworld(2), setviewport(2).
\manpend

\manpage halo_init(2)

\manname
    halo_init --- initialize the halo routines
\mansyn
    void halo_init()
\mandscr
    The \itwd halo_init function initializes the halo routines,
    resets the viewport to the entire screen, and resets world
    coordinates to device coordinates (i.e., x coordinates
    range from 0 to the x size of the device, similarly for
    y coordinates). It also moves the graphics cursor
    to~(0, 0) and sets the current drawing color to~0.
    This function must be called \itwd after
    every call to \itwd g_open and \itwd before any
    other halo routines are used.
\mansee
    g_open(1).
\manpend

\manpage lnabs(2)

\manname
    lnabs ---  draw a line to a specified point
\mansyn
    void lnabs(x, y)

    float *x, *y;
\mandscr
    The \itwd lnabs function draws a line from the current graphics
    cursor position to the point~\itpnt (*x, *y) in world coordinates and
    the graphics cursor is set to~\itpnt (*x, *y). The line is
    drawn in the current drawing buffer with the current drawing
    color. If xor mode is on the line is logically xor'ed with
    the existing data in the buffer.
\mansee
    g_line(1), lnrel(2).
\manpend

\manpage lnrel(2)

\manname
    lnrel --- draw a line relative to the current graphics cursor position
\mansyn
    void lnrel(dx, dy)

    float *dx, *dy;
\mandscr
    The \itwd lnrel function draws a line from the current graphics
    cursor to the point \break \itpnt ({cur_x + *dx}, {cur_y + *dy}) in
    world coordinates, where \itpnt (cur_x, cur_y) is the current
    position of the graphic cursor. After the line is drawn,
    the graphics cursor is moved to \itpnt ({cur_x + *dx},
    {cur_y + *dy}). The line is
    drawn in the current drawing buffer with the current drawing
    color. If xor mode is on the line is logically xor'ed with
    the existing data in the buffer.
\mansee
    g_line(1), lnabs(2).
\manpend

\manpage mapdton(2)

\manname
    mapdton --- map device to normalized device coordinates
\mansyn
    void mapdton(dx, dy, nx, ny)

    int *dx, *dy;
    float *nx, *ny;
\mandscr
    The \itwd mapdton function converts the device coordinates
    \itpnt (*dx, *dy) to the corresponding normalized device
    coordinates \itpnt (*nx, *ny).
\mansee
    coordinates(2),
    mapdtow(2), mapntod(2), mapntow(2), mapwtod(2),
    mapwton(2), setworld(2), setviewport(2).
\manpend

\manpage mapdtow(2)

\manname
    mapdtow --- map device to world coordinates
\mansyn
    void mapdtow(dx, dy, wx, wy)

    int *dx, *dy;
    float *wx, *wy;
\mandscr
    The \itwd mapdtow function converts the device coordinates
    \itpnt (*dx, *dy) to the corresponding world
    coordinates \itpnt (*wx, *wy).
\mansee
    coordinates(2),
    mapdton(2), mapntod(2), mapntow(2), mapwtod(2),
    mapwton(2), setworld(2), setviewport(2).
\manpend

\manpage mapntod(2)

\manname
    mapntod --- map normalized device to device coordinates
\mansyn
    void mapntod(nx, ny, dx, dy)

    float *nx, *ny;
    int *dx, *dy;
\mandscr
    The \itwd mapntod function converts the normalized device coordinates
    \itpnt (*nx, *ny) to the corresponding device
    coordinates \itpnt (*dx, *dy).
\mansee
    coordinates(2),
    mapdton(2), mapdtow(2),  mapntow(2), mapwtod(2),
    mapwton(2), setworld(2), setviewport(2).
\manpend

\manpage mapntow(2)

\manname
    mapntow --- map normalized device to world coordinates
\mansyn
    void mapntow(nx, ny, wx, wy)

    float *nx, *ny;
    float *wx, *wy;
\mandscr
    The \itwd mapntow function converts the normalized device coordinates
    \itpnt (*nx, *ny) to the corresponding world
    coordinates \itpnt (*wx, *wy).
\mansee
    coordinates(2),
    mapdton(2), mapdtow(2), mapntod(2), mapwtod(2),
    mapwton(2), setworld(2), setviewport(2).
\manpend

\manpage mapwtod(2)

\manname
    mapwtod --- map world to device coordinates
\mansyn
    void mapwtod(wx, wy, dx, dy)

    float *wx, *wy;
    int *dx, *dy;
\mandscr
    The \itwd mapwtod function converts the world coordinates
    \itpnt (*wx, *wy) to the corresponding device
    coordinates \itpnt (*dx, *dy).
\mansee
    coordinates(2),
    mapdton(2), mapdtow(2), mapntod(2), mapntow(2),
    mapwton(2), setworld(2), setviewport(2).
\manpend

\manpage mapwton(2)

\manname
    mapwton --- map world to normalized device coordinates
\mansyn
    void mapwton(wx, wy, nx, ny)

    float *wx, *wy;
    float *nx, *ny;
\mandscr
    The \itwd mapwton function converts the world coordinates
    \itpnt (*wx, *wy) to the corresponding normalized device
    coordinates \itpnt (*nx, *ny).
\mansee
    coordinates(2),
    mapdton(2), mapdtow(2), mapntod(2), mapntow(2), mapwtod(2),
    setworld(2), setviewport(2).
\manpend

\manpage movabs(2)

\manname
    movabs --- move the graphics cursor to a specified point
\mansyn
    void movabs(x, y)

    float *x, *y;
\mandscr
    The \itwd movabs function moves the graphics cursor to the
    position \itpnt (*x, *y) in world coordinates.
\mansee
    movrel(2).
\manpend

\manpage movrel(2)

\manname
    movrel --- move the graphics cursor relatively
\mansyn
    void movrel(dx, dy)

    float *dx, *dy;
\mandscr
    The \itwd movrel function moves the graphics cursor to the
    position \itpntb ({cur_x + *dx}, {cur_y + *dy}) in world
    coordinates where \itpnt (cur_x, cur_y) is the current position
    of the graphics cursor.
\mansee
    movabs(2).
\manpend

\manpage setcolor(2)

\manname
    setcolor --- set the current drawing color
\mansyn
    void setcolor(c)

    int *c;
\mandscr
    The \itwd setcolor function sets the current drawing color
    to~\itnc c . If~\itwd c is greater than the maximum color
    value available on the graphics device in use, the
    maximum value is used instead.
\manpend

\manpage setviewport(2)

\manname
    setviewport --- set the active viewport
\mansyn
    void setviewport(x1, y1, x2, y2, border, backgnd)

    float *x1, *y1, *x2, *y2;
    int *border, *backgnd;
\mandscr
    The \itwd setviewport function sets the viewport and the
    clipping boundaries to the rectangular area defined by the
    points \itpnt (x1, y1) and \itpnt (x2, y2) in normalized device
    coordinates. If \itwd border is not $-$1, a border of
    color~\itwd border will be drawn around the viewport (if there is
    room for it), and if~\itwd backgnd is not $-$1, the interior
    of the viewport will be cleared to color~\itnc backgnd .
\mansee
    g_setclip(1), coordinates(2), setworld(2).
\manpend

\manpage setworld(2)

\manname
    setworld --- set world coordinates
\mansyn
    void setworld(x1, y1, x2, y2)

    float *x1, *y1, *x2, *y2;
\mandscr
    The \itwd setworld function changes the current world coordinate
    system. The world coordinates of the lower left corner of
    the viewport become \itpnt (x1, y1), and the world
    coordinates of the upper right corner of the viewport
    become \itpnt (x2, y2).
\mansee
    coordinates(2), setviewport(2).
\manpend

\manpage setxor(2)

\manname
    setxor --- turn xor mode on or off
\mansyn
    void setxor(flag)

    int *flag;
\mandscr
    The \itwd setxor function turns xor mode on if \itwd~*flag
    is nonzero, or off if \itwd~*flag is zero. When xor mode is
    off, drawn objects are simply written over existing data in
    the drawing buffer. But if xor mode is on, drawn objects
    are logically xor'ed with the existing data. Thus if an object
    is drawn twice in a row in exactly the same position with xor
    mode on, it will be completely erased after the second drawing
    and the image on the
    screen restored to its state previous to the first drawing.
    This makes xor mode useful for animation and other effects.
    Functions which support xor mode are {\it g_box, g_circle,
    g_ellipse, g_line, g_point, box, cir, lnabs,} and \itnc lnrel .
\manpend