AutoCAD T Render API

Programmer’s Guide

Version 1.32

Copyright 1997 Autodesk, Inc.

All Rights Reserved

The publication, or parts thereof, may not be reproduced in any form, by any method, for any purpose.

AUTODESK, INC. MAKES NO WARRANTY, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, REGARDING THESE MATERIALS AND MAKES SUCH MATERIALS AVAILABLE SOLELY ON AN “AS-IS” BASIS.

IN NO EVENT SHALL AUTODESK, INC. BE LIABLE TO ANYONE FOR SPECIAL, COLLATERAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH OR ARISING OUT OF PURCHASE OR USE OF THESE MATERIALS. THE SOLE AND EXCLUSIVE LIABILITY TO AUTODESK, INC., REGARDLESS OF THE FORM OF ACTION, SHALL NOT EXCEED THE PURCHASE PRICE OF THE MATERIALS DESCRIBED HEREIN.

Autodesk, Inc. reserves the right to revise and improve its products as it sees fit. This publication describes the state of this product at the time of its publication, and may not reflect the product at all times in the future.

Autodesk Trademarks

The following are registered trademarks of Autodesk, Inc., in the USA and/or other countries: 3D Plan, 3D Studio, ADE, ADI, Advanced Modeling Extension, AME, Animator Pro, ATC, AutoCAD, AutoCAD Data Extension, AutoCAD Development System, Autodesk, Autodesk Animator, Autodesk LT, the Autodesk logo, Autodesk University, AutoLISP, AutoShade, AutoSketch, AutoSolid, AutoSurf, AutoVision, Design Companion, Education by Design, Generic, Generic CADD, Generic Softw 23223j92x are, Generic 3D Drafting, Geodyssey, HOOPS, MaterialSpec, Multimedia Explorer, NAAUG, Office Series, Opus, Solution 3000, PartSpec, Regis, TinkerTech, Texture Universe, Woodbourne, WorkCenter, and World-Creating Toolkit.

The following are trademarks of Autodesk, Inc., in the USA and/or other countries: 3D Props, 3D Studio MAX, 3DSurfer, ACAD, Advanced User Interface, AME Link, Animation Partner, Animation Player, Animation Pro Player, A Studio in Every Computer, ATLAST, AUGI, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL Interface, AutoCDM, Autodesk Animator Clips, Autodesk Animator Theatre, Autodesk Device Interface, Autodesk MapGuide, Autodesk PhotoEdit, Autodesk Software Developer's Kit, Autodesk WalkThrough, Autodesk World, AutoEDM, AutoFlix, AutoLathe, AutoSnap, BIPED, Bringing Information Down to Earth, Carpe Datum, Character Studio, Concept Studio, Content Explorer, DesignBlocks, DESIGNX, DesignScape, Design Your World, DXF, DWG Unplugged, Exegis, FLI, FLIC, GenCADD, Generic 3D, Heidi, Home Series, HyperWire, Inside Track, Kinetix, MapGuide, MAX DWG, Mechanical Desktop, Multiped, NetHead, ObjectARX, Octoped, PeopleTracker, Physique, Picture This Home, PlantSpec, Power and Light, Powered with Autodesk Technology, Quadruped, SketchTools, Smoke and Mirrors, Suddenly Everything Clicks, Supportdesk, Topper, Transforms Ideas Into Reality, and WHIP!.

Third Party Trademarks

ACIS ® is a registered trademark of SPATIAL TECHNOLOGY, INC.

Windows, Windows NT, Windows 95, and OpenGL are registered trademarks of Microsoft Corporation.

All brand names, product names, or trademarks belong to their respective holders.

Third Party Software Program Credits

ACIS ® Copyright © 1994, 1997 Spatial Technology, Inc., Three-Space Ltd., and Applied Geometry Corp. All rights reserved.

International CorrectSpell™ Spelling Correction System © 1995 by INSO Corporation.

All rights reserved. Reproduction or disassembly of embodied algorithms or database prohibited.

InstallShield™ 3.0. Copyright © 1997 InstallShield Software Corporation. All rights reserved.

Copyright © 1997 Microsoft Corporation. All rights reserved.

SmartHeap memory manager Copyright © 1991-1994 Arthur D. Applegate. All rights reserved.

Typefaces from the Bitstream ® typeface library copyright 1992.

Typefaces from Payne Loving Trust © 1996. All rights reserved.

