# LIBDM's Application Programming Interface

struct dm * DM_OPEN ( int dtype, int argc, char *argv[] )
  DM_OPEN creates a display manager of type dtype and returns a pointer to its dm structure. argc and argv are passed to dm_processOptions for interpretation. DM_NULL is returned if unable to acquire a display manager.
  Example:

            int dtype;
            int argc;
            char *argv[];
            struct dm *dmp;

            /*
             * Open a 512x512 X display manager window on the local
             * display using my_default_bindings to set default key
             * and mouse button bindings.
             */
            dtype = DM_TYPE_X;
            argv[0] = "X_open";
            argv[1] = "-i";
            argv[2] = "my_default_bindings";
            argv[3] = "-S";
            argv[4] = "512";
            argv[5] = "-d";
            argv[6] = ":0";
            argv[7] = (char *)NULL;
            dmp = DM_OPEN(dtype, argc, argv);

int DM_CLOSE ( struct dm *dmp )
  DM_CLOSE closes the display manager indicated by dmp.
  Example:

            /* open a display manager */
            dmp = DM_OPEN(dtype, argc, argv);

                      .  .  .

            /* close the display manager */
            DM_CLOSE(dmp);

int DM_DRAW_BEGIN ( struct dm *dmp )
  DM_DRAW_BEGIN prepares the display manager indicated by dmp for a round of drawing.
  Example:

            /* begin another drawing sequence */
            (void)DM_DRAW_BEGIN(dmp);

int DM_DRAW_END ( struct dm *dmp )
  DM_DRAW_END ends the drawing sequence for the display manager indicated by dmp. This should be called before the next call to DM_DRAW_BEGIN in order to see the results of the current drawing sequence.
  Example:

            /* end the current drawing sequence */
            (void)DM_DRAW_END(dmp);

int DM_NORMAL ( struct dm *dmp )
  DM_NORMAL restores the display manager indicated by dmp to a normal mode of operation (i.e. not scaled, rotated, displaced, etc.).
  Example:

            /* restore to normal mode */
            (void)DM_NORMAL(dmp);

int DM_LOADMATRIX ( struct dm *dmp, mat_t mat, int which_eye )
  DM_LOADMATRIX loads the display manager indicated by dmp with a new transformation matrix. mat indicates the matrix to be loaded. which_eye denotes the eye the matrix applies to and can have a value of 0 to indicate non-stereo, a value of 1 to indicate the right eye, or a value of 2 to indicate the left eye.
  Example:

            /* load the display manager with mat --- not using stereo */
            (void)DM_LOADMATRIX(dmp, mat, 0);

int DM_DRAW_STRING_2D ( struct dm *dmp, char *str, int x, int y, int size, int use_aspect )
  DM_DRAW_STRING_2D draws a string in the display manager window indicated by dmp. str is a pointer to the string to be drawn. x and y indicate where to begin drawing the string and are expected to be in the range [-2048,2047]. The size argument indicates the font size to use (currently used only by dm-ps). The expected values for size are 0 for small, 1 for medium, 2 for large, and 3 for huge. use_aspect indicates whether to use the aspect ratio to modify the starting point where the string will be drawn.
  Example:

            /*
             * - draw the string starting at the lower left corner
             * - use the small font
             * - don't use aspect ratio to modify string placement
             */
            (void)DM_DRAW_STRING_2D(dmp, "starting string at lower left", -2040, -2040, 0, 0)

int DM_DRAW_LINE_2D ( struct dm *dmp, int x1, int y1, int x2, int y2 )
  DM_DRAW_LINE_2D is used to draw two-dimensional lines in the display manager window indicated by dmp. x1, y1, x2, and y2 indicate the coordinates for the line to be drawn.
  Example:

            /* draw a line from the lower left corner of the window to the upper right corner */
            (void)DM_DRAW_LINE_2D(dmp, -2048, -2048, 2047, 2047);

int DM_DRAW_POINT_2D ( struct dm *dmp, int x, int y )
  DM_DRAW_POINT_2D draws a point in the display manager window indicated by dmp. x and y indicate the coordinates for the point to be drawn.
  Example:

            /* draw a yellow dot in the center of the window */
            (void)DM_SET_FGCOLOR(dmp, 230, 230, 0, 1);
            (void)DM_DRAW_POINT_2D(dmp, 0, 0);

int DM_DRAW_VLIST ( struct dm *dmp, struct rt_vlist *vp )
  DM_DRAW_VLIST takes the vlist pointer vp and interprets it for drawing into the display manager window indicated by dmp.
  Example:

            /* draw the vlists pointed to by view_list_ptr */
            (void)DM_DRAW_VLIST(dmp, view_list_ptr);

