DYNAVIEW.DOC MATROX GRAPHICS INC. April 1, 1996 Dynaview Advanced Features This file describes the advanced features of the MATROX MGA DynaView AutoCAD driver for DOS. The following topics are covered : 1. Customizing the AutoCAD MNU file 2. Making DynaView menus externally 3. DEF_MENU 4. DEF_BUTTON 5. Decompiling a menu 6. Customizing DynaView pop-up menus 7. Using multiple configurations 8. Customizing the color palette (256 color modes only) 9. Blackvec utility 10. Matrox AutoLISP Commands 1. Customizing the AutoCAD MNU file =================================== Adding to a Side-bar or Pull-down menu Matrox DynaView commands are primarily accessible from the keyboard and through the DynaView menus. These commands can also be made available from the AutoCAD side menu or pull-down menus. If you wish to add the DynaView commands to your AutoCAD menus, you can use the acad.mnu and matrox.mnu files which are copied to the driver directory during installation. First time customization If you are using AutoCAD Release 12 or 13, and have never customized your AutoCAD menu file before, you can simply copy the proper Matrox acad??.mnu file to your AutoCAD directory. This special .mnu files contain pull-down and side-bar menus for DynaView/2D and 3D. Note: This menu file assumes that the DynaView/3D ADS application is located in the default directory (\MGA\ACADRV). If you installed to a different directory, edit the acad.mnu file, search for MGA (there are four occurrences) and correct the path statement to point to your installation directory. Already customized If you have previously customized your AutoCAD menu, or are using AutoCAD Release 11, you can use the add-on.mnu file, which contains statements to make pull-down and side bar menus for the DynaView commands. In this case, you would copy the lines for the menu you want, into your acad.mnu file. We assume in this case that you are familiar with the AutoCAD menu file structure. If not, refer to your AutoCAD documentation. Note: If you change the command string called by the DynaView commands in the configuration facility, you must also update your acad.mnu file to reflect these changes. Otherwise, the pull-down and side bar menus will not work for those commands you have changed. 2. Making DynaView menus externally =================================== MENU_CMP compiler DynaView menus created externally are a little more complicated to make, but you have more flexibility in the layout, compared to when you use the MCREATE command. To make an external menu, you need a text editor and the menu_cmp menu compiler. The menu description file must have the .def extension, from which menu_cmp will create an associated .bin file, identical to the .bin files you can create within AutoCAD with MCREATE. Once a .bin file is created, the menu can be loaded while you are running AutoCAD. If you use the NO_LOCK switch (discussed below), the menu buttons can be edited with the Shift+Click feature. A menu description file contains two statement types: - One DEF_MENU statement, which specifies the total menu size, the initial position switch, and the string to display in the title bar. - Many DEF_BUTTON statements, which provide the necessary information for each button contained in the menu: button position and size, command string to call, text label to display, slide to display,switch to select text label or slide. 3. DEF_MENU =========== The syntax of the DEF_MENU statement is: DEF_MENU(x_size, y_size, CURSOR_POS or DEFAULT_POS, "title", LOCK or No_LOCK) Parameters x_size, y_size The x_size and y_size are in character units. Don't forget that characters are typically twice as high as they are wide, so to get a square menu, you must make the x_size equal to twice the y_size. CURSOR_POS or DEFAULT_POS The CURSOR_POS switch indicates that the menu should be presented at the cursor position. The DEFAULT_POS switch indicates that the menu should be presented at the same position as last time. The very first time a menu is called, DEFAULT_POS is the same as the cursor position, but on subsequent requests it will be at the last position you left the menu. Either CURSOR_POS or DEFAULT_POS must be specified. title The title must fit in the title bar, otherwise it will be clipped. Remember that the title bar also contains two icons (one to pin the window, and one to put it in the background), that use the equivalent of four characters. LOCK When the LOCK switch is used, the menu cannot be edited inside AutoCAD with the Shift+click method. The default switch is NO_LOCK. 4. DEF_BUTTON ============= The syntax of the DEF_BUTTON statement is: DEF_BUTTON(x_pos, y_pos, x_size, y_size, "command_string", "text_label", "slide_name" or "slide_lib(slide_name)", DISPLAY_TEXT or DISPLAY_ICON) Parameters position and size The position and size parameters are in character units, but you can use fraction values. It is however recommended to limit yourself to using .5 and .25, otherwise rounding could result in menus that are not very attractive. command string The command string can be up to 80 characters and it supports the special characters (`;', `^C', `^O', etc.). text_label The text label should be no longer than the button's x_size, otherwise it will be clipped. To be aesthetic, the text label should be one character shorter than the button width, otherwise the string will overwrite the button shadows. If the text label is smaller than the button width, it will be centered. The text label can be an empty string (` '). In this case, nothing will be displayed in the button, but the button will still be functional. Note that it is not possible to have a two-line text label. If you absolutely need this, use a slide. Slide_name The slide can either be a separate slide file or a slide taken from a slide library. In both cases, do not include the file name extension. The slide name can be an empty string (''). In this case, nothing will be displayed in the button, but the button will still be functional. DISPLAY_TEXT or DISPLAY_ICON The DISPLAY_TEXT switch indicates that the provided text label should be displayed. The DISPLAY_ICON indicates that the provided slide icon should be displayed. Either DISPLAY_TEST or DISPLAY_ ICON must be specified. Comments Aside from the two statements described above, blank lines and comments can be put in the .def file. Comments must start with \* and terminate with *\<|>. They may span more than one line. Example DEF_MENU( 15,14,DEFAULT_POS,"Draw Menu" ) DEF_BUTTON(1.0,1.0,6,3,"^C^CLINE","line","matrox(line)",DISPLAY_ICON) DEF_BUTTON(7.5,1.0,6,3,"^C^CPLINE","pline","matrox(pline)",DISPLAY_ICON) DEF_BUTTON(1.0,4.0,6,3,"^C^CARC","arc","matrox(arc)",DISPLAY_ICON) DEF_BUTTON(7.5,4.0,6,3,"^C^CCIRCLE","cir","matrox(circle)",DISPLAY_ICON) DEF_BUTTON(1.0,7.0,6,3,"^C^CELLIPSE","ellip","matrox(ellipse)",DISPLAY_ICON) DEF_BUTTON(7.5,7.0,6,3,"^C^CPOLYGON","polyg","matrox(polygon)",DISPLAY_ICON) DEF_BUTTON(1.0,10.0,6,3,"^C^CPOINT","point","matrox(point)",DISPLAY_ICON) DEF_BUTTON(7.5,10.0,6,3,"^C^CDONUT","donut","matrox(donut)",DISPLAY_ICON) 5. Decompiling a menu ===================== Converting a .bin file to a .def file The MENU_CMP utility features a -d switch, which lets you decompile a .bin file into a .def file. This feature is useful to get an ASCII copy of: - a menu created inside AutoCAD with MCREATE. - an external menu that you have modified with the Shift+Click feature. When decompiling it is possible to specify a different file name for the .def file. This is useful to avoid over writing an existing .def file of the same name. Example: menu_cmp -d mymenu mymenu2 The above command line decompiles mymenu.bin into mymenu2.def. 6. Customizing DynaView pop-up menus ==================================== As stated earlier in this manual, the DynaView pop-up menus are regular DynaView menus. Since we include the .def files (mpopup.def and mpop3d.def) you can edit the menus inside AutoCAD (with Shift+Click), or you can also modify the menu layouts and recompile them. The preceding sections give you all the details. Note: The mpopup.def file uses the default DynaView command names. If you have changed any of these command names within the configuration facility, you must update the mpopup.def file accordingly, and recompile the menu. 7. Using multiple configurations ================================ Place acadrv.cfg in different directories It is possible to set up the DynaView driver so that multiple configurations can be available. Determining the configuration The driver uses the acadrv.cfg file to determine its configuration. When AutoCAD is started, the driver looks first for the acadrv.cfg file in your current directory, then in the directory specified by the ACADRV environment variable. The acadrv.cfg file saves the status of items such as: - the resolution and font size - the MCONFIG flags (scroll bars, bird's eye mode, etc.) - the MBUTTON assignments - the window arrangement (position, size, pinned windows) - other parameters from the configuration program Using a different configuration Multiple configurations can be accomplished by making and copying different acadrv.cfg files into different directories, and then starting AutoCAD from one of those directories. You can also start up with different configurations by: - Making multiple configuration files with different names (in the same acadrv directory). - Have a batch file which copies the desired configuration file over acadrv.cfg before you start AutoCAD. 8. Customizing the color palette (256 color modes only) ======================================================= Custom color palettes are supported by this AutoCAD driver if they are described in a Matrox palette file. The palette file must be `activated', by using a special utility program. Palette File Creation A palette file is an ASCII file that you create with any text editor. The file extension must be .pal. In this file, each line contains one color definition, in the following format: index, red, green, blue. The file starts with a 16-color palette, followed by a 256-color palette. A sample palette file, standard.pal, is included with the distribution disk. It defines the standard 16 and 256 color palettes as stated by AutoCAD. To create a custom palette, you should make a copy of standard.pal to use as a starting point. Be careful not to change the file formatting, or to delete lines. Palette File Activation To activate your custom color palette, you must run the palname.exe utility program, which is included on the distribution diskette. This utility will update the Matrox configuration file, acadrv.cfg, with your new palette file name, and from then on your custom palette will be used. Your palette file must have the extension .pal. An example of a palette file is the file standard.pal which is shipped with the MGA AutoCAD driver. Example : palname standard.pal Note: Every time your reset the driver to the factory defaults (in the configuration facility), the driver will stop using the custom palette, and you must re-use palname to activate your custom palette. Color limitations Customizing the color palette is a powerful and potentially dangerous feature! Please note the following points when creating your palette: --- Color 0 is the background color. If you change it, check that no other colors in the palette are equal or very close to your new background color. Those colors would become barely visible, or even invisible. The normal practice is to set all colors that are close to the new background color, to black. (This is what the driver does when you select gray background in the configuration.) --- Colors 1 to 8 are used in the user interface. If you change one of them, it will affect not only your drawings but also the user interface. If, afterwards, you want to adjust the user interface colors through the configuration facility, the configuration will still call the colors by their original name (i.e. index no.2 will be called `yellow'). As a reference for you, see the table below which shows the values assigned for colors 1 to 8. Color Index Name r,g,b values -------------+-------------+------------------- 1 red 255,0,0 2 yellow 255,255,0 3 green 0,255,0 4 cyan 0,255,255 5 blue 0,0,255 6 magenta 255,0,255 7 white 255,255,255 8 gray 160,160,160 Animation limitations When you run in 8-bit mode with 256 colors, this has an impact on features that use animation. Due to these color limitations, the user interface colors could change during an animation command, for any menus that overlap a viewport in animation mode. Use these values To make your custom colors, and prevent the user interface colors from being affected, use only 0 and 255 as intensity values for the red, green, and blue components. Note that this limitation is not present when you are running in 16bpp and 24 bpp modes. 9. Blackvec utility =================== The automatic display list clean-up feature can be disabled through the blackvec utility. The command line syntax is shown below: blackvec off (to disable black vector cleanup) blackvec on (to enable black vector cleanup) Note: Every time you reset the driver to the factory defaults (in the configuration utility), the driver will reset black vector clean-up to ON. 10. Matrox AutoLISP Commands ============================ ======================================================================== MATRDINQ ======================================================================== Summary Inquire if a viewport is in rendering mode. Usage ( matrdinq [vport] ) Description If the vport argument is given, matrdinq returns a value for that viewport. If the vport argument is not given, matrdinq will check the current viewport to see if it is in rendering mode. Returns Value Meaning ----------+---------------------------- nil Viewport is not rendered. non-nil Viewport is rendered. ======================================================================== MATDISPLAY ======================================================================== Summary Change the display option used for rendering. Usage ( matdisplay vport mode ) Arguments vport Viewport to be affected mode Display option ("W", "H", "B", "F", or "G") to be used Description The matdisplay function changes the display option of a rendered viewport. The mode argument can be "W" (Wireframe),"H" (Hidden), "B" (Bordered),"F"(Flat), or "G"(Gouraud shaded) Returns Value Meaning -------+------------------------------------------------------ nil Indicates an error condition (not a rendered viewport, invalid argument, etc.). void No error condition. ======================================================================== MATVPOINT ======================================================================== Summary Change or request the viewing parameters of a rendered viewport. Usage To inquire: - ( matvpoint vport "?" ) To change: - ( matvpoint vport x ) Where x = mode (argument value) (arg. value) ...) Arguments Name Meaning -----------+-------------------------------- vport Viewport number mode "o": orthogonal "p": perspective [?] Display the viewing parameters. -------------------------------------+--------------------------------------- In Orthogonal view only: | In Perspective view only: -------------------------------------+--------------------------------------- ["c" 3dpoint] Set the view center | ["f" real] Set the focal length -------------------------------------+--------------------------------------- ["d" 3dpoint] Set viewing direction | ["ca" 3dpoint] Set camera location -------------------------------------+--------------------------------------- ["h" 3dpoint] Set the view height | ["ta" 3dpoint] Set target location -------------------------------------+--------------------------------------- | ["tw" real] Set the twist angle -------------------------------------+--------------------------------------- ======================================================================== MATDBLBUF ======================================================================== Summary Select double-buffering mode for a rendered viewport. Usage ( matdblbuf vport display_buf draw_buf ) Arguments vport Viewport number display_buf Display buffer draw_buf Drawing buffer Both display_buf and draw_buf can assume the following values: Value Configuration ---------+---------------------------- 0 Full frame buffer 1 Lower half of frame buffer 2 Upper half of frame buffer Description The matdblbuf function enables or disables double buffering. Returns void Important Points: If you cancel an AutoLISP program which uses double-buffering, make sure to reset the board to `Full frame buffer' as soon as possible, by typing: matdblbuf vport 0 0 If this is not done, many redraw type commands (REDRAW, MATVPOINT, MATDISPLAY) will not work. It will then be necessary to exit RD mode (MATEXIT, FLUSH, REGEN) and re-render the viewport. ======================================================================== MATLIGHT ======================================================================== Summary Change or request lighting parameters. Usage (matlight "?") to inquire current lighting (matlight "c" light1 light2 ...) to create lights (matlight "m" oldlight newlight) to modify a light (matlight "d" light1 light2 ...) to delete lights (matlight "u") to update drawing file lighting information Arguments Ambient light: -------------- (list "al" (list "ln" "light_name") (list "di" r g b)) Model Directional lights: ------------------------- (list "mdl" (list "ln" "light_name") (list "di" r g b) (list "sp" r g b) (list "po" x y z) (list "ap" x y z)) User Directional lights: ------------------------ (list "udl" (list "ln" "light_name") (list "di" r g b) (list "sp" r g b) (list "ha" angle) (list "ea" angle)) Positional lights: ------------------ (list "pl" (list "ln" "light_name") (list "di" r g b) (list "sp" r g b) (list "rl" residual) (list "rd" distance) (list "po" x y z) ) Spot lights: ------------ (list "sl" (list "ln" "light_name") (list "di" r g b) (list "sp" r g b) (list "rl" residual) (list "ca" angle) (list "cf" angle) (list "fd" string) (list "po" x y z) (list "ap" x y z)) Where: "ln" = light name string (up to 31 characters) "di" = diffusion color (0.0 <= r, g, b, <= 1.0) "sp" = specular color (0.0 <= r, g, b, <= 1.0) "po" = light position (in WCS Coordinate) "ap" = light aim point (in WCS Coordinates) "ha" = horizontal angle in degree (-180.0 <= angle <= 180.0) "ea" = elevation angle in degree (-90.0 <= angle <= 90.0) "rl" = residual light factor ( 0.0 <= factor <= 100.0 %) "rd" = residual light distance (in WCS Coordinates) "ca" = cone aperture angle in degrees (0.0 <= angle <= 160.0) "cf" = cone fall-off angle in degrees ( ca <= angle <= 160.0) "fd" = falloff distribution string ("linear", "square", or "cubic") Returns Value Meaning ---------+------------------------------------------------ non-nil No error nil Error (invalid argument type, invalid number of arguments, no light on layer, light name already exists, etc. list Current light list (with "?" only) Examples ; create Ambient light source and one Directional light source (matlight (list "c" (list "al" (list "ln" "am01") (list "di" 0.2 0.3 0.4)) (list "dl" (list "ln" "dir02") (list "di" 0.1 0.2 0.3) (list "po" 12.0 23.0 123.0) (list "ap" 22.0 33.0 143.0)))) ; delete Ambient light source (notice that the data for it must be provided) (matlight (list "d" (list "al" (list "ln" "light01") (list "di" 0.2 0.3 0.4)))) ; modify Ambient light source (matlight (list "m" (list "al" (list "ln" "am") (list "di" 0.2 0.3 0.4)) (list "al" (list "ln" "am2") (list "di" 0.3 0.4 0.6)))) Note: All r, g, b parameters are the red, green, and blue components of a light, and they must be within the range of 0.0 to 1.0. ======================================================================== MATMATERIAL ======================================================================== Summary Change or request material properties parameters. Usage (matmaterial "?" entityname) to inquire (matmaterial "r" entityname) to reset (matmaterial "c" entityname [argument_list]) to change Arguments ["am" r g b] Ambient color (0.0 <= r g, b, <= 1.0) ["di" r g b] Diffuse color (0.0 <= r, g, b, <= 1.0) ["em" r g b] Emission color (0.0 <= r, g, b, <= 1.0) ["sp" r g b] Specular color (0.0 <= r, g, b, <= 1.0) ["sc" coef ] Specular coefficient (0.0 <= coefficient <= 1.0) ["ma" "string"] Optional material name (31 char max) Returns Value Meaning ---------+----------------------------------------------- non-nil No error nil Error (invalid argument type, invalid number of arguments, no material on entity, etc.) list Current material data (with "?" only) Example (matmaterial "c" ename (list "di" 0.1 0.1 0.1) (list "am" 0.2 0.2 0.2) (list "ma" "plastic")) ======================================================================== MATCFG ======================================================================== Summary Change or request configuration parameters. Usage (matcfg "?") to inquire (matcfg [argument_list] ) to set Arguments ["l" "light_layer"] Light source layer ["r" method] Rendering method ("w" or "g") (now referred to as `Display Option' in the documentation) ["b" r g b] Background color ["a" min max] Min and max arc segmentation ["sp" "y" or "n"] Spline segmentation ["s" "y" or "n"] Automatic selection ["f" "y" or "n"] Full Gouraud flag ["n" level] Level for 3D face nesting ["t" angle] Threshold angle, in degrees ["m" "a" or "p" Default material, absolute or percentage, followed by one or all of the parameters below: ("am" r g b) ambient color (0.0 <= r, g, b, <= 1.0) ("di" r g b) diffuse color (0.0 <= r, g, b, <= 1.0) ("em" r g b) emission color (0.0 <= r, g, b, <= 1.0) ("sp" r g b) specular color (0.0 <= r, g, b, <= 1.0) ("sc" coef )] specular coefficient (0.0 <= coefficient <= 1.0) Returns Value Meaning ----------+------------------------------------------------ list Current parameters (with "?" only) non-nil No error nil Error (invalid argument type, invalid number of arguments, etc.) Examples ; set display option to Gouraud, and nesting level to 2 (matcfg (list (list "r" "g") (list "n" 2) ) ) ; set default material colors to Absolute, with no Ambient reflectivity (matcfg (list (list "m" "a" (list "am" 0.0 0.0 0.0 ) ) ) Note: All r,g,b parameters are the red, green, and blue components of a light, and they must be within the range of 0.0 to 1.0.