The license management portion of this product is based on Élan License Manager ©1989, 1990 Élan Computer Group, Inc. All rights reserved.

Portions of this software are based on the work of the Independent JPEG Group.

GOVERNMENT USE

Use, duplication, or disclosure by the U. S. Government is subject to restrictions as set forth in FAR 12.212 (Commercial Computer Software-Restricted Rights) and DFAR 267.7202 (Rights in Technical Data and Computer Software), as applicable.

Table of Contents

Table of Contents

Goal

High Level Design   

Limitations   

General Information   

Initialization   

Structures and Commands   

Filenames   

Undo

Return values   

Update for AutoCAD T   

AVLIB.H

New Material Features   

Programmer Note!   

Commands

av_background   

av_colormap   

av_errorstr   

av_fog

av_initialize   

av_light

av_loadlib   

av_lsobj

av_matlib   

av_rconfig   

av_render   

av_renderupate   

av_replay   

av_rfileopt   

av_rmat

av_rpref

av_saveimg   

av_scene

av_setuv

av_stats

ErrorCodes   

Sample Applications   

Make files   

template

template.cpp   

allmats

allmats.cpp   

Goal

The goal for the AutoCAD Render API is to provide our developers with an efficient mechanism for accessing Render functionality from other applications.

High Level Design

The basic design is made up of two parts; an AutoCAD dynamic link library (DLL) and the interface library. The DLL (acRender.arx) is, in fact, the full featured Render application loaded by AutoCAD. acRender.arx contains hooks(exported functions) to communicate with a 3rd party Render API client. The interface library (avlib.lib) is a set of routines that communicate through an Rx connection to acRender.arx, therfore any application linked with avlib.lib must be an Rx application.

Limitations

acRender.arx and the Render API library are tied to particular releases of AutoCAD since the required Rx interface libraries in AutoCAD are typically release dependant. This has the unfortunate consequence that 3rd party applications that link to avlib.lib will have to be rebuilt for each release of AutoCAD which changes the ARX footprint.

General Information

Initialization

To load the library call the function av_loadlib(). This should be done in response to the AcRx::kLoadADSMsg, usually at the same time you ads_defun your functions. Additionally you should call av_initialize() each time you receive an AcRx::invkSubrMsg, usually in your top-level function handler. See the sample file template.cpp for an example. Both of these functions will return quickly if the library is already loaded and initialized.

Structures and Commands

The basic paradigm for use of avlib.lib is a set of function calls. Each function corresponds to one of the lisp callable functions described in Autocad Customization Guide. Each structure has a flags field that has a bit position for each member of the structure. If the parameter is required its bit MUST be set. If it is optional it is only examined if the bit is set. Any inappropriately set bit will be flagged as an error. On error returns (return value not equal to AvRetNorm) the flags will indicate the first parameter that was detected to be in error. The only exception to this are excessive flags all of which will be set. Note that in the descriptions below, any field not listed in a table for a command mode is not permitted, and will be flagged as errors if passed in.

For fields which take string values the table will list how many characters are allowed in the string, but one more character may be needed for the NULL terminator for the string.

All commands which specify a color use the AvColor structure:

typedef enum AvColorSystem;

typedef struct AvColor;

For RGB colors the ADS point holds the red, green and blue components, all of which are in the range 0.0 to 1.0. For HLS the point holds the hue, lightness and saturation of the color. The ranges for hue, lightness and saturation are 0.0 to 1.0.

Filenames

Since the length of paths and file names is operating system specific throughout this document and the api such structure members are char *.

Memory Management

Most commands do not allocate any memory that need to be freed by the application. The exceptions to this rule are the various "List" modes which return results in resbuf chains. These return values must be freed by the user of the library with the ads_relrb() call. Additionally, several "List" modes return selection sets which should be freed with the ads_ssfree() call. Also, "List" modes that return parameters that are strings, the strings are dynamically allocated.

Undo

It is the responsibility of user applications to do undo management. Unlike the normal command paths to Render the C API path does not provide UNDO/Group UNDO/End pairs. This allows the user program to do so. If a user program fails to group actions the UNDO’ing of Render actions can not be guarenteed.

Return values

Functions returning AvExtraneousField will set the flags member of the parameters structure for each extraneous field.

Functions returning AvRequiredFieldMissing will set the flag for the first missing field found.

Functions returning AvFieldOutOfRange or AvBadFieldValue will set the flag for the first field found to cause the range or value error.

