Structural Informatics Group (SIG) logo
Home | Projects | Demos | Downloads | Publications | Local Info | About Us | New site
Go to the first, previous, next, last section, table of contents.

:DRAW

source files: [xc]cmr.[ch]

SYNTAX

(SEND <cmr> :DRAW
  [ :<keyword>     <parameter>       ]  ...
  [ :THINGS        <thinglist> )     ]

DESCRIPTION

This is it, the message that makes everything happen.

If the :THINGS <thinglist> prop-value pair is not present, then the thinglist must be present as an :THINGS property on the <cmr> itself or, failing that, on the MATRIX44 instance associated with the <cmr>. Note that all other prop-val pairs for this call may be specified within the <thinglist> if desired, allowing the call to reduce to a simple (send cmr :draw), and placing all the options in explicit datastructures instead of in the code. This is often a good idea in practice, although putting the options in the call may make for simpler tutorial code.

Any number of <keyword> <parameter> pairs may be supplied; The allowable values for these pairs are exactly those legal inside an <thinglist>, and the effect is exactly the same as inserting that <keyword> <parameter> pair everywhere through the <thinglist> (unless the <keyword> is already present in some things in the <thinglist>, in which case the <keyword> <parameter> pair has no effect on those things). Essentially, these 'global' <keyword> <parameter> pairs are just a convenience, allowing global defaults to be listed once here instead of explicitly in every thing in the <thinglist>.

The :DRAW command renders all of the 'things' in the thing list, in sequence. Each 'thing' is a list with the syntax

( [ :PICK-AS  { :SOLID | :BACKGROUND | :FOREGROUND  | :INVISIBLE } ]
  [ :USE-NORMALS { T | :ON-POINTS | :ON-FACETS  | NIL } ]
  [ :USE-COLORS  { T | :ON-POINTS | :ON-FACETS  | NIL } ]
  [ :REDRAW NIL ]
  [ :WHICH-BITPLANES { :RGB-BITPLANES
                     | :OVERLAY-BITPLANES
                     | :OVERLAY-BITPLANES-ERASE
                     | :CURSOR-BITPLANES
                     | :CURSOR-BITPLANES-ERASE
                     | :POPUP-BITPLANES
                     | :POPUP-BITPLANES-ERASE } ]
  [ :POINT-IF       <point-relation-name> ]
  [ :FACET-IF       <facet-relation-name> ]
  [ :POINT-RELATION <point-relation> ]
  [ :FACET-RELATION <facet-relation> ]
  [ :PIXEL-RELATION <pixel-relation> ]
  [ :TRANSFORM <modelling-matrix> ]
  [ :FIX-LIGHTS-ON-OBJECT t ]
  [ :LIGHTS <lightlist> ]
  [ :LIGHTING-MODEL <lighting-model> ]
  [ :MATERIAL <material> ]
  [ :TEXTURE <texture> ]
  [ :DROP-BACKFACES t]
  [ :DOWNCLICK-HOOK <hook-fn(s)>                  ]
  [ :DRAG-HOOK      <hook-fn(s)>                  ]
  [ :UPCLICK-HOOK   <hook-fn(s)>                  ]
  [ :SELECT-HOOK    <hook-fn(s)>                  ]
  [ :DESELECT-HOOK  <hook-fn(s)>                  ]
  [ :RESELECT-HOOK  <hook-fn(s)>                  ]
  [ :<anykeyword>   <anyvalue>                    ]
)

Any of the above keyword-value pairs may also appear within the thinglist (as opposed to the things proper), in which case it specifies a default value to apply to all succeeding things. For example,

(list :LIGHTS light-list
  (list   :POINT-RELATION points-0   :FACET-RELATION facets-0)
  (list   :POINT-RELATION points-1   :FACET-RELATION facets-1))

is equivalent to

(list 
  (list :LIGHTS light-list  :POINT-RELATION points-0   :FACET-RELATION facets-0)
  (list :LIGHTS light-list  :POINT-RELATION points-1   :FACET-RELATION facets-1))

Each 'thing' is a disembodied propertylist, interpreted as a sequence of property-value pairs: order of components in the list is not significant, and unknown property names will be silently skipped (along with the corresponding value) -- this lets the user add application-dependent information to the thinglist.