int DM_SET_FGCOLOR ( struct dm *dmp, short r, short g, short b, int strict )
  DM_SET_FGCOLOR sets the color for drawing in the display manager indicated by dmp. r, g, and b denote the color and have values in the range [0,255]. Strict specifies to really use this color (i.e. don't allow ogl to do fancy things with the color when depth cueing).
  Example:

            /* set the drawing color to red */
            (void)DM_SET_FGCOLOR(dmp, 220, 0, 0, 1);

int DM_SET_BGCOLOR ( struct dm *dmp, short r, short g, short b )
  DM_SET_BGCOLOR sets the background color for the display manager indicated by dmp. r, g, and b denote the color and have values in the range [0,255].
  Example:

            /* set the background color to red */
            (void)DM_SET_BGCOLOR(dmp, 220, 0, 0);

int DM_GET_BGCOLOR ( struct dm *dmp, Tcl_Interp *interp )
  DM_SET_BGCOLOR gets the background color for the display manager indicated by dmp and places the result in interp.
  Example:

            /* get the background color */
            return DM_GET_BGCOLOR(dmp, interp);

int DM_SET_LINE_ATTR ( struct dm *dmp, int width, int style )
  DM_SET_LINE_ATTR sets the display managers (i.e. dmp) line width to width and sets its line style to style. Currently, there are only 2 valid values for style: 0 for solid lines and 1 for dashed lines.
  Example:

            /* set the display manager up to draw fat dashed lines */
            (void)DM_SET_LINE_ATTR(dmp, 10, 1);

int DM_SET_WIN_BOUNDS ( struct dm *dmp, int clip[6] )
  DM_SET_WIN_BOUNDS sets the view clipping planes for the display manager indicated by dmp. clip is interpreted as follows: {XMIN, XMAX, YMIN, YMAX, ZMIN, ZMAX}
  Example:

            int clip[6] = { -2048, 2047, -2048, 2047, -2048, 2047 };

            /* set the display managers clipping planes */
            (void)DM_SET_WIN_BOUNDS(dmp, clip);

int DM_DEBUG ( struct dm *dmp, int lvl )
  DM_DEBUG sets the debug level to lvl. Currently, only two levels are recognized. lvl = 0 for debugging off and lvl > 0 for debugging on.
  Example:

            /* turn on debugging */
            (void)DM_DEBUG(dmp, 1);

int DM_BEGINDLIST ( struct dm *dmp, unsigned int list )
  DM_BEGINDLIST starts a display list definition for the display list list in the display manager indicated by dmp. The definition continues to build until a call to DM_ENDDLIST is made. Currently, only the ogl display manager supports display lists.
  Example:

            /* begin the definition of display list 1 */
            (void)DM_BEGINDLIST(dmp, 1);

int DM_ENDDLIST ( struct dm *dmp )
  DM_ENDDLIST ends the definition of the display list currently being defined for the display manager indicated by dmp.
  Example:

            /* define display list 1 to draw objects */
            (void)DM_BEGINDLIST(dmp, 1);

            /* Put code to draw objects here */

            (void)DM_ENDDLIST(dmp);

int DM_DRAWDLIST ( struct dm *dmp, unsigned int list )
  DM_DRAWDLIST draws the previously defined display list list in the display manager indicated by dmp.
  Example:

            unsigned int i;

            /* draw display lists 1 through 9 */
            for (i = 1; i < 10; ++i)
               (void)DM_DRAWDLIST(dmp, i);

int DM_FREEDLISTS ( struct dm *dmp, unsigned int list, int range )
  DM_FREEDLISTS frees the display lists indicated by list and range. list indicates the display list to start with and range indicates the number of display lists to be freed.
  Example:

            /* free display lists 10 through 29 */
            (void)DM_FREEDLISTS(dmp, 10, 20);

## LIBDM's Other Support Routines

int dm_share_list ( struct dm *dmp1, struct dm *dmp2 )
  dm_share_dlist provides a way to (un)share display lists. If dmp1 and dmp2 are not NULL, dmp1 will share its display lists with dmp2. If dmp2 is NULL, dmp1 will no longer share its display lists.

void dm_fogHint ( struct dm *dmp, int fastfog )
  dm_fogHint is used to give a hint to the display manager about whether to use an efficient fog calculation method or the most accurate. Note - this is currently only implemented by the ogl display manager.
  Example:

            /* use the most efficient method for calculating fog */
            dm_fogHint(dmp, 1);

            /* use the most accurate method for calculating fog */
            dm_fogHint(dmp, 0);

int dm_limit ( val )
  dm_limit takes an integer argument and returns zero if (-NOISE <= val <= NOISE ) where NOISE is the size of the dead spot around zero. If ( val < -NOISE ), the return value is ( val + NOISE ). If ( NOISE < val ), the return value is ( val - NOISE ).
  Examples:

            /* The examples below assume that NOISE is 16 */

            /* i = 0 */
            i = dm_limit(16);

            /* i = 1 */
            i = dm_limit(17);

            /* i = 0 */
            i = dm_limit(-16);

            /* i = -1 */
            i = dm_limit(-17);

int dm_unlimit ( val )
  dm_unlimit takes an integer value and returns zero if ( val == 0 ). If ( 0 < val ), the return value is ( NOISE + val ). If ( val < 0 ), the return value is ( -NOISE + val ). In short, dm_unlimit puts NOISE back into val.
  Examples:

            /* i = 0 */
            i = dm_unlimit(0);

            /* i = 17 */
            i = dm_unlimit(1);

            /* i = -17 */
            i = dm_unlimit(-1);

fastf_t dm_wrap ( val )
  dm_wrap wraps val into the range [-1.0, 1.0].
  Examples:

            /* f = 0.9 */
            f = dm_wrap(0.9);

            /* f = -0.5 */
            f = dm_wrap(1.5);

            /* f = 0.0 */
            f = dm_wrap(6.0);

            /* f = 1.0 */
            f = dm_wrap(7.0);

            /* f = 0.5 */
            f = dm_wrap(-1.5);

            /* f = -1.0 */
            f = dm_wrap(-5.0);

int dm_processOptions(struct dm *dmp, struct bu_vls *vls, int argc, char *argv[])
  dm_processOptions is used primarily by LIBDM's display manager open routines to process options. The table below lists the available options. Note - the application would not typically call processOptions. The application would instead build the desired options into the argv list that is supplied to the call to DM_OPEN.

  Options | Description
  --- | ---
  -d string | This option specifies where to draw the display manager. string is expected to be in the same form as the X DISPLAY environment variable.
  -i init_script | This option specifies a Tcl script to use to initialize the display manager.
  -N height | This option specifies the number of scanlines or height to make the display manager window.
  -n name | This option specifies a name to use for the display manager.
  -S size | This option specifies the display manager windows square size.
  -s | This option turns on stereo mode and is currently only available with the ogl display manager.
  -t 0|1 | This option specifies whether the display manager window will be a top level window or an embedded window. A non-zero value indicates a top level window, while zero indicates an embedded window.
  -W width | This option specifies the width in pixels of the display manager window.

void dm_configureWindowShape ( dmp )
  dm_configureWindowShape is used to update the internal state of a display manager after its window has been newly created or resized. This routine is typically called by an event handler.

void dm_zbuffer ( struct dm *dmp, zbuffer_on )
  dm_zbuffer is used to turn Z-buffering on/off. Note - zbuffering is only supported by the ogl display manager.
  Examples:

            /* turn zbuffering on */
            dm_zbuffer(dmp, 1);

void dm_lighting ( struct dm *dmp, int lighting_on )
  dm_lighting is used to turn lighting on/off. Note - lighting is only supported by the ogl display manager.
  Examples:

            /* turn lighting on */
            dm_lighting(dmp, 1);

fastf_t dm_Xx2Normal ( struct dm *dmp, int x )
  dm_Xx2Normal takes x in X screen coordinates and returns a value in the range [-1.0, 1.0]. dmp indicates the display manager of interest.

fastf_t dm_Xy2Normal ( struct dm *dmp, int y, int use_aspect )
  dm_Xy2Normal takes y in X screen coordinates and returns a value in the range [-1.0, 1.0]. dmp indicates the display manager of interest. use_aspect specifies whether to use the window's aspect ratio in the calculation.

int dm_Normal2Xx ( struct dm *dmp, fastf_t x )
  dm_Normal2Xx takes x in normalized coordinates and returns a value in X screen coordinates. dmp indicates the display manager of interest.

int dm_Normal2Xy ( struct dm *dmp, fastf_t y )
  dm_Normal2Xy takes y in normalized coordinates and returns a value in X screen coordinates. dmp indicates the display manager of interest.

int Dm_Init ( Tcl_Interp *interp )
  Dm_Init initializes LIBDM's tcl commands. interp indicates the Tcl interpreter.