Listing commands will set the flags to indicate the parameters that are being returned.

The flags field is undefined in all other cases.

Update for AutoCAD T

AutoCAD T introduced changes to the Render material definition that required changes to the Render API library for compatibility with AutoCAD R14. Application developers will need to link with versions of the library with the following changes:

AVLIB.H

#define AvLibVersion 0.02 ! Updated from 0.01

typedef enum AvRmatMapFlags;

typedef struct AvRmatMap;

New Material Features

The AutoCAD T Render material definition was modified to add real world scale and Auto-axis texture mapping. These attributes are attached to each map definition and are passed in the mappingFlags member of AvRmatMap. These fields greatly enhance the useability of texture mapping in AutoCAD Render.

Programmer Note!

AutoCAD R14 cannot receive materials with the new mappingFlags member, while AutoCAD T has this capability. The AvMapStyle flag is used to build the proper resbuf list. If the flag is set then the resbuf includes mappingFlags links. One way to tell whether AutoCAD R14 Render or AutoCAD T Render is loaded is to get a material from a drawing using AvRmatList. If the material returns with AvMapStyle set, then AutoCAD T is present and mappingFlags can be used safely.

Commands

av_background

GENERAL

The av_background command is used to set the background for rendering in Render.

SYNOPSIS

#include "avlib.h"

AvErrorCode av_background(AvBackgroundParam *p);

typedef enum AvBackgroundMode;

typedef enum AvBgFit;

typedef enum AvBackgroundFlags;

typedef struct AvBackgroundParam;

DESCRIPTION

av_background() has 7 modes:

AvBackgroundSolid

Set the background to be a solid color, either specified or locked to the AutoCAD background color.

Either the lock parameter or the color1 parameter MUST but both is an error.

AvBackgroundGradient

Sets the background to be a two or three color gradient.

If the height is set to 0.0 a two color gradient will be produced.

AvBackgroundImage

Set the background to be an image from a specified file.

imageFile (see AvRmatMap in the materials section)

The fit parameter specifies the action on the image if it is not set the scales and offset are used (or defaulted). The AVEMAPS path will be search at render time if an absolute path is not specified. Passing an tile of AvTileDefault is not allowed. NOTE: File existance and validity is only checked at render time.

AvBackgroundMerge

Sets the background to be an image from the current AutoCAD window. This mode supported only when rendering to viewport though it may be set at any time regardless of the current render destination setting. No parameters are required.

AvBackgroundEnv

Sets the global environment map. This can be locked to the background (Solid, Gradient or Image) or an image file may be specified. Setting no flags set the default of envLock to background.

Either envLock or envFile can be specified but not both.

AvBackgroundList

Lists the current state of the background. This will list what the use has set not what will be rendered (see AvBackgroundMerge above). No parameters are required. The state of background is returned in the structure.

AvBackgroundUI

Calls the UI version of Background.

av_colormap

GENERAL

The av_colormap command is used to do save and restore AutoCAD colormaps.

SYNOPSIS

#include "avlib.h"

AvErrorCode av_colormap(AvFogParam *p);

typedef enum AvColormapMode;

typedef struct AvColormapParam;

DESCRIPTION

av_colormap() has 2 modes:

AvInitAndSave