(Note that commonlisp isn't very fond of disembodied propertylists, so xthl.[ch] exports the functions XG.3D-GET, XG.3D-SET, XG.3D-REM, XG.3D-LENGTH and XG.3D-NTH to facilitate working with them.)

Any of the above components can actually be replaced by a symbol with the given component as its value -- this lets them be changed by SETQing a symbol instead of splicing the thinglist, but it can also be used to substituting materials or whatever in similar fashion.

If :PICK-AS is provided, it controls the way picking (as implemented by the :RUN-WIDGETS message) treats the thing. The default value :SOLID treats the thing normally, while :INVISIBLE treats the thing as totally non-existent for picking purposes (the thing will not even obscure other things). The :FOREGROUND and :BACKGROUND options completely ignore the geometry of the thing (if any!). A :PICK-AS :FOREGROUND will result in the thing being picked whenever the mouse is in the viewport -- it effectively blocks out the viewport completely. A :PICK-AS :BACKGROUND will result in the thing being picked whenever no other thing is picked by the mouse. Thus, by making a dummy thinglist entry like

(list   :PICK-AS :FOREGROUND   :DOWNCLICK-HOOK (lambda nil ...))

you can hook downclicks anywhere in the viewport.

If :USE-NORMALS is provided, it alters the way Skandha4 selects the lighting calculation:

t
This is the default. Skandha uses point normals if present (and point colors too, if present) resulting in Gouraud shading, else facet normals if present (and facet colors too, if present) resulting in flat shading, else lighting is ignored: Facet colors are used if present, else point colors, else the default material color.
:on-points
Same as first except that facet normals will never be used.
:on-facets
Same as first except that point normals will never be used.
nil
Same as first except all normals ignored, hence no lighting model used.

If :USE-COLORS is provided, it alters the way Skandha4 selects the color source in a manner very similar to the above:

t
This is the default, as described above.
:on-points
Same except that facet colors will never be used.
:on-facets
Same except that point colors will never be used.
nil
Same as first except both facet and point colors are ignored.

If :REDRAW NIL is specified, the camera will not automatically be redrawn in single buffer mode when a widget is selected (as it is by default).

The :WHICH-BITPLANES parameter defaults to :RGB-BITPLANES; if it is set to :OVERLAY-BITPLANES, then drawing will be done in the overlay bitplanes if they are available and if the driver and hardware support such. You should not expect anything but monochrome drawing in an unspecified color when drawing into the overlay bitplanes; they are intended for rubberbanding lines over an expensive-to-redraw image and such. If overlay planes are not available, the driver may try XOR-draws, and implement :CLEAR-OVERLAY-BITPLANES by simply redoing the same (internally buffered) XOR-draws, or on some machines it may have to simply do destructive 2-D draws into the main image buffer. Because of the latter possibility, it is a good idea to redraw the underlying image at the end of a rubberbanding operation, if practical.

Setting :WHICH-BITPLANES to :OVERLAY-BITPLANES-ERASE results in any drawing done clearing those pixels to transparent: Erasing a line or two this way can be much faster than clearing the entire overlay bitplane.

Setting :WHICH-BITPLANES parameter to :CURSOR-BITPLANES or :CURSOR-BITPLANES-ERASE is similar, but on some machines gives access to a separate overlay bitplane, normally used for the cursor.

Setting :WHICH-BITPLANES parameter to :POPUP-BITPLANES or :POPUP-BITPLANES-ERASE is similar, but on some machines gives access to a separate overlay bitplane, normally used for the popup menus.

If :DROP-BACKFACES is given a non-NIL value, faces facing away from the camera will not be drawn (on machines supporting this).

If :FIX-LIGHTS-ON-OBJECT is given a non-NIL value, lighting computations are done in the coordinate system of the object rather than that of the camera.

If :LIGHTS is supplied, it must be a list of LIGHT objects. If it is not supplied, a single default light will be used. The SGI library currently supports at most 8 lights in a scene.

If :LIGHTING-MODEL is supplied, it must be an instance of class LIGHTING-MODEL. If it is not supplied, a default model will be used.

If :MATERIAL is supplied, it must be an instance of class MATERIAL. If it is not supplied, a default material will be used.

Supplying a NIL value for :LIGHTS, :LIGHTING-MODEL, or :MATERIAL is exactly equivalent to supplying no value.

The <modelling-matrix>, if present, is an instance of MATRIX44, and will be used to transform (position and orient) the thing before display.

The <pixel-relation>, if present, will normally be the only thing present: This is a special hack for copying a pixel image to the screen. The <pixel-relation> will contain at least one of :PIXEL-RED, :PIXEL-GREEN or :PIXEL-BLUE, which must be CLASS-8-BIT-FLOAT-ARRAY. All three should be present for a color image; for a grayscale image, it is sufficient to provide any one of the three -- the missing colorplanes will be given the same intensities as the given one. The <pixel-relation> (and thus :PIXEL-RED / :PIXEL-GREEN / :PIXEL-BLUE) should be two-dimensional, of course, and will be drawn in the lower-left corner of the camera viewport, clipped to the viewport if need be. (It is permissible to provide :PIXEL-RELATION in addition to the usual complement of 3-D values; In this case, the :PIXEL-RELATION will be drawn first -- this is a useful way of providing a background.) The XTIF-LOAD-TIFF-FILE function is the usual way of reading an image in.

The <point-relation> is a graphics relation containing at a minimum :POINT-X, :POINT-Y and :POINT-Z float arrays specifying the x,y,z coordinates of the vertices of the thing to be displayed.

The <point-relation> may optionally include the following arrays:

:POINT-NORMAL-X :POINT-NORMAL-Y :POINT-NORMAL-Z
These three float arrays hold the x,y,z coordinates of the surface normals for the points. These normals should be of unit length. The lighting model will be applied to these normals to produce the color for each point.
:POINT-RED :POINT-GREEN :POINT-BLUE
These 8-bit-float arrays hold the r,g,b components specifying the color for each vertex. The components should be in the range from 0 to 1.
:POINT-IF
If no <facet-relation> is present, the POINT-IF bitvector may be used to select which points to draw. Points will be drawn iff the corresponding bit is one.

If a :POINT-IF <point-relation-name> option was supplied, then <point-relation-name> may be used in place of :POINT-IF as the name of the bitvector controlling drawing. (See :FACET-IF comments, below.)

It is legal and meaningful to provide both point colors and point normals.

The <facet-relation> need not be present, but usually is. If it is missing, the pointset will be drawn as a pointcloud.

The <facet-relation> serves mainly to specify a set of line segments, triangles, or quadralaterals to be drawn. These are stored in the int32 arrays :FACET-0, :FACET-1, :FACET-2, :FACET-3.

If only :FACET-0 and :FACET-1 are present, then line segments will be drawn. Each pair of matching values (i j) from these arrays will be interpreted as indices into the <point-relation>, and a line segment from POINT[i] to POINT[j] will be drawn.

If :FACET-2 is also present, then each triple of matching values (i j k) from the three FACET arrays will be interpreted as specifying a triangle POINT[i], POINT[j], POINT[k], which will be drawn.

If :FACET-3 is also present, then each quadruple of matching values (i j k l) the from four FACET arrays will be interpreted as specifying a quadrilateral POINT[i] POINT[j] POINT[k] POINT[l] to draw.

Optional arrays which may be included in <facet-relation> are:

:FACET-NORMAL-X :FACET-NORMAL-Y :FACET-NORMAL-Z
These three float arrays hold the x,y,z coordinates of the surface normals for the facets. These normals should be of unit length. The lighting model will be applied to these normals to produce the color for each facet.
:FACET-RED :FACET-GREEN :FACET-BLUE
These three 8-bit-float arrays hold the r,g,b components specifying the color for each facet. The components should be in the range from 0 to 1. NOTE: Some time soon, these will be changed from float to unsigned-byte arrays.
:FACET-IF
This bit array controls drawing on a facet-by-facet basis. Each facet will be drawn iff the corresponding bit is 1.

If a :FACET-IF <facet-relation-name> option was supplied, then <facet-relation-name> may be used in place of :FACET-IF as the name of the bitvector controlling drawing. Thus, a convenient way of drawing various subsets of a given set polygons is to establish facet-grl bitvectors named, say, :RED-FACETS, :BLU-FACETS ... and then doing

(send xcmr :DRAW
  :THINGS (list
    (list
      :FACET-IF       :RED-FACETS
      :MATERIAL       red-material
      :FACET-RELATION facet-grl
      :POINT-RELATION point-grl)
    (list
      :FACET-IF       :BLU-FACETS
      :MATERIAL       blu-material
      :FACET-RELATION facet-grl
      :POINT-RELATION point-grl)
    ...))

The preceding example shows one (good) way to highlight some subset of facets by drawing them using different materials. This is cheaper than assigning a color to every facet. Note that the same facet-grl and point-grl are used in each thinglist, only the :FACET-IF and :MATERIAL values differ.

It is legal and meaningful to provide both facet colors and facet normals. In fact, it is legal to provide any combination of facet and vertex colors and normals. :DRAW will ignore any information which it is unable to use. In general, it will use as much information as possible, favoring smooth (Gauroud) shading over facet shading.

It is legal and normal to have additional arrays beyond the above in the <point-relation> and <facet-relation>. These will be ignored by the :DRAW command, but may hold information useful to the application program.

Note that the shading model need not be explicitly selected: The shading model used will be selected based on the data provided. If vertex colors or normals are provided, then Gouraud shading will be used. If facet colors or normals are provided, then flat shading will be used. If none of the above are provided, then the thing will be drawn in the :DIFFUSE-COLOR for the specified (else default) material.

It is possible to explicitly select the shading model if desired: See the :DRAW-AS property on Materials. If one wants to flip back and forth frequently between different rendering styles, setting this property is more convenient than altering the graphic relations.

If the facet relation has a fill-pointer, only facets below the pointer will be drawn. (Similarly, if only a point relation is supplied, and the point relation has a fill-pointer, only points below the fill-pointer will be drawn.)

The :DOWNCLICK-HOOK, :DRAG-HOOK, :UPCLICK-HOOK and :[DE|RE]SELECT-HOOK keywords are currently no-ops in the :DRAW command, included only to emphasize that the same thinglist can be used for both the :DRAW and :RUN-WIDGETS messages. If these two messages turn out to always be used together in practice, they may be combined into a single call at some point.

The <anykeyword> <anyvalue> entry is included to emphasize that the application programmer is free to add arbitrary new property-value pairs to thinglists for purely application purposes.


Go to the first, previous, next, last section, table of contents.