This mode saves the current colormap and sets the current colormap to the AutoCAD default colormap. This is only effective when on 8 bit displays, of course. An AvRetError is returned if there is a currently save colormap (ie you can NOT nest calls to av_colormap().

AvRestoreAndForget

This mode restores the save colormap. An AvRetError is returned if no colormap has been saveed.

av_errorstr

GENERAL

The av_errorstr command is used to provide internationalized error strings for each of the error codes supported by the library.

SYNOPSIS

#include "avlib.h"

char *av_errorstr(AvErrorCode *code);

DESCRIPTION

av_errorstr takes as it's parameter an AvErrorCode. Out of range error codes return an "Unknown Error" string.

av_fog

GENERAL

The av_fog command is used to do fogging and depth cueing of scenes with Render. Depth Cueing is simply fogging with a dark (traditionally dark blue) color.

SYNOPSIS

#include "avlib.h"

AvErrorCode av_fog(AvFogParam *p);

typedef enum AvFogFlags;

typedef enum AvFogMode;

typedef struct AvFogParam;

DESCRIPTION

av_fog() has 3 modes:

AvFogSet

Sets the fog/depth cueing as specified by the AvFogParam structure.

Fog between the near and far planes is smoothly ramped from the nearPercent to the farPercent.

Dview's clipping planes can be used to sent the bounds of the scene (basis for near and far Distance). If the clipping planes are not set the bounding boxes of the geometry will be used to determine the bounds.

AvFogList

Lists the current state of fog. No parameters are required. The structure is filled in indicating the state of fog.

AvFogUI

Calls the UI version of Fog. No parameters are required.

av_initialize

GENERAL

The av_initialize command is used to initialize the library and its connections to Render.

SYNOPSIS

#include "avlib.h"

AvErrorCode av_initialize(void);

DESCRIPTION

av_ initialize takes no parameters. av_initialize needs to be called after av_loadlib and before any other calls are made to the library. The one restriction is that it may only be called in response to the AcRx::kInvkSubrMsg message from the Rx dispatcher. In other words, it must be called in a function call that was defined with ads_defun. It is recommended that you call this function every time you get a call to one of your functions. It will only initialize on the first call, and return immediately thereafter.

av_light

GENERAL

The av_light command is used to create, modify, and query lights and establish North in the drawing

SYNOPSIS

#include "avlib.h"

AvErrorCode av_light(AvLightParam *p);

typedef enum AvLightFlags;

typedef enum AvLightMode;

typedef enum AvAttenType;

typedef enum AvLightType;

typedef struct AvLightParam;

DESCRIPTION

av_light() has 13 modes:

AvLightNewDistant

Create a new distant light. If any of the sun angle parameters are supplied (month, day, hour, minute, daylight, latitude, longitude, timezone) then calculate the light location using the calculated sun angle.

AvLightParam:

AvLightNewSpot

Create a new spotlight.

AvLightParam:

† 0.0...1.0 (attenuation == AvAttenNone)

0.0...(drawing-extents/2) (attenuation == AvAttenInverse)

0.0...(drawing-extents/2)² (attenuation == AvAttenuationInverseSquare)

†† 1.0 (attenuation == AvAttenNone)

(drawing-extents/2) (attenuation == AvAttenInverse)

(drawing-extents/2)² (attenuation == AvAttenuationInverseSquare)

AvLightNewPoint

Create a new point light.

AvLightParam:

† 0.0...1.0 (attenuation == AvAttenNone)

0.0...(drawing-extents/2) (attenuation == AvAttenInverse)

0.0...(drawing-extents/2)² (attenuation == AvAttenuationInverseSquare)

†† 1.0 (attenuation == AvAttenNone)

(drawing-extents/2) (attenuation == AvAttenInverse)

(drawing-extents/2)² (attenuation == AvAttenuationInverseSquare)

AvLightAmbient

Specify settings related to ambient light.

AvLightParam:

AvLightAmbientList

Query settings related to ambient light.

AvLightParam:

AvLightModify

Modify any of the settings related to an individual existing light.

AvLightParam:

AvLightDelete

Delete a light.

AvLightParam:

AvLightRename

Rename a light.

AvLightParam:

AvLightNorthLocator

Modify settings related to North location.

AvLightParam:

† Use "WCS" to effectively disable this option.

AvLightNorthLocatorList

List North Location related information.

AvLightParam:

† It is the caller's responsibility to free the memory which has been allocated for this string

AvLightList

Query the settings for an individual light.

AvLightParam:

AvLightListAll

Provides the names of all lights in the drawing.

AvLightParam:

† Each resbuf element in the chain contains the name of a light using the pointer resbuf->resval.rstring.

AvLightUI

Invoke the Lights dialog.

av_loadlib

GENERAL

The av_loadlib command is used to load the library.

SYNOPSIS

#include "avlib.h"

AvErrorCode av_loadlib(void);

DESCRIPTION

av_loadlib takes no parameters.

av_lsobj

GENERAL

The av_lsobj command is used to create, modify, and delete landscape objects and libraries of landscape objects.

SYNOPSIS

#include "avlib.h"

AvErrorCode av_lsobj(AvLsParam *p);

typedef enum AvLsAlign;

typedef enum AvLsMode;

typedef enum AvLsFlags;

typedef struct AvLsParam;

DESCRIPTION

av_lsobj() has 12 modes:

AvLsNew

Creates a new landscape object. The name must be the name of an object in the current landscape object library.

AvLsEdit

Modify an existing landscape object.

Any fields not specified are left unchanged.

AvLsList

List the values in a landscape object.

This command fills in the name, height, position, and alignment fields of the structure for the specified object.

AvLsLibOpen

Open a new landscape library.

Open the specified library and makes it the current landscape library.

AvLsLibDelete

Delete an entry from the current landscape library.

AvLsLibModify

Modify an entry in the current landscape library.

AvLsLibAdd

Add and entry to the current landscape library.

AvLsLibList

List the entries in the landscape library. If the name is not specified, this mode returns a list of the names of the objects in the current landscape library in the "stringList" member of the structure. If a name is provided, it returns the alignment, texture and opacity for that entry.

AvLsLibSave

Saves the current landscape library into the given file.

AvLsNewUI

Display the "lsnew" dialog.

AvLsEditUI

Display the "lsedit" dialog.

AvLsLibUI

Display the "lslib" dialog.

av_matlib

GENERAL

The av_matlib command is used to manipulate Render material libraries (.mli files).

SYNOPSIS

#include "avlib.h"

AvErrorCode av_matlib(AvMatlibParam *);

typedef enum AvMatlibFlags;

/* All Possible modes for MATLIB command */

typedef enum AvMatlibMode;

/* Structure for the MATLIB command to be passed in */

typedef struct AvMatlibParam;

DESCRIPTION

av_matlib() has 6 modes:

AvMatlibImport

Import a material into the drawing from a .mli file.

AvMatlibParam:

AvMatlibExport

Export a material from the drawing to a .mli file.

AvMatlibParam:

AvMatlibDelete

Delete a material from the drawing.

AvMatlibParam:

AvMatlibPurge

Delete all unused materials from the drawing.

AvMatlibList

List the materials in the drawing or a .mli file.

AvMatlibParam:

AvMatlibSet

Set the current material library.

AvMatlibParam:

AvMatlibRemove

Remove a material from a .mli file.

AvMatlibParam:

AvMatlibName

Return the name of the current material library in the librayaName field of the AvMatParam structure. The caller is resposible for freeing this string..

AvMatlibUI

Invoke the Material Library dialog.

av_rconfig

GENERAL

The av_rconfig command calls Render and tells it to reconfigure. This command has NO parameters in that all it does is enter Render's interactive reconfiguration command. No other configuration management can be accomplished by the client application.

SYNOPSIS

#include "avlib.h"

AvErrorCode av_rconfig(void);

DESCRIPTION

av_rconfig takes no parameters. See the AutoVision User's Guide and Reference for specifics on use of this command.

av_render

GENERAL

The av_render command is used to invoke the renderers and control the name of the destination file or the size and position of the crop window.

SYNOPSIS

#include "avlib.h")

AvErrorCode av_render(AvRenderParam *p);

ttypedef enum AvRenderFlags;

/* All Possible modes for RENDER command */

typedef enum AvRenderMode;

/* Structure for the RENDER command to be passed in */

typedef struct AvRenderParam;

DESCRIPTION

av_render has 2 modes:

AvRender

Invoke the renderer, honoring the current render preferences settings. Regardless of the "skip render dialog" toggle in render preferences the dialog is skipped.

AvRenderParam:

AvRenderUI

Invoke the Render dialog.

av_renderupate

GENERAL

The av_renderupdate command is used to control the updating of the Render internal geometry database.

SYNOPSIS

#include "avlib.h"

AvErrorCode av_renderupdate(AvRenderUpdateParam *p);

typedef enum AvRenderUpdateMode;

typedef struct AvRenderUpdateParam;

DESCRIPTION

av_renderupdate has 4 modes:

AvRenderUpdateAlways

Causes the Render geometry database to be updated for every rendering.

AvRenderUpdateOff

Causes Render to update it's geometry database as it sees fit.

AvRenderUpdateNext

Forces an update of the geometry database for the next rendering then returns to the previous mode.

AvRenderUpdateNotNext

Forces the reuse of the geometry database for the next rendering then returns to the previous mode.

av_replay

GENERAL

The av_replay command is used to paint an image file onto the rendering screen for viewing. In the past is was also used to provide, in concert with a merge rendering, backgrounds. This need has been eliminated with the addition of the background command.

SYNOPSIS

#include "avlib.h"

AvErrorCode av_replay(AvReplayParam *p);

typedef enum AvReplayFileType;

typedef enum AvReplayMode;

typedef enum AvReplayFlags;

typedef struct AvReplayParam;

DESCRIPTION

av_replay() has 2 modes:

AvReplay

Sets the file, filetype, size and positions of the replayed image.

The length of the filename is MAXPATHLEN characters (OS dependent from ads.h).

AvReplayUI

Calls the UI version of Replay.

av_rfileopt

GENERAL

The av_rfileopt command is used to configure the render to file functionality. Fourteen file formats are supported as well as a large number of configurations of subtypes, eg. compression, colormodes, interlacing, etc. NOTE: there is no UI mode for this command since it is available from the rpref UI and render UI modes, though indirectly.

SYNOPSIS

#include "avlib.h"

AvErrorCode av_rfileopt(AvFileOptParam *p);

typedef enum AvFileOptColor;

typedef enum AvFileOptMode;

typedef enum AvImageSize;

typedef enum AvFileOptFlags;

typedef struct AvFileOptParam;

DESCRIPTION

av_rfileopt() has 16 modes, with 2 excptions they correspond to image file types:

AvFileOptGIF

Sets the output file type to the CompuServ GIF format.

AvFileOptX11

Sets the output file type to X11 pixmap format.

AvFileOptPBM

Sets the output file type to Jef Poskanzer's Portable Bitmap format.

AvFileOptPGM

Sets the output file type to Jef Poskanzer's Portable Graymap format.

AvFileOptPPM

Sets the output file type to Jef Poskanzer's Portable Pixmap format.

AvFileOptTGA

Sets the output file type to AT&T's Targa format.

AvFileOptPCX

Sets the output file type to ??? PCX format.

AvFileOptSUN

Sets the output file type to Sun Microsystems rasterfile format.

AvFileOptBMP

Sets the output file type to Microsoft Windows Bitmap format.

AvFileOptPS

Sets the output file type to Level 1 encapsulated postscript.

AvFileOptTIFF

Sets the output file type to Tag Indexed File Format.

AvFileOptFAX

Sets the output file type to Group 3 Fax format.

AvFileOptIFF

Sets the output file type to Amiga IFF format.

AvFileOptFITS

Sets the output file type to FITS format.

AvFileOptList

Lists the currently configured output file type.

av_rmat

GENERAL

The av_rmat command is used to create, duplicate, modify, attach, detach and list Render materials.

SYNOPSIS

#include "avlib.h"

AvErrorCode av_rmat(AvRmatParam *p);

typedef enum AvRmatMapFlags;

typedef enum AvTileType;

typedef struct AvRmatMap;

typedef enum AvRmatStandardFlags;

/* structure of the standard material type description. */

typedef struct AvRmatStandard;

typedef enum AvRmatMarbleFlags;

/* structure of the marble material type description. */

typedef struct AvRmatMarble;

typedef enum AvRmatGraniteFlags;

/* structure of the Granite material type description*/

typedef struct AvRmatGranite;

typedef enum AvRmatWoodFlags;

typedef struct AvRmatWood;

typedef enum AvRmatFlags;

typedef enum AvMaterialType;

typedef enum AvRmatAttachMethod;

typedef enum AvRmatMode;

/* structure of the material command */

typedef struct matParams;

unsigned long flags;

} AvRmatParam;

DESCRIPTION

In all of the commands below, parameters that specify colors are represented by the type AvColor, which holds the RGB or HLS values specifying the color. The special RGB value of (-1.0, -1.0, -1.0) is given the name "By ACI" and means that the color is determined from the AutoCAD Color Index of the object being rendered.

New behavior for AVLIB 0.2: The enum AvRmatMapFlags has a new member AvMapStyle. It flags the use of struct AvRmatMap member mappingFlags. It’s behavior when creating new materials is backward compatible with previous versions in that the field is NOT sent in the resbuf chain when the AvMapStyle flag is not set. Member mappingFlags has the following definition: 0x01 = Fixed Scale set, 0x02 = Use AutoAxis.

Many of the commands below take parameters in the AvRmatMap structure, which describes texture maps. Here is a description of its fields:

In the ads_point for offset and scale, it applies to the UV mapper on the material, and only the first two values are used in the point.

av_rmat has 8 modes:

AvRmatNew

Create a new material.

AvRmatParam:

The matParams union describes the parameters specific to the type of material begin created.

AvRmatStandard:

AvRmatMarble:

AvRmatGranite:

AvRmatWood:

AvRmatModify

The modify mode take exactly the same parameters as the AvRmatNew mode, except the name must refer to an existing material. Also, instead of default, fields that are left unspecified leave the object unmodified for that field, so no defaults apply.

AvRmatCopy

Copy a material.

AvRmatAttach

Attach a amterial to a selection set of objects, a layer or an ACI.

If no aci, selectionSet or layerName are specified, then this function reports back how the specified material is attached. It will set the selectionSet field to a set of all the entities that this material is attached to, it will also set the "rb" member to a resbuf chain with the layers and ACIs that it is attached to. In the resbuf chain, if the type is RTSTRING, it is a layer name, and if it is RTSHORT, it is an ACI number.

AvRmatAttachResbuf

This function call returns the resbuf chain which is the xdata required to attach a material to an entity. The chain may be use with ads_entmake or ads_entmod.

AvRmatDetach

Detach materials from a selection set of objects, a layer ar an ACI.

At least one of aci, selectionSet or layerName must be supplied.

AvRmatList

List the propoerties of a material, or the list of all materials in the drawing.

If no name is given, the AvRmatList mode returns a list of all the materials defined in the current drawing. The list is returned in the "rb" member of the AvRmatParam structure. It is a resbuf chain of RTSTRINGs. If the material name is specified, then all of the parameters of that material are filled into the AvRmatParam structure. The fields that are filled in are specified by the flags field in the structure.

AvRmatShowMat

Show what material is attached to a given object, layer or aci.

Return the name of the material attached to the given entity, layer or ACI in the "name" field. It also sets the "attachment" field to the method by which the material is attached if an entity is selected. Either an entity, layer or an ACI must be set.

AvRmatUI

This mode brings up the Render Rmat dialog.

av_rpref

GENERAL

The av_rpref command is used to control the renderer and its preference settings.

SYNOPSIS

#include "avlib.h"

AvErrorCode av_rpref(AvRprefParam *p);

typedef enum AvRprefFlags;

typedef enum AvRprefToggleFlags;

typedef struct AvRprefToggleParam;

/* All Possible modes for RPREF command */

typedef enum AvRprefMode;

typedef enum AvRprefPaletteType;

typedef enum AvRprefDestType;

typedef enum AvRprefRenderTypeParam;

typedef enum AvRprefQualityType;

typedef enum AvRprefAntiAliasType;

typedef enum AvRprefSampleType;

/* Structure for the RPREF command to be passed in */

typedef struct AvRprefParam;

DESCRIPTION

av_rpref has 4 modes:

AvRprefSet

Set common render options. Renderer-specific options apply to the current selected renderer.

AvRprefParam:

AvRprefToggle-Param:

AvRprefRopt

Set renderer-specific options.

AvRprefParam:

AvRprefList

Query render options. All parameters are returned. If renderType is supplied, then renderer-specific items are returned which correspond to renderType. Otherwise, renderType is returned with the value of the currently selected renderer.

AvRprefParam:

AvRprefUI

Invoke the Rendering Preferences dialog.

av_saveimg

GENERAL

The av_saveimg command is used to save the rendering in the current viewport to an image file. Only GIF, TGA, and TIFF file formats are supported. This feature has been made largely obsolete for rendering to an image file by the addition of the render to file capabilities (See av_rfileopt).

SYNOPSIS

#include "avlib.h"

AvErrorCode av_saveimg(AvSaveimgParam *p);

typedef enum AvSaveimgFileType;

typedef enum AvSaveimgPortion;

typedef enum AvSaveimgCompress;

typedef enum AvSaveimgMode;

typedef enum AvSaveimgFlags;

typedef struct AvSaveimgParam;

DESCRIPTION

av_saveimg has 2 modes:

AvSaveimg

Sets the file, filetype, source position and size for the image to be saved.

The portion parameter is only applicable when saveing from a viewport. If you are configured to render to a separate display, omit it. RLE is the only compression allowed for TGA. Only PACK and LZW compression is allowed for TIFF.

AvSaveimgUI

Calls the UI version of SaveImage.

av_scene

GENERAL

The av_scene command is used to create, modify, delete, rename, and list scenes. A Render scene is a named construct consisting of a view and some set of lights.

SYNOPSIS

#include "avlib.h"

AvErrorCode av_scene(AvSceneParam *p);

typedef enum AvSceneFlags;

typedef enum AvSceneMode;

typedef struct AvSceneParam;

DESCRIPTION

av_scene() has 6 modes:

AvSceneNew

Create a scene.

AvSceneParam:

AvSceneModify

Change the composition (name, view, lights) of a scene.

AvSceneParam:

AvSceneDelete

Delete a scene.

AvSceneParam:

AvSceneSet

Select a scene to be rendered (this is, in effect, a rendering preference).

AvSceneParam:

AvSceneList

Query the list of scenes in the drawing, or the composition of a given scene.

AvSceneParam:

† lights == 0 no lights in scene

lights->resval.rstring == "*ALL*" scene contains all lights

otherwise lights contains resbuf chain with all lights in scene

†† It is the caller's responsibility to free any memory allocated for this field.

AvSceneUI

Invokes the Scene dialog.

av_setuv

GENERAL

The av_setuv command is used to attach, detach, modify, or list the UV or RST mapper assigned to an entity or selection set of entities.

SYNOPSIS

#include "avlib.h"

AvErrorCode av_setuv(AvSetuvParam *p);

typedef enum AvSetuvType;

typedef enum AvSetuvMode;

typedef enum AvSetuvFlags;

typedef struct AvSetuvParam;

DESCRIPTION

av_setuv() has 5 modes:

AvSetuvAssign

Sets the mapper to the selection set of objects. Note that this command takes only a selection set of objects

The points specified have different meanings depending on the mappingType:

AvSetuvPlanar:

p1 is the bottom left corner of the mapper.

p2 is the bottom right corner of the mapper.

p3 is the top left corner of the mapper.

p4 is not legal.

AvSetuvCylindrical

p1 is the bottom center of the cylinder.

p2 is the top center of the cylinder.

p3 is in the direction of the wrap line.

p4 is not legal.

AvSetuvSpherical

p1 is the center of the sphere.

p2 is the north pole of the sphere.

p3 is in the direction of the wrap line.

p4 is not legal.

AvSetuvSolid

p1 is the origin of the mapper.

p2 is the U (X analog) coordinate of the mapper.

p3 is the V (Y analog) coordinate of the mapper.

p2 is the W (Z analog) coordinate of the mapper.

Note that the 3rd component of the ads_point for scale and offset is ignored.

AvSetuvAssignResbuf

Builds a resbuf that represents the specified mapper. This resbuf can be used by entmakes or entmods.

The command returns a resbuf in the rb entry in the structure. This resbuf can be used to set the mapping for an entity via entmake, entmod etc.

AvSetuvDetach

Detaches any mapper that might be assigned to a selection set of objects.

AvSetuvList

Returns the mapper associated with a entity.

The structure is filled in to indicate the type of mapper that has been assigned. If no flags are set no mapper has been explicitly assigned to the entity.

AvSetuvUI

Calls the UI version of SetUV. No parameters are required.

av_stats

GENERAL

The av_stats command is used to save the statistics from the previous and all subsequent renderings to the statistics file.

SYNOPSIS

#include "avlib.h"

AvErrorCode av_stats(AvStatsParam *p);

typedef enum AvStatsMode;

typedef enum AvStatsFlags;

typedef struct AvStatsParam;

DESCRIPTION

av_stats() has 3 modes:

AvStats

Sets the filename to save stats into and saves the statistics. To stop saving statistics with each rendering call the AvStats command with no filename parameter.

The length of a filename is MAXPATHLEN characters (OS dependent from ads.h).

AvStatsList

Returns the statistics for the last rendering. The returned flags field indicates which values are filled in. If no values (other than the statistics filename) then no rendering has taken place yet. Due to the way the various rendering algorithms work, not all timing values are filled for all rendering types. For example shadow time is never filled in for AutoCAD Render. As AutoCAD Render combines traversal and rendering, the traversal time is combined with the rendering time and only the rendering time is returned. Likewise, since the Render renderers combine rendering and display, stats returns the rendering time which has the display time combined with it.

AvStatsUI

Calls the UI version of Stats.

ErrorCodes

/* Return Codes for Render API */

typedef enum AvErrorCode;

Sample Applications

Make files

We provide a Microsoft Visual C++ 4.2b workbench makefile for each sample application.

template

template.cpp

The Template folder contains a skelelal project that can be used as a starting point for your own AVLib ARX application.

allmats

allmats.cpp

The Allmat folder contains a project that implements a command to display the contents of a materials library in an AutoCAD drawing, using AVLib.

00000-005000-3041