Autodesk Alias 2011

Alias Programmers Interfaces (API)

March 2010

2010 Autodesk, Inc. All Rights Reserved. Except as otherwise permitted by Autodesk, Inc., this publication, or parts thereof, may not be reproduced in any form, by any method, for any purpose. Certain materials included in this publication are reprinted with the permission of the copyright holder. Trademarks The following are registered trademarks or trademarks of Autodesk, Inc., and/or its subsidiaries and/or affiliates in the USA and other countries: 3DEC (design/logo), 3December, 3December.com, 3ds Max, Algor, Alias, Alias (swirl design/logo), AliasStudio, Alias|Wavefront (design/logo), ATC, AUGI, AutoCAD, AutoCAD Learning Assistance, AutoCAD LT, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL Interface, Autodesk, Autodesk Envision, Autodesk Intent, Autodesk Inventor, Autodesk Map, Autodesk MapGuide, Autodesk Streamline, AutoLISP, AutoSnap, AutoSketch, AutoTrack, Backburner, Backdraft, Built with ObjectARX (logo), Burn, Buzzsaw, CAiCE, Civil 3D, Cleaner, Cleaner Central, ClearScale, Colour Warper, Combustion, Communication Specification, Constructware, Content Explorer, Dancing Baby (image), DesignCenter, Design Doctor, Designer's Toolkit, DesignKids, DesignProf, DesignServer, DesignStudio, Design Web Format, Discreet, DWF, DWG, DWG (logo), DWG Extreme, DWG TrueConvert, DWG TrueView, DXF, Ecotect, Exposure, Extending the Design Team, Face Robot, FBX, Fempro, Fire, Flame, Flare, Flint, FMDesktop, Freewheel, GDX Driver, Green Building Studio, Heads-up Design, Heidi, HumanIK, IDEA Server, i-drop, ImageModeler, iMOUT, Incinerator, Inferno, Inventor, Inventor LT, Kaydara, Kaydara (design/logo), Kynapse, Kynogon, LandXplorer, Lustre, MatchMover, Maya, Mechanical Desktop, Moldflow, Moonbox, MotionBuilder, Movimento, MPA, MPA (design/logo), Moldflow Plastics Advisers, MPI, Moldflow Plastics Insight, MPX, MPX (design/logo), Moldflow Plastics Xpert, Mudbox, Multi-Master Editing, Navisworks, ObjectARX, ObjectDBX, Open Reality, Opticore, Opticore Opus, Pipeplus, PolarSnap, PortfolioWall, Powered with Autodesk Technology, Productstream, ProjectPoint, ProMaterials, RasterDWG, RealDWG, Real-time Roto, Recognize, Render Queue, Retimer,Reveal, Revit, Showcase, ShowMotion, SketchBook, Smoke, Softimage, Softimage|XSI (design/logo), Sparks, SteeringWheels, Stitcher, Stone, StudioTools, ToolClip, Topobase, Toxik, TrustedDWG, ViewCube, Visual, Visual LISP, Volo, Vtour, Wire, Wiretap, WiretapCentral, XSI, and XSI (design/logo). All other brand names, product names or trademarks belong to their respective holders. Disclaimer THIS PUBLICATION AND THE INFORMATION CONTAINED HEREIN IS MADE AVAILABLE BY AUTODESK, INC. "AS IS." AUTODESK, INC. DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE REGARDING THESE MATERIALS. Published by: Autodesk, Inc. 111 McInnis Parkway San Rafael, CA 94903, USA

Contents

Alias Programmers Interfaces (API) . . . . . . . . . . . . . . . . 1

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 What is the API? . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 What Can the API Do? . . . . . . . . . . . . . . . . . . . . . . . . 2 What Cant the API Do? . . . . . . . . . . . . . . . . . . . . . . . 2 Who needs OpenModel? . . . . . . . . . . . . . . . . . . . . . . . 2 Who Needs OpenAlias? . . . . . . . . . . . . . . . . . . . . . . . . 3 OpenModel versus OpenAlias . . . . . . . . . . . . . . . . . . . . 3 Where do I start? . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 How to Use this Document . . . . . . . . . . . . . . . . . . . . . . 4 The universe and its objects . . . . . . . . . . . . . . . . . . . . . . . . 4 The Universe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Cameras . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Lights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Curves and Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Surfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Animation and Rendering . . . . . . . . . . . . . . . . . . . . . 11 Shaders and Textures . . . . . . . . . . . . . . . . . . . . . . . . 13 Implementation Details . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Class Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Wrappers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Instantiation and Creation . . . . . . . . . . . . . . . . . . . . . 14

iii

Safe Type-casting . . . . . . . . . . . . . . . . . . . Deletion . . . . . . . . . . . . . . . . . . . . . . . . Core dumps . . . . . . . . . . . . . . . . . . . . . . Comparing Pointers . . . . . . . . . . . . . . . . . . Allocation of Input Values . . . . . . . . . . . . . . Allocation of Return Values . . . . . . . . . . . . . . Reserved Types for Blind Data . . . . . . . . . . . . Limitations . . . . . . . . . . . . . . . . . . . . . . Compiling and linking . . . . . . . . . . . . . . . . . . . Files and Directories . . . . . . . . . . . . . . . . . . Setting the Include Path . . . . . . . . . . . . . . . . Windows development environment requirements . Building the included examples . . . . . . . . . . . . . . About the API examples . . . . . . . . . . . . . . . . Building the API examples on Windows . . . . . . . Using the API . . . . . . . . . . . . . . . . . . . . . . . . Sharing Code between OpenModel and OpenAlias . Determining the Position of an Instance . . . . . . . Getting clustered position . . . . . . . . . . . . . . Using AlUniverse::redrawScreen . . . . . . . . . . . Iterating Over Objects . . . . . . . . . . . . . . . . . Iterators and AlObjects . . . . . . . . . . . . . . . . Cleaning up Lost Wrappers . . . . . . . . . . . . . . Invalidating Wrappers . . . . . . . . . . . . . . . . . Wrappers, Destructors, and Deleting Objects . . . . . Copying Wrappers . . . . . . . . . . . . . . . . . . How to invoke your OpenModel applications . . . . Receiving Messages . . . . . . . . . . . . . . . . . . Picking Objects . . . . . . . . . . . . . . . . . . . . Setting Light Direction . . . . . . . . . . . . . . . . Creating and Deleting Keyframes . . . . . . . . . . . Closed Forms . . . . . . . . . . . . . . . . . . . . . Detecting the Escape Key . . . . . . . . . . . . . . . Making your code run faster . . . . . . . . . . . . . Using view frames . . . . . . . . . . . . . . . . . . . Using OpenModel . . . . . . . . . . . . . . . . . . . . . . Using OpenAlias . . . . . . . . . . . . . . . . . . . . . . . Disclaimer . . . . . . . . . . . . . . . . . . . . . . . Setting up plug-ins . . . . . . . . . . . . . . . . . . . . . Managing plug-ins . . . . . . . . . . . . . . . . . . Defining a plug-in . . . . . . . . . . . . . . . . . . . Creating custom icons for plug-ins . . . . . . . . . . Writing a plug-in . . . . . . . . . . . . . . . . . . . . . . Coding Overview . . . . . . . . . . . . . . . . . . . Adding your plug-in to the UI . . . . . . . . . . . . . . . Momentary, Continuous and History plug-ins . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. 14 . 15 . 15 . 15 . 16 . 17 . 18 . 18 . 18 . 18 . 19 . 19 . 21 . 21 . 22 . 24 . 24 . 25 . 25 . 25 . 26 . 26 . 27 . 27 . 28 . 28 . 28 . 29 . 29 . 29 . 29 . 30 . 30 . 30 . 31 . 31 . 31 . 31 . 32 . 32 . 33 . 33 . 33 . 33 . 35 . 35

iv | Contents

Attaching a plug-in to a menu or palette . . . . . . Menu and palette IDs for attaching a plug-in . . . Building Options Boxes . . . . . . . . . . . . . . . . . . Building Dynamic Editors using the AlEditor class . Scheme Editors . . . . . . . . . . . . . . . . . . . Native Platform Editors . . . . . . . . . . . . . . . Important Plug-in Notes . . . . . . . . . . . . . . Debugging a plug-in in Windows . . . . . . . . . . Plug-in API Examples . . . . . . . . . . . . . . . . . . . Momentary plug-in example . . . . . . . . . . . . Continuous plug-in example . . . . . . . . . . . . Command History example . . . . . . . . . . . . . Command history plug-in example . . . . . . . . Option box scheme example . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. 37 . 39 . 48 . 48 . 50 . 56 . 56 . 56 . 58 . 58 . 63 . 67 . 69 . 91

Class Chapter 1

reference . . . . . . . . . . . . . . . . . . . . . . . . . . 95

AlAction AlBoxLight . . . . . . . . . . . . . . . . . . . . . . . 97
AlAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 AlAimConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 AlAmbientLight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 AlAngleLocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 AlAnimatable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 AlAnnotationLocator . . . . . . . . . . . . . . . . . . . . . . . . . . 121 AlArcAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 AlAreaLight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 AlAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 AlBlendCurve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 AlBlendPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 AlBlindData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 AlBoxLight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Chapter 2

AlCamera AlCylinderLight . . . . . . . . . . . . . . . . . . . 169

AlCamera . . . . . AlCameraNode . . AlCategory . . . . AlChannel . . . . AlCharacter . . . . AlCharacterSpace . AlCharSnippet . . AlCharTransition . AlCloud . . . . . AlCluster . . . . . AlClusterable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 . 177 . 180 . 185 . 195 . 205 . 210 . 218 . 225 . 238 . 244

Contents | v

AlClusterMember . . . . AlClusterNode . . . . . . AlClusterPreTMItem . . . AlCommand . . . . . . . AlCommandRef . . . . . AlConeLight . . . . . . . AlConicAttributes . . . . AlConstraint . . . . . . . AlConstructionEntity . . AlConstructionPlane . . . AlConstructionVector . . AlCursor . . . . . . . . . AlCurve . . . . . . . . . . AlCurveAttributes . . . . AlCurveCV . . . . . . . . AlCurvePoint . . . . . . . AlCurveNode . . . . . . . AlCurveOnSurface . . . . AlCurveOnSurfacePoint . AlCylinderLight . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. 250 . 254 . 255 . 256 . 264 . 274 . 276 . 281 . 285 . 288 . 295 . 298 . 301 . 334 . 337 . 348 . 353 . 357 . 372 . 377

Chapter 3

AlDagNode AlLocator . . . . . . . . . . . . . . . . . . . . . 381

AlDagNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 AlDebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 AlDeviationLocator . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 AlDirectionLight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 AlDistanceLocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 AlEditor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 AlEnvironment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458 AlFace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465 AlFaceNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471 AlFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 AlFunctionHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492 AlGroupNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501 AlIKHandleNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 AlImagePlane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 AlIntersect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 AlIterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 AlJoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 AlKeyframe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 AlLayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567 AlLight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 AlLightNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591 AlLinearLight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 AlLineAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598 AlLinkItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600

vi | Contents

AlList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 AlLiveData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 AlLocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614

Chapter 4

AlMappedFieldItem AlRevSurfAttributes . . . . . . . . . . . 619

AlMappedFieldItem . . . AlMeasure . . . . . . . . AlMesh . . . . . . . . . . AlMeshNode . . . . . . . AlMessage . . . . . . . . AlMinmaxLocator . . . . AlMotionAction . . . . . AlNameItem . . . . . . . AlNonAmbientLight . . . AlNotifyDagNode . . . . AlObject . . . . . . . . . AlObserver . . . . . . . . AlOrientationConstraint . AlParamAction . . . . . . AlPerformance . . . . . . AlPersistentID . . . . . . AlPerspectiveCamera . . . AlPickable . . . . . . . . AlPickList . . . . . . . . . AlPixFile . . . . . . . . . AlPlaneAttributes . . . . . AlPlayBack . . . . . . . . AlPlayFrame . . . . . . . AlPointConstraint . . . . AlPointLight . . . . . . . AlPoint . . . . . . . . . . AlPrintf . . . . . . . . . . AlProduct . . . . . . . . . AlRadialLocator . . . . . AlRender . . . . . . . . . AlRetrieve . . . . . . . . AlRevSurfAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619 . 620 . 624 . 635 . 636 . 646 . 657 . 659 . 660 . 663 . 665 . 688 . 690 . 695 . 702 . 714 . 715 . 730 . 732 . 740 . 744 . 746 . 749 . 751 . 753 . 755 . 755 . 757 . 757 . 763 . 796 . 800

Chapter 5

AlSet AlXEvents . . . . . . . . . . . . . . . . . . . . . . . . 803

AlSet . . . . . . . . . AlSetMember . . . . . AlSettable . . . . . . . AlShader . . . . . . . AlShadingFieldItem . AlShell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803 . 808 . 811 . 816 . 828 . 829

Contents | vii

AlShellNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838 AlSnap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839 AlSpacePoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842 AlSphereLight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844 AlSpotLight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846 AlStatusHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856 AlSurface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858 AlSurfaceCV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904 AlSurfacePoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917 AlSurfaceNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924 AlTesselate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927 AlTexture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933 AlTextureNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946 AlTM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948 AlTorusLight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962 AlTrimBoundary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964 AlTrimCurve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968 AlTrimRegion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976 AlUnits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988 AlUniverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993 AlUserCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042 AlUserPickItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058 AlUserPickList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1059 AlViewFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1059 AlVolumeLight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1062 AlWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1078 AlXevents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1090

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1097

viii | Contents

Alias Programmers Interfaces (API)

Describes the APIs to allow programs to interact with and extend Alias.

Introduction
Describes the API, what it can and cant do, and who should use it.

What is the API?

The API provides developers with access to Alias internal data and functionality through two products, OpenModel and OpenAlias.

OpenModel (OM) provides a programmers interface to the Alias wire file (our proprietary data files). OpenAlias (OA) provides a programmers interface to the Alias application.

The API is written in C++ and is supplied as C++ classes. Most of the discussion in this document is intended for C++ programmers, and we assume that you understand the C++ concepts of classes and inheritance, and have a familiarity with the Alias interactive software. The components of the API are:

Class descriptions and documentation for all classes and their methods

The OpenModel shared libraries (.dlls and stub .libs on Windows, dylibs on Mac): alias_api, api_image and api_memory and additionally the Alias shared libraries that the API libraries depend on. OpenAlias shared libraries (.so) The API header files Example plug-in programs in C++ for OpenAlias and OpenModel TIP It is important that you read the API-specific release notes to learn what changes have occurred in the API since the last release.

What Can the API Do?

A brief list of some of the possibilities includes

generating surfaces, modifying the Alias DAG (Directed Acyclic Graph) hierarchy, modifying animations, and writing conversion utilities.

Plug-ins can be written using OpenAlias, which can read or write new file formats and can interactively generate geometry, lights, and shaders. Many stand-alone OpenModel applications can be easily converted into OpenAlias plug-ins.

What Cant the API Do?

The API does not give access to all functions in Alias. You do not have access to functions such as the Rail surface tool. However, with each release we provide more functionality to the API programmer.

Who needs OpenModel?

The Alias wire file format is a binary format and is therefore not modifiable without proprietary knowledge of Alias data structures.

2 | Part 1 Alias Programmers Interfaces (API)

We have therefore provided a library that insulates developers from the details of the file format and from any future changes in the file format. Since a library is available to read, write, and query wire files, developers do not need to make software changes to accommodate wire file changes. Re-linking with a new wire file library is sufficient. With this library, you can:

Edit the contents of an existing Alias wire file and save the changes. Create a new Alias model from scratch and save the changes to a wire file.

Who Needs OpenAlias?

If C++ developers want to interact with data internal to the interactive Alias package, then OpenAlias is for them. With OpenAlias it is possible to:

Create or modify Alias models, shaders, windows, and so on, and see the results instantly on screen. Have limited access to the Alias UI.

OpenModel versus OpenAlias

Deciding whether to use OpenModel or OpenAlias is largely a simple matter of deciding whether instantaneous response is a concern. OpenModel allows for the development of stand-alone applications which can operate on several files one after another or can be launched from a script, and therefore require little interaction with a user. OpenAlias, on the other hand, is for developers who need instant feedback or wish to integrate new custom features into Alias. The results of using a plug-in appear immediately on the screen. Still unsure? If so, then it is likely best to start developing plug-ins. OpenAlias generally provides a tighter integration with Alias providing a greater number of possible solutions to design decisions.

Who Needs OpenAlias? | 3

Where do I start?
Within the API there is an object called the Universe, which contains all geometry, lights, cameras and clusters for a model, as well as animation and rendering data. Developers can use the API to change the universe and its contents. Understanding the Alias universe and the class hierarchy is the best way to get started.

How to Use this Document

The body of this document assumes a knowledge of the Alias interactive software. Keep the Alias manual at hand for any unfamiliar terms.

Documentation Notes
In the documentation, the characters <, > and | are used to indicate how an argument is used by a method.

< means an argument is used as input into the method. > means an argument is used as output. | means an argument is used for both input and output by a method.

Note to Windows users

Occasionally, there are places in the document where you will encounter UNIX-style directory path names. Keep this in mind when you see path names with forward slashes.

The universe and its objects

Describes the basic concepts and procedures you need to understand.

4 | Part 1 Alias Programmers Interfaces (API)

The Universe
The universe is a static class that can access all objects in a wire file or within Alias. The main feature of the universe is that it has a pointer to a tree-like data structure which is called a directed acyclic graph (DAG). All geometry, light, camera and cluster information is stored in this DAG. The DAG is composed of nodes called DAG nodes.

This diagram illustrates an example model. Arrows indicate that a class references the class that it is pointing to. Double sided arrows indicate a two way reference. The topmost DAG node is called the world. In this example, the world node (returned by AlUniverse::firstDagNode()) has three group nodes as its children and an AlFaceNode as a sibling. Notice that the two group nodes below the topmost DAG node are instances. They both refer to the same curve node. NULL nodes (with nothing below them) created in the Alias interactive package are retrieved as AlDagNodes. There are several classes derived from the DAG node class that refer to specific objects that contain geometry, light, camera, or cluster information. (When a DAG node refers to an object, it means that the DAG node has the object as a child object.) for example, a camera node is a DAG node that refers only to a camera object. A light node is a DAG node that refers only to a light object. Combinations such as these tend to be created at the same time,

The Universe | 5

manipulated together, and deleted at the same time. Whenever a DAG node is created, it is inserted into the world position. After creating a DAG node, the method AlUniverse::firstDagNode() will return this node. Other creation routines (such as texture creation) can also insert nodes into the world position as the first node.

Cameras

Above, we see three camera nodes and their camera object. The nodes represent the cameras eye, view, and up positions. To create this combination, it would be necessary to instantiate and create an AlOrthographicCamera or an AlPerspectiveCamera. When they are first created, the camera nodes are siblings under an AlGroupNode.

6 | Part 1 Alias Programmers Interfaces (API)

Lights

This diagram shows a light and its three light DAG nodes, grouped under a common group node. To create this structure, instantiate and create one of the several different light types. The three light nodes (the position, look at, and up DAG nodes) are created. The three light DAG nodes are grouped under a common group node. All of the different light types make use of the position DAG node; however, only the AlSpotLight makes use of the look at and up nodes.

Curves and Faces

Some objects have child objects as well. For example the AlCurve class has AlCurveCV as a child class.

Lights | 7

Here we see a curve DAG node, its curve object, and control vertices (CVs). To create this entire structure, first instantiate and create an AlCurve, then instantiate and create an AlCurveNode object. Note that if an AlCurve is created and not associated with an AlCurveNode, it doesnt become part of the universe. In this case, if the pointer to the AlCurve is lost, the AlCurve becomes wasted memory.

A face is similar to a curve. Here we see a face DAG node, its face objects and their control vertices (CVs). A face must have at least one face object. To create a face, instantiate and create an AlFace then instantiate an AlFaceNode and pass the AlFace to the face nodes create method. As with curves, if the pointer to an AlFace is lost without first being associated with an AlFaceNode, the AlFace becomes wasted memory.

8 | Part 1 Alias Programmers Interfaces (API)

Surfaces
Surfaces, like curves, have child classes, but surfaces are far more complex and have a far greater number of child classes, including trim classes. There are also surface methods which allow you to project a curve onto the surface, create a curve-on-surface, and other methods which allow you to trim the surface using the curves on the surface.

Above is a surface node, its surface object and associated objects for control vertices (CVs) and curve-on-surfaces. To create a surface/surface node pair, first instantiate and create an AlSurface, then instantiate and create a surface node. The surface CVs are created automatically. To create a curve-on-surface, instantiate and set the data of an AlCurveOnSurface object, then add it to an AlSurface. While you are able to add rows of CVs you are not able to delete CVs. Make sure you create a surface node for each surface that you create; a surface without a surface node is not added to the universe, and if the pointer is lost, the surface would become wasted memory.

Surfaces | 9

Clusters
Some objects rather than having a child object, refer to other objects in the universe. In particular the AlSetMember and AlClusterMember classes refer to objects which are components of the set or cluster respectively.

Here we have a cluster DAG node, its cluster object and cluster members. To create this structure, instantiate and create an AlCluster object. It is not possible to create or delete individual AlClusterMember objects. Instead, they are created or deleted when objects are added to or removed from the cluster.

10 | Part 1 Alias Programmers Interfaces (API)

Sets

This diagram shows some sets and their set members. A set has no DAG node and is not in the DAG; to get the global list of sets, use the AlUniverse::firstSet() method. To create a set, instantiate and create an AlSet and add members to the set. As with cluster members it is not possible to create or delete individual AlSetMember objects instead, they are created when objects are added to or removed from the set.

Animation and Rendering

Animation and rendering information can also be accessed through the universe. For example, you can traverse the list of all the channels, actions,or shaders in the universe. However, this information is also accessible through the objects that use it. For example, surfaces and faces have access to the list of shaders and animated objects that they use for example, a CV, light or texture has access to the channels that animate it. The diagrams below show an animation and rendering example respectively of the relationship between objects that refer to each other. In these figures, all objects are represented in a rectangular box.

Sets | 11

This diagram shows a CV on a surface animated by a motion path and timing curve. To create this structure: instantiate and create an AlMotionAction using an AlCurveNode above the motion path curve; instantiate and create an AlChannel with the AlSurfaceCV to animate, the X, Y, or Z parameter of a CV; and the newly-created AlMotionAction; now use the applyWarp() method of the AlChannel, which creates the AlParamAction as a timing curve. Access the two AlKeyframes through the AlParamAction and change the timing of the animation by using the setLocation() method of AlKeyframe.

12 | Part 1 Alias Programmers Interfaces (API)

Shaders and Textures

This diagram shows a surface with two shaders, the first shader having two textures. To create this structure, first create a surface. Then create the two shaders with AlShader::create(). To one of them add textures with AlShader::addTexture(). Then use AlSurface::assignShader()to add the first shaders to the surface and AlSurface::layerShader() to add the second one.

Implementation Details
Describes coding concepts unique to the API.

Class Hierarchy
All but a few objects in the API are derived from a base class called AlObject. By deriving all object classes from a common base class, most things can be treated as AlObjects until you need to know otherwise. To find the type of an AlObject, you can query the type or use the safe type-casting methods described later in this document.

Wrappers
The objects which make up the API (C++ classes) are wrappers on internal Alias data, whether read in from a file, or created while running the interactive package. These wrappers can be thought of as a means to indirectly access the data. Access to the data is done through methods contained in the wrapper classes. This provides a clean and consistent view of the data and hides its internal representation. Wrappers are only allocated when necessary. This means that developers using the API are responsible for deleting wrappers when they are no longer needed.

New versus Reused Wrappers

All methods which return a pointer to an object return a new wrapper, except for the casting methods (that is, AlObject::asLightNodePtr()). Methods are provided to reuse wrappers when sets of data are processed as a group. These

Shaders and Textures | 13

include any method whose name ends in D (that is, AlSurface::nextShaderD()), and any iterator (that is, AlIterator).

Instantiation and Creation

The API separates the operations of instantiation and creation. Developers must initialize the universe before doing anything else. Since most objects are derived from the AlObject base class, safe type casting must be used to convert a base object to a derived object. Deleting objects and wrappers requires extra care. The creation of an object often involves both instantiation and initialization. The initialization part, if its simple, can be put in the constructor of a class. However, if the initialization involves an operation that could fail (for example, memory allocation could fail), then the constructor is inadequate to convey failure. To address this, the API uses create methods to perform initialization because they return useful status codes. The following is an example of how an object should be created, and returns NULL if creation was unsuccessful.
// instantiation AlAmbientLight *ambientLight = new AlAmbientLight; if (ambientLight == NULL) { return NULL; } // creation statusCode status = ambientLight->create(); switch(status) { case sSuccess: break; case sInsufficientMemory: default: delete ambi entLight; // Remember to free the memory return NULL; }

Safe Type-casting
Type-casting a pointer from a derived class to a base class is inherent to C++. Type-casting a pointer from a base class to a derived class is not safe and could possibly point to the incorrect data. The API provides methods to achieve this down-casting. The example programs, especially the DAG traversal functions, show how down-casting is used. For example, if class derivation is AlObject->AlLight->AlAmbientLight, where the AlObject class is the base class, and AlAmbientLight is the most derived class, the following code shows how down-casting is done:
AlAmbientLight *ambientLightPtr = objectPtr->asAmbientLightPtr(); if (ambientLightPtr != NULL) { // then we know the object is an ambient light }

14 | Part 1 Alias Programmers Interfaces (API)

You do not have to first cast the object to an AlLight. Also note that a new wrapper is not allocated when using the casting methods. In this way these methods can be thought of as regular casts.

Deletion
Be very careful when deleting objects from the universe. Some complex objects are closely linked and behave as a single entity. This includes objects such as camera nodes and camera objects.When a member of the group is deleted, the other members will also be deleted. For example, when one of the three camera nodes is deleted, the other two nodes will also be deleted. Alternatively, if a camera node is deleted, its camera (and other camera nodes) are deleted. Since the camera nodes are often siblings, developers should be careful that they are not left with a pointer that refers to a deleted object. An advantage to wrappers is that they can be invalidated, meaning that the internal object they reference may be deleted, but the wrapper remains with the knowledge that it is not valid. Methods of an invalid wrapper will fail gracefully, avoiding dereferencing dangling pointers.

Core dumps
If a core dump happens, it could mean one of the following:

A pointer is NULL and has been de-referenced (that is, is being used as if it were non-NULL) An object has been deleted twice A pointer is being used that points to an object that has been deleted An object is being treated as something it isnt (for example, an object has been cast incorrectly to the wrong type of object)

Comparing Pointers
It is not possible to compare wrapper pointers to see if the wrapper objects are the same. Any number of different wrapper objects may reference the same

Deletion | 15

Alias data internally. It is necessary to use AlAreEqual() to compare objects. This will compare the Alias objects to which the wrappers point. It is a true test of equality between Alias objects. In addition, checking a pointer for NULL is not sufficient for determining its validity. It is possible that through interaction with Alias, a developer may delete an object, causing any associated wrappers to become invalid, lest they point to freed memory. AlIsValid() should be used on wrappers that may have become invalidated since they were last referenced. All classes implicitly perform validity checks on instances, so a member function called on an invalid object will simply fail.

Allocation of Input Values

As a rule, the API developer is not responsible for allocation of arguments to functions. For example, if a function takes a string as an argument, that string will be duplicated by the API. The developer may then deallocate the string. The exceptions to this rule are the old blind data interface (user defined and only accessible through the API) and comments. Blind data is not copied on input. Rather, a pointer to the users buffer is kept in the Alias object. As long as a reference exists from Alias to that blind data, the developer should avoid deleting the associated buffer. Note that when the wire file is stored, the blind data is copied into the wire file. When a wire file is retrieved, any blind data will then be copied into a newly allocated buffer. This has the same effect as creating duplicates of any shared blind data. As a general rule it is not a good idea to allow objects to share blind data.

Blind Data and New and Delete

Using the C++ new and delete functions to create and destroy memory for blind data can lead to program errors. There are several cases where Alias or OpenModel will need to remove or re-create blind data during normal operations. If a delete all operation is performed, all blind data is removed. If blind data is saved in the wire file, when the file is read in the blind data storage will be recreated. OpenAlias and OpenModel will use malloc() and free() for its blind data memory creation and destruction routines. Problems may occur if the blind data has been created with the new command since the wrong creation and destruction routine for the memory block would be used. As a general rule malloc() should be used to allocate memory used for blind data or comments.

16 | Part 1 Alias Programmers Interfaces (API)

NOTE There are currently two ways of managing blind data within the API. You can use the old blind data methods(setBlindData(), blindData(), removeBlindData()) or use the new AlBlindData class. The rules above apply to the old blind data methods rather than the AlBlindData class.

Allocation of Return Values

There has been some confusion in the past over which functions allocate their return values and which functions return pointers to existing data. As of the Version 7 release, we have taken care to keep the treatment of return values consistent. For example, all functions that return strings now return const char * references to Alias data. We believe this approach to be more general--it does not force the developer to perform extra memory management if it is not necessary. If this returned string is required for future reference, then it is up to the developer to make a copy.

A Few Simple Rules for Return Values

While the allocation of return values may change and although there may be some exceptional cases, here are some rules of thumb to remember.

All methods that return strings return a const char * reference that is not allocated. The downcasting methods in AlObject (as*Ptr) do not allocate their return values. They simply act as a safe type cast to the derived type. The AlObjects passed to an AlIterator function are effectively not allocated. While they may still be allocated internally, the developer need not, and should not, perform any memory management on them - the applyIterator method handles that. If the iterator needs to return a pointer to a wrapper object it should copy it (that is, use the copyWrapper method). The destructive methods (methods whose names end in D) do not perform any memory management. If they succeed, they transform the passed in object in place. If they fail, they do nothing to the passed in object. Otherwise, any other method that returns a pointer to an object derived from AlObject allocates its return value. If this return value is not later deallocated, it will cause a memory leak.

Allocation of Return Values | 17

It is important to remember that return values will point to internal Alias objects that may change. For example, the return of an Alias objects name may change due to an action performed in the interactive package.

Reserved Types for Blind Data

User-types 0 to 9999 are reserved for Autodesk plug-in development. User-types 10000 to 13449 are currently reserved for third-party plug-in development.

Contact Autodesk if you would like to have a block of user-types reserved for your plug-in applications.

Limitations

The API provides limited access for changing data structures related to the user interface. OpenModel will retrieve wire files only if they are created with AliasStudio version 10.0 or later. On Windows, to retrieve older wire files for versions 3.2.2 to 9.7.x or PowerAnimator 4.0.1 to 9.0 you must set the LEGACY_WIRE_CONVERTER_LOCATION to $ALIAS_LOCATION/bin so that OpenModel can find the from100to97 executable. OpenModel cannot store wire file formats of previous releases.

Compiling and linking

Describes the process of creating a working executable application that uses the API.

Files and Directories

In the Alias directory, there is a directory called ODS (an abbreviation for Open Digital Studio):

18 | Part 1 Alias Programmers Interfaces (API)

Inside the directory are three directories relevant to the API:

OpenModel - examples, compiled examples, and libraries specific to OpenModel OpenAlias - examples and compiled examples (plug-ins) specific to OpenAlias (an external library is not required) Common - examples and include files common to OpenModel and OpenAlias

Compiling code for either OpenModel or OpenAlias is straightforward and the process can easily be understood when reading the example Makefiles in:
c:\Program Files\Autodesk\Alias2011\ODS\OpenModel\examples or ODS\OpenAlias\examples (Windows). /Applications/Autodesk/Alias2011/Alias.app/Contents/Resources/ODS/OpenModel/examples or ODS/OpenAlias/examples (Mac)

However below are detailed the important concepts.

Setting the Include Path

When building API programs, ensure that the include path for the compiler includes the path (in the CFLAGS variable):
-I$(ALIAS_LOCATION)/ODS/Common/include

where $(ALIAS_LOCATION) is usually c:\Program Files\Autodesk\Alias2011 (Windows) or /Applications/Autodesk/Alias2011/Alias.app/Contents/Resources (Mac). On Windows, the CFLAGS and CPLUSPLUSFLAGS variable would include the following:
/I$(ALIAS_LOCATION)\ODS\Common\include

Windows development environment requirements

Microsoft Visual Studio .NET 2008 is required for developing plug-ins and OpenModel applications on Windows XP or Vista.

Setting the Include Path | 19

Compiling and linking OpenModel programs for Windows

In the current release, the building of OpenModel applications is done at the command line rather than with in the Microsoft Visual Studio IDE. The OpenModel example applications included are built as console applications for the purpose of writing standard output. For OpenModel, ensure that the library path includes the following:
/LIBPATH:$(ALIAS_LOCATION)/lib

In addition, the LFLAGS variable should contain the following:

/SUBSYSTEM:CONSOLE /NODEFAULTLIB:LIBC.LIB /machine:I386

The link libraries for a console application are:

libalias_api.lib libapi_memory.lib libapi_image.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib comctl32.lib netapi32.lib version.lib ws2_32.lib

And the CFLAGS and CPLUSPLUSFLAGS variables should contain:

/MD.

The makefiles in the directories OpenModel/examples and OpenAlias/examples demonstrate how all this is done, and you should study them before creating new makefiles. As well, ensure that Path environment variable is set to reference the Alias library directory along with the directory that contains the compiler libraries. For example, use the following command in Command Prompt Shell:
set Path=%ALIAS_LOCATION%\bin;%SOME_MS_PATH%

Note that the %ALIAS_LOCATION%\bin directory contains the API .dlls and the %ALIAS_LOCATION\lib directory contains the API .lib files required at link time.

Compiling and Linking Plug-ins for Windows

In the current release, the building of OpenAlias plug-ins is done at the command line rather than within the Microsoft Visual Studio IDE. Linking a plug-in requires the following flags on a 32-bit machine: /nologo /DLL /opt:noref /incremental:no /machine:I386 "$(ALIAS_LOCATION)\lib\libAliasCore.lib And on a 64-bit machine:

20 | Part 1 Alias Programmers Interfaces (API)

/nologo /DLL /opt:noref /incremental:no /machine:X64 "$(ALIAS_LOCATION)\lib\libAliasCore.lib" For example, if the plug-in is composed of the object files obj1.obj obj2.obj obj3.obj, then the plug-in will be linked by the following command on a 32-bit machine:
link.exe /nologo /DLL /opt:noref /incremental:no /machine:I386 "$(ALIAS_LOCATION)\lib\libAliasCore.lib obj1.obj obj2.obj obj3.obj /out:output_name.plugin

Building the included examples

Describes how to build the examples included with the application.

About the API examples

See the Readme files for information on the examples.

OpenAlias/plugins
In this directory you will find precompiled versions of some of the files in the examples directory. We only precompile plug-ins that have useful functionality as opposed to programming examples. Note, however, that these plug-ins, whether compiled or not, are provided as examples only and are not supported by Autodesk.

Common/include
All the include files necessary to build OpenAlias plug-ins are located in this directory.

Common/examples
Some of the example source code is common between OpenAlias and OpenModel. This source code is located in this directory. Note that you will need to have the compiler flag
-I$(ALIAS_LOCATION)/ODS/Common/examples

in your compile flags (CFLAGS) in your Makefile if you use the AlPrint functions in your programs.

Building the included examples | 21

Building the API examples on Windows

OpenModel
To build the OpenModel examples, type the following in a command prompt window and exclude any text in brackets:
mkdir examples cd examples copy c:\Program Files\Autodesk\Alias2011\ODS\OpenModel\ex amples\Makefile . notepad Makefile (Set ALIAS_LOCATION variable to correct path.) vsvars32.bat (Set the Visual C++ environment variables.) nmake copy (Copies example code into the current directory.) nmake set Path=%Path%;c:\Program Files\Autodesk\Alias2011\\bin (Sets Path variable so .dlls can be found .) .\cppCreate.exe new.wire (Run an example.)

Notes

You may need to change the copy path in the OpenModel example directory above depending on the location of your Alias install directory. In addition, you will require the Microsoft Visual Studio bin directory to be in your path. You must set the Path variable so that it includes the location of Alias bin directory so that the OpenModel .dlls can be found.

OpenAlias
To build the OpenAlias example plug-ins, you need the following installed on your machine:

A compatible C++ compiler. For version 2011 that compiler is VC9.0 and it comes with Visual Studio 2008. An installed copy of Alias 2011.

Next you need to identify the following paths:

The plug-in .cpp files are located in your Alias 2011 install directory under ...\ODS\OpenAlias\examples\

22 | Part 1 Alias Programmers Interfaces (API)

The plug-in include files (.h files) are located in your Alias 2011 install directory under ...\ODS\Common\include\ The plug-in scheme files (.scm files) are located in your Alias 2011 install directory under ...\ODS\OpenAlias\examples\scm\ The Makefile is located in your Alias 2011 install directory in
...\ODS\OpenAlias\examples\Makefile

The program you use to run the Makefile is called nmake.exe and is located in the Visual Studio 2008 install directory. There will be two versions: a 32-bit and a 64-bit. Make sure to use the correct version. The batch files used to set the development paths are called vcvars32.bat (for 32bit) and vcvarsamd64.bat (for 64 bit) and are also located in the Visual Studio 2008 install directory. Run cmd.exe to open the command prompt window then follow these steps. 1 Set the development path by typing the following in the command prompt window. (Exclude any text in brackets.)
set PATH= (This clears your path to prevent the compiler from accidently finding old versions of DLLs or LIBs) vsvars32.bat (or vcvarsamd64.bat for 64-bit. This sets the devel opment path to use the compiler.)

2 Open the Makefile (using Notepad or any text editor) and set ALIAS_LOCATION to the Alias 2011 install directory. This is usually C:\Program Files\Autodesk\Alias2011 (Windows) or
/Applications/Autodesk/Alias2011/Alias.app/Contents/Resources

(Mac). 3 Create a new directory where you want to build the plug-ins, and copy the Makefile and example code into it.
mkdir <directory_name> cd <directory name> copy [ALIAS_LOCATION]\ODS\OpenAlias\examples\Makefile . nmake copy

NOTE If you want, you can compile the examples directly into the
...\ODS\OpenAlias\examples\ directory and skip this step.

4 Add the directories listed above to your path, that is, the \examples directory, the \include directory, and the \scm directory).

Building the API examples on Windows | 23

NOTE If you are using a 64 bit machine and have both a 32-bit and a 64-bit installation of Alias, make sure to use the correct install path depending on whether you are attempting to complile a 32-bit or 64-bit plug-in. 5 Add the \bin and \lib directories for the Alias 2011 install to the path. (Again match 32 bit or 64 bit paths if you have both.) 6 Type the following in the command window to compile the plug-ins:
nmake

The built plug-ins can now be loaded through the Plug-in Manager.

Notes

You may need to change the copy path to the OpenAlias example directory above depending on the location of your Alias install directory. In addition, you will require the Microsoft Visual Studio bin directory to be in your path.

Using the API

Useful suggestions for common tasks.

Sharing Code between OpenModel and OpenAlias

With careful coding, you can share code between OpenModel and OpenAlias plug-ins. To simplify code sharing, you can:

limit an applications main() and a plug-ins plugin_init() (described later) to do only initialization. Pool common code between the OpenModel and OpenAlias routines into a utility library. This could be accessed by either the main() routine (in OpenModel) or by the main function in the OpenAlias plug-in. This helps to avoid the heavy use of #ifdefs in the source code.

24 | Part 1 Alias Programmers Interfaces (API)

Determining the Position of an Instance

To determine the position of a CV in an uninstanced piece of geometry simply use the worldPosition() methods on the various CV classes. When geometry is instanced it is not possible to use the worldPosition() methods (since they will only indicate the position of the first instance). Instead it is necessary to use the affectedPosition() methods. In the simple case, where instance nodes have no parents there will be distinct paths to the instanced geometry. The method AlDagNode::globalTransformationMatrix() is used to calculate the transformation matrix of the instance node. Use this AlTM and the CV's affectedPosition() method to get the position of the CV in the instanced geometry. In the more complex case of instances being applied to instances, there will be several non unique paths to the geometry. Each path will represent an instanced piece of geometry. It will be necessary to walk each path and accumulate the transformation matrices( while walking down) and then apply that accumulated AlTM to the CV/Vertex positions.

Getting clustered position

Sometimes it is desirable to get the position of a CV including the effect of any clusters but excluding the DAG transformations above the CV. To do this supply the affectedPosition() methods with an identity matrix.

Using AlUniverse::redrawScreen
This method is only useful to OpenAlias plug-ins. You should call it whenever a change has been made to a model or a window. However, it could be expensive to use, so you might use it only after completing all necessary changes. For example, a plug-in might project several curves on to a surface and then trim the surface. You could call AlUniverse::redrawScreen() after each projection and after the trim: that would create an interesting visual effect as each curve appears on the surface. Alternatively, if you prefer speed over the visual effects, you might call AlUniverse::redrawScreen() only after trimming is complete. If you do not use AlUniverse::redrawScreen(), the display shows out-of-date images of the data.

Determining the Position of an Instance | 25

You can improve performance by postponing screen updates until all objects have been updated. The developer can implement this speed-up by using AlUniverse::doUpdates().

Iterating Over Objects

The AlIterator class simplifies writing code that must operate on lists of objects. AlIterators significantly reduce the overhead associated with using wrappers to walk lists of items. The applyIterator() methods on many classes will traverse a list of objects in the most efficient method possible and may reuse wrappers. For example, using AlSet::firstMember() and AlSetMember::nextSetMember() may require O(nlog n) operations to traverse the entire Alias set. Using the iterator requires only O(n) operations. See the documentation in the AlIterator class. Explicit traversals can be optimized through the use of the nextD and prevD destructive methods.
AlCurveCV* cv; if ( cv = curve->firstCV() ) { do something ... } while( sSuccess == cv->nextD()); { ... do delete cv; }

The statement cv->nextD() causes the current wrapper to reference the next CV in the curve. No additional memory is allocated, and in general the destructive methods will run faster than the non-destructive methods. Whenever possible, one should use the AlIterator class when traversing a collection of objects. Not only will the traversal be as quick as possible, but the memory management is taken care of. The wrappers passed to the iterators callback function are destroyed by the class and need not be freed explicitly.

Iterators and AlObjects

An iterator is a special form of callback function. By providing an overloaded class, you can also maintain data between each call to the callback function. When using iterators to find AlObjects, you need to copy the wrapper rather than just storing a pointer to it. Below is an example of an iterator which looks for a DAG node named George.

26 | Part 1 Alias Programmers Interfaces (API)

class findGeorgeIterator : public { public: findGeorgeIterator() : george( NULL ) {}; ~findGeorgeIterator() {}; virtual int func( AlObject* obj ) { if ( strcmp( obj>name(), "George" ) ) { george = obj->copyWrapper(); // Copy the wrapper! return 1; } }; AlDagNode* result() { return george; }; private: AlDagNode* george; } // ... then to use the class. int result; findGeorgeIterator iter; AlDagNode *george = NULL; if ( sSuccess == AlUniverse::apply IteratorToDagNodes( &iter, result ) ) { george = iter.result(); }

If the result of such an iterator is always used, then the above is adequate. However, the return value could be ignored, a better implementation of the iterator would have the destructor delete the wrapper and have the result method return a copy of the saved wrapper.

Cleaning up Lost Wrappers

If you forget to delete a wrapper or lose a pointer to one, you can use AlDebug::cleanUpUniverse(). This method deletes all invalid wrapper objects in the current universe. Wrapper operations (most notably the deleteObject() operations) will slow down with the more wrappers you use. If calls to the API deleteObject() method start to slow down the longer it runs, it is likely that wrappers are being lost (resulting in a memory leak) and the code should be corrected. As a temporary kludge, the AlDebug::cleanupUniverse() method can be called. You should avoid AlDebug::cleanUpUniverse() if at all possible. It can cause core dumps if used when other plug-ins are running or with wrappers that are not dynamically allocated. (See the AlDebug::cleanUpUniverse() documentation for a discussion of why.) Furthermore, this function deletes all the wrappers in the universe, regardless of the plug-in that created them. This can cause another plug-in to lose a reference to data and crash. In short, this function is intended for debugging until you have eliminated all of your memory leaks.

Invalidating Wrappers
As mentioned earlier, wrappers can be invalidated. A wrapper references Alias data. When the Alias data is deleted, rather than deleting the wrapper we just invalidate it. (If we deleted it, an API user might try to dereference it and cause

Cleaning up Lost Wrappers | 27

a core dump.) An invalidated wrapper is one which does not reference any Alias data. Accessing any of the methods of an invalid wrapper does not cause a fatal error, but causes a failure code (usually sInvalidObject) or an error value to be returned. You can use the function AlIsValid() on objects derived from AlObject to determine if they are valid or not. AlIsValid() will return FALSE for an input of NULL. In OpenAlias and OpenModel, when moving between stages, wrappers which reference objects in inactive stages become invalid until the stage becomes active again. They are also made invalid if the universe that they are in is deleted.

Wrappers, Destructors, and Deleting Objects

The destructor deletes the wrapper and leaves the Alias data intact. To delete the Alias data use the wrappers deleteObject() method which will delete the object and invalidate the wrapper. Note that although every class derived from AlObject has a deleteObject() method, not every type of Alias data can be deleted from a plug-in. for example, curve CVs are not deletable. As a result, calling deleteObject() on an AlCurveCV will simply return sFailure.

Copying Wrappers
The copyWrapper() method allows developers to create a new wrapper which references the same Alias data as an existing wrapper. As a result it is not possible to compare wrapper pointers to learn whether they reference the same object, instead you must use AlAreEqual() to determine whether the wrappers reference the same object.

How to invoke your OpenModel applications

The application $ALIAS_LOCATION/bin/ print_wire_header now outputs the coordinate system stored in a wire file. You can use this information and a wrapper script to invoke your OpenModel applications with the correct Coordinate axis.

28 | Part 1 Alias Programmers Interfaces (API)

Receiving Messages
To accomplish some tasks the universe relies on messages. The API provides methods to receive and post messages. You can also define a custom message type which extends the standard collection of Alias messages. Although Alias has no understanding of the new message type (because Alias cannot receive messages from plug-ins or OpenModel applications), plug-ins can use them as communication channels. This allows for interesting possibilities, such as a group of plug-ins collaborating on a function. See the documentation on the AlMessage class for more information.

Picking Objects
The class AlPickList provides access to the list of active objects from within an OpenAlias plug-in and OpenModel applications. The pick list could include objects picked from the modeling windows and the multilister. AlPickList also includes methods to manipulate the pick list and perform global picking operations, such as picking an object from the screen. Most of the non-interactive methods will also function in OpenModel, making this class a useful utility in both situations. Many objects are derived from AlPickable. Like AlAnimatable and AlClusterable, AlPickable encapsulates the shared behavior of a collection of types, in this case the behavior of all objects that can be picked. See the AlPickable documentation for further information.

Setting Light Direction

Setting the direction of a light can be accomplished using the setDirection() method in the AlDirectionLight and AlSpotLight classes.

Creating and Deleting Keyframes

The API supports creating and deleting keyframes in blocks. In the class AlParamAction, there are two methods called addKeyframeRange() and deleteKeyframeRange() for performing block keyframe creation and deletion. These block operations will be faster than individual creation or deletion of keyframes.

Receiving Messages | 29

Closed Forms
Alias and the API have slightly different definitions of curve and surface form. After building a Closed curve or surface in Alias where the first and last CVs are co-incident, the information window will still report that the curve or surface is Open. This is because Alias does not support the concept of Closed geometry. The API supports Closed geometry and AlCurve::form() and AlSurface::vForm() or uForm() will report that the curve or surface is Closed.

Detecting the Escape Key

The AlEscapeKeyPressed() function defined in AlLiveData.h returns TRUE if the Escape key has been pressed. When going into loop operations that may take a great deal of time to complete, add a call to this function. If the user has pressed Escape, cleanup and exit from the loop. This function only exists in OpenAlias.

Making your code run faster

Two simple coding practices can make a plug-in or OpenModel application run faster. These ideas are stated elsewhere in the API documentation but are worth repeating here. Adhering to these coding practices are even more important if your code will be dealing with large numbers of objects.

Where possible, utilize the destructive wrapper methods such as nextD() or prevD() to iterate over objects. The destructive methods re-use the wrapper object so no memory allocation and destruction needs to be performed to iterate to another object. Turn off updating until you have finished a batch of changes. Many classes contain a doUpdates( boolean newState ) method. Before going into a batch of geometry changes, call doUpdates( FALSE ) to turn off updating. After the batch of geometry changes, call doUpdates( TRUE ) to update any changed object.

An additional coding practice that can be utilized is wherever possible takes advantage of methods that perform operations on multiple objects. Some of the batch routines are described above. These include creating and deleting keyframes.

30 | Part 1 Alias Programmers Interfaces (API)

Using view frames

When using the AlViewFrame::viewFrame( ... , const double,Options=kObject) method, it is important to realize that the view will be determined by the heirarchy evaluation that was requested. The Options parameter is one of:
kObject kObjectAndAbove kObjectAndBelow kObjectAndAboveBelow

As a result, you must specify the correct direction of the heirarchy to evaluate. For example, if you were evaluating a leaf node and specified kObjectAndBelow, the view would not change.

Using OpenModel
Information on programming OpenModel.

Using OpenAlias
Information on creating Alias plug-ins with OpenAlias.

Disclaimer
In the directory $ALIAS_LOCATION/ODS/, there are a number of pre-compiled plug-ins and source code examples. These plug-ins and source code examples are provided to you on an "AS-IS" basis. You are free to make use of these plug-ins and source code examples, however Autodesk does not provide any support in connection with them. Autodesk makes no warranties, express, implied or arising by custom or trade usage, and to the extent permitted by applicable law, specifically disclaims any implied warranties of title, noninfringement or of fitness for a particular purpose. To the extent permitted by applicable law, (I) Autodesk's liability in contract, tort or otherwise arising out of or in connection with the plug-ins or source code shall not exceed the purchase price paid by customer for the plug-ins or source code examples, and (Ii) in no event shall Autodesk be liable for any punitive damages or lost profits or other special, indirect, incidental,

Using view frames | 31

or consequential damages, including any damages resulting from loss of business arising out of or in connection with the performance of the plug-ins or source code examples, even if Autodesk has been advised of the possibility of such damages. Customer shall indemnify Autodesk and hold it harmless from and against any loss, claim or damage to any person arising out of customer's use of the plug-ins or source code examples.

Setting up plug-ins
Managing plug-ins
The defaults for OpenAlias are set up such that it is not necessary to do anything before using plug-ins. However, you may want to set up your OpenAlias environment with the configurable options in the Alias Preferences window. These items are both set to appropriate defaults so they do not need to be changed before using plug-ins in Alias. The configurable items are:

Plug-in search path Plug-in message level

Plug-in search path

This colon-delimited path is used to search for plug-ins specified in the auto-load list and by the searching routines of the Plug-in Manager window. Set the search path in the Miscellaneous section of the General Preferences window. By default this path on Wnidows is: .:$ALIAS_LOCATION/ODS/OpenAlias/plugins which causes $ALIAS_WORKENV (or the directory Alias was launched from if $ALIAS_WORKENV is not set - Alias does an implicit change of directory to $ALIAS_WORKENV when it starts) to be searched first, followed by the directory containing the example plug-ins. Any number of directories can be listed with each searched in turn until a plug-in is found. Note that this default path is one of many that are searched for plug-ins.

32 | Part 1 Alias Programmers Interfaces (API)

Plug-in message level

The Messages popup allows the selection of Full (verbose) or Brief messages. In Full message mode, detailed information will be written to the errlog file if there is an error during the loading or unloading of plug-ins.

The plug-in manager window

To open the Plug-in manager, choose Utilities > Plug-in Manager .

Defining a plug-in
A plug-in may consist of several files. The only file required is the C++ source which defines the functionality of the plug-in. Additional files include scheme and icon files. The most common scheme files a plug-in may use are a pair of files describing the option box. One scheme file describes the layout of the option box and the second provides commands which initialize the default values of variables.

Creating custom icons for plug-ins

A general solution for creating icons involves using the Alias renderer. A model of the icon you wish to represent would be created within Alias. Use the Render -> Globals -> Image File Output option to set the Format and Depth Format to ALIAS. Then set the X and Y resolution to 32 for small icons or 48 for medium icons. Render the image and then use that image as the icon for the plug-in. This solution will work on any platform.

Writing a plug-in
Coding Overview
Building a plug-in requires the creation of a function handle(class AlFunctionHandle). The function handle encapsulates all the operations on a UI menu button. A plug-in can define and control any number of menu buttons. A plug-in must define a entry function called plugin_init(). The exit

Defining a plug-in | 33

function called plugin_exit() is optional. Plug-ins without exit functions will not be unloaded.

plugin_init()
This function must be defined as:
extern C PLUGINAPI_DECL int plugin_init( const char* plu ginDirPath )

It is run as soon as the plug-in is loaded. pluginDirPath is a NULL-terminated string which contains the absolute pathname to the directory that the plug-in was loaded from. This path is provided as a convenience to the plug-in. It is intended to be passed to the initialization routines as an additional argument. This allows the plug-in to specify the exact location of its scheme and icon files if they are not located in the default directories. NOTE On Windows, PLUGINAPI_DECL is defined to export the associated symbol from the plug-in. On Mac, PLUGINAPI_DECL is not neededit is an empty define. The developer uses this function to initialize the OpenAlias universe, and uses instances of the AlFunctionHandle class and AlMomentaryFunction or AlContinuousFunction classes (declared in the file scope to be available to the plugin_exit() function as well) to define the interface between Alias and the plug-in. On successful completion this function should return zero. If a non-zero value is returned from the plugin_init function, OpenAlias will assume that some error condition was encountered in initialization and will unload the plug-in. NOTE We suggest doing the bare minimum in the plugin_init function. Allocate any user data that the plug-in will need but do not allocate any OpenAlias classes.

plugin_exit()
This function must be declared as:
extern C PLUGINAPI_DECL int plugin_exit( void )

It is called when the plug-in is removed or Alias is shut down. The programmer uses this function to do whatever is necessary to clean up the plug-in. This function should remove the plug-in from all menus using the deleteObject() method for each declared AlFunctionHandle and destroy any created AlFunctions using the deleteObject() method. On successful completion this function should return zero. Failing to remove all references may result in

34 | Part 1 Alias Programmers Interfaces (API)

core dumps if they are accessed by Alias after the plug-in has been removed. In addition, ensure that any callbacks that have been installed are removed.

Static destructors and exiting from Alias

Plug-ins are not unloaded when Alias exits. This decreases the time that Alias takes to exit but results in static destructors of C++ classes not being called. The DSO is not explicitly unloaded but is removed when Alias exits. Static destructors are called when a plug-in is unloaded manually. We suggest not doing operations within the static destructors of your classes. Note that plugin_exit() is still called when Alias exits, so any saving of data can be done within that function.

Adding your plug-in to the UI

Momentary, Continuous and History plug-ins
There are three kinds of tools in Alias: momentary functions, continuous functions and construction history functions.

Momentary tools
A momentary function is essentially a single event: a function that takes no arguments and has no return value. It is simply a jump point in memory. Alias transfers control to this point when the menu item is invoked, the function executes, and control is returned to Alias. An example of a momentary function is delete all. The simplest way to define a momentary function is through the AlMomentaryFunction class. Calling one of the create methods on an instance of that class will generate a new momentary function in Alias.

Continuous tools
A continuous function is more complicated than a momentary function. It is event driven: it must respond to user interaction through the mouse, keyboard, and user defined devices. As a result, continuous functions do not actually take over control of Alias when they execute. Rather, they define a context under which UI events are interpreted. Alias reads these events and transfers them to a group of event handlers defined by the continuous function. Thus

Adding your plug-in to the UI | 35

a continuous function is a set of five callback functions: init, mouse down, mouse move, mouse up and cleanup. In addition, a continuous function is allowed to define pre-init and post-cleanup functions. The reason for these is that there are two ways to enter and leave the context of a continuous function. The function can be preempted temporarily by selecting some momentary function, or terminated more permanently by switching contexts to some other continuous function (or quitting Alias, of course). The pre-init and post-cleanup functions allow you to define actions that get invoked when Alias truly changes contexts and does not merely preempt your continuous function.

Init
Init is executed when the context of a continuous function is entered. This occurs when the function is first invoked, or after returning from a momentary function which pre-empted the function, or after reselecting this continuous function after completing some other continuous function.

Mouse Down
Down is called on every mouse down event. Use this function to detect the start of a click-drag type of operation.

Mouse Move
Move corresponds to the sequence of mouse movement events that occur between a mouse down and a mouse up. A move event is generated for each significant mouse movement while a button is being held down. Further, move is called in the case that the enter key is pressed on the keyboard. Therefore, it is in the move function that keyboard input should be detected.

Mouse Up
Up is called on mouse up events. Use this function to do things like commit transforms or create geometry corresponding to some sequence of mouse drags.

Cleanup
Cleanup is called when the context of this function is left to perform some other action. For example, if the user is in the context of your continuous plug-in, and invokes some other momentary function, the cleanup function

36 | Part 1 Alias Programmers Interfaces (API)

is called, followed by the momentary function, followed by the init function when Alias returns to the context of the original continuous function.

Command history plug-ins

Command history plug-ins are very complex, and it is advisable not to attempt creating one until you have a firm understanding of momentary and continuous plug-ins. Command history plug-ins are not menu-based but rather are invoked when geometry changes. You install a command plug-in by selecting a menu item. This calls plugin_init() to install the command in Alias. Once installed, the command plug-in can run without your reselecting the command plug-in menu item. A command or construction history object has knowledge of how it is created. The constructors of the object are tracked as well as the targets (outputs) of the command. When a constructor is modified, the geometry of the targets are rebuilt. A command history plug-in would program the behavior of the modifications of the targets based on the changes of the constructors. See the documentation on AlCommand, AlUserCommand, and AlNotifyDagNode, as well as the examples constrainCVExample.cpp and polyHistoryExample.cpp. When you are modifying geometry, the doUpdates() method of the geometry should be called with FALSE, and never called with TRUE. This is necessary since the command is being called from within the message system and updates generate messages. If updates are done during a command, then unnecessary messages are generated and that could create a loop where the command is responding to a message it generated.

Attaching a plug-in to a menu or palette

The first step in attaching plug-in functionality to a menu is to create an AlFunction object. The AlFunction class encapsulates information about what actions to perform when your plug-in is selected. It represents the back end of a menu item. In particular, a plug-in would create an AlMomentaryFunction or an AlContinuousFunction to describe its operation. To actually define the menu item which will invoke that AlFunction, use the AlFunctionHandle class, which provides a C++ interface to Scheme.

Attaching a plug-in to a menu or palette | 37

The file AlFunctionHandle.h must be included by the plug-in to use AlFunctionHandle. AlFunction.h must be included to use either AlMomentaryFunction or AlContinuousFunction. In the plugin_init() function of the plug-in the various methods of the AlFunctionHandle are used to define the menu item (or menu items) that is added to OpenAlias, and the AlFunction classes are used to register the functions which make up the functionality of the plug-in. In the case of using Scheme instead of AlFunctionHandle, plugin_init() would at some point invoke a Scheme file that performs the necessary UI initialization. General momentary plug-in code would look like the following: Includes:
#include <AlLiveData.h> #include <AlFunction.h> #include <AlFunctionHandle.h>

Declaration of function and function handles:

static AlFunctionHandle h; static AlMomentaryFunction hFunc;

Attaching to the Alias menus, during plugin_init():

// All plug-ins must initialize the universe AlUniverse::initialize( ); // Create the function and associate the // callback to be invoked. hFunc.create( "plugin_func_name", plugin_callback ); h.create( "PluginFunction", &hFunc ); h.setAttributeString( "PluginFunction" ); // Alias will search for icons named // plugin_func_name.M and plugin_func_name.S // in this directory. h.setIconPath( makeAltPath( dirName, NULL ) ); // Which menu to install on. h.installOnMenu( "al_goto", FALSE /* top */ ); // Let the user know where the plug-in is AlPrintf( kPrompt, "Plug-in function installed under the Utilit ies menu."); // All is ok, let Alias know. return 0;

Removing the plug-in from the menus at plugin_exit() time:

38 | Part 1 Alias Programmers Interfaces (API)

// Cleanup any private programmed defined data. if ( pluginData != NULL ) removeData( pluginData ); // Remove the plugin from the menu and free the FunctionHandle. h.deleteObject(); hFunc.deleteObject(); // All is ok, let Alias know. return 0;

Continuous plug-ins follow a similar programming pattern. Declaration of function handles:

static AlFunctionHandle h; static AlContinuousFunction hFunc;

Attaching to the Alias menus, during plugin_init():

AlUniverse::initialize(); // Continuous callbacks are specified. hFunc.create( "Continuous", init_func, down_func, move_func, up_func, cleanup_func, TRUE ); hFunc.setPrompt( my_prompt, inbuf, kFilterNone ); h.create( "Cont Test", &hFunc ); h.setAttributeString( "cont" ); h.setIconPath( makeAltPath( dirName, NULL ) ); h.addToMenu( "mp_objtools" ); AlPrintf( kPrompt, "Continuous example installed on Palette Ob ject Edit."); return 0;

Removing a plug-ins menus at plugin_exit() time is the same for both continuous and momentary plug-ins.

Menu and palette IDs for attaching a plug-in

NOTE Some of the menu items listed may not be available to you. For example, they may not have been purchased as part of your package or may not be available on your platform.

Menu and palette IDs for attaching a plug-in | 39

Menus
Menu Name
Animation

OpenAlias Menu Identifier

ap_animwinds

Canvas Construction mp_grid

Curves

al_curvetoolbox

Curve Edit

mp_crvtools

Delete

al_delete

Edit

al_edit

Evaluate

mp_evaltool

File

al_file

Help

al_help

Layers

ma_layers

Layouts

mp_window

Locators

al_locate

Mesh ObjectDisplay mp_objdisplay

Object Edit

mp_objtools

40 | Part 1 Alias Programmers Interfaces (API)

Menu Name
Paint Paint Edit Pick

OpenAlias Menu Identifier

mp_pick

Point Clouds

al_cloudtoolbox

Preferences

al_envtools

Render

rp_render

Surfaces

mp_buildsurf

Surface Edit

mp_srftools

Transform

mp_xform

Utilities

al_goto

View

mp_views

WindowDisplay

mp_display

Windows

mp_windows_menu

Submenus
Menu Names
Animation > Create Animation > Edit

OpenAlias Menu Identifiers

Menu and palette IDs for attaching a plug-in | 41

Menu Names
Animation > Editors Animation > IK Animation > Keyframe Animation > Pick Animation > Show Animation > Tools Blend Curve > Constraint Continuity

OpenAlias Menu Identifiers

mo_blend_crv_continuity

Blend Curve > Constraint Curvature Type

mo_blend_crv_extension

Blend Curve > Constraint Direction Type

mo_blend_crv_direction

Blend Curve > Constraint Interpolation Direction Blend Curve > Curve Degree

mo_blend_crv_toggle

mo_blend_crv_degree

Blend Curve > Curve Knot Spacing

mo_blend_crv_parameter

Keypoint Curve > Arcs

mo_arc_funcs

Keypoint Curve > Lines

mo_line_funcs

Keypoint Curve > Line Tangent & Perp

mo_linetan_funcs

Keypoint Curve > Break & Join

42 | Part 1 Alias Programmers Interfaces (API)

Menu Names
Curves > New Curves

OpenAlias Menu Identifiers

mo_curve_funcs

Curves > Primitives Curve Edit > Create curve_create_sub

Curve Edit > Cut

mo_cut_funcs

Curve Edit > Modify

modify_types_sub

Curve Networks > Add/Delete Sculpt

mo_cnet_add_control_sub

Curve Networks > Add/Subtract Curves

mo_cnet_add_sub

Curve Networks > Continuity

mo_cnet_continuity_sub

Curve Networks > Influence Weights

mo_cnet_weight_sub

Curve Networks > Region of Influence

mo_cnet_region_sub

Delete > Painting Delete > Animation WindowDisplay > Anti-Alias Window Display > Toggles mp_display_window_sub

Edit > Duplicate Evaluate > Continuity curvature_sub

Evaluate > Surface Evaluate

Menu and palette IDs for attaching a plug-in | 43

Menu Names
File > Export

OpenAlias Menu Identifiers

al_export_types_sub

File > Image References File > Import al_import_sub

File > Open Recent Layers > Delete layer_delete

Layers > Select

layer_select

Layers > Set state

layer_states

Layers > Symmetry

layer_symmetric

Layers > Visibility

layer_visibility

Layouts > All Windows

windows_all_sub

Layouts > User Windows

windows_load_save

Locators > Deviation

al_locate_deviation_sub

Locators > Measure Mesh > Mesh Partitioning Mesh > Mesh Curves Mesh > Mesh Cleanup Mesh > Tessellation

44 | Part 1 Alias Programmers Interfaces (API)

Menu Names
Object Edit > Align Object edit > Attach

OpenAlias Menu Identifiers

attach_types_sub

Object Edit > Dynamic Shape Modeling Paint > Airbrush Paint > Effect Brush Paint > Eraser Paint > Marker Paint > PaintSymmetry Paint > Pencil Paint > Select Paint > Shape Paint > Solid Brush Paint Edit > Modify Layer Paint Edit > Color Correction Paint Edit > Layer Effect Paint Edit > Layer Operation Render > Ambient Occlusion

Menu and palette IDs for attaching a plug-in | 45

Menu Names
Render > Create Lights

OpenAlias Menu Identifiers

rp_light_sub

Render > Create Texture Projections

mo_object_projprims

Render > Editors Render > Multi-lister mlist_sub

Pick > Object Types

obj_types_sub

Pick > Point Types

point_types_sub

Point Clouds > Surfaces

cloud_surf_sub

Preferences > Interface

interface_sub

Preferences > Menus Preferences > User Options user_options_sub

Preferences > User Preferences Preferences > Workflows Surface Edit > Create CurvesOnSurface create_COS_types_sub

Surface Edit > Orientation Surface Edit > Shells solid_types_sub

Surface Edit > Stitch

stitch_types_sub

Surface Edit > Trim

trim_types_sub

46 | Part 1 Alias Programmers Interfaces (API)

Menu Names
Surfaces > Boundary Surfaces

OpenAlias Menu Identifiers

boundary_types_sub

Surfaces > Draft Surfaces Surfaces > Multi-Surface Blend Surfaces > Planar Surfaces Surfaces > Primitives mo_object_primitives

Surfaces > Rolled Edge Surfaces > Swept Surfaces sweep_types_sub

Utilities > Command Stepper

command_stepper_sub

Utilities > SBD View > Local Move Camera camera_local_move ments_types_sub

View > World Move Camera

camera_world_move ments_types_sub

View > View 1:1 Windows > Editors editor_sub

Windows > Information

information_sub

Transform > Local

pivot_types_sub

Transform > Modify

prop_mod_types_sub

Menu and palette IDs for attaching a plug-in | 47

Menu Names
Transform > Object Placement

OpenAlias Menu Identifiers

Building Options Boxes

There are two ways of building Alias Option boxes for plug-ins. The new and preferred method involves using the AlEditor C++ class to define and manage the Option box. Prior to the introduction of this method, option boxes were built with Scheme files.

Building Dynamic Editors using the AlEditor class

The new technique for building editors in OpenAlias plug-ins is considered dynamic since a plug-in developer has control over when the editor is displayed. The older scheme editor boxes were only capable of being displayed when the user selected the tool from the menu. Creating and managing editors follows general API programming principles: To create the editor:
apieditor = new AlEditor; if ( apieditor == NULL ) return sFailure; if ( apieditor->create( "Dynamic Editor Example" ) != sSuccess ) return sFailure;

Once the editor has been created, UI components can be added to it:

48 | Part 1 Alias Programmers Interfaces (API)

ComponentDescriptor *descriptor = NULL; descriptor = new ComponentDescriptor("Enter some text"); if ( apieditor->addString( descriptor, "Hello world!", idStringC allback ) != sSuccess ) return sFailure; addToDesciptorList( descriptor ); descriptor = new ComponentDescriptor("Separator"); if ( apieditor->addSeparator( descriptor ) != sSuccess ) return sFailure; addToDesciptorList( descriptor ); descriptor = new ComponentDescriptor("Check Box"); if ( apieditor->addCheckBox( descriptor, checkValue, idCallback ) != sSuccess ) return sFailure; addToDesciptorList( descriptor );

The AlEditor class assigns dynamic identifiers to the descriptor for the UI component. Each descriptor must be kept for later look up and matching so that the correct action can be performed. We then open the editor:
if ( apieditor->open() != sSuccess ) return sFailure;

To close the editor:

if ( apieditor->close() != sSuccess ) return sFailure; if ( apieditor->deleteEditor() != sSuccess ) return sFailure; deleteDescriptorList(); delete apieditor;

Events associated with the UI component on the editor are passed to the plug-in via a callback that is defined by the programmer.

Building Dynamic Editors using the AlEditor class | 49

if ( apieditor->addCheckBox( descriptor, checkValue, idCallback ) != sSuccess ) return sFailure; ... static void idCallback( ComponentId id ) { ComponentDescriptor *descriptor = idToDescriptor( id ); if ( descriptor == NULL ) return; if ( matchDescriptorToLabel( descriptor, "Check Box" ) ) { HandleCheckBoxFunction(); } }

Scheme Editors
The alternate and original way of creating Alias editors utilizes a scheme interface. This technique is described next.

First scheme file

If the plug-in requires an option box, the first scheme file is used to define it. All Alias option boxes are written in Scheme, which is described below. For many examples of option box files, examine the .o.scm files that reside in subdirectories in the Alias install area.

Second scheme file

If the plug-in requires an option box and the option box requires default values for its variables, these default values are set in this file, which is invoked from plugin_init().

Creating symbols and strings in Scheme

To pass information around in scheme,we define symbols as place-holders for values, and strings as names for those values. This is done through two primitives, ui-symbol and ui-string. These functions add elements to symbol tables inside of Alias, unlike the define primitive which adds a symbol to Schemes symbol table. In places where the name of a symbol is desired (for example, the label for a menu item), a search is done of the string symbol table for a string with the same symbol name as the given symbol. If one is

50 | Part 1 Alias Programmers Interfaces (API)

found, the associated string is used. If not, the actual symbol name is used instead. So, for example:
(ui-symbol my_symbol 16)

The default value of the symbol will be 16. No ui-string is associated with this symbol. Therefore, the text my_symbol will appear whenever the name of this symbol is displayed.
Example 2: (ui-string my_symbol Number of Cows) my_symbol 16) (ui-symbol

In this case a ui-string is defined with the same symbol name. When the name of the symbol my_symbol is required, a search is done for a ui-string with the same name. Here one is found, and the text Number of Cows will be used as the name of this symbol.

Creating an Option Box with Scheme

You create option boxes with a call to the ui-editor primitive. There are several arguments that apply to option boxes in general. The remaining arguments specify the widgets (editor tools) that make up the option box.

General option box attributes

The following attributes describe the general behavior of an option box.

(list title <symbol>) - a previously defined ui-string that defines the title of the option box.
Example: (list 'title "View Frame Options")

(list symbols <symbol> <symbol> ...) - a list of all the ui-symbols referenced by this option box. These should correspond to the names of all the widgets that appear in the option box.
Example: (list 'symbols ing.boolean ) 'nothing.intval 'nothing.doubval 'noth

(list init_option_function <func>) - the name of a momentary function to invoke before the option box gets opened. This can be used, for example, to set the values of ui-symbols based on the current state of Alias.
Example: Scheme file: (ui-editor 'control.options (list 'symbols 'con trol.pos_x) (list 'init_option_function "control.init_func" ) (list 'title "Control Options") (ui-double-widget 'control.pos_x (list 'range -10.0 10.0) (list

Scheme Editors | 51

'precision "%f4.6") ) ) ) Scheme init file: (ui-symbol 'control.pos_x 0.0) (ui-string 'control.pos_x "X") Plug-in: static void option_box_init_func( void ) { AlSetDouble( "control.pos_x", 45 ); } static AlMomentaryFunction function; static AlFunctionHandle handle; extern "C" int plugin_init( const char* dirName ) { AlUniverse::initialize(); function.create( "control.init_func", option_box_init_func ); // other code goes here }

(list reset_option_function <func>), (list save_option_function <func>), (list go_option_function <func>) - used to specify momentary functions that get invoked in addition to the standard behaviors of these buttons.
Note: Allocating memory in the init_option_function will result in memory leaks if the Exit button is selected. There is no cor responding exit_option_function where allocated memory can be released. This function follows the same programming principles as the ex ample in the previous bullet except that 3 functions will be needed.

Option box widgets

An option box can specify any number of ui-widgets, a set of editor tools like sliders, ticks, and buttons that can be used to set ui-symbols. Radio and popup widgets are collectively called selector widgets. The order of the elements of the widget is unimportant with the exceptions that the variable is the first item and the choices will appear in the order specified. The following apply to both popup widgets and radio widgets. The columns property only applies to ui-radio-widget. It is ignored if specified in a popup widget.

A simple radio widget

; Define the label strings. (ui-string title_symbol_1 First Choice) (ui-string title_symbol_2 Second Choice) (ui-string title_symbol_3 Third Choice) (ui-radio-widget variable (ui-choice title_symbol_1 VALUE1) (ui-choice title_symbol_2 VALUE2) (ui-choice title_symbol_3 VALUE3) )

A simple popup widget

(ui-popup-widget variable (ui-choice VALUE1) (ui-choice title_symbol_2 title_symbol_3 VALUE3) ) title_symbol_1 VALUE2) (ui-choice

52 | Part 1 Alias Programmers Interfaces (API)

Slider widgets allow the entry of data either by keyboard or with the slider. Below is a double slider.
(ui-string 'ao_set_device_offset "Offset") 'symbols 'ao_set_device_offset ) (ui-double-widget 'ao_set_device_offset list 'precision "%f6.3") (list 'slider_range 1 10) ) (list

A simple tick widget.

(list 'symbols ing.boolean) 'nothing.boolean ) (ui-tick-widget 'noth

Tick left/right
Left: (list symbols mo_bevel_front_cap) (ui-tick-left-widget mo_bevel_front_cap) Right: (list symbols mo_bevel_front_cap) (ui-tick-right-widget mo_bevel_back_cap) If there is a whole group with a tick-left at the end,use the regular ui-tick-widget for the last one,other wise there will be a hole on the right.

Rebuilding Selectors
If a rebuild is desired when a change of value occurs we add the rebuild property.
(ui-radio-widget variable (list rebuild) (ui-choice title_symbol_1 VALUE1) (ui-choice title_symbol_2 VALUE2) (ui-choice title_symbol_3 VALUE3) )

Selectively Enabling Selectors

Sometimes the selector should be displayed only under certain conditions. The enabled property is used to specify this condition. The expression is built from the relational primitives ui-eq (equal), ui-ne (not equal), ui-lt (less than), ui-le (less than or equal), ui-gt (greater than), ui-ge (greater than or equal). The relational primitives can be combined using the logical primitives ui-and, ui-or, and ui-not.
(ui-radio-widget variable (list enabled (ui-eq other_variable SOME_VALUE)) (list rebuild) (ui-choice title_symbol_1 VALUE1) (ui-choice title_symbol_2 VALUE2) (ui-choice title_symbol_3 VALUE3) )

Scheme Editors | 53

Changing Number of Columns

The default for radio widgets is two columns. To specify the number of columns use the columns property. The value range is 1, 2 or 3.
(ui-radio-widget variable (list columns 3) (list enabled (ui-eq other_variable SOME_VALUE)) (list rebuild) (ui-choice title_symbol_1 VALUE1) (ui-choice title_symbol_2 VALUE2) (ui-choice title_symbol_3 VALUE3) )

Making Assignments to Variables

When a choice is selected you may assign a value to another variable. For example in the primitives option box the number of caps is set when cylinders or cones are specified.
(ui-radio-widget mo_prim_type (list rebuild #t) (ui-choice prim.type.cube MO_CUBE) (ui-choice prim.type.plane MO_PLANE) (ui-choice prim.type.circle MO_CIRCLE) (ui-choice prim.type.cylinder MO_CYLINDER (list assign mo_prim_caps 2) ) (ui-choice prim.type.cone MO_CONE (list assign mo_prim_caps 1) ) (ui-choice prim.type.sphere MO_SPHERE) )

These assignments may be made conditionally. If for example the number of caps for a cone should be set to one only if it was two then we could specify this as
(ui-choice prim.type.cone MO_CONE mo_prim_caps 2) mo_prim_caps 1) ) (list assign (ui-eq

This way if it was set to zero then it wouldnt change.

Additional Widgets

Separator widget
(ui-separator-widget)

Note that if the ui-radio-widget has an enabled bit to it, the separator widget has to have the same.

54 | Part 1 Alias Programmers Interfaces (API)

A Complete List of Widgets Selection Widgets

ui-radio-widget - radio choices ui-popup-widget - choices on popup ui-boolean-widget - on/off choice (shown as tick)

Numbers

ui-integer-widget ui-double-widget ui-distance-widget - double which displays in current linear unit ui-angle-widget - double which displays in current angular unit

Triples

ui-wdltriple-widget - triple with 3 symbols ui-wdltriple-linear-widget - triple with 3 symbols representing distance. ui-triple-widget - triple using array (instead of 3 numbers).

Miscellaneous

ui-string-widget ui-separator-widget - visual separator ui-group-widget - group a section of widgets together under expand/compress

Widget Properties

ui-radio-widget

(list rebuild) (list 'enabled (some condition)) (list 'columns 3)

Scheme Editors | 55

ui-double-widget (and so on)

(list rebuild) - this widget gets a rebuild if another widget elsewhere in the option box is depending on its state. (list 'enabled (some condition)) - condition for when the widget is shown. (list 'precision %f6.2) - precision (list 'range 0 360) - valid range (list slider_range 0.0 500.0) - allows numbers outside of the range to be entered

Tooltips
(ui_function_tooltip_item "FunctionName" "ToolTip String")

See the supplied examples for uses of these widgets.

Native Platform Editors

It is possible also to create a plug-in interface. Please review the OpenAlias example files for Cocoa (Mac), winDialogBoxExample or winMsgBoxExample (Windows) depending on the platform you are on.

Important Plug-in Notes

Scheme symbols are common to the entire Alias environment, so they must be unique. Scheme symbols should be limited as to scope; instead of naming a symbol radius, name it my_plugin.radius If there are any spaces in AlFunction function names, the plug-in will have a blank icon.

Debugging a plug-in in Windows

Debugging a plug-in in Windows requires the Microsoft Visual Studio IDE.

56 | Part 1 Alias Programmers Interfaces (API)

1 Launch the Alias application. 2 Launch the Microsoft Visual C++ application. In the Microsoft Visual C++ application: 1 Select Build > Start Debug > Attach to Process. 2 Select Alias and click the OK button. In Alias:

Use the Plug-in Manager to load the plug-in to be debugged.

In the Microsoft Visual C++ application: 1 Select Debug > Break. 2 Open the source file associated with the plug-in that is to be debugged. 3 Set a break point where you wish to start debugging. 4 Select Debug > Go to continue debugging. In Alias:

Invoke the plug-in and the appropriate code path to hit the breakpoint.

In the Microsoft Visual C++ application:

Step through the source interactively.

To debug a plug-in on Windows, include the following option in the C and C++ flags:
/DEBUG

In addition, the following flag must be included on the link line:

/DEBUG

Debugging a plug-in in Windows | 57

Plug-in API Examples

Momentary plug-in example
Below is an example of a plug-in which does a viewframe on all picked objects. It is a simple example of a momentary plug-in.

ViewFrameExample - init.scm
;; This file simply gives the defaults for the Scheme variables ;; used in the option box. (ui-symbol "frame" 0) (ui-string "frame" "Frame")

ViewFrameExample .scm
;; This file defines the option box (ui-editor "frame.options" (list 'symbols 'frame ) (list 'title "View Frame Op tions") (ui-integer-widget "frame" (list 'range 0 65535) ) )

58 | Part 1 Alias Programmers Interfaces (API)

ViewFrameExample .cpp

Momentary plug-in example | 59

#include <AlUniverse.h> #include <AlViewFrame.h> #include <AlPickList.h> #include <AlObject.h> #include <AlLiveData.h> #include <AlFunction.h> #include <AlFunctionHandle.h> #include <AlIterator.h> #include <strings.h> // A simple iterator used to pass the frame number // along when viewing an object. class viewIterator: public AlIterator { public: viewIterator( double frame = 0.0 ) : frameNum( frame ) {}; virtual ~viewIterator() {}; virtual int func( AlObject* ); private: double frameNum; }; // The iterator's one and only method. Does a viewframe // on the passed in object using the frame number in the // iterator object. int viewIterator::func( AlObject* obj ) { if ( obj == NULL ) return 0; AlAnimatable* animitem; AlCurve* curve; AlSurface* surface; AlObjectType type = obj->type(); if( animitem = obj->asAnimatablePtr() ) AlViewFrame::viewFrame( animitem, frameNum, AlViewFrame::kOb jectAndBelow ); else if( curve = obj->asCurvePtr() ) AlViewFrame::viewFrame( curve, frameNum ); else if( surface = obj->asSurfacePtr() ) AlViewFrame::viewFrame( surface, frameNum ); else AlPrintf( kPrompt, "Sorry, %s is not a viewable object", obj->name() ); ; // a non viewable object return 0; } // The actual plug-in function.

60 | Part 1 Alias Programmers Interfaces (API)

void my_view() { int frameNum; // Get the frame number from the option box. if( sSuccess == AlGetInteger( "frame", frameNum ) ) { // Print the number to the promptline. AlPrintf( kPrompt, "Viewing frame %d.", frameNum ); // Instantiate an iterator and apply it to all picked // objects. int rc; viewIterator* view = new viewIterator( frameNum ); if ( sSuccess != AlPickList::applyIteratorToItems( view, rc ) ) AlPrintf( kPrompt, "Iterator failed." ); if ( rc != 0 ) AlPrintf( kPrompt, "Return code is %d.", rc ); AlPrintf( kPrompt, "Viewing complete." ); } } // This handle may have to be global if you wish to remove the // plug-in from the menu using the h.destroy() method in the // 'momentary_exit' function. // The menu entry is automatically removed when Alias exits. // static AlFunctionHandle h; static AlMomentaryFunction hFunc; extern "C" int PLUGINAPI_DECL int plugin_init( const char *dirName ) // // This routine initializes the plugins and attaches it to the menu. // It returns 0 if there is no initialization error. // { char *dirScm; // Initialize the universe. This must be done by all // plug-ins. If the universe is not initialized the plug-in // will fail. AlUniverse::initialize( ); dirScm = makeAltPath(dirName,"scm"); // Invoke the scheme file which sets defaults for the scheme // variables. AlInvokeSchemeFile( "frame_init.scm", dirScm );

Momentary plug-in example | 61

// Allocate a function handle. The first argument is the label on // the menu and the second is the function to invoke when the // menu item is selected. hFunc.create( my_view ); h.create( "View Frame", &hFunc ); // Define the attribute string for the attribute line below // the prompt line. h.setAttributeString( "viewframe" ); // Read in the option box. The first argument is the // option box in $ALIAS_WORKENV, and // the second argument is the name of the option box given // in the scheme file. The third argument is a directory // path(possibly NULL) where to look for the scheme file. // If a call to this method is omitted, there will be no option box. if ( sSuccess != h.setOptionBox( "frame.scm", "frame.options", dirScm) ) { AlPrintf( kPrompt, "Frame plug-in unable to find .scm file for option box" ); return (1); } // Indicate which menu to add the plugin to. addToMenu() // adds the plugin to the bottom of the menu, while // appendToMenu() will add it to the top of the menu. h.addToMenu( "mp_objtools" ); h.setIconPath( makeAltPath( dirName, NULL ) ); // Return a success code. // Returning a non zero indicates an error. // An error value ( a non-zero ) will be printed on the prompt // line in Alias. AlPrintf( kPrompt, "Frame attached to Palette 'Object Edit'"); return 0; } extern "C" PLUGINAPI_DECL int plugin_exit( void ) { // Remove the plugin from the menu and free the FunctionHandle. // Note that h.destroy() implicitly calls h.removeFromMenu() h.deleteObject(); hFunc.deleteObject(); return 0;

62 | Part 1 Alias Programmers Interfaces (API)

Continuous plug-in example

This example is a skeleton for continuous plug-ins. It echoes all user interaction to stdout.

Continuous plug-in example | 63

continuousFuncExample.cpp

64 | Part 1 Alias Programmers Interfaces (API)

// cont.plugin // // This file implements a simple continuous function plugin, a plugin // that gets events from Alias and can interact with the user. It can // be used as a skeleton from which to construct other, more com plicated // continuous functions if desired. // #include <AlLiveData.h> #include <AlFunction.h> #include <AlFunctionHandle.h> #include <AlUniverse.h> #include <AlDagNode.h> #include <AlPickList.h> #include <AlPickable.h> #include <AlWindow.h> #include <AlTM.h> char inbuf[ 256 ]; char text_buf[ 100 ]; const char * my_prompt = "Enter some text: %s"; void go_button_pressed( void ) { AlPrintf( kStdout, "Go button pressed!\n" ); AlContinuousFunction::createGoButton( go_button_pressed ); } static void init_func( void ) { AlPrintf( kStdout, "Now entering continuous plugin.\n" ); AlContinuousFunction::createGoButton( go_button_pressed ); } static void down_func( int input, Screencoord x, Screencoord y ) { int button; double dx=-1, dy=-1, dz=-1, ex=-1, ey=-1, ez=-1; AlWindow * w; switch( AlContinuousFunction::translateInput( input, button ) ) { case kInputButton: w = AlUniverse::currentWindow(); w->mapToWorldSpace( x, y, dx, dy, dz, ex, ey, ez ); AlPrintf( kStdout, "Mousedown at %d,%d [%lf,%lf,%lf %lf,%lf,%lf]. Button %d.\n", x,y, dx,dy,dz, ex,ey,ez, button );

Continuous plug-in example | 65

delete w; break; } } static void move_func( int input, Screencoord x, Screencoord y ) { int button; double dx=-1, dy=-1, dz=-1, ex=-1, ey=-1, ez=-1; AlWindow * w; switch( AlContinuousFunction::translateInput( input, button ) ) { case kInputButton: w = AlUniverse::currentWindow(); w->mapToWorldSpace( x, y, dx, dy, dz, ex, ey, ez ); AlPrintf( kStdout, "Mousemove at %d,%d [%lf,%lf,%lf %lf,%lf,%lf]. Button %d.\n", x,y, dx,dy,dz, ex,ey,ez, button ); delete w; break; case kInputKeyboard: sscanf( inbuf, "%s", text_buf ); AlPrintf( kStdout, "Text input: %s [%s]\n", text_buf, inbuf ); break; } } static void up_func( int input, Screencoord x, Screencoord y ) { int button; double dx=-1, dy=-1, dz=-1, ex=-1, ey=-1, ez=-1; AlWindow * w; switch( AlContinuousFunction::translateInput( input, button ) ) { case kInputButton: w = AlUniverse::currentWindow(); w->mapToWorldSpace( x, y, dx, dy, dz, ex, ey, ez ); AlPrintf( kStdout, "Mouseup at %d,%d [%lf,%lf,%lf %lf,%lf,%lf]. Button %d.\n", x,y, dx,dy,dz, ex,ey,ez, button ); delete w; break; } }

66 | Part 1 Alias Programmers Interfaces (API)

static void cleanup_func() { AlPrintf( kStdout, "Now leaving continuous plugin.\n" ); AlContinuousFunction::clearGoButton( TRUE ); } AlFunctionHandle h; AlContinuousFunction hFunc; extern "C" PLUGINAPI_DECL int plugin_init( char *dirName ) { AlUniverse::initialize(); hFunc.create( "Continuous", init_func, down_func, move_func, up_func, cleanup_func, TRUE ); hFunc.setPrompt( my_prompt, inbuf, kFilterNone ); h.create( "Cont Test", &hFunc ); h.setAttributeString( "cont" ); h.setIconPath( makeAltPath( dirName, NULL ) ); h.addToMenu( "mp_objtools" ); AlPrintf( kPrompt, "Continuous example installed on Palette 'Ob ject Edit."); return 0; } extern "C" PLUGINAPI_DECL int plugin_exit( void ) { h.removeFromMenu(); h.deleteObject(); hFunc.deleteObject(); return 0; }

Command History example

As mentioned above, installed command history plug-ins are invoked when specific events occur in Alias. Implementing a command history plug-in involves deriving a new class from AlUserCommand and implementing the bodies of the necessary methods of the new class. Below is an outline of the necessary components of a command history plug-in:

Command history plug-ins require constructor and target DAG nodes. It is a good idea to encapsulate these items into a small class, since this data will be passed to the store code and received from the retrieve code.

Command History example | 67

Create a new command class by deriving from the AlUserCommand class. The new command class must implement these methods:

::isValid() so that Alias can determine if your command history plug-in can be executed. ::execute() so that the command plug-in can control how the target objects will be rebuilt. ::declareReferences() so that the command history plug-in can inform Alias which DAG nodes are the constructors and targets. This method would use the methods addConstructorRef() and addTargetRef(). ::instanceDag() to handle the case of if a user instances a dag that is a part of the command history object. ::dagModified() and ::geometryModified() to rebuild the geometry. (The linkObjectExample.cpp command history plug-in implements only dagModified() currently.) ::listModifiedDagNodes() to inform Alias about dependencies on other DAG nodes ::storeWire() and ::retrieveWire() so that Alias can save and retrieve the construction history data from wire files. These methods use the command data class that store the constructor and target DAG nodes.

Command plug-in data is stored in Alias wire files. Alias can load a wire file that contains command plug-in data.

If the plug-in is already loaded, the command is reinstated for the objects. If the plug-in is not loaded, Alias displays a message on the prompt line, indicating that the plug-in could not be found. If the wire file is re-saved, the command plug-in data is also re-saved.

Moving a target node produces a confirm box asking if it is OK to break construction history. This is necessary since the targets are based on the state of the constructors and not the other way around. It is safer to change the geometry of the targets than to delete and recreate them when updating the objects. This avoids problems with animation.

68 | Part 1 Alias Programmers Interfaces (API)

Command history plug-in example

The linkObjectExample command history plug-in builds linked geometry. Its input is 2 curve nodes and its output is 2 straight lines (also curve nodes) which link the first 2 CVs and the last 2 CVs of the curves nodes together. When a constructor curve node is modified, the linked geometry is rebuilt.

Command history plug-in example | 69

linkObject.c++

70 | Part 1 Alias Programmers Interfaces (API)

#include <AlUniverse.h> #include <AlCurve.h> #include <AlCurveCV.h> #include <AlCurveNode.h> #include <AlLiveData.h> #include <AlFunction.h> #include <AlFunctionHandle.h> #include <AlCommand.h> #include <AlUserCommand.h> #include <AlNotifyDagNode.h> #include <AlPickList.h> #include <AlAttributes.h> #include <AlLineAttributes.h> #include <string.h> // Construction history plug-in example: // ===================================== // // The following code implements a simple construction history // command plug-in. Construction history plug-ins tie into the // command mechanism of Alias and allow the rebuilding of geometry // on the fly. // // This plug-in accepts two curve nodes from the pick list as in put. // The output of the command are two lines. The first line joins // the start points of the two picked curve nodes together. The // second line joins the end points of the two picked curve nodes // together. The ouput lines are rebuilt as changes are made to // the constructors to provide the appearance of link objects. // // Notes on construction history: // ============================== // // 1. Construction history commands contain constructor objects // which are used in the construction or creation of new objects. // // 2. The new objects created are called targets. // // 3. AlUserCommand is a class that is tied into the command // command mechanism of Alias. Events happen in Alias which // may force a rebuild or save, retrieve etc in a command. The // construction history plug-in implements handlers for the above events.

Command history plug-in example | 71

// These handlers are called when required by Alias. // // 4. The inputs or constructors of the command can be taken from // the pick list as this example illustrates. // // 5. For an Alias created object that has construction history, // moving the targets causes construction history to be broken. A // plug-in would have to program this enforcement if it did not want // the geometry to become out of sync. One of the reasons why // construction history should not update if a target is moved is // that it is very difficult to know how to update a constructor // based on the targets new state. To enforce this condition, // a plug-in would have to make sure it called addTargetRef() on // its targets. If this is done properly, the targets will auto matically // be given the default construction history colour which is green. // In addition, the user will be prompted if construction history // is about to be broken. // // 6. There are several helper classes required by construction // history plug-ins. These include AlNotifyDagNode, AlInput, // AlOutput and AlCommand. It would be very useful to read // the documentation for these classes before attempting to // write a construction history plug-in. // // 7. It is not usually the case that one AlUserCommand method calls // another. Instead the Alias command engine calls into the // AlUserCommand methods or the AlCommand class is used to make // calls to the AlUserCommand. // // 8. It is possible to save plug-in construction history data into // a wire file so that the next time the file is loaded with the // plug-in also loaded, the command will automatically be rein stated // for the objects. // If the plug-in is not loaded the construction history data is loaded, // and a message is emitted to the promptline history saying

72 | Part 1 Alias Programmers Interfaces (API)

// that the plug-in associated with the construction history // command cannot be found. The construction history data will // be resaved when the wire file is written out again regardless // of if the plug-in is loaded. // // Notes on this plug-in: // ====================== // // 1. This plug-in deletes the targets every time the command // is executed for simplicity. This would cause many problems // if there was animation on the constructors and we played // the frames. See the AlPlayFrame class for more details. It // is better to modify the geometry than to delete and recreate // it. // // 2. Many parts of the code below are generic to all construction // history plug-ins. The specific code that should be replaced // for a new plug-in is any code snippet that references the con structors // or targets. The cmdData class would also have to be updated // to support the data types required by your plug-in. // // 3. Dont underestimate the usefullness of the printfs() in // the code below. Construction history plug-ins are difficult // to write or understand because of the multiple entry points that are // required by the code. The printfs() will help a great deal in // analyzing how this example works. // Also if you call AlCommand::setDebug( TRUE ), messages related // to the command will be written to the errlog. // // // Prototypes // static statusCode firstPosition( AlObject *obj, double& x, double& y, double& z ); static statusCode lastPosition( AlObject *obj, double& x, double& y, double& z ); static statusCode createLine( AlCurveNode *&cp, double a[3], double b[3] );

Command history plug-in example | 73

static void updateLinePosition( AlCurveNode *curveNode, double x, double y, double z, double x2, double y2, double z2 ); #define CMD_NAME "linkObject" // Used by OpenAlias for creation and // destruction of the command plug-in. #define CMD_CLASS_ID 50 // A user defined type in case you have // more than 1 command. const int kIntId = 100; const int kCharId = 101; const int kDoubleId = 102; // // A user defined data class. This class contains two // constructor dag nodes and their targets. firstDagObject // and secondDagObject are the constructors. firstLineDag and // secondLineDag are the targets and are // rebuilt based on the changes to the constructors. // class cmdData { public: cmdData* cmdDataPtr() { return this; } AlCurveNode* firstDagObject; AlCurveNode* secondDagObject; AlCurveNode* firstLineDag; AlCurveNode* secondLineDag; AlData *charData; AlData *intData; AlData *doubleData; }; class genericCmd: public AlUserCommand, private cmdData { enum error { kOkay = 0, kInvalid = 1, kDagNodeNotHandled }; public: genericCmd(); ~genericCmd(); virtual int isValid(); virtual int execute(); virtual int declareReferences(); virtual int instanceDag( AlDagNode *oldDag, AlDagNode *newDag ); virtual int undo();

74 | Part 1 Alias Programmers Interfaces (API)

virtual int geometryModified( AlDagNode *dag ); virtual int listModifiedDagNodes( const AlNotifyDagNode *dagMod, AlObject *obj ); virtual int debug( const char *prefix ); virtual void * asDerivedPtr(); virtual statusCode retrieveWire( AlInput *input ); virtual statusCode storeWire( AlOutput *output ); virtual int dagModified( AlDagNode *dag ); // for your own use virtual int type(); // We didnt bother to implement these commands since they dont apply // to us (they would be similar to instanceDag() and geometryMod ified() ) // // virtual int curveOnSurfaceModified( AlCurveOnSurface *surf ); // The following command is not yet supported // virtual statusCode storeSDL( ofstream &outputSDL ); public: // Methods that the UI commands can use to set our fields statusCode set( AlDagNode *firstDag, AlDagNode *secondDag ); private: boolean requireStrongValidity; }; // // Start command definition // genericCmd::genericCmd() // // Initialize the structure // { firstDagObject = NULL; secondDagObject = NULL; firstLineDag = NULL; secondLineDag = NULL; requireStrongValidity = TRUE; charData = NULL; intData = NULL;

Command history plug-in example | 75

doubleData = NULL; } genericCmd::~genericCmd() // // Provide a safe cleanup. // { if ( firstDagObject != NULL ) delete firstDagObject; if ( secondDagObject != NULL ) delete secondDagObject; if ( firstLineDag != NULL ) delete firstLineDag; if ( secondLineDag != NULL ) delete secondLineDag; if ( charData ) delete charData; if ( intData ) delete intData; if ( doubleData ) delete doubleData; } void *genericCmd::asDerivedPtr() // // Provide safe down casting. // { return this; } int genericCmd::type() // // User defined value so you can determine the class type // of the command. // { return CMD_CLASS_ID; } int genericCmd::isValid() // // Since the construction history plug-in maintains its own data, // it is necessary for it to implement the isValid() method to // tell the command layer that it is ok to call this command.

76 | Part 1 Alias Programmers Interfaces (API)

// { // Testing will involve NULL pointer checks, making sure you // have the correct kind of Dags and so on. if( firstDagObject == NULL || secondDagObject == NULL ) return kInvalid; if ( requireStrongValidity ) if ( firstLineDag == NULL || secondLineDag == NULL ) return kInvalid; int result1, result2; switch( firstDagObject->type() ) { case kCurveNodeType: result1 = kOkay; break; default: result1 = kDagNodeNotHandled; break; } switch( secondDagObject->type() ) { case kCurveNodeType: result2 = kOkay; break; default: result2 = kDagNodeNotHandled; break; } if ( result1 == kOkay && result2 == kOkay ) return kOkay; return kDagNodeNotHandled; } int genericCmd::execute() // // This method is called when the geometry needs to be updated. // This will occur if the constructor dag nodes are modified. // { double a[3],b[3];

Command history plug-in example | 77

if ( firstPosition( firstDagObject,a[0], a[1], a[2] ) == sSuccess && firstPosition( secondDagObject, b[0], b[1], b[2] ) == sSuccess ) { if ( firstLineDag == NULL ) { if ( createLine( firstLineDag, a, b ) == sSuccess ) printf("created new line\n"); else printf("failed to create new line\n"); } else { updateLinePosition( firstLineDag, a[0], a[1], a[2], b[0], b[1], b[2] ); } } if ( lastPosition( firstDagObject,a[0], a[1], a[2] ) == sSuccess && lastPosition( secondDagObject, b[0], b[1], b[2] ) == sSuccess ) { if ( secondLineDag == NULL ) { if ( createLine( secondLineDag, a, b ) == sSuccess ) printf("created new line\n"); else printf("failed to create new line\n"); } else { updateLinePosition( secondLineDag, a[0], a[1], a[2], b[0], b[1], b[2] ); } } // Force the redrawing of the screen AlUniverse::redrawScreen( kRedrawAll ); return kOkay; } int genericCmd::instanceDag( AlDagNode *oldDag, AlDagNode *newDag ) //

78 | Part 1 Alias Programmers Interfaces (API)

// Handle a dag node being instanced. Go through the class and replace // any references to oldDag with newDag // { printf("genericCmd::instanceDag()\n"); if ( oldDag == NULL || newDag == NULL ) return -1; if( AlAreEqual( firstDagObject, oldDag ) ) { // Toss our old wrapper and replace it with a new one. delete firstDagObject; firstDagObject = newDag->copyWrapper()->asCurveNodePtr(); } if( AlAreEqual( secondDagObject, oldDag ) ) { // Toss our old wrapper and replace it with a new one. delete secondDagObject; secondDagObject = newDag->copyWrapper()->asCurveNodePtr(); } return kOkay; } int genericCmd::declareReferences() // // Declare any references to constructors and targets. // The constructors are the inputs to the command and // the targets are the outputs. By setting this association, // Alias will know to call the methods implemented in // the plug-in for modifications to the constructor and // target dags. // { printf("genericCmd::declareReferences()\n"); if ( firstDagObject != NULL ) addConstructorRef( firstDagObject ); if ( secondDagObject != NULL ) addConstructorRef( secondDagObject ); if ( firstLineDag != NULL ) addTargetRef( firstLineDag ); if ( secondLineDag != NULL ) addTargetRef( secondLineDag );

Command history plug-in example | 79

return kOkay; } int genericCmd::geometryModified( AlDagNode *dag ) // // The geometry for the constructor dags has been modified. // { if ( dag == NULL ) return -1; if ( dag->name() != NULL ) printf("genericCmd::geometryModified( %s )\n",dag->name()); // If the parameter dag is the same as one of our dags // then we dont have to do much. if( AlAreEqual( firstDagObject, dag) ) { return kOkay; } if( AlAreEqual( secondDagObject, dag) ) { return kOkay; } // If we have gotten to this point, then one of the // dags our command knows about has changed. Free // the dags up and let the command know it has been // modified. delete firstDagObject; firstDagObject = NULL; delete secondDagObject; secondDagObject = NULL; // Signal that the command has been modified by making the // appropriate call. AlCommand *cmd = command(); cmd->modified(); delete cmd; return kOkay; } int genericCmd::dagModified( AlDagNode *dag ) // // The dag was modified. This method will be called if the // dag is translated and so on. // { if ( dag == NULL )

80 | Part 1 Alias Programmers Interfaces (API)

return -1; if ( dag->name() != NULL ) printf("genericCmd::dagModified( %s )\n",dag->name()); // This method does not need to do much for this plug-in. if( ( AlIsValid( dag ) && AlIsValid( firstDagObject ) && AlAreEqual( dag, firstDagObject ) ) || ( AlIsValid( dag ) && AlIsValid( secondDagObject ) && AlAreEqual( dag, secondDagObject ) )) { } return kOkay; } int genericCmd::debug( const char *prefix ) { if ( prefix != NULL ) printf("genericCmd::debug( %s )\n",prefix); return kOkay; } int genericCmd::undo() // // Undo everything the execute did. The cmdData class would need // to store the previous state of the world so we can undo one // step. // // Note: for this simple example undo does not need to be written. // If a user transforms the constructors curves and then undos the // transform from the Alias Edit menu, the ::execute() command will // be called and the curves redrawn properly because of the dag // modification handler. // { printf("genericCmd::undo() called\n"); return kOkay; } int genericCmd::listModifiedDagNodes( const AlNotifyDagNode *dag Mod, AlObject *obj ) //

Command history plug-in example | 81

// This routine should call dagMod->notify on every dag node that might // be affected if obj is modified. // In our example, if one of the constructor is modified, we // call the notify() method on the targets of the command. // { printf("genericCmd::listModifiedDagNodes() called\n"); if ( dagMod == NULL || obj == NULL ) return -1; if ( AlAreEqual( obj, firstDagObject ) || AlAreEqual( obj, secondDagObject ) ) { dagMod->notify( firstLineDag ); dagMod->notify( secondLineDag ); } return -1; } statusCode genericCmd::retrieveWire( AlInput *input ) // // Handler called by the Alias retrieve code for the construction // history objects. // { printf("genericCmd::retrieveWire()\n"); // Replace the old pointers with the newly relocated ones. The // order of resolving must be the same as the declare when // we store. AlObject *objDag = input->resolveObject(); AlObject *objDag2 = input->resolveObject(); AlObject *objDag3 = input->resolveObject(); AlObject *objDag4 = input->resolveObject(); if ( !objDag || ! objDag2 || !objDag3 || !objDag4 ) return sFailure; // // // // // If a pointer was not resolved, then NULL is returned This can happen if the geometry has been deleted when the plug-in is not loaded. Alternatively, we could have just returned sSuccess.

82 | Part 1 Alias Programmers Interfaces (API)

// When our command is executed, it will be invalid and so it will be // deleted. firstDagObject = objDag->asCurveNodePtr(); secondDagObject = objDag2->asCurveNodePtr(); firstLineDag = objDag3->asCurveNodePtr(); secondLineDag = objDag4->asCurveNodePtr(); if ( !firstDagObject || !secondDagObject || !firstLineDag || !secondLineDag ) return sFailure; // Test info; if ( charData ) delete charData; int i; if ( ( charData = input->resolveData( AlData::kDataChar, kCharId )) == NULL ) return sFailure; printf("char data <%s>\n",charData->asCharPtr()); // Null termin ated string. if ( intData ) delete intData; if ( ( intData = input->resolveData( AlData::kDataInt, kIntId ) ) == NULL ) return sFailure; const int *idata = intData->asIntPtr(); printf("int data <"); for ( i = 0; i< intData->count(); i++ ) printf("%d ",idata[i]); printf(">\n"); if ( doubleData ) delete doubleData; if ( ( doubleData = input->resolveData( AlData::kDataDouble, kDoubleId ) ) == NULL ) return sFailure; printf("double data <"); const double *ddata = doubleData->asDoublePtr(); for ( i = 0; i< doubleData->count(); i++ ) printf("%g ",ddata[i]); printf(">\n");

Command history plug-in example | 83

return sSuccess; } statusCode genericCmd::storeWire( AlOutput *output ) // // This routine is the handler called by the Alias store code so // that it can get a pointer to the construction history plug-ins // data. // { printf("genericCmd::storeWire()\n"); if ( output == NULL ) return sFailure; // Declare all of our references to data so that we can get them back // on retrieval. We are telling Alias to keep track of these // pointers in the wire file. output->declareObject( firstDagObject ); output->declareObject( secondDagObject ); output->declareObject( firstLineDag ); output->declareObject( secondLineDag ); // Test info AlData *data1 = new AlData;; char *cdata = "Save this data."; int count = strlen( cdata ) + 1; if ( data1->create( kCharId, cdata, count ) != sSuccess ) return sFailure; if ( output->declareData( data1 ) != sSuccess ) return sFailure; AlData *data2 = new AlData; int idata[10] = { 10, 11, 12, 13, 14, 15, 16, 17, 18, 19 }; count = 10; if ( data2->create( kIntId, idata, count ) != sSuccess ) return sFailure; if ( output->declareData( data2 ) != sSuccess ) return sFailure; AlData *data3 = new AlData;; double ddata[9] = { 10.1, 11.1, 12.1, 13.1, 14.2, 15.1, 16.1, 17.1, 18.1 }; count = 9; if ( data3->create( kDoubleId, ddata, count ) != sSuccess ) return sFailure; if ( output->declareData( data3 ) != sSuccess ) return sFailure;

84 | Part 1 Alias Programmers Interfaces (API)

return sSuccess; } statusCode genericCmd::set( AlDagNode *firstDag, AlDagNode *secondDag ) // // Our helper function for setting the cmdData constructors. // { if ( firstDag == NULL || secondDag == NULL ) return sFailure; firstDagObject = (AlCurveNode *) firstDag->copyWrapper(); secondDagObject = (AlCurveNode *) secondDag->copyWrapper(); requireStrongValidity = FALSE; return sSuccess; } // // End command definition // // // Begin command invocation (the UI chunk of the code) // AlUserCommand *allocLinkObjectCmd() // // Allocate & return a new command. This function will be passed // to the AlCommand::add() routine // { return new genericCmd; } void do_add_cmd( AlCurveNode *firstDag, AlCurveNode *secondDag ) { AlCommand::setDebug( TRUE ); // Static member function call AlCommand cmd; if( sSuccess == cmd.create( CMD_NAME ) ) { genericCmd *g_cmd = (genericCmd *)cmd.userCommand()->asDe rivedPtr(); g_cmd->set( firstDag, secondDag ); if( cmd.execute() == 0 ) cmd.install();

Command history plug-in example | 85

else cmd.deleteObject(); } } // // Procedure to find two picked curve nodes and pass them to the // construction history command so that they can be used as the // constructors of the command. // void do_linkObject() { AlObject *firstPickedItem, *secondPickedItem; firstPickedItem = NULL; secondPickedItem = NULL; for( statusCode stat = AlPickList::firstPickItem(); stat == sSuccess; stat = AlPickList::nextPickItem() ) { AlObject *pickedItem = AlPickList::getObject(); if( pickedItem ) { if( pickedItem->asCurveNodePtr() ) { if ( firstPickedItem == NULL ) firstPickedItem = pickedItem->copyWrapper(); else if ( secondPickedItem == NULL ) secondPickedItem = pickedItem->copyWrapper(); } delete pickedItem; } } if ( firstPickedItem && secondPickedItem ) { do_add_cmd( firstPickedItem->asCurveNodePtr(), secondPickedItem>asCurveNodePtr() ); } else printf("Failed to get the two picked curve nodes.\n"); if ( firstPickedItem ) delete firstPickedItem;

86 | Part 1 Alias Programmers Interfaces (API)

if ( secondPickedItem ) delete secondPickedItem; } static AlFunctionHandle h; static AlMomentaryFunction hFunc; extern "C" PLUGINAPI_DECL int plugin_init( const char *dirName ) { AlUniverse::initialize( kZUp ); // // Create a new construction history command // if ( AlCommand::add( allocLinkObjectCmd, CMD_NAME ) != sSuccess ) { AlPrintf( kPrompt, "The linkObject plug-in failed to in stall.\n"); return 1; } if ( hFunc.create( do_linkObject ) != sSuccess ) return 1; if ( h.create( "linkObject command", &hFunc ) != sSuccess ) return 1; if ( h.setAttributeString( "linkObject plugin cmd" ) != sSuccess ) return 1; if ( h.setIconPath( makeAltPath( dirName, NULL ) ) != sSuccess ) return 1; if ( h.appendToMenu( "mp_objtools" ) != sSuccess ) return 1; AlPrintf( kPrompt, "linkObject installed on Palette Object Edit"); return 0; } extern "C" PLUGINAPI_DECL int plugin_exit( void ) { (void) AlCommand::remove(CMD_NAME ); (void) h.deleteObject();

Command history plug-in example | 87

(void) hFunc.deleteObject(); // A redraw is required to ensure history // is no longer displayed for the plug-ins // entities. AlUniverse::redrawScreen( kRedrawAll ); // do nothing return 0; } // // Helper functions. // static statusCode firstPosition( AlObject *obj, double& x, double& y, double& z ) // // A simple function for returning the x,y,z values of the first CV. // { AlCurveNode *cnode = NULL; AlCurve *curve = NULL; AlCurveCV *cv = NULL; statusCode result = sFailure; if ( ( cnode = obj->asCurveNodePtr()) != NULL ) { curve = cnode->curve(); if ( curve != NULL ) { cv = curve->firstCV(); if ( cv != NULL ) { double w; if ( cv->worldPosition( x, y, z, w ) == sSuccess ) result = sSuccess; } } } // // // if The cnode wrapper is really the same as obj which is the same as one of the constructors of the command so do not delete it. ( curve )

88 | Part 1 Alias Programmers Interfaces (API)

delete curve; if ( cv ) delete cv; return result; } static statusCode lastPosition( AlObject *obj, double& x, double& y, double& z ) // // A simple function for returning the x,y,z values of the last CV. // { AlCurveNode *cnode = NULL; AlCurve *curve = NULL; AlCurveCV *cv = NULL; statusCode result = sFailure; if ( ( cnode = obj->asCurveNodePtr()) != NULL ) { curve = cnode->curve(); if ( curve != NULL ) { int numCVs = curve->numberOfCVs(); cv = curve->getCV( numCVs -1 ); if ( cv != NULL ) { double w; if ( cv->worldPosition( x, y, z, w ) == sSuccess ) result = sSuccess; } } } // The cnode wrapper is really the same as obj which is the // same as one of the constructors of the command so do not // delete it. if ( curve ) delete curve; if ( cv ) delete cv; return result; }

Command history plug-in example | 89

static statusCode createLine( AlCurveNode *&cp, double a[3], double b[3] ) // // A simple function for creating a line between points a and b. The // curve node created is returned in the cp parameter. // { AlCurveNode *cnode = NULL; AlCurve *curve = NULL; statusCode result = sFailure; curve = new AlCurve; if ( curve ) { if ( curve->createLine( a, b ) == sSuccess ) { cnode = new AlCurveNode; if ( cnode ) { if ( cnode->create( curve ) == sSuccess ) { cp = cnode; result = sSuccess; } } } } if ( curve ) delete curve; return result; } // // Function for updating the position of the line. // static void updateLinePosition( AlCurveNode *curveNode, double x, double y, double z, double x2, double y2, double z2 ) { if ( curveNode == NULL ) return; AlCurve *curve = curveNode->curve(); if ( curve == NULL )

90 | Part 1 Alias Programmers Interfaces (API)

return; AlAttributes *attr = curve->firstAttribute(); if ( attr == NULL ) return; AlLineAttributes* lineAttr = attr->asLineAttributesPtr(); if ( lineAttr ) { lineAttr->setStartPoint( x, y, z ); lineAttr->setEndPoint( x2, y2, z2 ); } delete curve; delete attr; }

Option box scheme example

The following are the scheme files of the createTree.plugin in the supplied examples. This code defines the option box used by the tree growing code. As mentioned above, the default values for these widgets are set from a separate file, invoked in the plug-ins initialization function. That file is also used to define the string names for the widgets. That way, these extra Scheme statements do not need to be reread each time the option box file is invoked. The file that defines the default values and the strings is called createTree_init.scm:

Option box scheme example | 91

createTree_init.scm: (ui-symbol 'seed 0) (ui-string 'seed "Seed") (ui-symbol 'max_branch 15) (ui-string 'max_branch "Max Branch Limit"); (ui-symbol 'bend 0.2) (ui-string 'bend "Bend") (ui-symbol 'fork_angle 30.0) (ui-string 'fork_angle "Fork Angle (deg)") (ui-symbol 'branch_frequency 50.0) (ui-string 'branch_frequency "Branch Frequency %") (ui-symbol 'gravity -0.1) (ui-string 'gravity "Gravity") (ui-symbol 'branch_length 5.0) (ui-string 'branch_length "Grow Length") (ui-symbol 'trunk_taper 95.0 ) (ui-string 'trunk_taper "Trunk Taper %") (ui-symbol 'min_branch_size 0.025 ) (ui-string 'min_branch_size "Minimum Branch Size") (ui-symbol 'twist 45.0 ) (ui-string 'twist "Twist Angle (deg)") (ui-symbol 'leaf.choice 0) (ui-string 'leaf.choice "Type of Leaves") (ui-string 'leaf_none "None") (ui-string 'leaf_oak "Oak") (ui-string 'leaf_maple "Maple") (ui-string 'leaf_pine "Pine")

The other file is called createTree.scm and contains the actual definition of the option box:

92 | Part 1 Alias Programmers Interfaces (API)

createTree.scm: (ui-editor 'tree.options (list 'title "Fractal Tree Options") (list 'symbols 'seed 'bend 'fork_angle 'branch_frequency 'gravity 'branch_length 'trunk_taper 'min_branch_size 'twist 'leaf.choice 'max_branch ) (ui-integer-widget 'seed (list 'range 0 65535) ) (ui-integer-widget 'max_branch (list 'range 1 100) ) (ui-double-widget 'bend (list 'precision "%f6.4") (list 'range -1.0 1.0) ) (ui-double-widget 'fork_angle (list 'precision "%f6.1") (list 'range 0.0 90.0) ) (ui-double-widget 'branch_frequency (list 'precision "%f6.1") (list 'range 0.0 100.0) ) (ui-double-widget 'gravity (list 'precision "%f6.4") (list 'range -1.0 1.0) ) (ui-double-widget 'branch_length (list 'precision "%f6.4") (list 'range 0.0 10.0) ) (ui-double-widget 'trunk_taper (list 'precision "%f6.1") (list 'range 0.0 100.0) ) (ui-double-widget 'min_branch_size (list 'precision "%f6.4") (list 'range 0.0001 1.0) ) (ui-double-widget 'twist (list 'precision "%f6.4") (list 'range 0.0 90.0)

Option box scheme example | 93

) (list 'title "Leaf Options") (ui-radio-widget 'leaf.choice (ui-choice 'leaf_none 0) (ui-choice 'leaf_oak 1) (ui-choice 'leaf_maple 2) (ui-choice 'leaf_pine 3) ) )

94 | Part 1 Alias Programmers Interfaces (API)

Class reference

Describes the APIs object classes and their methods.

95

96

AlAction AlBoxLight

AlAction
Basic interface to Alias action.

Synopsis
#include <AlAction.h> class AlAction : public AlObject virtual ~AlAction(); virtual statusCode deleteObject(); virtual AlObjectType type() const; virtual const char* name() const; virtual statusCode setName(const char *); const char* comment() const; AlActionExtrapType extrapTypePRE() const; AlActionExtrapType extrapTypePOST() const; statusCode setComment(const char *); statusCode setExtrapTypePRE(AlActionExtrapType); statusCode setExtrapTypePOST(AlActionExtrapType); AlAction* copy() const; statusCode copyD(); double eval( double, AlTripleComponent = kX_COMPONENT ) const; int numChannelReferences() const; AlChannel* channelReference(const int) const;

Description
AlAction is the base class for an Alias action. An action is an entity that will map time to a value. In Alias, there are two types of actions: parameter curve

97

actions, represented by the derived class AlParamAction, and motion path actions, represented by the derived class AlMotionAction. You can create new AlActions by creating an AlParamAction or an AlMotionAction. Existing actions can be accessed either through the global list of actions (AlUniverse::firstAction(), AlUniverse::nextAction()) or through the list of actions that a channel uses to animate a field of an item (AlChannel::appliedAction()). If you delete an action, it may cause other classes to be deleted (for example, AlKeyframe, and AlChannel if the action was the base action of a channel).

AlAction::~AlAction() Description
Deletes an AlAction wrapper object.

statusCode AlAction::deleteObject() Description

Deletes an action. The action is removed from any channel that uses it as a time warp. If the action is a base action of a channel, the channel is also deleted.

Return Codes
sSuccess - the data for the action was successfully deleted sInvalidObject - the action was not valid the data may have been deleted already)

AlObjectType AlAction::type() const Description

Returns the class identifier kActionType.

const char* AlAction::name() const Description

Returns the name of the action.

98 | Chapter 1 AlAction AlBoxLight

statusCode AlAction::setName(const char *newName) Description

Changes the name of the action. If the given name is not a unique name in the universe, then a unique name is generated based on the given name and this name is given to the action. In this case, a status code of sNameChangedToUniqueOne is returned.

Arguments
< newName - new name for action

Return Codes
sSuccess - name was changed to newName sInvalidArgument - the given string is NULL sInvalidObject - the action is not valid sNameChangedToUniqueOne - name was changed to be unique

const char* AlAction::comment() const Description

Returns the comment on the action.

statusCode AlAction::setComment(const char *newComment) Description

Makes a copy of newComment and replaces the existing comment on the action with this new comment.

Arguments
< newComment - the new comment to assign to the action

Return Codes
sSuccess - actions comment was changed to newComment sInvalidArgument - newComment was NULL

AlAction | 99

sInvalidObject - this action is not valid

AlActionExtrapType AlAction::extrapTypePRE() const Description

Gets the out-of-range, or extrapolation to infinite type of the action before its defined range. If the type could not be retrieved, kEXTRAP_INVALID is returned.

statusCode AlAction::setExtrapTypePRE(AlActionExtrapType extrapType) Description

Sets the out-of-range, or extrapolation to infinite type of the action before its defined range to the given extrapolation type.

Arguments
< extrapType - extrapolation type to set for action before defined range

Return Codes
sSuccess - the extrapolation type was successfully determined sInvalidObject - the action was not valid sInvalidArgument - the given extrapolation type was not valid

AlActionExtrapType AlAction::extrapTypePOST() const Description

Returns the out-of-range, or extrapolation to infinite type of the action after its defined range. If the type can not be retrieved, kEXTRAP_INVALID is returned.

statusCode AlAction::setExtrapTypePOST(AlActionExtrapType extrapType) Description

Sets the out-of-range, or extrapolation to infinite type of the action after its defined range to the given extrapolation type.

100 | Chapter 1 AlAction AlBoxLight

Arguments
< extrapType - extrapolation type to set for action after defined range

Return Codes
sSuccess - the extrapolation type was successfully determined sInvalidObject - the action was not valid sInvalidArgument - the given extrapolation type was not valid

AlAction* AlAction::copy() const Description

Makes a copy of this action and returns the copy. If the copy fails, NULL is returned. Note that this method copies the action NOT the wrapper object.

statusCode AlAction::copyD() Description

Makes a copy of the action (not the wrapper) and modifies the wrapper to point to the new action. This method is faster than AlAction::copy() above.

Return Codes
sSuccess - the action was successfully copied sInvalidObject - the action was not valid sFailure - the action was not valid or the copy failed

double AlAction::eval( double time, AlTripleComponent compo ) const Description

Evaluates this action at the given time, and returns the value of the action at that time. If the action is an AlMotionAction, then you must specify which component of the resulting (x,y,z) value to retrieve using the optional second argument. If the action is not valid, 0.0 is returned. Evaluation of an AlParamAction is as follows

AlAction | 101

An animation parameter curve is a "Poon-Ross" spline (developed by Angus Poon and Dave Ross). This spline is basically a Hermite-linear spline. That is, it is a Hermite in y (the vertical axis) and a linear in x (the horizontal axis). If we call this spline C(t) = (x(t), y(t)), then we see that it is fairly straightforward to compute for the case when x = T since x(t) = t. So we would get C(t) for x = T is (T, y(T)). To compute a point on a curve segment C(t) (which is bounded by the CVs (t1, y1), (t2, y2) and has tangents m1 and m2 at the start and end of the segment) at t = T, we first make the mapping
T = (T - t1) / (t2 - t1)

so that t is in the range [0, 1]. We then get the y value off of the curve segment using the standard computation
C(T) = [T^3 T^2 T 1] * H * | m1 | | m2 | | y1 | | y2 |

where H is the hermite basis matrix.

Arguments
< time - the time at which to evaluate the action < compo - which component to get, for motion actions

double AlChannel::sample( void ) const Description

Samples the channel without actually evaluating it. The value of the current parameter is read without any updates being done. The channel is sampled at the current time. This method is faster than eval(), and is useful in cases where eval() has already been called, either explicitly or through a viewFrame operation. If this method succeeds, it returns the value of the channel at the current frame. If it fails, 0.0 is returned.

int AlAction::numChannelReferences() const Description

Returns the number of channels that use this action. If 0 is returned, this action is considered non-referenced. Note that if one channel uses this action 2 times, this is counted as 2 references. Also note that if the action is not valid -1 is returned.

102 | Chapter 1 AlAction AlBoxLight

AlChannel* AlAction::channelReference(const int n) const Description

Returns the nth AlChannel that references this AlAction. If n is less than 1, or greater than the number of channels that reference this action (as returned by AlAction::numChannelReferences()), then NULL is returned. The list of channels is not in any particular order.

Arguments
< n - the index between 1 and numChannelReferences() of the channel reference to return.

AlAimConstraint
Interface to IK aim constraint data.

Synopsis
#include <AlAimConstraint.h> class AlAimConstraint : public AlConstraint AlAimConstraint(); virtual ~AlAimConstraint(); virtual AlObject* copyWrapper() const; statusCode create(AlDagNode*, AlDagNode*, AlAimConstraintAxis, AlAimConstraintAxis ); statusCode create(AlDagNode*, AlDagNode*, AlAimConstraintAxis, AlAimConstraintAxis, double[2] ); virtual AlObjectType type() const; AlAimConstraintAxis aimAxis( void ) const; AlAimConstraintAxis upAxis( void ) const; statusCode at( double[3] ) const; statusCode setAimAxis( AlAimConstraintAxis ); statusCode setUpAxis( AlAimConstraintAxis );

Description
The AlAimConstraint class allows access to the IK aim constraint information on an AlJoint. This class is derived from the AlConstraint class.

AlAimConstraint | 103

(See the discussion of skeletons, joints, constraints, IK, and so on, in the printed reference manuals for a full description.)

AlAimConstraint::AlAimConstraint() Description
Constructs an AlAimConstraint wrapper object.

AlAimConstraint::~AlAimConstraint() Description
Deletes an AlAimConstraint wrapper object.

AlObject *AlAimConstraint::copyWrapper() const Description

Wrapper object duplicator for AlAimConstraint.

statusCode AlAimConstraint::create(AlDagNode* srcNode, AlDagNode* destNode, AlAimConstraintAxis aim, AlAimConstraintAxis up) Description
Does all the initialization necessary to attach the constraint node to the DAG node as an aim constraint. A DAG node can not be constrained to itself.

Arguments
< srcNode - AlDagNode this constraint is to be added to < destNode - AlDagNode that srcNode is constrained to < aim - the axis this constraint is tied to < up - the up axis which completes the constraint

Return Codes
sInvalidArgument - one of the arguments was wrong or tried to constrain a node to itself sInsufficientMemory - ran out of memory

104 | Chapter 1 AlAction AlBoxLight

sFailure - failed to add the constraint sSuccess - successfully added the constraint

statusCode AlAimConstraint::create(AlDagNode* srcNode, AlDagNode* destNode, AlAimConstraintAxis aim, AlAimConstraintAxis up, double uv[2]) Description
This method does all the initialization necessary to attach the constraint node to the dag node as an uv aim constraint. A dag node can not be constrained to itself. The destNode must be spline geometry node, for example, spline curve or a spline surface.

Arguments
< srcNode - AlDagNode this constraint is to be added to. < destNode - AlDagNode that srcNode is constrained to. < aim - The axis this constraint is tied to. < up - The up axis which completes the constraint. < uv[2] - The uv parameter on destNode that srcNode is constrained to. If the destNode is a curve, only uv[0] is used.

Return Codes
sInvalidArgument - one of the arguments was wrong or tried to constrain a node to itself. sInsufficientMemory - ran out of memory. sFailure - failed to add the constraint. sSuccess - successfully added the constraint.

AlObjectType AlAimConstraint::type() const Description

Returns the class identifier kAimConstraintType;

AlAimConstraint | 105

AlAimConstraintAxis AlAimConstraint::aimAxis( void ) const Description

Returns the aim axis associated with this constraint.

AlAimConstraintAxis AlAimConstraint::upAxis( void ) const Description

Returns the up axis associated with this constraint.

statusCode AlAimConstraint::at( double point[3] ) const Description

Puts the aimed-at point into the passed-in argument. Returns a statusCode indicating whether the method was successful.

statusCode AlAimConstraint::setAimAxis( AlAimConstraintAxis axis ) Description

Sets the aim axis for this constraint to the passed-in argument.

statusCode AlAimConstraint::setUpAxis( AlAimConstraintAxis axis ) Description

Sets the up axis for this constraint to the passed-in argument.

AlAmbientLight
Encapsulates the creation, deletion and manipulation of an ambient light.

106 | Chapter 1 AlAction AlBoxLight

Synopsis
#include <AlAmbientLight.h> class AlAmbientLight : public AlLight AlAmbientLight(); virtual ~AlAmbientLight(); virtual AlObject* copyWrapper() const; statusCode create(); AlObjectType type() const; double shadeFactor() const; double intensity() const; statusCode setShadeFactor( double ); statusCode setIntensity( double );

Description
An ambient light is similar to a point light, except that only a portion of the illumination comes from the point. The remainder of the illumination comes from all directions and lights everything uniformly. (For more information on lights in general, see the Class Description of the AlLight on page 582 class.)

AlAmbientLight::AlAmbientLight() Description
Constructs an AlAmbientLight wrapper object.

AlAmbientLight::~AlAmbientLight() Description
Deletes an AlAmbientLight wrapper object.

statusCode AlAmbientLight::create() Description

Creates all the DAG nodes for this light and adds them to the universe. The DAG nodes are for position, look at and up, and another DAG node that groups these three together.

AlAmbientLight | 107

Return Codes
sSuccess - everything was successful sInsufficientMemory - not enough memory available sAlreadyCreated - light is already created

AlObjectType AlAmbientLight::type() const Description

Returns the class identifier, kAmbientLightType.

double AlAmbientLight::shadeFactor() const Description

Returns the lights shade factor. Valid shade factors range from 0.0 to 1.0. Shade factor defines the omnidirectionality of the light. Set to 0.0, ambient light will come from all directions and surfaces will not show edge definition. Set to 1.0, the ambient light comes solely from the position of the light and objects will show definite edge contrast. If the light is not valid then -1 is returned.

statusCode AlAmbientLight::setShadeFactor( double newShadeFactor) Description

Sets the lights shade factor. Valid shade factors range from 0.0 to 1.0. Shade factor defines the omnidirectionality of the light. Set to 0.0, ambient light will come from all directions and surfaces will show not edge definition. Set to 1.0, the ambient light comes solely from the position of the light and objects will show definite edge contrast.

Arguments
< double newShadeFactor - is the new shade factor

Return Codes
sSuccess - setting shade factor succeeded sInvalidObject - the light was not valid

108 | Chapter 1 AlAction AlBoxLight

sFailure - not an ambient light sInvalidArgument - shade out of range

double AlAmbientLight::intensity() const Description

Returns the intensity of this ambient light. The value returned is greater than or equal to 0.0. If the light is not valid -1 is returned.

statusCode AlAmbientLight::setIntensity( double newIntensity ) Description

Sets the intensity of this ambient light. The given intensity value must be greater than or equal to 0.0.

Arguments
< newIntensity - the intensity that this light is set to

Return Codes
sSuccess - setting intensity succeeded sInvalidObject - not a valid ambient light sInvalidArgument - intensity out of range

AlAngleLocator
Displays the included angle between three locators.

AlAngleLocator | 109

Synopsis
#include <AlAngleLocator.h> class AlAngleLocator : public AlLocator AlAngleLocator(); virtual ~AlAngleLocator(); virtual AlObject * copyWrapper() const; virtual AlObjectType type() const; statusCode create(const AlPointLocator *, const AlPointLocator *, const AlPointLocator *, boolean trueDisplay = TRUE); AlPointLocator * startLocator() const; AlPointLocator * middleLocator() const; AlPointLocator * endLocator() const; statusCode trueDisplay(boolean &) const; statusCode setTrueDisplay(boolean); statusCode offset(double &) const; statusCode setOffset(double); statusCode angle(double &) const;

Description
An angle locator is used to find the included angle between any three point locators (AlPointLocator). If any of the three point locators on which this locator depends is deleted, this locator is deleted. This class contains methods to create the locator, query the angle, and set the display attributes of the locator in the Alias windows.

AlAngleLocator::AlAngleLocator(void) Description
Constructs an AlAngleLocator wrapper object.

AlAngleLocator::~AlAngleLocator() Description
Deletes an AlAngleLocator wrapper object.

110 | Chapter 1 AlAction AlBoxLight

AlObject *AlAngleLocator::copyWrapper() const Description

Returns an exact copy of the AlAngleLocator wrapper.

AlObjectType AlAngleLocator::type() const Description

Returns the class identifier kAngleLocatorType.

statusCode AlAngleLocator::create(const AlPointLocator *startLocator, const AlPointLocator *middleLocator, const AlPointLocator *endLocator, boolean trueDisplay) Description
Creates an angle locator to measure the included angle between three point locators. The measured angle is between the lines formed by startLocator and middleLocator, and middleLocator and endLocator.

Arguments
< startLocator - the starting point locator < middleLocator - the middle point locator < endLocator - the ending point locator < displayType - determines whether the true value or projection of the true value in the Alias window should be shown. The default is true display.

Return Codes
sSuccess - the angle locator was successfully created sAlreadyCreated - the object has already been created sFailure - the angle locator could not be created sInvalidArgument - one or more of the point locators are not valid

AlAngleLocator | 111

AlPointLocator *AlAngleLocator::startLocator() const Description

Returns the starting point locator of this angle locator. If the angle locator is not valid, NULL is returned.

AlPointLocator *AlAngleLocator::middleLocator() const Description

Returns the middle point locator of this angle locator. If the angle locator is not valid, NULL is returned.

AlPointLocator *AlAngleLocator::endLocator() const Description

Returns the ending point locator of this angle locator. If the angle locator is not valid, NULL is returned.

statusCode AlAngleLocator::trueDisplay(boolean &trueDisplay) const Description

Determines if the angle locator is depicting the true angle or projected angle in the Alias Modeling windows.

Arguments
> trueDisplay - the value is true if the angle locator displays true angle in a modeling window. It is set to false for a projected angle.

Return Codes
sSuccess - the display mode was found sInvalidObject - the locator is not valid

112 | Chapter 1 AlAction AlBoxLight

statusCode AlAngleLocator::setTrueDisplay(boolean trueDisplay) Description

Sets the mode to display the angle locator as either true angle or projected angle in the Modeling window.

Arguments
< trueDisplay - if the value is true then the distance locator displays true distance; if the argument is false, the projected distance is displayed.

Return Codes
sSuccess - the display mode was set sInvalidObject - the locator is not valid

statusCode AlAngleLocator::setOffset(double offset) Description

Sets the offset of the angle locator display.

Arguments
< offset - the offset value

Return Codes
sSuccess - the offset value was set sInvalidObject - the locator is not valid

statusCode AlAngleLocator::offset(double &offset) const Description

Finds the offset of the angle locator display.

Arguments
> offset - the offset value

AlAngleLocator | 113

Return Codes
sSuccess - the offset value was found sInvalidObject - the locator is not valid

statusCode AlAngleLocator::angle(double &includedAngle) const Description

Finds the angle of the angle locator.

Arguments
> includedAngle - the included angle between the three point locators

Return Codes
sSuccess - the angle was found sInvalidObject - the locator is not valid

AlAnimatable
Basic Interface to Alias objects that support animation.

114 | Chapter 1 AlAction AlBoxLight

Synopsis
#include <AlAnimatable.h> class AlAnimatable virtual AlChannel* firstChannel() const; virtual AlChannel* nextChannel( const AlChannel* ) const; virtual AlChannel* prevChannel( const AlChannel* ) const; virtual statusCode nextChannelD( AlChannel* ) const; virtual statusCode prevChannelD( AlChannel* ) const; virtual statusCode applyIteratorToChannels( AlIterator*, int &); virtual statusCode deleteAnimation(); statusCode globalParam( const char *param, boolean& ); AlList* globalParamList(); statusCode localParam( const char *param, boolean& ); AlList* localParamList(); statusCode setLocalParam( const char *paramName, boolean state ); statusCode setGlobalParam( const char *paramName, boolean state ); class AlParamItem : public AlLinkItem AlParamItem* nextItem() AlParamItem* prevItem() char* name; boolean value;

Description
This class encapsulates the functionality of Alias objects that have the capacity to be animated. It also provides access to channels. The AlParamItem class is also defined in the AlAnimatable.h header file. AlParamItem classes are used for returning information from several of the methods of AlAnimatable. In both cases, an AlList of AlParamItem classes is returned by this API. No specific method information is provided for AlParamItem because it is similar to AlLinkItem with the addition of two variable fields.

AlChannel* AlAnimatable::firstChannel() const Description

Gets the first channel animating this object. If this object is not animated, this method returns NULL.

AlAnimatable | 115

AlChannel* AlAnimatable::nextChannel( const AlChannel *channel) const Description

Gets the next channel after the specified channel, as determined by the objects list of channels. If the specified channel is not part of the objects channel list, or it is the last channel in the list, then NULL is returned.

Arguments
< channel - one of this objects channels for which we want to find the next channel

AlChannel* AlAnimatable::prevChannel( const AlChannel *channel) const Description

Gets the next channel in this objects list of channels following the given channel. If channel is not part of the objects channel list, or it is the last channel in the list, then NULL is returned.

Arguments
< channel - one of this objects channels for which we want to find the next channel.

statusCode AlAnimatable::nextChannelD( AlChannel *channel ) const Description

Destructively sets the passed-in channel to point to the next channel in the list of channels for this object.

Arguments
< channel - the channel

Return Codes
sSuccess - the next channel was successfully found sInvalidObject - the channel was not valid sFailure - there is no next channel

116 | Chapter 1 AlAction AlBoxLight

statusCode AlAnimatable::prevChannelD( AlChannel *channel ) const Description

Destructively sets the passed-in channel to point to the next channel in the list of channels for this object.

Arguments
< channel - the channel

Return Codes
sSuccess - the previous channel was successfully determined sInvalidObject - the channel was not valid sFailure - there is no next channel

statusCode AlAnimatable::applyIteratorToChannels( AlIterator* iter, int &rc ) Description

Applies the given iterator to each of the channels in this object. See the documentation for AlIterator on page 544.

Arguments
< iter - the iterator to apply to each channel > rc - the result of the last application of the iterator

Return Codes
sSuccess - the iterator was successfully applied sInvalidObject - the object was not valid sFailure - the application of the iterator failed or the object had no channels sInvalidArgument - the iterator was NULL

AlAnimatable | 117

AlChannel *AlAnimatable::findChannel( int parameter ) const Description

A fast way to obtain a particular AlChannel on an object from the parameter of that channel. This method returns the AlChannel, which animates the passed-in parameter of the given AlAnimatable. If the object is not valid, or the parameter is not currently animated, NULL is returned.

Arguments
< parameter - the parameter of the AlAnimatable corresponding to the desired channel.

double AlAnimatable::sampleChannel( int parameter ) const Description

Samples the parameter of the AlAnimatable without actually evaluating it. It reads the current value of the parameter and returns it as a double. Note that the parameter does not need to be currently animated to sample it. If this method succeeds, it returns the value of the parameter at the current frame. If it fails, 0.0 is returned.

Arguments
< parameter - the parameter of the AlAnimatable to be sampled.

statusCode AlAnimatable::deleteAnimation() Description

Deletes all the channels that currently animate this object.

Return Codes
sSuccess - the animation was successfully deleted sInvalidObject - the object was not valid

118 | Chapter 1 AlAction AlBoxLight

statusCode AlAnimatable::globalParam( const char *paramName, boolean& state ) Description

Returns the parameter control.

Arguments
paramName - the name of the parameter in question state - the returned state of the parameter

Return Codes
sSuccess - the parameter was read sObjectNotFound - the paramName could not be found sInvalidArgument - paramName was NULL sInvalidObject - the object was not valid

statusCode AlAnimatable::localParam( const char *paramName, boolean& state ) Description

Returns the parameter control. If there are no local params set, then the default local params are returned.

Arguments
paramName - the name of the parameter in question state - the returned state of the parameter

Return Codes
sSuccess - the parameter was read sObjectNotFound - the paramName could not be found sInvalidArgument - paramName was NULL sInvalidObject - the object was not valid

AlAnimatable | 119

AlList* AlAnimatable::localParamList() Description

Returns a list of the parameter control names. The list contains a list of AlParamItems.

AlList* AlAnimatable::globalParamList() Description

Returns a list of the parameter controls.

statusCode AlAnimatable::setLocalParam( const char *paramName, boolean state ) Description

Sets the parameter control.

Arguments
paramName - the name of the parameter in question state - the returned state of the parameter

Return Codes
sSuccess - the parameter was read sObjectNotFound - the paramName could not be found sFailure - there were no local params set sInvalidArgument - paramName was NULL sInvalidObject - the object was not valid

statusCode AlAnimatable::setGlobalParam( const char *paramName, boolean state ) Description

Sets the parameter control for objects of this type.

120 | Chapter 1 AlAction AlBoxLight

Arguments
paramName - the name of the parameter in question state - the new state of the parameter

Return Codes
sSuccess - the parameter was read sObjectNotFound - the paramName could not be found sInvalidArgument - paramName was NULL sInvalidObject - the object was not valid

AlAnnotationLocator
Displays a text string for existing locators

Synopsis
#include <AlAnnotationLocator.h> class AlAnnotationLocator : public AlLocator AlAnnotationLocator(); virtual ~AlAnnotationLocator(); virtual AlObject * copyWrapper() const; virtual AlObjectType type() const; statusCode create(const AlPointLocator *, const char *, double, double, double); statusCode setString(const char *); statusCode setWorldLeaderPosition(double x = 0.0, double y = 0.0, double z = 0.0); statusCode setLocalLeaderPosition(double x = 0.0, double y = 0.0, double z = 0.0); statusCode setLeftJustify(boolean); const char * string() const; statusCode worldLeaderPosition(double &, double &, double &) const; statusCode localLeaderPosition(double &, double &, double &) const; statusCode leftJustify(boolean &) const;

AlAnnotationLocator | 121

Description
This class creates an annotation to existing point locators (for example, the space locator, curve locator, curve on surface locator, and surface locator). An annotation is a line of text and a leader (line with arrow) that is drawn relative to a locator (point type). To create an annotation locator, first create a point locator and then attach the annotation string through this class using its create method. There are also methods to manipulate the position and starting point of the leader line for the annotation.

AlAnnotationLocator::AlAnnotationLocator(void) Description
Constructs an AlAnnotationLocator wrapper object.

AlAnnotationLocator::~AlAnnotationLocator() Description
Deletes an AlAnnotationLocator wrapper object.

AlObject *AlAnnotationLocator::copyWrapper() const Description

Returns an exact copy of the AlAnnotationLocator wrapper.

AlObjectType AlAnnotationLocator::type() const Description

Returns the class identifier kAnnotationLocatorType.

statusCode AlAnnotationLocator::create(const AlPointLocator *pointLocator, const char *string, double x, double y, double z) Description
Creates an annotation locator on another point locator.

122 | Chapter 1 AlAction AlBoxLight

Arguments
> pointLocator - The AlPointLocator on which the annotation locator is created. The pointLocator should be created before creating the annotation locator. > string - The string to be displayed in the annotation. > x, y, z - The coordinates relative to the point locator on which annotation depends, at which the leader line of the text starts.

Return Codes
sSuccess - the text change was successful sAlreadyCreated - the annotation locator was created already sInvalidArgument - the point locator has not been created, or the string argument is NULL sFailure - the method failed to create an annotation locator

statusCode AlAnnotationLocator::setString(const char *string) Description

Changes the string in an annotation locator.

Arguments
< string - the string to substitute in the present annotation locator

Return Codes
sSuccess - the text change was successful sInvalidObject - the object is not valid sInsufficientMemory - there was not enough memory to create a copy of the string sInvalidArgument - a NULL argument was supplied

const char *AlAnnotationLocator::string() const Description

Returns a pointer to the annotation string.

AlAnnotationLocator | 123

Return Codes
NULL - if the annotation locator is not valid, or the string is NULL

statusCode AlAnnotationLocator::setWorldLeaderPosition(double x, double y, double z) Description

Sets the position of the annotation leader line in world coordinates.

Arguments
> x, y, z - the world coordinates at which the leader line starts

Return Codes
sInvalidObject - the object is not valid sSuccess - change was successful

statusCode AlAnnotationLocator::setLocalLeaderPosition(double x, double y, double z) Description

Sets the position of the annotation leader line, relative to the point locator on which the annotation locator is created.

Arguments
> x, y, z - the local coordinates at which the leader line starts

Return Codes
sInvalidObject - the object is not valid sSuccess - change was successful

124 | Chapter 1 AlAction AlBoxLight

statusCode AlAnnotationLocator::setLeftJustify(boolean leftJustify) Description

Sets the justification of the annotation text for the annotation locator. The text can be right justified or left justified.

Arguments
< leftJustify - a value of true left-justifies the text; a value of false right-justifies it.

Return Codes
sSuccess - the setting was successful sInvalidObject - the object is not valid

statusCode AlAnnotationLocator::worldLeaderPosition(double &x, double &y, double &z) const Description

Gets the position of the annotation leader line in world coordinates.

Arguments
< x, y, z - the world coordinates at which the leader line starts

Return Codes
sInvalidObject - the object is not valid sSuccess - the change was successful

statusCode AlAnnotationLocator::localLeaderPosition(double &x, double &y, double &z) const Description

Gets the position of the annotation leader line, relative to the point locator on which the annotation locator is created.

AlAnnotationLocator | 125

Arguments
< x, y, z - the local coordinates at which the leader line starts.

Return Codes
sInvalidObject - the object is not valid sSuccess - the change was successful

statusCode AlAnnotationLocator::leftJustify(boolean &leftJustify) const Description

Determines whether the annotation text is left-justified or right-justified.

Arguments
> leftJustify - a value of true indicates that it is left-justified; false indicates right-justification

Return Codes
sSuccess - the justification was found sInvalidObject - the object is not valid

AlArcAttributes
Interface to Alias arc curve attributes.

126 | Chapter 1 AlAction AlBoxLight

Synopsis
#include <AlArcAttributes.h> class AlArcAttributes : public AlAttributes virtual AlObjectType type() const; AlObject* copyWrapper() const; statusCode centerPoint(double&, double&, double&) const; statusCode startPoint(double&, double&, double&) const; statusCode endPoint(double&, double&, double&) const; double sweep() const; double radius() const; statusCode calculateStartAndEndAngles( double& start_angle, double& end_angle, double xaxis[3], double yaxis[3], double zaxis[3]); statusCode setStartPoint(double, double, double); statusCode setEndPoint(double, double, double); statusCode setSweepFromStartPoint(double); statusCode setSweepFromEndPoint(double); statusCode setRadius(double);

Description
AlArcAttributes is a class derived from the AlAttributes class. This class allows access to the attributes for an arc. The attributes that define an arc are its radius, sweep angle, center point, start point, and end point. Coordinates are given in object space, and not world space.

AlObjectType AlArcAttributes::type() const Description

Returns the class identifier kArcAttributeType.

AlObject* AlArcAttributes::copyWrapper() const Description

Makes a copy of the AlArcAttributes. The returned AlArcAttributes will reference the same data as the original.

AlArcAttributes | 127

statusCode AlArcAttributes::centerPoint(double& x, double& y, double& z) const Description

Returns the center point for the arc. Note that there is no "set" method for the center point. The center point is moved by changing the arcs radius.

Arguments
> double& x - center point x coordinate > double& y - center point y coordinate > double& z - center point z coordinate

Return Codes
sSuccess - the center point was successfully returned sInvalidObject - the attribute was invalid

statusCode AlArcAttributes::startPoint(double& x, double& y, double& z) const Description

Returns the point where the arc starts.

Arguments
> double& x - start point x coordinate > double& y - start point y coordinate > double& z - start point z coordinate

Return Codes
sSuccess - the start point was successfully returned sInvalidObject - the attribute was invalid

128 | Chapter 1 AlAction AlBoxLight

statusCode AlArcAttributes::endPoint(double& x, double& y, double& z) const Description

Returns the point where the arc ends.

Arguments
> double& x - end point x coordinate > double& y - end point y coordinate > double& z - end point z coordinate

Return Codes
sSuccess - the start point was successfully returned sInvalidObject - the attribute was invalid

double AlArcAttributes::sweep() const Description

Returns the number of degrees in the arc. Zero is returned if the attribute is not valid.

double AlArcAttributes::radius() const Description

Returns the radius of the arc. Zero is returned if the attribute is not valid.

statusCode AlArcAttributes::calculateStartAndEndAngles( double& start_angle, double& end_angle, double xaxis[3], double yaxis[3], double zaxis[3] ) Description
This function will convert the attribute information to start and end angle format. The start and end angles are rotated by the axis into their correct position.

AlArcAttributes | 129

Arguments
> x,y,z axis > start and end angle

Return code
sSuccess - Converting the data succeeded sInvalidObject - the attribute was invalid sFailure - Conversion failed

statusCode AlArcAttributes::setStartPoint(double x, double y, double z) Description

Moves the start point of the arc. Changing the start point changes the size of the sweep, and if the new start point is not on the circle about the arcs center point, the center point is moved.

Arguments
< double x - start point x coordinate < double y - start point y coordinate < double z - start point z coordinate

Return code
sSuccess - setting the start point succeeded sInvalidObject - the attribute was not valid sFailure - setting the start point failed

statusCode AlArcAttributes::setEndPoint(double x, double y, double z) Description

Moves the end point of the arc. Changing the end point changes the size of the sweep, and if the new end point is not on the circle about the arcs center point, the center point is moved.

130 | Chapter 1 AlAction AlBoxLight

Arguments
< double x - end point x coordinate < double y - end point y coordinate < double z - end point z coordinate

Return code
sSuccess - setting the end point succeeded sInvalidObject - the attribute was invalid sFailure - setting the end point failed

statusCode AlArcAttributes::setSweepFromStartPoint(double sweep) Description

Changes the sweep of the arc from the start point. This operation will move the end point. The sweep is given in degrees.

Arguments
< sweep - the sweep from the start point (in degrees)

Return code
sSuccess - setting the sweep succeeded sInvalidObject - the attribute was invalid sFailure - setting the sweep failed

statusCode AlArcAttributes::setSweepFromEndPoint(double sweep) Description

Changes the sweep of the arc from the end point. This operation will move the start point. The sweep is given in degrees.

Arguments
< sweep - the sweep from the end point (in degrees)

AlArcAttributes | 131

Return code
sSuccess - setting the sweep succeeded sInvalidObject - the attribute was invalid sFailure - setting the sweep failed

statusCode AlArcAttributes::setRadius(double radius) Description

Change the radius for the arc. This operation will move the center point for the arc.

Arguments
< radius - the radius of the arc

Return code
sSuccess - setting the sweep succeeded sInvalidObject - the attribute was invalid sFailure - setting the sweep failed

AlAreaLight
Encapsulates the creation, deletion and manipulation of area lights.

132 | Chapter 1 AlAction AlBoxLight

Synopsis
#include <AlAreaLight.h> class AlAreaLight: public AlDirectionLight AlAreaLight(); virtual ~AlAreaLight(); statusCode create(); virtual AlObject* copyWrapper() const; AlObjectType type() const; statusCode longAxis( double&, double&, double& ) const; statusCode shortAxis( double&, double&, double& ) const; statusCode setLongAxis( double, double, double ); statusCode setShortAxis( double, double, double ); statusCode cornerPoints( double&, double&, double&, double&, double&, double&) const;

Description
An area light is a rectangular area that emits light in all directions. An area light would be used, for instance, to simulate bright light coming through a rectangular window. The size of the rectangle is defined by a long and short axis. To create an area light, the user must instantiate and call the create method on an AlAreaLight object. (For more information on lights in general, see the Class Description of the AlDirectionLight on page 434 object.) To determine the orientation of the rectangular area of this light, use the worldPosition() of this light and the method cornerPoints(). The cornerPoints() method returns points A and B in world space, as in the following diagram: (WP is the World Position)

Although this class inherits methods to access the look at and up nodes of a light, they are not used. The direction and twist of an area light is changed by translating and rotating the transformation of the lights position node.

AlAreaLight | 133

AlAreaLight::AlAreaLight() Description
Constructs an AlAreaLight wrapper object.

AlAreaLight::~AlAreaLight() Description
Deletes an AlAreaLight wrapper object.

statusCode AlAreaLight::create() Description

Creates all the DAG nodes for this light and adds them to the universe. The DAG nodes are for position, look at and up, and another DAG node that groups these three together.

Return Codes
sSuccess - everything was successful sInsufficientMemory - not enough memory available sAlreadyCreated - light is already created

AlObjectType AlAreaLight::type() const Description

Returns the class identifier, kAreaLightType.

statusCode AlAreaLight::longAxis( double &x, double &y, double &z) const Description
Returns the linear lights long axis in x, y & z.

Arguments
> double &x - the length of the axis in the x direction > double &y - the length of the axis in the y direction

134 | Chapter 1 AlAction AlBoxLight

> double &z - the length of the axis in the z direction

Return Codes
sSuccess - successfully determined long axis of the light sInvalidObject - the light was not valid sFailure - the axis was not set

statusCode AlAreaLight::shortAxis( double &x, double &y, double &z) const Description
Returns the linear lights short axis in x, y & z.

Arguments
> double &x - the length of the axis in the x direction > double &y - the length of the axis in the y direction > double &z - the length of the axis in the z direction

Return Codes
sSuccess - successfully determined short axis of the light sInvalidObject - the light was not valid sFailure - the axis was not set

statusCode AlAreaLight::setLongAxis( double x, double y, double z ) Description

Sets the long axis of the light to be x, y, & z. The given vector must be non-zero.

Arguments
< double x - the new length of the axis in the x direction < double y - the new length of the axis in the y direction < double z - the new length of the axis in the z direction

AlAreaLight | 135

Return Codes
sSuccess - setting long axis succeeded sInvalidObject - not a valid area light sInvalidArgument - axis vector was zero sFailure - the axis was not set

statusCode AlAreaLight::setShortAxis( double x, double y, double z ) Description

Sets the short axis of the light to be x, y, & z. The given vector must be non-zero.

Arguments
< double x - the new length of the axis in the x direction < double y - the new length of the axis in the y direction < double z - the new length of the axis in the z direction

Return Codes
sSuccess - setting short axis succeeded sInvalidObject - not a valid area light sFailure - the axis was not set sInvalidArgument - axis vector was zero

statusCode AlAreaLight::cornerPoints( double &x1, double &y1, double &z1,double &x2, double &y2, double &z2) const Description
Returns the corner points of the rectangular area of this area light. The corner points are in world space. The corner points are A and B in the following diagram (WP is World Position of the light)

136 | Chapter 1 AlAction AlBoxLight

Arguments
> double &x1 - the world space short axis corner point in x direction > double &y1 - the world space short axis corner point in y direction > double &z1 - the world space short axis corner point in z direction > double &x2 - the world space long axis corner point in x direction > double &y2 - the world space long axis corner point in y direction > double &z2 - the world space long axis corner point in z direction

Return Codes
sSuccess - successfully determined the lights corner points sInvalidObject - the light was not valid sFailure - unable to complete the request

AlAttributes
Interface to Alias curve and surface attributes.

Synopsis
#include <AlAttributes.h> class AlAttributes : public AlObject virtual ~AlAttributes(); virtual AlObjectType type() const; AlObject* copyWrapper() const; AlAttributes* nextAttribute() const;

AlAttributes | 137

Description
AlAttributes is the base class for a set of classes that allow access to curve and surface attributes. It is not possible to create AlAttributes directly; instead they are created when you use the AlCurve::create*() methods. An attribute is an alternate way to specify an object. For example, in Alias normally a circle is represented by a NURBS curve that approximates a circle. With attributes instead, a circle is represented by an origin, a radius, and so on. Several types of attributes are derived from this class that are used for particular types of objects.

AlObjectType AlAttributes::type() const Description

Returns the class identifier kAttributeType.

AlObject* AlAttributes::copyWrapper() const Description

Makes a copy of the AlAttribute. The returned AlAttribute will reference the same data as the original.

AlAttributes* AlAttributes::nextAttribute() const Description

This virtual function returns a pointer to the next attribute in the objects list of attributes.

AlBlendCurve
Interface to Alias blend curves.

Synopsis
#include <AlBlendCurve.h>

138 | Chapter 1 AlAction AlBoxLight

class AlBlendCurve : public AlObject enum AlKnotSpacingType { kChord, kUniform }; AlBlendCurve(); virtual ~AlBlendCurve(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; statusCode create( int , AlKnotSpacingType , int , const double[][3] ); statusCode create( int , AlKnotSpacingType ); virtual AlObjectType type() const; int degree(); statusCode setDegree( int ); statusCode knotSpacingType( AlKnotSpacingType& ); statusCode setKnotSpacingType( AlKnotSpacingType ); int numberOfPoints(); statusCode param( int, double& ); AlBlendPoint* getPoint( int ); statusCode points( int, double[] ); statusCode insert( int, double, double, double ); statusCode append( double, double, double ); boolean isPicked(); AlBlendCurve* next(); statusCode nextD( AlBlendCurve * ); AlBlendCurve* prev(); statusCode prevD( AlBlendCurve * ); AlCurveNode* curveNode();

Description
An Alias Blend Curve is a normal NURBS curve with construction history. This class allows blend curves to be created and intersected with other curves, curves on surfaces, blend curves and surfaces. Note that intersection with clouds is not currently supported. Blend Curves contain Blend Points so it is necessary to use the AlBlendPoint class to make use of all of the Blend Curve functionality. To find the curve node which is the output of the Blend Curve command, use the curveNode() method. Notes: 1. If a blend curve is active and the API is used to create another blend curve, the first blend curve will become inactive.

AlBlendCurve | 139

2. Blend curves can be made active or inactive by finding the curveNode() method and calling pick() on unpick() with the AlCurveNode.

AlBlendCurve::AlBlendCurve() Description
NULL constructor.

AlBlendCurve::~AlBlendCurve() Description
NULL destructor.

statusCode AlBlendCurve::deleteObject() Description

This method deletes a blend curve object and any points it has. In addition, the output AlCurve of the blend curve object is deleted.

Return Codes
sSuccess - the object was successfully deleted sFailure - the method failed sInvalidObject - the object was invalid

AlObject *AlBlendCurve::copyWrapper() const Description

Returns an exact copy of the blend curve wrapper. NULL is returned if this method failed.

statusCode AlBlendCurve::create( int degree, AlKnotSpacingType ks ) Description

Create a blend curve based on a specified degree and knot spacing. Points are added to the blend curve using the insertPoint() or appendPoint() methods.

140 | Chapter 1 AlAction AlBoxLight

Arguments
< degree - one of 1, 2, 3, 5, or 7 < ks - kChord or kUniform

Return Codes
sSuccess - a blend curve was created sFailure - blend curve is currently valid, or other internal error occurred sInvalidArgument - degree is not one of 1, 2, 3, 5, 7

statusCode AlBlendCurve::create( int degree, AlKnotSpacingType ks, int numPoints, const double points[][3]) Description
Create a blend curve based on a specified degree, knot spacing and points. More points can be added to the blend curve using the insertPoint() or appendPoint() methods. Note: a new point is initially not connected to any object, has a location interpolation direction, and has a parallel direction type.

Arguments
< degree - one of 1, 2, 3, 5, or 7 < ks - kChord or kUniform < numPoints - number of points in the point[] array < points[] - array of 3D points

Return Codes
sSuccess - a blend curve was created sFailure - blend curve is currently valid, or other internal error occurred sInvalidArgument - degree is not one of 1, 2, 3, 5, 7, or points are too close together (tolerance = 0.01).

AlBlendCurve | 141

AlObjectType AlBlendCurve::type() const Description

Returns the class identifier kBlendCurveType.

int AlBlendCurve::degree() Description

Returns the degree of the blend curve. Note that -1 is returned if the blend curve is invalid or if an internal error occurs.

statusCode AlBlendCurve::setDegree( int degree ) Description

Sets the degree of the blend curve.

Arguments
< degree - one of 1, 2, 3, 5, or 7

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidArgument - degree was not one of 1, 2, 3, 5 or 7 sInvalidObject - invalid blend curve

statusCode AlBlendCurve::knotSpacingType( AlKnotSpacingType& kst ) Description

Returns the knot spacing setting of the blend curve.

Arguments
> kst - knot spacing of the curve

142 | Chapter 1 AlAction AlBoxLight

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - invalid blend curve

statusCode AlBlendCurve::setKnotSpacingType( AlKnotSpacingType kst ) Description

Sets the knot spacing of the blend curve.

Arguments
< kst - kChord or kUniform

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - invalid blend curve

int AlBlendCurve::numberOfPoints() Description

Returns the number of points in a blend curve. If this method fails, -1 is returned. This method will fail if the blend curve is invalid.

statusCode AlBlendCurve::param( int index, double& param ) Description

Returns the param or t value of the blend point at the index specified in the blend curve. The first blend point is at index = 0.

Arguments
index - the index of the point on the blend curve to return the param for param - the blend points param value

AlBlendCurve | 143

Return Codes
sSuccess - the method succeeded sFailure - internal failure, sInvalidObject - the blend point is invalid

AlBlendPoint* AlBlendCurve::getPoint( int index ) Description

Returns the Nth point of the blend curve. NULL is returned if this method fails. This method will fail if index is less than 0 or greater than the number of points in the blend curve. The first blend curve point is at index = 0.

statusCode AlBlendCurve::points( int numPoints, double points[] ) Description

Returns the world position of the points of a blend curve. Example code:
int num = blendCurve->numberOfPoints(); double *points = (double *) malloc( sizeof(double) * num * 3 ); if ( points == NULL ) return; if ( blendCurve->points( num, points ) != sSuccess ) return; double *pt = points; for ( int i = 0 ; i < num ; i++ ) { pt[0] += x; pt[1] += y; pt[2] += z; pt += 3; }

Note: numPoints can be less than the actual number of points. The method will place as many points as possible into the array and then return successfully.

Arguments
< numPoints - size of the points array, must be a value greater than 0. For every n points, you need to allocate n * 3 elements > points - array to return points in

Return Codes
sSuccess - the method succeeded sFailure - internal failure

144 | Chapter 1 AlAction AlBoxLight

sInvalidObject - the blend curve is invalid sInvalidArgument - numPoints < 1

statusCode AlBlendCurve::insert( int index, double x, double y, double z ) Description

Inserts a new blend point before the blend point at the index specified. Note: a new point is initially not connected to any object, has a location interpolation direction, and has a parallel direction type.

Arguments
< index - position to insert the point before < x,y,z - world space location of the new point

Return Codes
sSuccess - method succeeded sFailure - internal failure sInvalidObject - the blend curve is invalid sInvalidArgument - index < 0 or falls after the last point

statusCode AlBlendCurve::append( double x, double y, double z) Description

Appends a new blend point to the end of the blend curve. Note: a new point is initially not connected to any object, has a location interpolation direction, and has a parallel direction type.

Arguments
x,y,z - the world space coordinates of the new blend point

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - the blend curve is invalid

AlBlendCurve | 145

AlCurveNode* AlBlendCurve::curveNode() Description

Returns the construction history curve that is the output of the blend curve.

boolean AlBlendCurve::isPicked() Description

Returns TRUE is the blend curve is currently picked. FALSE is returned if the blend curve is invalid or if an internal error occurs.

lBlendCurve* AlBlendCurve::next() Description

Returns the next blend curve in the Universe.

statusCode AlBlendCurve::nextD( AlBlendCurve *blendCurve ) Description

Destructive method for returning the next blend curve in the universe. sFailure is returned if there is no next blend curve in the universe.

Arguments
< blendCurve - the blend curve to obtain the next blend curve from

Return Codes
sSuccess - the method worked sFailure - the method failed, could be due to there being no next blend curve sInvalidObject - this blend curve is invalid

AlBlendCurve* AlBlendCurve::prev() Description

Returns the previous blend curve in the Universe.

146 | Chapter 1 AlAction AlBoxLight

statusCode AlBlendCurve::prevD( AlBlendCurve *blendCurve ) Description

Destructive method for returning the previous blend curve in the universe. sFailure is returned if there is no previous blend curve in the universe.

Arguments
< blendCurve - the blend curve to obtain the previous blend curve from

Return Codes
sSuccess - the method worked sFailure - the method failed, could be due to there being no previous blend curve sInvalidObject - this blend curve is invalid

AlBlendPoint
Interface to Alias blend points.

AlBlendPoint | 147

Synopsis

148 | Chapter 1 AlAction AlBoxLight

#include <AlBlendPoint.h> class AlBlendPoint : public AlObject enum AlConstraintContinuityType { kG0, kG1, kG2, kG3, kG4 }; enum AlCurvatureType { kGeometricCurv, kParametric }; enum AlInterpolationDirectionType { kLocation, kWorldSpace, kGeometricInterp }; enum AlDirectionType { kRay, kParallel }; AlBlendPoint(); virtual ~AlBlendPoint(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; statusCode setPoint( double , double , double ); statusCode point( double& , double& , double& ); statusCode param( double& ); statusCode tangent( double&, double&, double& ); statusCode setTangent( double, double, double ); statusCode interpolationDirectionType( AlInterpolationDirection Type& ); statusCode setInterpolationDirectionType( AlInterpolationDirec tionType ); statusCode directionType( AlDirectionType& ); statusCode setDirectionType( AlDirectionType ); statusCode curvatureType( AlCurvatureType& );

AlBlendPoint | 149

statusCode setCurvatureType( AlCurvatureType ); statusCode constraintContinuityType( AlConstraintContinuityType& ); statusCode setConstraintContinuityType( AlConstraintContinuityType ); statusCode attachConstraint( AlSurface *, double, double ); statusCode attachConstraint( AlCurve *, double ); statusCode attachConstraint( AlCurveOnSurface *, double ); statusCode disassociateConstraint(); statusCode attachedTo( AlObject *&, double&, double& ); boolean isSlave(); statusCode makeMaster(); AlBlendCurve* blendCurve(); AlBlendPoint* next(); statusCode nextD( AlBlendPoint * ); AlBlendPoint* prev(); statusCode prevD( AlBlendPoint * );

Description
Alias Blend Curves contain Alias Blend Points. Blend Points have constraints and curvature types as described in the Alias manuals. Methods for getting and setting the tangency, position, constraint continuity and the geometry the point is associated with are included. Notes:

To find the Alias Blend Curve this point is on, use the blendCurve() method. To find the Alias Curve that this point is on, find the blend curve, then call the AlBlendCurve::curveNode() method. setPoint() will disassociate a blend point from any geometry that it is attached to. Do not rely on the param() value staying the same. It is modified every time the curve is modified. Attaching a point to a cloud is not currently supported. Some of the methods will only work if we have the proper context. For example, the interpolation direction might have to be a certain type to make a method work.

150 | Chapter 1 AlAction AlBoxLight

Deleting blend points can also delete the blend curve. If there are fewer than two points left, then the blend curve is deleted by the deleteObject() method.

AlBlendPoint::AlBlendPoint() Description
Null constructor.

AlBlendPoint::~AlBlendPoint() Description
Null destructor.

statusCode AlBlendPoint::deleteObject() Description

This method deletes a blend point on a blend curve. If there are two blend points left on the curve and one of them is deleted, the blend curve will also be deleted.

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - the object was invalid

AlObject *AlBlendPoint::copyWrapper() const Description

Returns an exact copy of the blend point wrapper. NULL is returned if the method fails.

AlObjectType AlBlendPoint::type() const Description

Returns the class identifier kBlendPointType.

AlBlendPoint | 151

statusCode AlBlendPoint::setPoint( double x , double y , double z ) Description

Set the world space location of the blend point. If this curve is associated with geometry then that association is removed.

Arguments
< x,y,z - new world space location for the blend point.

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - the blend point is invalid

statusCode AlBlendPoint::point( double& x , double& y , double& z ) Description

Returns the world space location of the blend point

Arguments
> x,y,z - world space location of the point

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - the blend point is invalid

statusCode AlBlendPoint::param( double& param ) Description

Return the param or t value of this point on the curve. Note: this value will change as the Blend Curve is modified.

152 | Chapter 1 AlAction AlBoxLight

Arguments
> param - the param value of this point

Return Codes
sSuccess - the method succeeded sFailure - internal failure, sInvalidObject - the blend point is invalid

statusCode AlBlendPoint::tangent( double& x, double& y, double& z ) Description

Returns the tangent information for the blend point. This method will only work if this blend point has a world space or geometric interpolation direction.

Arguments
> x,y,z - the tangent of the blend point

Return Codes
sSuccess - the method succeeded sFailure - internal failure, sInvalidObject - the blend point is invalid sInvalidArgument - cannot ask for tangent information since the point does not have world space or geometric interpolation set

statusCode AlBlendPoint::setTangent( double x, double y, double z ) Description

Sets the tangent for the blend point. This method will only work if this blend point has a world space or geometric interpolation direction.

Arguments
< x,y,z - the new tangent for the point

AlBlendPoint | 153

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - the blend point is invalid sInvalidArgument - cannot set tangent information since the point is not using world space or geometric interpolation or the tangent vector did not have a direction (0, 0 0).

statusCode AlBlendPoint::constraintContinuityType(AlBlendPoint::AlConstraintContinuityType& cc ) Description

Returns the type of constraint continuity that is being used by this blend point. This method works only if we are using location or geometric interpolation directions at this point.

Arguments
> cc - constraint continuity of the blend curve

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - the blend point is invalid sInvalidArgument - the blend point is not using location or geometric interpolation directions

statusCode AlBlendPoint::setConstraintContinuityType( AlConstraintContinuityType cc ) Description

Sets the type of constraint continuity of this blend point. This method works only if we are using location or geometric interpolation directions at this point.

154 | Chapter 1 AlAction AlBoxLight

Arguments:
< cc - constraint continuity of the blend curve

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - the blend point is invalid sInvalidArgument - the blend point is not using location or geometric interpolation directions

statusCode AlBlendPoint::interpolationDirectionType(AlBlendPoint::AlInterpolationDirectionType& id) Description

Returns the interpolation direction of the blend point.

Arguments
> id - interpolation direction of the blend point

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - the blend point is invalid

statusCode AlBlendPoint::setInterpolationDirectionType( AlInterpolationDirectionType id ) Description

Sets the interpolation direction of the blend point.

Arguments
< id - interpolation direction of the blend point

AlBlendPoint | 155

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - the blend point is invalid

statusCode AlBlendPoint::directionType(AlBlendPoint::AlDirectionType& dt) Description

Returns the direction type that is being used by this blend point. This method works only if we are using world space or geometric interpolation directions at this point.

Arguments
> dt - the blend points direction type

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - the blend point is invalid sInvalidArgument - the blend point is not using world space or geometric interpolation directions

statusCode AlBlendPoint::setDirectionType( AlDirectionType dt ) Description

Sets the direction type of this blend point. This method works only if we are using world space or geometric interpolation directions at this point.

Arguments
< dt - the blend points direction type

Return Codes
sSuccess - the method succeeded

156 | Chapter 1 AlAction AlBoxLight

sFailure - internal failure sInvalidObject - the blend point is invalid sInvalidArgument - the blend point is not using world space or geometric interpolation directions

statusCode AlBlendPoint::curvatureType(AlBlendPoint::AlCurvatureType& ct ) Description

Returns the curvature type that is being used by this blend point. This method works only if we are using geometric interpolations of geometry and we are attached to a surface with G2 or greater continuity at this point.

Arguments
> ct - the blend points direction type

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - the blend point is invalid sInvalidArgument - the blend point is not using geometric interpolations of geometry and is not attached to a surface with G2 or greater continuity.

statusCode AlBlendPoint::setCurvatureType( AlCurvatureType ct ) Description

Sets the curvature type that is being used by this blend point. This method works only if we are using geometric interpolations of geometry and we are attached to a surface with G2 or greater continuity at this point.

Arguments
> ct - the blend points direction type

Return Codes
sSuccess - the method succeeded

AlBlendPoint | 157

sFailure - internal failure sInvalidObject - the blend point is invalid sInvalidArgument - the blend point is not using geometric interpolations of geometry and is not attached to a surface with G2 or greater continuity.

statusCode AlBlendPoint::attachConstraint( AlSurface *surface, double u, double v ) Description

Attaches this blend point as a constraint to a surface.

Arguments
< surface - the surface to attach to < u,v - position on surface to attach to

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - the blend point is invalid sInvalidArgument - surface is NULL, or surface is invalid, or u,v is invalid for the surface.

statusCode AlBlendPoint::attachConstraint( AlCurve *curve, double t ) Description

Attaches this blend point as a constraint to a curve. To attach a blend curve to another, pass the resulting curve of the second blend curve into this method. Note: this method will fail if the AlCurve of the AlBlendCurve of this AlBlendPoint is passed in as an argument.

Arguments
< curve - the surface to attach to < t - position on curve to attach to

158 | Chapter 1 AlAction AlBoxLight

Return Codes
sSuccess - the method succeeded sFailure - internal failure, or tried to attach point to its own curve sInvalidObject - the blend point is invalid sInvalidArgument - curve is NULL, or curve is invalid, or t is invalid for the curve.

statusCode AlBlendPoint::attachConstraint( AlCurveOnSurface *cos, double t) Description

Attaches this blend point as a constraint to a curve on surface.

Arguments
< cos - the curve on surface to attach to < t - position on curve on surface to attach to

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - the blend point is invalid sInvalidArgument - curve on surface is NULL, or curve on surface is invalid, or t is invalid for the surface.

statusCode AlBlendPoint::disassociateConstraint() Description

Disassociates the blend point from geometry it is attached to. The position of the blend curve is not changed by this method

Return Codes
sSuccess - the method succeeded

AlBlendPoint | 159

sFailure - internal failure sInvalidObject - the blend point is invalid

statusCode AlBlendPoint::attachedTo( AlObject *&obj, double& p1, double& p2 ) Description

Returns the object and point of attachment parameterization value.

Arguments
> obj - the object the blend point is attached to. > p1, p2 - if the object is a surface, both p1 and p2 is set to the u, v values of the point of attachment. If the object is a curve or curve on surface, p1 is set to the t value of the point of attachment to the curve and p2 is unused and set to 0.

Return Codes
sSuccess - the method succeeded sFailure - internal failure sInvalidObject - the blend point is invalid

boolean AlBlendPoint::isSlave() Description

Returns TRUE if this is a slave point.

statusCode AlBlendPoint::makeMaster() Description

If the current point is a slave, this method will make it a master.

Return Codes
sSuccess - the method succeeded sFailure - internal failure or point is already a master sInvalidObject - the blend point is invalid

160 | Chapter 1 AlAction AlBoxLight

AlBlendCurve* AlBlendPoint::blendCurve() Description

Returns the blend curve this point is associated with.

AlBlendPoint* AlBlendPoint::next() Description

Returns the next blend point in the blend curve.

statusCode AlBlendPoint::nextD( AlBlendPoint* blendPoint ) Description

Destructive method for returning the next blend point on the curve. sFailure is returned if there is no next blend point on the curve.

Arguments
< blendPoint - the blend point to obtain the next blend point from

Return Codes
sSuccess - the method worked sFailure - the method failed, could be due to there being no next blend point sInvalidObject - this blend point is invalid

AlBlendPoint* AlBlendPoint::prev() Description

Returns the previous blend point in the blend curve.

statusCode AlBlendPoint::prevD( AlBlendPoint* blendPoint ) Description

Destructive method for returning the previous blend point on the curve. sFailure is returned if there is no previous blend point on the curve.

AlBlendPoint | 161

Arguments
< blendPoint - the blend point to obtain the previous blend point from

Return Codes
sSuccess - the method worked sFailure - the method failed, could be due to there being no previous blend point sInvalidObject - this blend point is invalid

AlBlindData
Improved blind data support class.

Synopsis
class AlBlindData public: AlBlindData(AlObject *obj, int userID, size_t size); AlBlindData(int userID, size_t size); virtual ~AlBlindData(); virtual statusCode create(); virtual statusCode deleteData(); virtual bool isValid() const; protected: void convert(int&); void convert(float&); void convert(short&); void convert(double&); void setEndian(); void *getData() const;

162 | Chapter 1 AlAction AlBoxLight

Description
This class provides an improved blind data support. AlBlindData is a base class for OpenAlias plug-ins and OpenModel applications which need to maintain blind data (that is, data which Alias does not know about in a platform independent form). This class supersedes the existing blind data support (AlDagNode::blindData for example). The previous implementation for blind data did not provide any support for moving data between platforms which have different endian representations (for example Irix and NT). This class provides a nearly invisible solution to this problem. As such the previous implementation is obsolete and will be removed in a future release of the API.

AlBlindData::AlBlindData(int userID, size_t userSize) Description

Constructor for referencing blind data on an AlUniverse. If data with the userID already exists this wrapper will reference it, otherwise it will initialized for a call to the create() method.

Arguments
< userID - user ID of the data desired. < userSize - number of bytes in the block of data.

AlBlindData::AlBlindData(AlObject *parent, int userID, size_t userSize) Description

Constructor for referencing blind data on an AlObject. Only those object types which support blind data will successfully initialize this wrapper. If data with the userID already exists this wrapper will reference it, otherwise it will initialized for a call to the create() method.

Arguments
< parent - AlObject to attach blind data to. < userID - user ID of the data desired. < userSize - number of bytes in the block of data.

AlBlindData | 163

AlBlindData::~AlBlindData() Description
Delete the AlBlindData object. This does not affect the blind data.

bool AlBlindData::isValid() const Description

This method returns true if it is possible to read or write to the blind data. Accessing the blind data when this method returns false can lead to unexpected results including segmentation violations.

statusCode AlBlindData::deleteData() Description

This method deletes the blind data referenced by this wrapper. NOTE Under no circumstances should you delete the data yourself.

Return Codes
sSuccess - the data was successfully deleted. sInvalidObject - the wrapper does not reference a valid object.

statusCode AlBlindData::create() Description

Create an instance of the blind data on the object and of the size set when the AlBlindData object was instantiated. If this object already references blind data this method fails.

Return Codes
sAlreadyCreated - this object already references blind data. sInvalidObject - the parent object was invalidated or cannot accept blind data. sObjectAlreadyPresent - blind data of the same user ID but different size exists. This likely happens when attempting to reference old style blind data.

164 | Chapter 1 AlAction AlBoxLight

sInsufficientMemory - insufficient memory to creat the blind data. sSuccess - the blind data was successfully created.

void *AlBlindData::getData() const Description

This protected method returns a pointer to the data referenced by this wrapper. The validity of the data should be checked with isValid() before the data is accessed. The AlBlindData object maintains ownership of the data and you are provided a pointer to the data only for the purposes of reading and writing to it. You may not free this pointer. The only way to delete the data is with the deleteData() method above.

void AlBlindData::convert(int& val) Description

This method ensures that the integer is properly converted from whatever endian representation the integer was saved in to the representation appropriate for the current platform. This method is called in the constructor of classes derived from this one.

void AlBlindData::convert(int& val) Description

This method ensures that the integer is properly converted from whatever endian representation the integer was saved in to the representation appropriate for the current platform. This method is called in the constructor of classes derived from this one.

void AlBlindData::convert(float& val) Description

This method ensures that the float is properly converted from whatever endian representation the float was saved in to the representation appropriate for the current platform. This method is called in the constructor of classes derived from this one.

AlBlindData | 165

void AlBlindData::convert(double& val) Description

This method ensures that the double is properly converted from whatever endian representation the double was saved in to the representation appropriate for the current platform. This method is called in the constructor of classes derived from this one.

void AlBlindData::setEndian() Description

This method sets the endian flag of the wrapper appropriately for the current platform. This method must be the last one called in constructors of classes derived from this one.

AlBoxLight
A class used to reference a box light.

Synopsis
#include <AlBoxLight.h> class AlBoxLight: public AlVolumeLight AlBoxLight(); virtual ~AlBoxLight(); statusCode create(); virtual AlObject* copyWrapper() const; AlObjectType type() const;

Description
A box light is a volume light where light exists within a cube. There are no additional parameters other than those already on the volume light. A box light could be np-scaled and used to fill a room with light. If it is used as a force field, it could fill the room with turbulence, leaving the air outside the room still.

166 | Chapter 1 AlAction AlBoxLight

AlBoxLight::AlBoxLight() Description
Constructs an AlBoxLight wrapper object.

AlBoxLight::~AlBoxLight() Description
Deletes an AlBoxLight wrapper object.

statusCode AlBoxLight::create() Description

Creates all the DAG nodes for this light and adds them to the universe. The DAG nodes are for position, look at and up, and another DAG node that groups these three together.

Return Codes
sSuccess - everything was successful sInsufficientMemory - not enough memory available sAlreadyCreated - light is already created

AlObjectType AlBoxLight::type() const Description

Returns the class identifier kBoxLightType.

AlBoxLight | 167

168

AlCamera AlCylinderLight

AlCamera
A base class that encapsulates behavior of perspective.

169

Synopsis
#include <AlCamera.h> class AlCamera : public AlObject virtual ~AlCamera(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; virtual const char* name() const; virtual statusCode setName( const char* ); statusCode addImagePlane( const char * ); AlImagePlane* firstImagePlane( void ); statusCode applyIteratorToImagePlanes( AlIterator*, int& ); AlWindow* firstWindow( void ); AlWindow* nextWindow( AlWindow *lastWindow ); statusCode nextWindowD( AlWindow *lastWindow ); statusCode nearClippingPlane( double& ) const; statusCode farClippingPlane( double& ) const; statusCode setNearClippingPlane( double ); statusCode setFarClippingPlane( double ); statusCode stereoView(boolean&, double&) const; statusCode setStereoView(boolean, double); statusCode motionBlur(boolean&) const; statusCode setMotionBlur(boolean);

Description
This class represents all of the functionality of Alias perspective cameras. When the AlWindow class was developed and it became possible to get and set the window associated with a camera, it became necessary not only to provide an interface to orthographic cameras as well, but also to separate the differences in functionality into two child classes. The AlCamera class remains as a base class, providing access to the behavior that all cameras share. In places where AlCameras were formerly used, it is possible to easily convert old code simply by substituting AlPerspectiveCamera for AlCamera almost everywhere. (A few other small modifications may be necessary.) Any camera can have image planes attached to it. To create an image plane on a camera, use the addImagePlane() method. If a window is associated with this camera (which will always be the case for orthographic cameras, but not so for perspective cameras) the firstWindow() function will return it.

170 | Chapter 2 AlCamera AlCylinderLight

AlCamera::~AlCamera() Description
Deletes an AlCamera wrapper object.

AlObject *AlCamera::copyWrapper() const Description

Makes a copy of the AlCamera. The returned AlCamera will reference the same data as the original.

statusCode AlCamera::deleteObject() Description

Abstract base class function, always returns sFailure.

AlObjectType AlCamera::type() const Description

Returns the class identifier kCameraType.

const char* AlCamera::name() const Description

Returns a pointer to this cameras name.

statusCode AlCamera::setName( const char *newName ) Description

Changes the cameras name to the given name. If the given name is not a unique one, then a unique name is generated based on the given name and assigned to the camera. In this case, a status code of sNameChangedToUniqueOne is returned. A copy of the argument string is made, so you are responsible for deleting it.

AlCamera | 171

Arguments
< newName - the name to be given to the camera

Return Codes
sSuccess - successful sInvalidObject - the camera is not valid sInvalidArgument - given pointer is NULL

statusCode AlCamera::addImagePlane( const char * fname ) Description

Builds an image from an image file and attaches it to the camera.

Arguments
fname - the name of the image to attach to the camera

Return Codes
sSuccess - successful sInvalidObject - the camera is not valid sInvalidArgument - given pointer is NULL sFailure - image could not be built

AlImagePlane* AlCamera::firstImagePlane( void ) Description

Returns the first image plane attached to this camera.

statusCode AlCamera::applyIteratorToImagePlanes( AlIterator* iter, int& rc ) Description

Applies an iterator to each image that is attached to this camera.

172 | Chapter 2 AlCamera AlCylinderLight

Arguments
iter - the iterator to apply > rc - the return variable for the return value of the last iterators application

Return Codes
sSuccess - successful sInvalidObject - the camera is not valid sInvalidArgument - given pointer is NULL

AlWindow *AlCamera::firstWindow( void ) Description

Returns the first window attached to this camera.

AlWindow *AlCamera::nextWindow( AlWindow *window ) Description

Returns the next window attached to this camera.

Arguments
< window - the window from which to walk forward

statusCode AlCamera::nextWindowD( AlWindow *lastWindow ) Description

Destructively points the given wrapper to the next window attached to this camera.

Arguments
< lastWindow - the window from which to walk forward

Return Codes
sSuccess - the wrapper now points to the next object in the list

AlCamera | 173

sFailure - there is no next window sInvalidObject - the camera is invalid sInvalidArgument - the given window is invalid

statusCode AlCamera::nearClippingPlane( double& ncp ) const Description

Returns the distance from the eye position to the near clipping plane.

Arguments
> ncp - return variable for the distance to the clipping plane

Return Codes
sSuccess - plane was retrieved sInvalidObject - the camera is not valid

statusCode AlCamera::farClippingPlane( double& fcp ) const Description

Returns the distance from the eye position to the far clipping plane.

Arguments
> fcp - return variable for the distance to the clipping plane

Return Codes
sSuccess - plane was retrieved sInvalidObject - the camera is not valid

statusCode AlCamera::setNearClippingPlane( double newNearDistance ) Description

Sets the distance between the eye position to the near clipping plane. The new distance to the near clipping plane must be SMALLER than the distance to the far clipping plane.

174 | Chapter 2 AlCamera AlCylinderLight

Arguments
< newNearDistance - the new distance to the clipping plane

Return Codes
sSuccess - plane was set sInvalidArgument - new near distance was greater than current far distance sInvalidObject - the camera is not valid

statusCode AlCamera::setFarClippingPlane( double newFarDistance) Description

Sets the distance to the far clipping plane. The new distance to the far clipping plane must be larger than the near clipping plane.

Arguments
< double newFarDistance - the new distance to the clipping plane

Return Codes
sSuccess - plane was set sInvalidArgument - new far distance was less than current near list sInvalidObject - the camera is not valid

statusCode AlCamera::stereoView(boolean& stereoEnabled, double& eyeOffset) const Description

Returns the camera stereo view information.

Arguments
> stereoEnabled - TRUE if stereo view is enabled, FALSE if not > eyeOffset - ocular separation

AlCamera | 175

Return Codes
sSuccess - successful sInvalidObject - the camera is not valid

statusCode AlCamera::setStereoView(boolean stereoEnabled, double eyeOffset) Description

Sets the camera stereo view information.

Arguments
< stereoEnabled - TRUE to enable stereo viewing, FALSE to disable it < eyeOffset - ocular separation

Return Codes
sSuccess - successful sInvalidObject - the camera is not valid

statusCode AlCamera::motionBlur( boolean& blur) const Description

Returns the camera motion blur information.

Arguments
> blur - TRUE if motion blur is on

Return Codes
sSuccess - successful sInvalidObject - the camera is not valid

176 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCamera::setMotionBlur( boolean blurEnabled ) Description

Sets the camera motion blur information.

Arguments
< blurEnabled - TRUE to enable motion blur

Return Codes
sSuccess - successful sInvalidObject - the camera is not valid

AlCameraNode
Dag node class for cameras.

Synopsis
#include <AlCameraNode.h> class AlCameraNode : public AlDagNode virtual ~AlCameraNode(); virtual AlObject* copyWrapper() const; virtual statusCode deleteObject(); virtual AlObjectType type() const; virtual boolean isInstanceable(); boolean isEyeNode() const; boolean isViewNode() const; boolean isUpNode() const; AlCamera* camera() const; AlCamera* camera(AlTM&) const;

Description
This class is a DAG node class used specifically for cameras. Each AlCamera object has three camera nodes, one for each of eye, view, and up positions. (For more information on how AlCameras and AlCameraNodes work together, see the Class Description for the AlCamera on page 169 object.)

AlCameraNode | 177

To create a camera node, the user must create a camera, which will is create the necessary camera nodes. The user cannot directly instantiate an AlCameraNode. To figure out which position a camera node represents, the user can use: 1) the isEyeNode(), isViewNode(), isUpNode() methods, or 2) the type() method to compare types with kCameraEyeType, kCameraUpType, or kCameraViewType. A camera node can be deleted in two ways. When a camera node is deleted, its associated camera (and other camera nodes) are deleted. When a camera is deleted, its camera nodes are also deleted.

AlCameraNode::~AlCameraNode() Description
Deletes an AlCameraNode wrapper object.

AlObject* AlCameraNode::copyWrapper() const Description

Makes a copy of the AlCameraNode. The returned AlCameraNode will reference the same data as the original.

statusCode AlCameraNode::deleteObject() Description

Deletes the associated AlCamera (which in turn deletes all the attached camera eye, view and up nodes).

Return Codes
sSuccess - the camera data was successfully deleted sInvalidObject - the camera was not valid

178 | Chapter 2 AlCamera AlCylinderLight

AlObjectType AlCameraNode::type() const Description

Returns the class identifier for a camera node. This can be any one of kCameraEyeType, kCameraViewType, or kCameraUpType.

boolean AlCameraNode::isInstanceable() Description

Returns FALSE. An AlCameraNode is not an instanceable DAG node.

boolean AlCameraNode::isEyeNode() const Description

Returns TRUE if this camera node represents the eye position of a camera.

boolean AlCameraNode::isViewNode() const Description

Returns TRUE if this camera node represents the view position of a camera.

boolean AlCameraNode::isUpNode() const Description

Returns TRUE if this camera node represents the up position of a camera.

AlCamera* AlCameraNode::camera() const Description

Returns a pointer to the attached AlCamera object.

AlCamera* AlCameraNode::camera(AlTM& tm) const Description

Returns a pointer to the attached camera object. The AlTM is updated with the cameraNodes TM if a camera exists.

AlCameraNode | 179

Arguments
> tm - the transformation matrix to be updated with the cameraNodes TM

AlCategory
Interface to Alias category objects.

Synopsis
#include <AlCategory.h> class AlCategory : public AlObject virtual ~AlCategory(); AlCategory(); virtual AlObject* copyWrapper() const; virtual statusCode deleteObject(); virtual AlObjectType type() const; statusCode create(const char * = NULL); statusCode addMember(int); statusCode removeMember(int); int numberOfMembers() const; statusCode members(int numMembers, int members[]); const char * name() const; statusCode setName( const char*); const char * description() const; statusCode setDescription( const char*); statusCode pick(int); int isPicked() const;

Description
Categories are a way of organizing lists of layers. This organization simplifies changing the attributes of associated layers. Each AlCategory has a non unique name, picked status, description and a list of associated layers. The layer list contains layer numbers. Notes: 1) Attempting to add a layer to a category that is already in the list will fail. 2) Layers can belong to multiple categories. 3) All functions will fail if layers are not enabled.

180 | Chapter 2 AlCamera AlCylinderLight

4) AlCategory is available through OpenModel

AlCategory::AlCategory(void) Description
Constructs an AlCategory wrapper object.

AlCategory::~AlCategory() Description
Deletes an AlCategory wrapper object.

statusCode AlCategory::deleteObject() Description

Deletes the category.

Return Codes
sSuccess - the object was deleted sFailure - layers functionality turned off or internal failure sInvalidObject - the object was invalid

AlObject* AlCategory::copyWrapper() const Description

Returns an exact copy of the AlCategory wrapper.

AlObjectType AlCategory::type() const Description

Returns the class identifier kCategoryType.

AlCategory | 181

statusCode AlCategory::create( const char* name ) Description

Create a new category.

Arguments
< name - the name of the new category, default parameter name is NULL if not specified

Return Codes
sSuccess - the category was created sFailure - the category was not created because the layer functionality is turned off. sAlreadyCreated - object has already been created

const char * AlCategory::name() const Description

Returns the name of the object.

statusCode AlCategory::setName( const char *newName ) Description

Sets the name of the category

Arguments
< newName - new name of category

Return Codes
sSuccess - the name was set sFailure - the name length exceed 255 characters or layers functionality is disabled. sInvalidArgument - newName was NULL sInvalidObject - the object is not valid

182 | Chapter 2 AlCamera AlCylinderLight

const char * AlCategory::description() const Description

Returns the description of the object.

statusCode AlCategory::setDescription( const char *newDesc ) Description

Sets the description of the category

Arguments
< newDesc - new description of the category

Return Codes
sSuccess - the description was set sFailure - the description length exceed 255 characters or layers functionality is disabled. sInvalidArgument - newDesc was NULL sInvalidObject - the object is not valid

statusCode AlCategory::addMember(int layerID) Description

Adds a layer to the current category.

Arguments
< layerID- Numerical ID of the Layer to be added

Return Codes
sSuccess - the layer id was added sFailure - layers functionality turned off or internal failure or the layer id has already been added sInvalidObject - the object was invalid

AlCategory | 183

sInvalidArgument - the layer ID was invalid

statusCode AlCategory::removeMember(int layerID ) Description

Removes a layer from the current category

Arguments
< layerID- numerical ID of the layer to be removed

Return Codes
sSuccess - the layer id was removed sFailure - layers functionality turned off or internal failure or the layer id does not exist in the category sInvalidObject - the object was invalid sInvalidArgument - the layer ID was invalid

int AlCategory::numberOfMembers() const Description

Returns the member count of the category. If this method fails, -1 is returned.

statusCode AlCategory::members(int numMembers, int members[]) Description

Returns the members of the category

Arguments
< numMembers- size of array members > members - array of size numMembers, to return the member list in

Return Codes
sSuccess - the number of members is returned can legally be zero sFailure - layers functionality turned off or internal failure

184 | Chapter 2 AlCamera AlCylinderLight

sInvalidObject - the object was invalid sInvalidArgument - the value numMembers was not within layer range or the numMembers was greater then the numberOfMembers() in the category

boolean AlCategory::isPicked() const Description

Returns the pick status of the category;

Return Codes
true - if the category is picked false - if it is not picked, the object is invalid or layer functionality is turned off.

statusCode AlCategory::pick (boolean state) Description

Sets the pick status of the category

Arguments
< state - new state of the category, a value of true makes the category picked and false sets it to unpicked

Return Codes
sSuccess - the state was set sFailure - layers functionality is disabled. sInvalidObject - the object is not valid

AlChannel
Basic interface to Alias channels.

AlChannel | 185

Synopsis
#include <AlChannel.h> class AlChannel : public AlObject AlChannel(); virtual ~AlChannel(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; statusCode create( AlAnimatable*, int, AlAction*, AlTripleComponent = kX_COMPONENT ); statusCode create( AlAnimatable *, int, const char *); virtual AlObjectType type() const; AlObject* animatedItem() const; int parameter() const; const char* parameterName() const; AlChannelDataType channelType() const; AlChannel* copy( AlAnimatable*, int ); statusCode copyD( AlAnimatable*, int ); statusCode link(AlAction*, AlTripleComponent); statusCode applyWarp(); AlParamAction* applyWarpO(); statusCode removeWarp(AlAction*); double eval( double ) const; int numAppliedActions() const; AlAction* appliedAction(const int) const; AlTripleComponent appliedActionComponent( const int ) const; const char* expressionString () const;

Description
A channel controls how a field of an animatable item should change over time. It contains one or more actions that are evaluated at a given time and combined to produce an overall value of the channel at that time. When a channel is evaluated, for example at playback time, or, in the method AlViewFrame::viewFrame(), the value it is evaluated to is "stuffed" into the parameter of the item, thereby changing the value of that items parameter over time. A channel belongs solely to one field or parameter of an animatable item. A parameter of an item is animated by at most one channel. Thus, the create() methods will fail if an attempt is made to create a channel of a field that already has a channel (that is, is already animated). Under similar conditions, the copy() method will fail.

186 | Chapter 2 AlCamera AlCylinderLight

Currently a channel must contain at least one action (the base action of the channel), and thus the create() method requires you to supply this base action. You can modify this base action using the link() method. The applyWarp() and removeWarp() methods modify the time warp actions applied to the base action of the channel. They cannot affect the base action of the channel. The numAppliedActions() method will tell you how many actions are currently used by channel. This number will always be at least 1, since a channel must be animated by at least a base action. The appliedActions() will tell you which actions animate the channel. appliedActions(1) is the base action, and appliedActions(2 to n) are the time warp actions, where n is numAppliedActions(). If any of the actions are an AlMotionAction, then you may also want to know which of the X, Y or Z components the channel is using from the AlMotionAction (since this type of action evaluates to a triple of values). The method appliedActionComponent() can be used to determine this.

AlChannel::AlChannel() Description
Constructs an AlChannel wrapper object. Use the create() method to initialize the AlChannel.

AlChannel::~AlChannel() Description
Deletes an AlChannel wrapper object.

statusCode AlChannel::deleteObject() Description

Deletes a channel. The actions that are used by the channel will not be deleted.

Return Codes
sSuccess - the data for the AlChannel was successfully deleted sInvalidObject - the channel was not valid

AlChannel | 187

AlObject* AlChannel::copyWrapper() const Description

Makes a copy of the AlChannel. The returned AlChannel will reference the same data as the original.

statusCode AlChannel::create(AlAnimatable *anima, int field,AlAction *faction, AlTripleComponent component) Description

Creates a new channel that will animate the given field of the given object. The channel is animated using the given action as a base action. If the field of the object is already animated (that is, already has a channel), then this method will fail, and a new channel will not be created. The channel will also not be created if there is a motion path curve somewhere below this DAG node.

Arguments
< dagNode - DAG node that will be animated < field - which field of the DAG node to animate < action - base action which the channel should use < component - if the action is an AlMotionAction, this specifies which component of the evaluation of the curve should be used when evaluating the channel; if the action is not an AlMotionAction, this argument is ignored.

Return Codes
sSuccess - channel was successfully created sInvalidArgument - either faction was invalid or anima was NULL sInvalidObject - channel was not created sAlreadyCreated - channel is already created

188 | Chapter 2 AlCamera AlCylinderLight

statusCode AlChannel::create(AlAnimatable *anima, int field,const char *szExprText) Description

Creates a new channel that will attach an expression to the given field of the given object. If the field of the object is already animated or has an expression attached to it (that is, already has a channel), then this method will fail, and a new channel will not be created.

Note
This method sends out an update message in order to have the expression evaluated properly. As a result, creating a lot of expressions could be a slow process.

Arguments
< anima - the object that will be animated < field - which field of DAG node to attach the expression to < szExprText - expression to be attached to the field

Return Codes
sSuccess - channel was successfully created sInvalidArgument - either szExprText or anima was NULL sInvalidObject - channel was not created sAlreadyCreated - channel is already created sExpr{Errors} - errors from parsing the expression (see statusCodes.h)

AlObjectType AlChannel::type() const Description

Returns the class identifier kChannelType.

AlChannel | 189

AlObject* AlChannel::animatedItem() const Description

Returns the item that is being animated by this AlChannel. The item can be any of the possible animatable items, namely: AlDagNode, AlCurveCV, AlSurfaceCV, AlCamera, AlLight, AlShader, AlTexture or AlEnvironment.

int AlChannel::parameter() const Description

Returns the field of the item that is being animated by this channel. The return value is cast from whatever enum type corresponds to the animatable item, to an integer. For example: If this channel is animating an AlDagNode, then this method will return an AlDagNodeFields cast to an integer. If this channel is animating an AlCamera, then this method will return an AlCameraFields cast to an integer. If this channel is animating an AlShader, AlTexture or an AlEnvironment, then this method will return an AlShadingFields cast to an integer. If the call could not be completed, -1 is returned.

const char* AlChannel::parameterName() const Description

Returns a string that is a lexical name for the parameter/field that this channel animates.

AlChannelDataType AlChannel::channelType() const Description

Returns the type of channel (kAnimChannel or kExprChannel). kUnknownChannel is returned if there is an error.

AlChannel* AlChannel::copy(AlAnimatable *anima, int field) Description

Copies this channel, and applies the copied channel to animating the given field of the given object. If the given object is already animated by that field, this method will fail. When the channel is copied, each action in the original channel will be reused by the copy of the channel. This means that each of

190 | Chapter 2 AlCamera AlCylinderLight

the actions will now be referenced by at least two channels. The new copy of the channel will be returned. If any error occurred (for example object is already animated by the given field, or animating this object would animate a motion path) then NULL will be returned.

Arguments
< anima - the item to receive the new copy of the channel < field - the field of the DAG node that will be animated by the new copy of the channel

statusCode AlChannel::copyD(AlAnimatable *anima, int field) Description

Copies this channel, and applies the copied channel to animating the given field of the given object. If the given object is already animated by that field, this method will fail. When the channel is copied, each action in the original channel will be reused by the copy of the channel. This means that each of the actions will now be referenced by at least two channels. The new copy of the channel will be returned. If any error occurred (for example object is already animated by the given field, or animating this object would animate a motion path) then NULL will be returned.

Arguments
< anima - the item to receive the new copy of the channel < field - the field of the DAG node that will be animated by the new copy of the channel

Return Codes
sSuccess - the channel was successfully copied sInvalidArgument - anima was NULL sInvalidObject - the channel was not valid or the copy failed sFailure - could not copy the channel

AlChannel | 191

statusCode AlChannel::link(AlAction* action, AlTripleComponent component) Description

Replaces the base action of this channel with the given action. For example, if this channel is currently animated by action A, then this method will remove action A from the channel, and replace it by the given action, action. This channel will now only be animated by action. If this channel is currently animated by three actions, a base action A, and two time warp actions T1 and T2, then this method will replace the base action A with the given action so that the channel will now be animated by the base action action and the two time warp actions T1 and T2.

Arguments
< action - the action with which the channel should replace its current base action < component - if the action is an AlMotionAction, this specifies which component of the evaluation of the motion action curve should be used when evaluating the channel; if the action is not an AlMotionAction, this argument is ignored.

Return Codes
sSuccess - the link was successfully completed sInvalidObject - the channel was not valid sFailure - an error occurred sInvalidArgument - the action was invalid

statusCode AlChannel::applyWarp() Description

Creates a new action and applies it as a time warp to this channel. The new action will be an AlParamAction, and will have two keyframes, one at each of the min and max time of the range of animation of the channel. The time warp will be initially created to have no effect on the channel (that is, y = x, with kEXTRAP_IDENTITY extrapolation types).

192 | Chapter 2 AlCamera AlCylinderLight

Return Codes
sSuccess - the application of the warp was successful sInvalidObject - the channel was not valid sFailure - applying the warp failed sInsufficientMemory - the new warp was not created

AlParamAction* AlChannel::applyWarpO() Description

Creates a new action and applies it as a time warp to this channel. The new action will be an AlParamAction, and will have two keyframes, one at each of the min and max time of the range of animation of the channel. The time warp will be initially created to have no effect on the channel (that is, y = x, with kEXTRAP_IDENTITY extrapolation types). The newly created action will be returned.

statusCode AlChannel::removeWarp(AlAction* action) Description

Removes the given action from the channel as a time warp. For example, if the channel is currently animated by action A, followed by action as a first time warp, and action T as a second time warp, then after this method has been invoked, the channel will be animated by action A followed by action T. If this channel is currently animated by action, action as a base action, followed by four time warps in the following order: T1, action, action, "T2." After this method has been invoked, the channel will be animated by action action as a base action, and three time warps as follows: T1, action, "T2." Note that the base action cannot be removed from the channel by using this method. Removing the base action (for example, by deleting the action), will also cause the channel to be deleted.

Arguments
< action - the action to be removed from the channels list of time warps

AlChannel | 193

Return Codes
sSuccess - the action was successfully removed from the channels time warp actions sInvalidArgument - action was invalid sInvalidObject - the channel was not valid sFailure - the action was not being used as a time warp by this channel

double AlChannel::eval( double time ) const Description

Evaluates this channel at the given time, and returns the value of the channel at that time. If the call can not be completed, 0.0 is returned.

Arguments
< time - the time at which to evaluate the channel

int AlChannel::numAppliedActions() const Description

Returns the number of actions that this channel references and uses for its evaluation. The return value will always be >= 1 (except in the case of failure in which the return value is 0), since the channel must be animated by at least one base action. For example, if this channel is animated using base action A, and two time warp actions, T1 and T2, then this method will return 3.

AlAction* AlChannel::appliedAction(const int n) const Description

Returns the nth action that is applied to this channel. For example, if this channel is animated by action A as a base action, and then three time warps, T, A and T (note the reuse of the same actions), then appliedAction(1) and appliedAction(3) will return action A, and appliedAction(2) and appliedAction(4) will return action T. If n is less than 1, or greater than the number of actions used by this channel (as returned by AlChannel::numAppliedActions()), then NULL will be returned.

194 | Chapter 2 AlCamera AlCylinderLight

Arguments
< n - which action of the channel to return, where 1 refers to the base action of the channel, and 2 to numAppliedActions() refers to the channels time warp actions

AlTripleComponent AlChannel::appliedActionComponent(const int n ) const Description

Returns the extract component that the channel applies to the nth action. This method makes sense only if the nth action of the channel is an AlMotionAction. If the action is an AlParamAction, or the channel does not have a n action, then kINVALID_COMPONENT is returned. For example, if the channel is animated by the following actions,
AlMotionAction: A, kY_COMPONENT AlParamAction: T1 AlParamAction: T2

then this method will return kY_COMPONENT if n is 1, kINVALID_COMPONENT if n is 2 or 3 (since these actions are AlParamActions, and this method doesnt make sense for those values of n), and kINVALID_COMPONENT if n is less than 1, or greater than numAppliedActions().

Arguments
< n - which action of the channel the extract component should be determined for

const char* AlChannel::expressionString() const Description

If this channel is represented by an expression, this method returns a string representing the expression.

AlCharacter
Interface to Alias Character Network.

AlCharacter | 195

Synopsis
#include <AlCharacter.h> class AlCharacter : public AlObject enum AlCharacterStringInfo { kBlindData1, kBlindData2, kBlindData3, kBlindData4 }; AlCharacter(); virtual ~AlCharacter(); virtual AlObject* copyWrapper() const; statusCode create(const char *); virtual statusCode deleteObject(); virtual AlObjectType type() const; virtual const char* name() const; virtual statusCode setName(const char *); AlCharSnippet* createSnippet(const char *); AlCharTransition* createTransition(const char *); statusCode removeSnippet(AlCharSnippet *); statusCode removeTransition(AlCharTransition *); AlCharSnippet* findSnippetByName(const char *); AlCharTransition* findTransitionByName(const char *); AlCharSnippet* firstSnippet(void); AlCharSnippet* nextSnippet(void); AlCharTransition* firstTransition(void); AlCharTransition* nextTransition(void); statusCode connectSnippets(AlCharSnippet *, AlCharTransition *, AlCharSnippet *); statusCode convertTransitionToSnippet(AlCharTransition *, int, AlCharSnippet **, AlCharTransition **, AlCharTransition **); statusCode characterStringInfo(AlCharacterStringInfo, const char *&) const; statusCode setCharacterStringInfo(AlCharacterStringInfo, const char*);

Description
AlCharacter is the interface to the Character Network data of Alias Character Network objects.

196 | Chapter 2 AlCamera AlCylinderLight

A Character Network is a topology whose nodes are sequences (short linear pieces of animation) referred to as snippets and whose arcs are transitions between nodes. See the AlCharSnippet on page 210 class for more information snippets. See the AlCharTransition on page 218 class for more information transitions.

AlCharacter::AlCharacter() Description
Default constructor for AlCharacter Wrapper object. Use the create() method to initialize an AlCharacter object.

AlCharacter::~AlCharacter() Description
Deletes an AlCharacter wrapper object.

AlObject* AlCharacter::copyWrapper() const Description

Makes an exact copy of the AlCharacter wrapper

Return Values
NULL - unable to create new wrapper due to lack of memory non NULL - new Character Network wrapper

statusCode AlCharacter::deleteObject() Description

Deletes the Alias Character Network object. This method deletes the Character Network object data. Upon return there will be no Character Network corresponding to this wrapper or any other wrapper that references the same Character Network.

Return Codes
sSuccess - the Character Networks has been deleted

AlCharacter | 197

sInvalidObject - the Character Network was not valid

AlObjectType AlCharacter::type() const Description

Returns the class identifier kCharacterType.

statusCode AlCharacter::create(const char *characterName) Description

Does any initialization and allocation of data for an AlCharacter. Allocates room for this AlCharacter and adds this character to the universe.

Arguments
< characterName - name of the Character Network object

Return Codes
sSuccess - named Character Network object created sFailure - this wrapper already has a Character Network object, i.e already created sInsufficientMemory - not enough memory available

const char *AlCharacter::name(void) const Description

Returns the name of the Character Network.

Return Values
NULL - invalid wrapper non NULL - Character Network name

198 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCharacter::setName(const char *newCharacterName) Description

Renames a Character Network object. If the new name is already in use then a unique name will be generated. Use the name() method to determine the actual name of the Character Network object.

Arguments
< newCharacterName - the new name of the Character Network object

Return Codes
sSuccess - the Character Network object has been renamed sInvalidObject - the Character Network was not valid

AlCharSnippet* AlCharacter::createSnippet(const char *snippetName) Description

Creates the named Snippet for the Character. If the new name is already in use then a unique name will be generated. Use the AlSnippet::name() method to determine the actual name of the Character Network Snippet object. See the AlCharSnippet on page 210 class for more information on Character Network Snippets.

Arguments
< snippetName - the name of the new Character Network Snippet

Return Values
NULL - invalid wrapper non NULL - new Character Network Snippet wrapper

AlCharacter | 199

AlCharTransition* AlCharacter::createTransition(const char *transitionName) Description

Creates the named Transition for the Character. If the new name is already in use then a unique name will be generated. Use the AlTransition::name() method to determine the actual name of the Character Network Transition object. See the AlCharTransition on page 218 class for more information on Character Network Transitions.

Arguments
< transitionName - the name of the new Character Network Transition

Return Values
NULL - invalid wrapper non NULL - new Character Network Transition wrapper

statusCode AlCharacter::removeSnippet(AlCharSnippet *snippet) Description

Deletes the Character Network Snippet from the Character Network. See the AlCharSnippet on page 210 class for more information on Character Networks Snippets.

Arguments
< snippet - the AlCharSnippet wrapper of the Character Network Snippet

Return Codes
sSuccess - the Character Network Snippet has been deleted sInvalidObject - the Character Network Snippet was not valid

200 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCharacter::removeTransition(AlCharTransition *transition) Description

Deletes the Character Network Transition from the Character Network. See the AlCharTransition on page 218 class for more information on Character Networks Transitions.

Arguments
< snippet - the AlCharTransition wrapper of the Character Network Transition

Return Codes
sSuccess - the Character Network Transition has been deleted sInvalidObject - the Character Network Transition was not valid

AlCharSnippet* AlCharacter::findSnippetByName(const char *snippetName) Description

Finds the named Character Network Snippet in the Character Network and returns a new wrapper for it.

Arguments
< characterName - name of the object

Return Values
NULL - wrapper not valid, unable locate the named Character Network Snippet or unable to construct the wrapper non NULL - named Character Network Snippet wrapper

AlCharTransition* AlCharacter::findTransitionByName(const char *transitionName) Description

Finds the named Character Network Transition in the Character Network and returns a new wrapper for it.

AlCharacter | 201

Arguments
< characterName - name of the object

Return Values
NULL - wrapper not valid, unable locate the named Character Network Transition or unable to construct the wrapper non NULL - named Character Network Transition wrapper

AlCharSnippet* AlCharacter::firstSnippet(void) Description

Returns a new wrapper to first Character Network Snippet in the Character Network.

Return Values
NULL - wrapper not valid, no Character Network Snippets or unable to construct the wrapper non NULL - first Character Network Snippet wrapper

AlCharSnippet* AlCharacter::nextSnippet(void) Description

Returns a new wrapper to next Character Network Snippet in the Character Network.

Return Values
NULL - wrapper not valid, no more Character Network Snippets or unable to construct the wrapper non NULL - next Character Network Snippet wrapper

AlCharTransition* AlCharacter::firstTransition(void) Description

Returns a new wrapper to first Character Network Transition in the Character Network.

202 | Chapter 2 AlCamera AlCylinderLight

Return Values
NULL - wrapper not valid, no Character Network Transitions or unable to construct the wrapper non NULL - first Character Network Transition wrapper

AlCharTransition* AlCharacter::nextTransition(void) Description

Returns a new wrapper to next Character Network Transition in the Character Network.

Return Values
NULL - wrapper not valid, no more Character Network Transitions or unable to construct the wrapper non NULL - next Character Network Transition wrapper

statusCode AlCharacter::connectSnippets(AlCharSnippet *sourceSnippet,AlCharTransition *transition,AlCharSnippet *destinationSnippet) Description

Connects the sourceSnippet to the destinationSnippet via the transition. The snippets and the transition must have been previously created via createSnippet() and createTransition().

Arguments
< sourceSnippet - source Snippet for transition < transition - connect source to destination < destinationSnippet - destination Snippet for transition

Return Codes
sSuccess - everything okay sInsufficientMemory - not enough memory available sFailure - could not complete request

AlCharacter | 203

statusCode AlCharacter::convertTransitionToSnippet(AlCharTransition *transition,int transitionIsDeleted,AlCharSnippet **newSnippet,AlCharTransition **newSourceTransition,AlCharTransition **newDestinationTransition) Description

Converts a transition from snippet A to snippet B into a transition X from A to new snippet C, and a transition X" from C to B. Note that snippets A and B are implied by the transition. newSnippet, newSourceTransition and newDestinationTransition are declared by the caller and passed to the method as follows:
AlCharSnippet *newSnippet; AlCharTransition *newSourceTransition; AlCharTransition *newDestinationTransition; status = character->convertTransitionToSnippet( transition, TRUE, &newSnippet, &newSourceTransition, &newDestinationTransition );

The create() method for the new Snippet and Transitions are invoked by the method so valid wrappers for each object are passed back to the caller.

Arguments
< transition - the transition that connects snippet A to B < transitionIsDeleted - TRUE (1) if transition is to be deleted > newSnippet - new snippet C > newSourceTransition - new transition X > newDestinationTransition - new transition X"

Return Codes
sSuccess - everything okay sInsufficientMemory - not enough memory available sFailure - could not complete request

204 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCharacter::characterStringInfo(AlCharacterStringInfo dataType,const char *& sValue) const Description

Returns the specified string valued Character data.

Arguments
< dataType - the type of Character data to return > sValue - the value of the Character data

Return Codes
sSuccess - the Character data was returned in sValue sInvalidArgument - the Character dataType is not string valued

statusCode AlCharacter::setCharacterStringInfo(AlCharacterStringInfo dataType,const char* sValue) Description

Sets the specified string valued Character data.

Arguments
< dataType - the type of Character data to return < sValue - the new value of the Character data

Return Codes
sSuccess - the Character data was updated from sValue sInvalidArgument - the Character dataType is not string valued

AlCharacterSpace
Basic Interface to Alias Character Network Space.

AlCharacterSpace | 205

Synopsis
#include <AlCharacterSpace.h> class AlCharacterSpace : public AlObject AlCharacterSpace(); virtual ~AlCharacterSpace(); statusCode create(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; // Character network methods. AlCharacter* createCharacter(const char *); statusCode deleteCharacter(AlCharacter *); AlCharacter* findCharacterByName(const char *); AlCharacter* firstCharacter(void); AlCharacter* nextCharacter(void);

Description
This class encapsulates the basic functionality for creating, iterating through, locating by name, and deleting Character Networks. See the AlCharacter on page 195 class for a description of a Character Network. The Character Network Space is the set of all Character Networks.

AlCharacterSpace::AlCharacterSpace() Description
Default constructor for AlCharacterSpace Wrapper object. Use the create() method to initialize an AlCharacterSpace object.

AlCharacterSpace::~AlCharacterSpace() Description
Deletes an AlCharacterSpace wrapper object.

206 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCharacterSpace::deleteObject() Description

Delete all the Alias Character Network objects in the Alias Character Network space. For each Character Network in the Character Network space, the deleteObject() method will be invoked for that Character Network. See the AlCharacter on page 195 class for more information on Character Networks. This method deletes all the Character Network object data. Upon return there will be no Character Networks.

Return Codes
sSuccess - all Character Networks have been deleted from the Character Network Space sInvalidObject - the Character Network Space was not valid

AlObject* AlCharacterSpace::copyWrapper() const Description

Makes an exact copy of the AlCharacterSpace wrapper.

Return Values
NULL - unable to create new wrapper due to lack of memory non NULL - new Character Network Space wrapper

statusCode AlCharacterSpace::create() Description

Initializes the AlCharacterSpace object.

Return Codes
sSuccess - the Character Network Space has been initialized sInsufficientMemory - not enough memory available

AlCharacterSpace | 207

AlObjectType AlCharacterSpace::type() const Description

Returns the class identifier kCharacterSpaceType.

AlCharacterSpace* AlCharacterSpace::asCharacterSpacePtr() Description

This virtual function returns a non-null pointer to itself, indicating that it is safe to cast to an object of this class.

AlCharacter* AlCharacterSpace::createCharacter(const char *characterName) Description

Creates a new Character Network in the Character Network Space and returns a pointer to the AlCharacter wrapper. If a Character Network object with the requested name already exists then a new unique name is used for the new Character Network. Uses the AlCharacter::name() method to determine the actual name of a Character Network. See the AlCharacter on page 195 class for more information on Character Networks.

Arguments
< characterName - name of the object

Return Values
NULL - unable to create new Character Network due to lack of memory non NULL - new Character Network wrapper

statusCode AlCharacterSpace::deleteCharacter(AlCharacter *character) Description

Deletes the specified Character Network object from the Character Network Space. See the AlCharacter on page 195 class for more information on Character Networks.

208 | Chapter 2 AlCamera AlCylinderLight

Arguments
< character - the AlCharacter wrapper of the Character Network object

Return Codes
sSuccess - the Character Network object has been deleted sInvalidObject - the Character Network Space was not valid

AlCharacter* AlCharacterSpace::findCharacterByName(const char *characterName) Description

Finds the named Character Network in the Character Network Space and returns a new wrapper for it.

Arguments
< characterName - name of the object

Return Values
NULL - wrapper not valid, unable locate the named Character Network or unable to construct the wrapper non NULL - named Character Network wrapper

AlCharacter* AlCharacterSpace::firstCharacter(void) Description

Returns a new wrapper to first Character Network in the Character Network Space.

Return Values
NULL - wrapper not valid, no Character Networks or unable to construct the wrapper non NULL - first Character Network wrapper

AlCharacterSpace | 209

AlCharacter* AlCharacterSpace::nextCharacter(void) Description

Returns a new wrapper to next Character Network in the Character Network Space.

Return Values
NULL - wrapper not valid, no Character Networks or unable to construct the wrapper non NULL - next Character Network wrapper

AlCharSnippet
Interface to the Alias CharSnippet Network.

210 | Chapter 2 AlCamera AlCylinderLight

Synopsis

AlCharSnippet | 211

#include <AlCharSnippet.h> class AlCharSnippet : public AlObject enum AlCharSnippetIntegerInfo { kXPosition, kYPosition, kStart, kEnd, kPreviewMeasure, kRunLoops, kRunExit, kRunFrames, kLastStored, kNodeNumber }; enum AlCharSnippetStringInfo { kStageName, kSetName, kBlindData1, kBlindData2, kBlindData3, kBlindData4 }; AlCharSnippet(); virtual ~AlCharSnippet(); virtual AlObject* copyWrapper() const; AlCharSnippet* copyObject(); virtual statusCode deleteObject(); statusCode create(AlCharacter *, const char *); virtual AlObjectType type() const; virtual const char* name() const; virtual statusCode setName(const char*); AlCharTransition* firstTransition(void); AlCharTransition* nextTransition(void); int setTraversal(int); statusCode charSnippetIntegerInfo(AlCharSnippetIntegerInfo, int&) const; statusCode charSnippetStringInfo(AlCharSnippetStringInfo, const char *&) const; statusCode setCharSnippetIntegerInfo(AlCharSnippetIntegerInfo, int);

212 | Chapter 2 AlCamera AlCylinderLight

statusCode setCharSnippetStringInfo(AlCharSnippetStringInfo, const char*);

Description
AlCharSnippet is the interface to the CharSnippet Network data of Alias Character Network objects. A Snippet is a sequence or short linear pieces of animation. Snippets are connected by Transitions to form a Character Network. See the AlCharacter on page 195 class for more information Character Networks. See the AlCharTransition on page 218 class for more information on transitions.

AlCharSnippet::AlCharSnippet() Description
Default constructor for AlCharSnippet Wrapper object. Use the create() method to initialize an AlCharSnippet object.

AlCharSnippet::~AlCharSnippet() Description
Deletes an AlCharSnippet wrapper object.

AlObject* AlCharSnippet::copyWrapper() const Description

Makes an exact copy of the AlCharSnippet wrapper

Return Values
NULL - unable to create new wrapper due to lack of memory non NULL - new Character Network Snippet wrapper

AlCharSnippet *AlCharSnippet::copyObject() Description

Copies this AlCharSnippet returning a pointer to the new copy.

AlCharSnippet | 213

Return Values
NULL - unable to create new object or wrapper due to lack of memory non NULL - new Character Network Snippet wrapper

statusCode AlCharSnippet::create(AlCharacter *character,const char *snippetName) Description

Does any initialization and allocation of data for an AlCharSnippet. Allocates room for this AlCharSnippet and adds this Snippet to the character.

Arguments
< character - Character Network to create the Snippet in < snippetName - name of the Character Network Snippet object

Return Codes
sSuccess - named Character Network Snippet object created sInsufficientMemory - not enough memory available

statusCode AlCharSnippet::deleteObject() Description

Deletes an AlCharSnippet object. This method deletes the Character Network Snippet object data. Upon return there will be no Character Network Snippet corresponding to this wrapper or any other wrapper that references the same Character Network Snippet.

Return Codes
sSuccess - the Character Network Snippet has been deleted sInvalidObject - the Character Network Snippet wrapper was not valid

214 | Chapter 2 AlCamera AlCylinderLight

AlObjectType AlCharSnippet::type() const Description

Returns the class identifier kCharSnippetType. AlCharSnippet* AlCharSnippet::asCharSnippetPtr()

Description
This virtual function returns a non-null pointer to itself, indicating that it is safe to cast to an object of this class.

const char *AlCharSnippet::name(void) const Description

Returns the name of the CharSnippet.

Return Values
NULL - invalid wrapper non NULL - Character Network Snippet name

statusCode AlCharSnippet::setName(const char* newSnippetName) Description

Renames a Character Network Snippet object. If the new name is already in use then a unique name will be generated. Use the name() method to determine the actual name of the Character Network Snippet object.

Arguments
< newCharacterName - the new name of the Character Network object

Return Codes
sSuccess - the Character Network object has been renamed sInvalidObject - the Character Network was not valid

AlCharSnippet | 215

AlCharTransition* AlCharSnippet::firstTransition(void) Description

Returns a new wrapper to first transition of the Character Network Snippet.

Return Values
NULL - wrapper not valid, no transitions or unable to construct the wrapper non NULL - first Snippet transition wrapper

AlCharTransition* AlCharSnippet::nextTransition(void) Description

Returns a new wrapper to next transition in the Character Network Snippet.

Return Values
NULL - wrapper not valid, no more transitions or unable to construct the wrapper non NULL - next Snippet transition wrapper

int AlCharSnippet::setTraversal(int traversalStatus) Description

Sets the Snippet traversal status and returns the previous status.

Arguments
< traversalStatus - the new Snippet object traversal status

Return Values
the previous traversal status

216 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCharSnippet::charSnippetIntegerInfo(AlCharSnippetIntegerInfo dataType,int& iValue) const Description

Returns the specified integer valued Character Transition data.

Arguments
< dataType - the type of Character Transition data to return > iValue - the value of the Character Transition data

Return Codes
sSuccess - the Character Transition data was returned in iValue sInvalidArgument - the Character Transition dataType is not integer valued

statusCode AlCharSnippet::charSnippetStringInfo(AlCharSnippetStringInfo dataType,const char *& sValue) const Description

Returns the specified string valued Character Transition data.

Arguments
< dataType - the type of Character Transition data to return > sValue - the value of the Character Transition data

Return Codes
sSuccess - the Character Transition data was returned in sValue sInvalidArgument - the Character Transition dataType is not string valued

AlCharSnippet | 217

statusCode AlCharSnippet::setCharSnippetIntegerInfo(AlCharSnippetIntegerInfo dataType,int iValue) Description

Sets the specified integer valued Character Transition data.

Arguments
< dataType - the type of Character Transition data to return < iValue - the new value of the Character Transition data

Return Codes
sSuccess - the Character Transition data was updated from iValue sInvalidArgument - the Character Transition dataType is not integer valued

statusCode AlCharSnippet::setCharSnippetStringInfo(AlCharSnippetStringInfo dataType,const char* sValue) Description

Sets the specified string valued Character Transition data.

Arguments
< dataType - the type of Character Transition data to return < sValue - the new value of the Character Transition data

Return Codes
sSuccess - the Character Transition data was updated from sValue sInvalidArgument - the Character Transition dataType is not string valued

AlCharTransition
Interface to Alias CharTransition Network.

218 | Chapter 2 AlCamera AlCylinderLight

Synopsis

AlCharTransition | 219

#include <AlCharTransition.h> class AlCharTransition : public AlObject enum AlCharTransitionIntegerInfo { kLength, kActive, kStartTransitionType, kStartType, kStartFrame, kStartTo, kByFrame, kEndTransitionType, kEndType, kEndFrame, kTangentIn, kTangentOut, kPreCalcAnimation, kLastStored }; enum AlCharTransitionStringInfo { kBlindData1, kBlindData2, kBlindData3, kBlindData4 }; AlCharTransition(); virtual ~AlCharTransition(); virtual AlObject* copyWrapper() const; AlCharTransition* copyObject(); virtual statusCode deleteObject(); statusCode create(AlCharacter *, const char *); virtual AlObjectType type() const; virtual const char* name() const; virtual statusCode setName(const char *); int setTraversal(int); statusCode getSnippets(AlCharSnippet **, AlCharSnippet **); statusCode charTransitionIntegerInfo(AlCharTransitionIntegerInfo, int&) const; statusCode charTransitionStringInfo(AlCharTransitionStringInfo, const char *&) const; statusCode setCharTransitionIntegerInfo(AlCharTransitionInteger Info, int);

220 | Chapter 2 AlCamera AlCylinderLight

statusCode setCharTransitionStringInfo(AlCharTransitionStringInfo, const char *);

Description
AlCharTransition is the interface to the CharTransition Network data of Alias CharTransition Network objects. To create a character transition, first instantiate and create an AlCharTransition.

AlCharTransition::AlCharTransition() Description
Constructs an AlCharTransition wrapper object.

AlCharTransition::~AlCharTransition() Description
Deletes an AlCharTransition wrapper object.

AlObject* AlCharTransition::copyWrapper() const Description

Makes an exact copy of the AlCharTransition wrapper.

AlCharTransition *AlCharTransition::copyObject() Description

Copies this AlCharTransition returning a pointer to the new copy.

statusCode AlCharTransition::create(AlCharacter *character,const char *arc_name) Description

Does any initialization and allocation of data for an AlCharTransition. Allocates room for this AlCharTransition and adds this character to the universe.

AlCharTransition | 221

Return Codes
sSuccess - operation was successful sInsufficientMemory - not enough memory available sFailure - could not complete request

statusCode AlCharTransition::deleteObject() Description

Deletes an AlCharTransition wrapper object.

Return Codes
sInvalidObject - invalid wrapper sSuccess - deletion was successful

AlObjectType AlCharTransition::type() const Description

Returns the class identifier kCharTransitionType.

const char *AlCharTransition::name(void) const Description

Returns the name of the CharTransition.

statusCode AlCharTransition::setName(const char *new_transition_name) Description

Renames a transition.

int AlCharTransition::setTraversal(int traversalStatus) Description

Sets the Transition traversal status and returns the previous status.

222 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCharTransition::getSnippets(AlCharSnippet **sourceSnippet,AlCharSnippet **destinationSnippet) Description

Returns the source and destination snippets for the transition.

Return Codes
sSuccess - operation was successful sInvalidObject - invalid wrapper sInsufficientMemory - not enough memory available sFailure - could not complete request

statusCode AlCharTransition::charTransitionIntegerInfo(AlCharTransitionIntegerInfo dataType,int& iValue) const Description

Returns the specified integer valued Character Transition data.

Arguments
< dataType - the type of Character Transition data to return > iValue - the value of the Character Transition data

Return Codes
sSuccess - the Character Transition data was returned in iValue sInvalidArgument - the Character Transition dataType is not integer valued

statusCode AlCharTransition::charTransitionStringInfo(AlCharTransitionStringInfo dataType,const char *& sValue) const Description

Returns the specified string valued Character Transition data.

AlCharTransition | 223

Arguments
< dataType - the type of Character Transition data to return > sValue - the value of the Character Transition data

Return Codes
sSuccess - the Character Transition data was returned in sValue sInvalidArgument - the Character Transition dataType is not string valued

statusCode AlCharTransition::setCharTransitionIntegerInfo(AlCharTransitionIntegerInfo dataType,int iValue) Description

Sets the specified integer valued Character Transition data.

Arguments
< dataType - the type of Character Transition data to return < iValue - the new value of the Character Transition data

Return Codes
sSuccess - the Character Transition data was updated from iValue sInvalidArgument - the Character Transition dataType is not integer valued

statusCode AlCharTransition::setCharTransitionStringInfo(AlCharTransitionStringInfo dataType,const char* sValue) Description

Sets the specified string valued Character Transition data.

Arguments
< dataType - the type of Character Transition data to return < sValue - the new value of the Character Transition data

224 | Chapter 2 AlCamera AlCylinderLight

Return Codes
sSuccess - the Character Transition data was updated from sValue sInvalidArgument - the Character Transition dataType is not string valued

AlCloud
Interface to Alias clouds.

AlCloud | 225

Synopsis
#include <AlCloud.h> class AlCloud : public AlObject enum Subset { kSubsetInside, kSubsetOutside, kSubsetBoth }; AlCloud(); virtual ~AlCloud(); virtual AlObjectType type() const; virtual AlObject * copyWrapper() const; virtual statusCode deleteObject(); statusCode create(); virtual const char* name() const; virtual statusCode setName( const char* ); boolean visible(); statusCode setVisibility( boolean ); statusCode translation( double&, double&, double& ); statusCode setTranslation( double, double, double ); statusCode rotation( double&, double&, double& ); statusCode setRotation( double, double, double ); statusCode scale( double&, double&, double& ); statusCode setScale( double, double, double ); statusCode boundingBox( double&, double&, double&, double&, double&, double& ); statusCode subset( Subset, AlCloud **, double, double, double, double, double, double ); statusCode merge( AlCloud * ); int numberOfPoints() const; statusCode points( int, float[] ); statusCode addPoints(double, double, double, double, double, double, int, float[] ); statusCode pick(); statusCode unpick(); boolean isPicked(); AlCloud * nextCloud() const; statusCode nextCloudD( AlCloud * ) const;

226 | Chapter 2 AlCamera AlCylinderLight

Description
The AlCloud API is the interface to clouds and their data. You can do operations on clouds of points such as: creating, naming, picking, or merging them; controlling their visibility; setting their transformations; subsetting a cloud of points; or adding points to an existing cloud. You can also access most cloud settings, such as the current translation, scale or pick state. You can also:

Retrieve the number of points in a cloud with the numberOfPoints() method Retrieve the actual points with the points() method Add points with the addPoints() method. (See the descriptions below for information on how to set up the data structures for these methods.) Import a cloud of points with the method AlUniverse::importCloudFile() Walk a cloud list with AlUniverse::firstCloud() in conjunction with AlCloud::nextCloud(). (Use AlUniverse::applyIteratorToClouds() to walk all cloud elements.)

See the descriptions below for information on how to set up the data structures for these methods. NOTE Clouds are not in the Alias DAG tree. A cloud will not be an item on the Alias pick list. (You must use AlCloud pick methods rather than AlPickList methods.) To add arbitrary points to a cloud, you must create a cloud with the new points and then merge it into the cloud that you want to expand. The new cloud is deleted once it is merged. The new extended cloud has the outer bounding box of the two clouds. AlUniverse::importCloudFile() has a parameter which controls the sampling factor when the cloud file is imported.

AlCloud::AlCloud() Description
Constructs an AlCloud wrapper object.

AlCloud | 227

AlCloud::~AlCloud() Description
Deletes an AlCloud wrapper object.

statusCode AlCloud::deleteObject() Description

Deletes the cloud object.

Return Codes
sSuccess - the method succeeded sFailure - the method failed sInvalidObject - the object was invalid

AlObject *AlCloud::copyWrapper() const Description

Returns an exact copy of the cloud wrapper.

statusCode AlCloud::create() Description

Creates a cloud object. The cloud will have no points and the minimum and maximum points of its bounding box will all be zero.

Return Codes
sSuccess - the cloud was created sFailure - the cloud could not be created or the cloud object is already valid

AlObjectType AlCloud::type() const Description

Returns the class identifier kCloudType.

228 | Chapter 2 AlCamera AlCylinderLight

const char *AlCloud::name() const Description

Returns the name of the cloud object.

statusCode AlCloud::setName( const char *cloudName ) Description

Changes the name of a cloud. If the name is not unique then a new name is generated and a status of sNameChangedToUniqueOne is returned.

Arguments
< cloudName - new name of the object

Return Codes
sSuccess - the name was changed sInvalidArgument - the cloudName was NULL sFailure - the request could not be completed sInvalidObject - the cloud was invalid sNameChangedToUniqueOne - the name was changed to a unique version of the given name

boolean AlCloud::visible() Description

Returns TRUE if the cloud is visible.

statusCode AlCloud::setVisibility( boolean on_or_off ) Description

Sets the visibility of the cloud according to the boolean on_or_off parameter. Note: if this cloud is currently picked, it is unpicked so that pick list operations will not affect the cloud while it is invisible. When made visible again, the cloud will be unpicked.

AlCloud | 229

Arguments
< on_or_off - either TRUE or FALSE

Return Codes
sSuccess - the method was able to set the visibility sFailure - the method failed sInvalidObject - the cloud is invalid

statusCode AlCloud::translation( double &x, double &y, double &z ) Description

Returns the current translation of the cloud of points. The returned translation is in world space.

Arguments
> x - the clouds x translation > y - the clouds y translation > z - the clouds z translation

Return Codes
sSuccess - the translation was found sFailure - the method failed sInvalidObject - the cloud is invalid

statusCode AlCloud::setTranslation( double x, double y, double z ) Description

Sets the translation of the cloud of points. The translation is in world space coordinates.

Arguments
< x - x translation to be set < y - y translation to be set

230 | Chapter 2 AlCamera AlCylinderLight

< z - z translation to be set

Return Codes
sSuccess - the translation of the cloud was set sFailure - the method failed sInvalidObject - the cloud is invalid

statusCode AlCloud::rotation( double &x, double &y, double &z ) Description

Returns the current rotation of the cloud of points. The rotation returned is in world space coordinates.

Arguments
> x - clouds x rotation > y - clouds y rotation > z - clouds z rotation

Return Codes
sSuccess - the rotation was found sFailure - the method failed sInvalidObject - the cloud is invalid

statusCode AlCloud::setRotation( double x, double y, double z ) Description

Sets the rotation of the cloud of points. The rotation is in world space coordinates.

Arguments
< x - x rotation to be set < y - y rotation to be set < z - z rotation to be set

AlCloud | 231

Return Codes
sSuccess - the rotation of the cloud was set sFailure - the method failed sInvalidObject - the cloud is invalid

statusCode AlCloud::scale( double &x, double &y, double &z ) Description

Returns the current scale of the cloud of points. The scale returned is in world space coordinates.

Arguments
> x - clouds x scale > y - clouds y scale > z - clouds z scale

Return Codes
sSuccess - the scale was found sFailure - the method failed sInvalidObject - the cloud is invalid

statusCode AlCloud::setScale( double x, double y, double z ) Description

Sets the scale value of the cloud of points. The scale is in world space coordinates.

Arguments
< x - x scale to be set < y - y scale to be set < z - z scale to be set

232 | Chapter 2 AlCamera AlCylinderLight

Return Codes
sSuccess - the scale of the cloud was set sFailure - the method failed sInvalidObject - the cloud is invalid

statusCode AlCloud::boundingBox( double &minX, double &minY, double &minZ, double &maxX, double &maxY, double &maxZ ) Description
Returns the bounding box of the cloud of points. The bounding box corners are determined by combinations of the min and max values: (minX,minY,minZ), (minX,minY,maxZ), (minX,maxY,minZ), (minX,maxY,minZ) and so on.

Arguments
> minX - minimum x value of the cloud > minY - minimum y value of the cloud > minZ - minimum z value of the cloud > maxX - maximum x value of the cloud > maxY - maximum y value of the cloud > maxZ - maximum z value of the cloud

Return Codes
sSuccess - the bounding box was found sFailure - the method failed sInvalidObject - the cloud was invalid

statusCode AlCloud::subset( Subset partToKeep, AlCloud **newCloud, double minX, double minY, double minZ, double maxX, double maxY, double maxZ ) Description
Subsets a cloud of points based on which part to keep and the bounding box min and max value parameters. When both parts of the subsetted cloud are

AlCloud | 233

kept, the part outside the bounding box is returned as the newCloud variable. newCloud may be NULL. Note: calling subset(kSubsetBoth, ... ) has side effects on the cloud link list that is retrieved from the AlUniverse class. This same link list is also used by the AlUniverse::applyIteratorsToClouds() method. In the kSubsetBoth case, when the method is successfully completed the original cloud is deleted and two new clouds are created. Note that when you walk the cloud list yourself or use an iterator, your code will fail if it tries to advance from the cloud that was just deleted. If this method fails, it may be the case that the cloud was deleted.

Arguments
< partToKeep - one of kSubsetInside, kSubsetOutside or kSubsetBoth > newCloud - cloud created outside of the bounding box when kSubsetBoth is used; could be a NULL parameter < minX - minimum x of cloud subset bounding box < minY - minimum y of cloud subset bounding box < minZ - minimum z of cloud subset bounding box < maxX - maximum x of cloud subset bounding box < maxY - maximum y of cloud subset bounding box < maxZ - maximum z of cloud subset bounding box

Return Codes
sSuccess - the cloud was subsetted successfully sInvalidArgument - invalid bounding box minimum and maximum parameters sFailure - the method failed sInvalidObject - the cloud is invalid

statusCode AlCloud::merge( AlCloud *cloudToMerge ) Description

Merges a valid cloud into the current cloud. cloudToMerge is deleted and its wrapper is invalidated after the successful completion of this method. The

234 | Chapter 2 AlCamera AlCylinderLight

resulting cloud takes on the outer extents of itself and the cloud that was merged.

Arguments
< cloudToMerge - cloud to be merged

Return Codes
sSuccess - the merge was successful sInvalidArgument - the cloud to be merged was invalid, or the two clouds to be merged were the same sFailure - the method failed sInvalidObject - this cloud is invalid

int AlCloud::numberOfPoints() const Description

Returns the number of points that are in the cloud. A negative number is returned if there is an error or if the cloud is invalid. This routine is used in conjunction with AlCloud::points() so that you know how much storage to allocate for the points array.

statusCode AlCloud::points(int numberOfPoints, float pointArray[] ) Description

Provides access to the list of points within a cloud. Because a point consists of 3 floats, a cloud with 10 points would require a pointArray of size 30 to retrieve all points of the cloud. To access the points within the array, use the following code:
Example code: int num = cloud->numberOfPoints(); float *points = (float *) malloc( sizeof(float) * num * 3 ); if ( points == NULL ) return; if ( cloud->points( num, points ) != sSuccess ) return; float *pt = points; for ( int i = 0 ; i < num ; i++ ) { pt[0] += x; pt[1] += y; pt[2] += z; pt += 3; }

Note: numberOfPoints can be less than the actual number of points. The method will place as many points as possible into the array and then return successfully.

AlCloud | 235

Arguments
< numberOfPoints - size of the pointArray. Must be a value greater than 0 for every n points; you need to allocate n * 3 elements > pointArray - array in which to return points

Return Codes
sSuccess - the method succeeded sInvalidArgument - the method failed. numberOfPoints is less than 1 or pointArray is NULL sFailure - the method failed sInvalidObject - the cloud is invalid

statusCode AlCloud::addPoints( double minX, double minY, double minZ, double maxX, double maxY, double maxZ, int numberOfPoints, float points[] ) Description
Adds points within a min and max bounding box to a cloud. This method only works on a cloud that has no points and extents of zero. Any point in the points[ ] array outside of the specified min and max extents is skipped. Note: as in the points() method, the points parameter is a float[ 3 * numberOfPoints ] array.

Arguments
< minX - minimum x of cloud bounding box < minY - minimum y of cloud bounding box < minZ - minimum z of cloud bounding box < maxX - maximum x of cloud bounding box < maxY - maximum y of cloud bounding box < maxZ - maximum z of cloud bounding box < numberOfPoints - number of points in the point array. Each point is 3 doubles. (This is not the same as array size.) < points - the point array

236 | Chapter 2 AlCamera AlCylinderLight

Return Codes
sSuccess - the points were successfully added to the cloud sInvalidArgument - invalid bounding box sFailure - the current cloud does not have zero extents and no points, or the method failed sInvalidObject - the cloud is invalid

statusCode AlCloud::pick() Description

Picks the cloud of points.

Return Codes
sSuccess - the pick worked sFailure - the method failed sInvalidObject - the cloud is invalid

statusCode AlCloud::unpick() Description

Unpicks the cloud of points.

Return Codes
sSuccess - the unpick worked sFailure - the method failed sInvalidObject - the cloud is invalid

boolean AlCloud::isPicked() Description

Returns TRUE if the cloud is picked.

AlCloud | 237

AlCloud *AlCloud::nextCloud() const Description

Returns the next cloud in the universe.

statusCode AlCloud::nextCloudD( AlCloud *currentCloud ) const Description

A destructive method for moving to the next cloud. sFailure is returned if there is no next cloud.

Arguments
< currentCloud - the cloud to obtain the next cloud from

Return Codes
sSuccess - the method succeeded sFailure - the method failed or there is no next cloud in the list sInvalidObject - the cloud is invalid

AlCluster
Encapsulates creation, deletion and manipulation of clusters.

238 | Chapter 2 AlCamera AlCylinderLight

Synopsis
#include <AlCluster.h> class AlCluster : public AlObject enum PercentEffectType { kInvalid, kLeafNode, kJoint }; AlCluster(); virtual ~AlCluster(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; statusCode create(); AlObjectType type() const; AlCluster* nextCluster() const; statusCode nextClusterD(); AlCluster* prevCluster() const; statusCode prevClusterD(); AlClusterNode* clusterNode() const; boolean isEmpty() const; int numberOfMembers() const; AlClusterMember* firstMember() const; statusCode applyIteratorToMembers( AlIterator*, int& ) const; statusCode clusterRestrict( AlClusterRestrict& ) const; statusCode setClusterRestrict( AlClusterRestrict ); statusCode originalTRS( double[3], double[3], double[3] ) const;

Description
This class encapsulates the functionality for creating, manipulating and deleting a cluster. A cluster is a group of DAG nodes and/or curve and surface control points, which are grouped as such for deformation purposes. Every cluster has a cluster DAG node which is in the universes DAG. Adding and removing nodes and control points to and from a cluster does not affect the topology of the universes DAG. Transforming the cluster DAG node affects the transformations of the objects in the cluster. Empty clusters are allowed. An object can be in more than one cluster at a time, provided that those clusters are of type kMultiCluster. When an object is added to a cluster, it is given a weight that indicates how much of the clusters leaf transformation is applied to the object. The default weight is 100%. If a DAG node is added to a cluster the percentages of each individual CV may be manipulated separately without actually adding the CVs themselves to the cluster. To create a cluster, the user must instantiate and call create on an AlCluster object. This also creates an AlClusterNode which gets attached to the AlCluster

AlCluster | 239

and which is inserted into the universes DAG. The user may not instantiate an AlClusterNode or an AlClusterMember directly. There are two ways to delete a cluster object. When a cluster is deleted, its attached cluster node is deleted. Alternatively, when AlClusterNode::deleteObject() is used, its cluster is deleted. The DAG nodes and control points in a cluster are not deleted, however the AlClusterMember objects that represented the "in a cluster" relation are invalidated. Clusters dont have names. Any attempts to query for a name will return NULL.

AlCluster::AlCluster() Description
Constructs an AlCluster wrapper object.

AlCluster::~AlCluster() Description
Deletes an AlCluster wrapper object.

AlObject* AlCluster::copyWrapper() const Description

Returns an exact duplicate of the current AlCluster wrapper.

statusCode AlCluster::deleteObject() Description

Deletes the associated cluster node and for removes the cluster from the universe. This function also invalidates all of the AlClusterMember objects associated with this cluster. A cluster can be deleted in two ways. If AlCluster::deleteObject() is called, it deletes the associated cluster node. If AlClusterNode::deleteObject() is called, it invalidates the associated AlCluster and AlClusterMembers. Note that removing all members of a cluster will not destroy it. You must call the cluster deleteObject() to do this.

240 | Chapter 2 AlCamera AlCylinderLight

Return Codes
sSuccess - the data for the cluster was successfully deleted sInvalidObject - the cluster was not valid

statusCode AlCluster::create() Description

Creates a cluster and a cluster DAG node. The cluster DAG node is added to the current universe. The cluster by default is given non-exclusive status this means that a particular item can be in more than one cluster at a time.

Return Codes
sSuccess - everything was successful sInsufficientMemory - not enough memory available

AlObjectType AlCluster::type() const Description

Returns the class identifier kClusterType.

AlCluster* AlCluster::nextCluster() const Description

Returns a pointer to the cluster following this one in the global cluster list. If this is the last one then NULL is returned.

statusCode AlCluster::nextClusterD() Description

Destructively sets the object to point to the next cluster in the global cluster list, if the next cluster can be found. If not, the object is unaffected.

Return Codes
sSuccess - the AlCluster was successfully updated sInvalidObject - the AlCluster was not valid

AlCluster | 241

sFailure - the method failed

AlCluster* AlCluster::prevCluster() const Description

Returns a pointer to the cluster preceding this one in the global cluster list. If this is the first one then NULL is returned.

statusCode AlCluster::prevClusterD() Description

Destructively sets the object to point to the next cluster in the global cluster list, if the next cluster can be found. If not, the object is unaffected.

Return Codes
sSuccess - the AlCluster was successfully updated sInvalidObject - the AlCluster was not valid sFailure - the method failed

AlClusterNode *AlCluster::clusterNode() const Description

Returns a pointer to the attached (parent) cluster node. The cluster node must exist.

boolean AlCluster::isEmpty() const Description

Returns TRUE if this cluster is empty (that is, doesnt have any members). If the call fails, TRUE is returned.

AlClusterMember* AlCluster::firstMember() const Description

Returns the head of the list of members in this cluster.

242 | Chapter 2 AlCamera AlCylinderLight

int AlCluster::numberOfMembers() const Description

Returns the number of members in this cluster. Zero is returned if the call fails.

statusCode AlCluster::applyIteratorToMembers( AlIterator* iter, int &rc ) const Description

Applies the given iterator to each member of this cluster. See the documentation for AlIterator on page 544.

Return Codes
sSuccess - the iterator completed successfully sInvalidArgument - the iterator iter was NULL sInvalidObject - the cluster was invalid sFailure - the iterator completed abnormally

statusCode AlCluster::clusterRestrict( AlClusterRestrict& restrict ) const Description

Puts the type of the current cluster, kMultiCluster or kExclusiveCluster, into the argument.

Arguments
> restrict - value to return

Return Codes
sSuccess - the cluster type was successfully set sInvalidObject - the cluster was invalid sFailure - the cluster type could not be determined

AlCluster | 243

statusCode AlCluster::setClusterRestrict( AlClusterRestrict newRestrict ) Description

Sets the type of the current cluster, kMultiCluster or kExclusiveCluster

Arguments
< newRestrict - new cluster type

Return Codes
sSuccess - everything successful sInvalidObject - the cluster was not valid sFailure - if cluster could not take on the given type sInvalidArgument - the argument was neither kMultiCluster nor kExclusiveCluster

statusCode AlCluster::originalTRS( double [3], double [3], double [3]) const Description
Gets the original translate, rotate and scale of this cluster.

Return Codes
sSuccess - original TRS was get successfully sInvalidObject - the cluster was not valid sFailure - cant get the original TRS sInvalidArgument - if any of the arguments are NULL

AlClusterable
Encapsulates methods common to Alias objects that can belong to clusters.

244 | Chapter 2 AlCamera AlCylinderLight

Synopsis
#include <AlClusterable.h> class AlClusterable virtual AlCluster* firstCluster() const; virtual AlCluster* nextCluster( const AlCluster* ) const; virtual AlCluster* prevCluster( const AlCluster* ) const; virtual statusCode nextClusterD( AlCluster* ) const; virtual statusCode prevClusterD( AlCluster* ) const; virtual statusCode applyIteratorToClusters( AlIterator*, int& ); statusCode addToCluster( AlCluster*, double = 1.0 ); statusCode removeFromCluster( AlCluster* ); statusCode removeFromAllClusters(); AlClusterMember* isClusterMember( AlCluster* ) const; double percentEffect( AlCluster* ) const; statusCode setPercentEffect( AlCluster*, double );

Description
This class is a base class for all objects which can be contained in a cluster. It provides the methods necessary to access the cluster methods of these objects.

AlCluster* AlClusterable::firstCluster() const Description

Finds and returns the first cluster of which this object is a member. If no such cluster can be found, NULL is returned.

AlCluster* AlClusterable::nextCluster( const AlCluster* lastCluster ) const Description

Finds and returns the cluster following the given one of which this object is a member. If no such cluster can be found, NULL is returned.

Argument
< lastCluster - cluster to walk forward from

AlClusterable | 245

AlCluster* AlClusterable::prevCluster( const AlCluster* lastCluster ) const Description

Finds and returns the cluster preceding the given one of which this object is a member. If no such cluster can be found, NULL is returned.

Argument
< lastCluster - cluster to walk forward from

statusCode AlClusterable::nextClusterD( AlCluster* lastCluster ) const Description

Destructively sets the passed-in cluster to the next cluster for the given object. If this can not be accomplished, the passed-in cluster is unaffected.

Argument
< lastCluster - cluster to walk forward from

Return Codes
sSuccess - the cluster now points to the next cluster sInvalidArgument - lastCluster was invalid or NULL sFailure - there was no next cluster

statusCode AlClusterable::prevClusterD( AlCluster* lastCluster ) const Description

Finds and returns the cluster preceding the given one of which this object is a member. If no such cluster can be found, NULL is returned.

Argument
< lastCluster - cluster to walk forward from

Return Codes
sSuccess - the cluster now points to the previous cluster

246 | Chapter 2 AlCamera AlCylinderLight

sInvalidArgument - lastCluster was invalid or NULL sFailure - there was no previous cluster

statusCode AlClusterable::applyIteratorToClusters( AlIterator* iter, int &rc ) Description

Applies the given iterator to all the clusters in this object. See the documentation for AlIterator on page 544. Warning: be careful when using this iterator. If you modify the actual cluster during an iteration, it is possible that this routine will end up pointing to invalid data and send you garbage. This should not happen when simply applying transformations to a cluster. But deleting a cluster using this method is considered unsafe. If you do it, return immediately.

Arguments
< iter - the iterator to apply to each cluster > rc - the return from the last application of the iterator

Return Codes
sSuccess - the application of the iterator terminated normally sFailure - the application of the iterator terminated abnormally sInvalidArgument - the iterator was NULL

double AlClusterable::percentEffect( AlCluster* cluster ) const Description

Returns the percentage effect the given cluster has on this object. If the call fails, 0.0 is returned.

Arguments
< cluster - the cluster whose percentage effect is to be found

AlClusterable | 247

statusCode AlClusterable::setPercentEffect( AlCluster* cluster, double percentage ) Description

Sets the percentage effect the given cluster has on all things below this object.

Arguments
< cluster - the object whose children are to have their cluster percentage effects set

Return Codes
sSuccess - method was successful sInvalidArgument - clustobj was NULL sFailure - the percentage effect setting failed sInvalidObject - the cluster was not valid

statusCode AlClusterable::addToCluster( AlCluster* cluster, double percentage ) Description

Adds this clusterable object to a cluster. This means that all CVs under this DAG are affected by the cluster. The percentage defines how much of the clusters transformation is applied to the CVs under the DAG node. The default value of 1.0 means that the objects CVs are affected 100% by the cluster leaf transformations. The method may fail if unable to create a cluster member object, or if the addition of the object would create a cycle of clusters, or if the object to be added is already in the cluster, or if the object to be added already has an ancestor in the same target cluster.

Arguments
< cluster - the cluster to add this object to < percentage - the extent of the effect of the cluster on the objects CVs. The default is 1.0 (100%).

248 | Chapter 2 AlCamera AlCylinderLight

Return Codes
sSuccess - everything was successful sInvalidArgument - cluster was NULL sFailure - failed for one of the reasons outlined above sInvalidObject - the cluster was invalid sInsufficientMemory - not enough memory

statusCode AlClusterable::removeFromCluster( AlCluster* cluster ) Description

Removes this object from the cluster.

Arguments
< cluster - the cluster to remove this object from.

Return Codes
sSuccess - everything was successful sInvalidObject - the cluster is not valid sInvalidArgument - clustobj was not valid

AlClusterMember* AlClusterable::isClusterMember( AlCluster* cluster ) const Description

Finds the AlClusterMember that corresponds to the relationship between this object and the cluster object. NULL is returned if the object is not a member of the cluster or the cluster is not valid.

Arguments
< cluster - the cluster object to be checked

AlClusterable | 249

statusCode AlClusterable::removeFromAllClusters() Description

Removes this object from all clusters in the universe that it may be in.

Return Codes
sSuccess - the object was successfully removed from all clusters sInvalidArgument - the object was not valid

AlClusterMember
Represents the relationship between an item and a cluster to which it belongs.

Synopsis
#include <AlClusterMember.h> class AlClusterMember : public AlObject , public AlAnimatable virtual ~AlClusterMember(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; AlClusterMember* nextClusterMember() const; AlClusterMember* prevClusterMember() const; statusCode nextClusterMemberD(); statusCode prevClusterMemberD(); AlObject* object() const; AlCluster* cluster() const; statusCode removeFromCluster( AlCluster* );

Description
This class encapsulates the relationship that is cluster membership. Whenever an object is placed into a cluster an AlClusterMember object is created to represent the relationship. Each AlClusterMember object knows the associated cluster object as well as the geometry object which represents the item in the cluster. Currently, this object can be an AlDagNode, AlSurfaceCV, or AlCurveCV. To determine an AlClusterMembers type, use the following method:

250 | Chapter 2 AlCamera AlCylinderLight

AlClusterMember* clusterMember; AlObject* objectMember; objectMember = clusterMember->object(); if( objectMember->asDagNodePtr() ) ;// This member is an AlDagNode object else if( asCurveCVPtr( objectMember ) ) ;// This member is an AlCurveCV object else if( asSurfaceCVPtr( objectMember ) ) ;// This member is an AlSurfaceCV object

Alternatively, the type() method in the AlObject class can be used to determine the object type:
AlClusterMember* clusterMember; AlObject* objectMember; objectMember = clusterMember->object(); switch( objectMember->type() ) { case kDagNodeType: { AlDagNode *dagNode = objectMember->asDagNodePtr(); .... } }

If an AlDagNode is a member of an AlCluster then every AlSurfaceCV, or AlCurveCV that appears in the DAG hierarchy underneath the AlDagNode is affected by the AlCluster. For example, if you wanted to set the percentage effects of all CVs that were affected by an AlCluster, you would use the firstMember() method from the AlCluster object, then walk along the AlClusterMember list using the method nextClusterMember() in the AlClusterMember object. Whenever you encountered an AlDagNode member (as determined by the code fragment above) you would recursively walk down the DAG node to find all AlSurfaceCVs and AlCurveCVs below it in the DAG. The AlClusterMember object may not be created or destroyed directly. The AlCluster object creates or destroys the AlClusterMember object when the memberships of the AlCluster object change. The print() method is an aid to debugging code. It prints the current contents of the cluster member object.

AlClusterMember | 251

AlClusterMember::~AlClusterMember() Description
Deletes an AlClusterMember wrapper object.

AlObject* AlClusterMember::copyWrapper() const Description

Makes an exact copy of the current AlClusterMember wrapper.

AlObjectType AlClusterMember::type() const Description

Returns the class identifier kClusterMemberType.

AlClusterMember* AlClusterMember::nextClusterMember() const Description

Returns a pointer to the cluster member following this one in the cluster. If this is the last one then NULL is returned.

AlClusterMember* AlClusterMember::prevClusterMember() const Description

Returns a pointer to the cluster member preceding this one in the cluster. If this is the first one then NULL is returned.

statusCode AlClusterMember::nextClusterMemberD() Description

Destructively points the current wrapper to the cluster member following this one in the cluster.

Return Codes
sSuccess - the wrapper now points to the next cluster member sInvalidObject - the cluster member was invalid

252 | Chapter 2 AlCamera AlCylinderLight

sFailure - there was no next cluster member

statusCode AlClusterMember::prevClusterMemberD() Description

Destructively points the current wrapper to the cluster member previous to this one in the cluster.

Return Codes
sSuccess - the wrapper now points to the previous cluster member sInvalidObject - the cluster member was invalid sFailure - there was no previous cluster member

AlObject* AlClusterMember::object() const Description

Returns the object that this cluster member references.

AlCluster* AlClusterMember::cluster() const Description

Returns the cluster that this cluster member belongs to.

statusCode AlClusterMember::removeFromCluster( AlCluster* cluster ) Description

Removes this cluster member from the cluster.

Arguments
< cluster - the cluster to be removed from

Return Codes
sSuccess - everything was successful sInvalidObject - cluster is not valid

AlClusterMember | 253

sInvalidArgument - clusterMember was not valid

AlClusterNode
Is the DAG node class for clusters.

Synopsis
#include <AlClusterNode.h> class AlClusterNode : public AlDagNode virtual ~AlClusterNode(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; virtual boolean isInstanceable(); AlCluster * cluster() const; AlCluster * cluster(AlTM&) const;

Description
This class is a DAG node class used specifically for clusters. Every AlClusterNode object has an AlCluster attached to it. (For more information on how AlClusters and AlClusterNodes work together, see the Class Description for the AlCloud on page 225 object.) To create a cluster node, the user must instantiate and call the create method on an AlCluster object, which will create an AlClusterNode. The user cannot directly instantiate an AlClusterNode. A cluster node can be deleted in two ways. When a cluster node is deleted, its associated cluster is deleted. When a cluster is deleted, its cluster node is also deleted.

AlClusterNode::~AlClusterNode() Description
Deletes an AlClusterNode wrapper object.

AlObject* AlClusterNode::copyWrapper() const Description

Makes an exact copy of this AlClusterNode wrapper.

254 | Chapter 2 AlCamera AlCylinderLight

AlObjectType AlClusterNode::type() const Description

Returns the class identifier, kClusterNodeType.

boolean AlClusterNode::isInstanceable() Description

Returns FALSE. An AlClusterNode is not an instanceable DAG node.

AlCluster* AlClusterNode::cluster() const Description

Returns a pointer to the attached AlCluster object.

AlCluster* AlClusterNode::cluster(AlTM& tm) const Description

Returns a pointer to the attached AlCluster object. The AlTM will be updated with the clusterNodes TM if a cluster exists.

Arguments
> tm - the transformation matrix to be updated with the clusterNodes TM

AlClusterPreTMItem
An item from a list holding AlTM on page 948 and AlCluster on page 238 items.

AlClusterPreTMItem | 255

Synopsis
#include <AlClusterPreTMItem.h> class AlClusterPreTMItem : public AlLinkItem ~AlClusterPreTMItem(); AlClusterPreTMItem* nextItem() AlClusterPreTMItem* prevItem() AlTM fTM; AlTM fInvTM; AlCluster* fAlCluster;

Description
This class is used in a list of objects (AlList) created by the AlDagNode::clusterPreTransformationMatrices() method. It is derived from AlLinkItem.

AlClusterPreTMItem::~AlClusterPreTMItem() Description
Deletes the AlClusterPreTMItem. This method will also delete the fAlCluster wrapper.

AlCommand
Encapsulates the user defined interface to command history.

256 | Chapter 2 AlCamera AlCylinderLight

Synopsis
#include <AlCommand.h> class AlCommand : public AlObject AlCommand(); virtual ~AlCommand(); virtual statusCode deleteObject(); virtual AlObjectType type() const; statusCode create( const char *name ); statusCode install(); statusCode uninstall(); statusCode modified(); int execute( boolean freeIfInvalid = TRUE ); int undo( boolean freeIfInvalid = TRUE ); AlSurfaceType surfaceType() const; statusCode setSurfaceType( AlSurfaceType ); AlUserCommand* userCommand(); int status() const; static statusCode setDebug( boolean on ); static statusCode add( AlUserCommandAlloc *, const char *name ); static statusCode remove( const char *name );

Description
This file contains the definitions required to define an user command history command. The command layer in Alias is a software layer that is between the user interface and the main application. A command is an object that represents actions such as: fillet, square, or patch. The user interface code builds commands that are sent through the layer to be executed. The user interface does not create geometry itself, it creates commands that do it. Commands can be saved somewhere and re-executed whenever the system feels it is necessary. As long as the data the command depends upon is valid, the command remains valid. The most practical application of re-executing a command is the generation of data from a piece of source geometry. When the original geometry changes, the new model can be automatically created by re-executing the command history on the new data. Command functions: These are outlined in the AlUserCommand class.

AlCommand | 257

A constructor DAG node is considered to be a DAG node which creates the result. An example of a constructor is one of the original curves in a fillet operation. A target DAG node is considered to be the result of a command operation. An example is the fillet created by the fillet command. The AlCommand class is used to maintain a list of the current plug-in defined command history commands. New commands are installed using the AlCommand::add method. This associates a string with a function that allocates a new copy of a command. The first parameter of the add command is a AlUserCommandAlloc. An AlUserCommandAlloc is a pointer to a function returning an AlUserCommand class as defined below.
typedef AlUserCommand *AlUserCommandAlloc();

AlCommand::remove is used to remove a command type from the database. AlCommand::create is used to create an new copy of the command. After a command has been created, its data fields can be accessed using the AlCommand->userCommand method. A command has two components, the UI driver and the underlying geometry manipulation code. The UI creates a new command using AlCommand::create. The private data is accessed using the AlCommand -> userCommand method (which is typecast to the plug-ins derived command). From this, the command data structures fields can be filled in. The UI uses the execute method to call the userCommands execute command. This does the actual command. Finally the result is added to the Alias system using the install method. The Alias messaging system will call the various functions in the command to maintain the dependencies and re-execute the command if necessary.

statusCode AlCommand::setDebug( boolean on ) Description

Turns command history debugging on (TRUE) or off (FALSE). Alias will write information into the errlog as the construction history plug-in runs if this boolean is set.

Arguments
< on - the new value of command history debugging

258 | Chapter 2 AlCamera AlCylinderLight

Return Codes
sSuccess - setting worked

AlCommand::AlCommand() Description
Constructor for a command wrapper.

AlCommand::~AlCommand() Description
Destructor for a command wrapper.

AlObjectType AlCommand::type() const Description

Returns kCommandType.

AlCommand *AlCommand::asCommandPtr() Description

Safe downcast to AlCommand.

AlUserCommand *AlCommand::userCommand() Description

Returns a pointer to the user command.

int AlCommand::status() const Description

Returns the value of the result from the last execution of the command. Returns -1 if this command is invalid.

AlCommand | 259

statusCode AlCommand::create( const char *name ) Description

Allocates a new user defined command history command.

Arguments
< name - the name of the command to create

Return Codes
sSuccess - method was successful sInvalidArgument - name was NULL sObjectNotFound - the command name was not found (undefined) sFailure - not enough memory or user constructor failure

statusCode AlCommand::deleteObject() Description

Deletes the command (also calls the user command destructor)

Return Codes
sSuccess - the command was deleted sInvalidObject - the command was invalid

AlSurfaceType AlCommand::surfaceType() const Description

Gets the type of surface produced by the given command.

statusCode AlCommand::modified() Description

Marks this command as being modified.

260 | Chapter 2 AlCamera AlCylinderLight

Return Codes
sInvalidObject - the command was invalid sSuccess - the command was marked as being modified

statusCode AlCommand::setSurfaceType( AlSurfaceType type ) Description

Sets the type of surface produced by the given command.

Arguments
< type - type of surface to be produced by the given command

Return Codes
sSuccess - setting was successful sInvalidArgument - type was neither kSurfaceSpline nor kSurfacePolyset sInvalidObject - the command was invalid

statusCode AlCommand::install() Description

Installs a command in the construction history list.

Return Codes
sInvalidObject - the command was invalid sSuccess - the command was installed sFailure - the command was already installed

statusCode AlCommand::uninstall() Description

Remove a command from the construction history list.

AlCommand | 261

Return Codes
sInvalidObject - the command was invalid sSuccess - the command was uninstalled sFailure - the command was not installed

int AlCommand::execute( boolean freeIfInvalid ) Description

Executes the command after it has been created. Do not directly call the execute command in the user command, but use this function instead.

Arguments
< freeIfInvalid - the command is freed if it is found to be invalid

Return Values
zero - command was successful negative number - the command is no longer valid positive number - the command did not succeed (the number returned is the error return value)

int AlCommand::undo( boolean freeIfInvalid ) Description

Undoes the command after it has been created. Do not directly call the undo command in the user command, but use this function instead.

Arguments
< freeIfInvalid - the command is freed if it is found to be invalid

Return Values
zero - command was successful negative number - the command is no longer valid

262 | Chapter 2 AlCamera AlCylinderLight

positive number - the command did not succeed (the number returned is the error return value)

statusCode AlCommand::add( AlUserCommandAlloc *func, const char *name ) Description

Adds the construction history command to the list of available commands.

Arguments
func - name of the function that will allocate the new AlUserCommand name - string name of the function

Return Codes
sFailure - another command with the same name already exists sInvalidArgument - func is NULL or name is NULL sInsufficientMemory - could not allocate memory for new function sSuccess - the add was successful

statusCode AlCommand::remove( const char *name ) Description

Deletes the construction history command.

Arguments
name - string name of the function

Return Codes
sFailure - command not found sInvalidArgument - name is NULL sSuccess - command was removed

AlCommand | 263

AlCommandRef
Interface to construction history command constructors, AlContact - Interface to Alias contact information.

264 | Chapter 2 AlCamera AlCylinderLight

Synopsis

AlCommandRef | 265

#include <AlContact.h> class AlCommandRef : public AlObject AlCommandRef(); virtual ~AlCommandRef(); virtual AlObjectType type() const; AlCommandRef* nextRef(); AlCommandRef* prevRef(); statusCode nextRefD(); statusCode prevRefD(); AlDagNode* dagNode(); AlCurveOnSurface* curveOnSurface(); AlContact* contact(); class AlContact : public AlObject AlContact(); virtual ~AlContact(); statusCode deleteObject(); virtual AlObjectType type() const; statusCode create(); statusCode appendContact( AlContact * ); int numberContacts() const; AlContact* nextContact(); AlContact* prevContact(); statusCode nextContactD(); statusCode prevContactD(); AlContactType contactType() const; // These are different values common to the various contact types // derived classes are not used since this would result in about 6 // new classes, each with a single method. // statusCode calculate( AlDagNode *dagNode, double tolerance = 0, boolean adjustTolerance = FALSE ); boolean areEqual( AlDagNode *dagNodeThis, AlContact *contactOther, AlDagNode *dagNodeOther) const; AlTrimCurve* trimCurve(); AlCurveOnSurface* curveOnSurface(); int freeCurveIndex(); double curveOnSurfaceParam() const; double paramValue() const; double nonisoparamMin() const; double nonisoparamMax() const; AlCurve* curve(); AlCurve* curveUV();

266 | Chapter 2 AlCamera AlCylinderLight

Description
Two classes are defined here. The first, AlContact, is used to access Alias contact information. It can be used in conjunction with commands to describe a constructor curve. The second class, AlCommandRef, is used to access the constructor references for the command.

AlCommandRef::AlCommandRef() Description
Constructs a wrapper for a reference object.

AlCommandRef::~AlCommandRef() Description
Destructor for a reference object.

AlObjectType AlCommandRef::type() const Description

Returns kCommandRefType.

AlCommandRef* AlCommandRef::nextRef() Description

Returns the next reference in this list of references for the command's constructor or target.

statusCode AlCommandRef::nextRefD() Description

Returns the next reference in this list of references for the command's constructor or target.

Return Codes
sSuccess - the wrapper points to the next reference sFailure - there is no next reference

AlCommandRef | 267

sInvalidObject - the reference is invalid

AlCommandRef* AlCommandRef::prevRef() Description

Returns the previous reference in this list of references for the command's constructor or target.

statusCode AlCommandRef::prevRefD() Description

Returns the previous reference in this list of references for the command's constructor or target.

Return Codes
sSuccess - the wrapper points to the next reference sFailure - there is no previous reference sInvalidObject - the reference is invalid

AlDagNode *AlCommandRef::dagNode() Description

Returns the DAG node that this reference refers to. Note that exactly one of dagNode() or curveOnSurface() will be used (the other will be NULL).

AlCurveOnSurface *AlCommandRef::curveOnSurface() Description

Returns the curve on surface that this reference refers to. Note that exactly one of dagNode() or curveOnSurface() will be used (the other will be NULL).

268 | Chapter 2 AlCamera AlCylinderLight

AlContact *AlCommandRef::contact() Description

If this reference was generated from a contact, this pointer points to it. dagNode() and curveOnSurface() are set properly regardless of whether a contact generated this reference.

AlContact::AlContact() Description
Constructor for a contact wrapper.

AlContact::~AlContact() Description
Destructor for a contact wrapper.

AlObjectType AlContact::type() const Description

Returns kContactType

statusCode AlContact::create() Description

Creates a contact (to be used along with a reference). Note: you will have to call deleteObject() on this contact in your destructor or the memory will be lost. Contacts are often used in conjunction with commands to describe a constructor curve. In Alias, the contacts are the individual curves selected in the command history.

Return Codes
sSuccess - the contact was created sInsufficientMemory - no memory

AlCommandRef | 269

statusCode AlContact::deleteObject() Description

Deletes a contact object. See the note in create().

Return Codes
sSuccess - the contact was deleted sInvalidObject - the contact was invalid

AlContact* AlContact::nextContact() Description

Returns the contact of the next contact curve.

AlContact* AlContact::prevContact() Description

Returns the contact of the previous contact curve.

statusCode AlContact::nextContactD() Description

Returns the contact of the next contact curve.

Return Codes
sSuccess - the wrapper points to the next contact sFailure - there is no next contact sInvalidObject - the object is invalid

statusCode AlContact::prevContactD() Description

Returns the contact of the previous contact curve.

270 | Chapter 2 AlCamera AlCylinderLight

Return Codes
sSuccess - the wrapper points to the next contact sFailure - there is no next contact sInvalidObject - the object is invalid

statusCode AlContact::appendContact( AlContact *addcontact ) Description

Considering the current contact to be the head in a list, adds the given contact to this list.

Arguments
< addcontact - the contact to add

Return Codes
sInvalidArgument - contact was invalid sObjectInvalid - the current contact was invalid sSuccess - the contact was added

int AlContact::numberContacts() const Description

Considering the current contact to be the head of a list, returns the number of contacts in this list. Returns 0 on error.

AlContactType AlContact::contactType() const Description

Returns the type of this contact. From the type, the appropriate information can be determined by using the methods trimCurve(), freeCurve(), curveOnSurface(), curveOnSurfaceParam(), isoparamValue(), nonisoparamMin() or nonisoparamMax(). This method returns one of the following:

AlCommandRef | 271

kContactInvalid, kContactIsoparamU/V, kContactCurveOnSurface, kContactTrimEdge or kContactFreeCurve.

AlTrimCurve* AlContact::trimCurve() Description

If this is a kContactTrimEdge, then this returns the selected trim edge.

AlCurveOnSurface* AlContact::curveOnSurface() Description

If this is a kContactCurveOnSurface, then this returns the selected curve on surface.

double AlContact::paramValue() const Description

Returns the Isoparametric value or Curve On Surface parameter.

double AlContact::nonisoparamMin() const Description

Returns the non iso-parameter minimum.

double AlContact::nonisoparamMax() const Description

Returns the non iso-parameter maximum.

AlCurve *AlContact::curve() Description

Returns the resulting contact line (in XYZ coordinates). Note that if this curve is allocated, a deleteObject() must be used to delete it.

272 | Chapter 2 AlCamera AlCylinderLight

AlCurve *AlContact::curveUV() Description

Returns the resulting contact line (in UV coordinates). Note that if this curve is allocated, a deleteObject() must be used to delete it.

statusCode AlContact::calculate( AlDagNode *dagNode, double tolerance, boolean adjustTolerance ) Description

Calculates the geometry describing the contact. If transform is not set, the tolerance will be adjusted (so specify the world space tolerance).

Arguments
< dagNode - picked DAG node < tolerance - error tolerance (0 indicates use default) < adjustTolerance

Return Codes
sSuccess - geometry calculated sFailure - geometry could not be calculated sInvalidArgument - dagNode was NULL

boolean AlContact::areEqual( AlDagNode *dagNodeThis,AlContact *contactOther, AlDagNode *dagNodeOther) const Description

Returns TRUE if the two contact descriptions are equal.

Arguments
this - the first contact to compare dagNodeThis - the dagnode of this contact contactOther - the other contact dagNodeOther - its dagnode

AlCommandRef | 273

AlConeLight
Adds parameters for cone-shaped volume lights.

Synopsis
#include <AlConeLight.h> class AlConeLight: public AlVolumeLight AlConeLight(); virtual ~AlConeLight(); virtual AlObject* copyWrapper() const; statusCode create(); AlObjectType type() const; double arc() const; double coneEndRadius() const; statusCode setArc(double); statusCode setConeEndRadius(double);

Description
A cone light allows light to exist inside the volume of a cone. A cone light could be made similar to a spotlight by setting Concentric and radial to 0, directional to 1, decay to 0 and dropoff to slightly less than 1. A cone light would make a good vortex field by setting the Radial to 1, concentric to .5, directional depending on whether the vortex is sucking up things or dropping them.

AlConeLight::AlConeLight() Description
Constructs an AlConeLight wrapper object.

AlConeLight::~AlConeLight() Description
Deletes an AlConeLight wrapper object.

274 | Chapter 2 AlCamera AlCylinderLight

statusCode AlConeLight::create() Description

Creates all the DAG nodes for this light and adds them to the universe. The DAG nodes are position, look at and up, and a DAG node that groups these three together.

Return Codes
sSuccess - everything was successful sInsufficientMemory - not enough memory available sAlreadyCreated - light is already created

AlObjectType AlConeLight::type() const Description

Returns the class identifier kConeLightType.

double AlConeLight::arc() const Description

Returns the cone lights arc (how much of the cone you actually have). This method returns -1 if the light is invalid.

double AlConeLight::coneEndRadius() const Description

Returns the cone lights coneEndRadius. This defines the shape of the cone. This method returns -1 if the light is invalid.

statusCode AlConeLight::setArc( double arc ) Description

Sets the arc of the light. The given arc must be in the range 0 to 360.

AlConeLight | 275

Arguments
< double arc - portion of the sphere to use

Return Codes
sSuccess - setting arc succeeded sInvalidObject - not a valid volume light sFailure - setting the arc failed sInvalidArgument - the arc was not in the range of 0 to 360

statusCode AlConeLight::setConeEndRadius( double cone_end_radius ) Description

Sets the cone end radius of the light.

Arguments
< cone_end_radius - radius to set

Return Codes
sSuccess - setting the radius succeeded sInvalidObject - the current light is not a valid volume light sFailure - setting the radius failed

AlConicAttributes
Interface to Alias conic curve attributes.

276 | Chapter 2 AlCamera AlCylinderLight

Synopsis
#include <AlConicAttributes.h> class AlConicAttributes : public AlAttributes virtual AlObjectType type() const; AlObject* copyWrapper() const; statusCode coefficients( double&, double&, double&, double&, double&, double& ) const; double zDisplacement() const; statusCode startPoint( double&, double& ) const; statusCode endPoint( double&, double& ) const; statusCode centerPoint( double&, double& ) const; statusCode transform( double[4][4] ) const; statusCode transform( AlTM& ) const; AlConicType form() const;

Description
AlConicAttributes is a class derived from the AlAttributes class. This class allows access to the attributes for a conic section. Conics may not be created, but they can be brought into Alias through the IGES interface. A conic is one of ellipse, hyperbola, parabola, circle, or line. Conics exist in the XY plane and are defined by the equation: A * X^2 + B * X * Y + C * Y^2 + D * X + E * Y + F = 0.

AlObjectType AlConicAttributes::type() const Description

Returns the class identifier kConicAttributeType.

AlObject* AlConicAttributes::copyWrapper() const Description

Makes a copy of the AlConicAttributes. The returned AlConicAttributes will reference the same data as the original.

AlConicAttributes | 277

statusCode AlConicAttributes::coefficients( double& c_a, double& c_b, double& c_c, double& c_d, double& c_e, double& c_f ) const Description
Determines the coefficients for the Conic, where the Conic is defined by the equation: A * X^2 + B * X * Y + C * Y^2 + D * X + E * Y + F = 0

Arguments
> c_a - the coefficient A > c_b - the coefficient B > c_c - the coefficient C > c_d - the coefficient D > c_e - the coefficient E > c_f - the coefficient F

Return Codes
sSuccess - coefficients were successfully returned sInvalidObject - the attribute was invalid sFailure - an error occurred

double AlConicAttributes::zDisplacement() const Description

Returns the displacement for the conic along the Z axis.

statusCode AlConicAttributes::startPoint( double& x, double& y ) const Description

Determines the start point for a conic. Note that for an ellipse the direction of the desired elliptical arc is counterclockwise.

278 | Chapter 2 AlCamera AlCylinderLight

Arguments
> x - x coordinate of the start point > y - y coordinate of the start point

Return Codes
sSuccess - the start point was successfully returned sInvalidObject - the attribute was invalid sFailure - an error occurred

statusCode AlConicAttributes::endPoint( double& x, double& y ) const Description

Determines the end point for a conic. Note that for an ellipse the direction of the desired elliptical arc is counterclockwise.

Arguments
> x - x coordinate of the end point > y - y coordinate of the end point

Return Codes
sSuccess - the end point was successfully returned sInvalidObject - the attribute was invalid sFailure - an error occurred

statusCode AlConicAttributes::centerPoint( double& x, double& y ) const Description

Determines the center point for a conic.

Arguments
> x - x coordinate of the center point < y - y coordinate of the center point

AlConicAttributes | 279

Return Codes
sSuccess - the center point was successfully returned. sInvalidObject - the attribute was invalid sFailure - an error occurred

statusCode AlConicAttributes::transform( AlTM& tm ) const Description

Returns the transformation matrix which transforms the 2D conic into 3D.

Arguments
> tm - where to place the resulting transformation matrix

Return Codes
sSuccess - the transform was successfully returned sInvalidObject - the attribute was invalid sFailure - an error occurred

statusCode AlConicAttributes::transform( double tm[4][4] ) const Description

A conic is defined in the XY plane. This method returns the transformation matrix that transforms the 2D conic into 3D.

Arguments
> tm - where to place the transformation matrix

Return Codes
sSuccess - the transform was successfully returned sInvalidArgument - tm was NULL sInvalidObject - the attribute was invalid sFailure - an error occurred

280 | Chapter 2 AlCamera AlCylinderLight

AlConicType AlConicAttributes::form() const Description

Returns the type of the conic. One of kEllipse, kHyperbola, kParabola, kCircle, or kLine may be returned. kNoConic may be returned if the attribute is no longer active or there is an error.

AlConstraint
Interface to IK constraint data.

Synopsis
#include <AlConstraint.h> class AlConstraint : public AlObject , public AlAnimatable virtual ~AlConstraint(); virtual statusCode deleteObject(); virtual AlObjectType type() const; virtual AlAnimatable* asAnimatablePtr( void ); AlConstraint* next( void ) const; boolean on() const; double weight() const; boolean isUVConstraint() const; statusCode uv( double[2] ) const; statusCode setOn( boolean ); statusCode setWeight( double ); statusCode setUV( double[2] ); AlDagNode* sourceNode( void ) const; AlDagNode* destinationNode( void ) const;

Description
The AlConstraint class allows access to the IK constraint information on an AlJoint. (See the discussion of skeletons, joints, constraints, ik, and so on, in the printed reference manuals for a full description.) Briefly, the constraint data constrains the joint node to another object. The constraint can be a point constraint, an orientation constraint, or an aim constraint.

AlConstraint | 281

This is the base class for constraints. Point, orientation, and aim constraints are derived from this class.

AlConstraint::~AlConstraint() Description
Destructor for the AlConstraint wrapper.

statusCode AlConstraint::deleteObject() Description

Destructor for AlConstraint.

Return Codes
sSuccess - the constraint was deleted sInvalidObject - the constraint was invalid sFailure - the constraint could not be deleted

AlObjectType AlConstraint::type() const Description

Returns the class identifier kConstraintType;

AlConstraint* AlConstraint::next() const Description

Returns the next constraint after this one. If no constraint follows, NULL is returned.

boolean AlConstraint::on() const Description

Indicates whether this constraint is active or not.

282 | Chapter 2 AlCamera AlCylinderLight

Return Values
TRUE - this constraint is active FALSE - this constraint is not active

double AlConstraint::weight() const Description

Returns the weight on this constraint. The weight will be between 0.0 and 100.0 inclusive (or -1 on error).

boolean AlConstraint::isUVConstraint() const Description

This method returns TRUE if the constraint is an uv constraint.

statusCode AlConstraint::uv(double uv[2]) const Description

This method returns uv values of the uv constraint.

Arguments
> uv[2] - the u and v parameter of the constraint. If the dest node is a curve, only uv[0] is valid.

Return Codes
sSuccess - the uv or u parameter(s) were returned sInvalidArgument - the uv was NULL sInvalidObject - this constraint is invalid or is not a uv constraint sFailure - this constraint is not a uv constraint.

AlDagNode* AlConstraint::sourceNode( void ) const Description

Returns the AlDagNode that the constraint is on.

AlConstraint | 283

AlDagNode* AlConstraint::destinationNode( void ) const Description

Returns the AlDagNode that the source node is constrained to.

statusCode AlConstraint::setOn( boolean onOff ) Description

Turns the effect of the constraint on or off.

Arguments
< onOff - TRUE turns the effect on, FALSE turns it off

Return Codes
sSuccess - effect set sInvalidObject - object invalid

statusCode AlConstraint::setWeight( double weight ) Description

Sets the weight of the constraint. The weight must be between 0.0 and 100.0 inclusive. If the weight is outside this range it will be clipped.

Arguments
< weight - the percentage effect of this constraint

Return Codes
sSuccess - weight set sInvalidObject - object invalid

statusCode AlConstraint::setUV(double uv[2]) Description

Sets the constraints uv values.

284 | Chapter 2 AlCamera AlCylinderLight

Arguments
< uv[2] - the u and v parameter for the constraint.

Return Codes
sSuccess - the uv or u parameter(s) were set sInvalidArgument - the uv was NULL sInvalidObject - this constraint is invalid or is not a uv constraint sFailure - this constraint is not a uv constraint

AlConstructionEntity
Base class for Alias construction entities.

Synposis
#include <AlConstructionEntity.h> class AlConstructionEntity : public AlObject, public AlPickable virtual ~AlConstructionEntity(); virtual statusCode deleteObject(); virtual AlObject * copyWrapper() const = 0; virtual AlObjectType type() const; virtual const char* name() const; virtual statusCode setName( const char * ); AlLayer * layer(); statusCode setLayer( AlLayer * ); boolean invisible(); statusCode setInvisible( boolean ); statusCode templated(boolean &) const;

Description
This base class encapsulates methods common to Alias construction entities. These entities include space points, curve points, surface points, curve on surface points, construction planes and construction vectors. Construction points have similarities to locator objects. A major difference between construction points and locators is that construction points will be on the Alias pick list. The AlPickList class can be used to retrieve picked construction

AlConstructionEntity | 285

entity objects. As you will see below, the AlConstructionEntity class multiply inherits from the AlPickable class. This class contains methods for deleting, and naming locators. In addition, methods are available for working with layers and for changing invisibility and templated modes. As in the locator objects, if a construction entity is dependent on an object that is deleted, it will also be removed.

AlConstructionEntity::AlConstructionEntity(void) Description
Constructs an AlConstructionEntity wrapper object.

AlConstructionEntity::~AlConstructionEntity() Description
Deletes an AlConstructionEntity wrapper object.

AlObjectType AlConstructionEntity::type() const Description

Returns the class identifier kConstructionEntityType.

const char *AlConstructionEntity::name() const Description

Returns the name of the construction entity. NULL is returned if this method fails.

statusCode AlConstructionEntity::setName( const char *name ) Description

Sets the name of the construction entity

Arguments
< name - name that construction entity should be called

286 | Chapter 2 AlCamera AlCylinderLight

Return Codes
sSuccess - the name was set sFailure - the method failed sInvalidObject - the construction entity is invalid sNameChangedToUniqueOne - the name was not unique so it was changed

AlLayer *AlConstructionEntity::layer() Description

Returns the layer that this construction entity is in. NULL is returned if this method failed.

statusCode AlConstructionEntity::setLayer( AlLayer *layer ) Description

Sets the layer of the construction entity.

Arguments
< layer - the layer to put this construction entity into

Return Codes
sSuccess - the layer was set sFailure - failed to set the layer sInvalidObject - the construction entity is invalid sInvalidArgument - layer is NULL or is invalid

boolean AlConstructionEntity::invisible() Description

Returns TRUE if the layer is invisible. FALSE will be returned if the method failed.

AlConstructionEntity | 287

statusCode AlConstructionEntity::setInvisible( boolean invisible ) Description

Sets the invisibility of the construction entity

Arguments
< invisible - either TRUE or FALSE

Return Codes
sSuccess - the visibility was set sFailure - failed to set the visibility sInvalidObject - the construction entity is invalid

statusCode AlConstructionEntity::templated(boolean &tmpl) const Description

Finds whether the object on which a construction entity depends is templated. If a construction entity does not depend on any other object, the argument is set to false.

Arguments
> tmpl - is set to true if the object on which a locator depends is templated. Otherwise, tmpl is set to false.

Return Codes
sSuccess - The value was set successfully sInvalidObject - the object is not valid

AlConstructionPlane
Interface to Alias construction planes.

288 | Chapter 2 AlCamera AlCylinderLight

Synopsis
#include <AlConstructionPlane.h> class AlConstructionPlane : public AlConstructionEntity AlConstructionPlane(); virtual ~AlConstructionPlane(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; statusCode create( AlPoint *, AlPoint *, AlPoint * ); statusCode create( AlPoint *, AlPoint *, double[3] ); statusCode create( double[3], double[3], double[3]); AlPoint * first(); AlPoint * second(); AlPoint * third(); statusCode scale( double&, double& ); statusCode setScale( double, double ); statusCode rotate( double&, double&, double& ); statusCode translate( double&, double&, double& ); statusCode transformationMatrix( double[4][4] ); statusCode origin( double&, double&, double& ); statusCode axes( double[3], double[3], double[3] );

Description
This class provides functionality for creating, manipulating and querying Alias construction planes. Construction planes can be specified several ways.

3 Points - The first 2 points specify the X axis. The first and last points specify a line that is used in the cross product with the x axis to provide the Z axis. Once the Z is known, the Y axis is calculated internally. 2 points and a normal - The first 2 points specify the X axis. The normal is the Z axis to the plane. 2 points in the form of doubles and a normal. The first 2 points specify the X axis. The normal is the Z axis to the plane.

This class provides access to the points used to create the construction plane (end may be NULL depending on the specification), transformation and axes information.

AlConstructionPlane | 289

AlConstructionPlane::AlConstructionPlane() Description
Null constructor.

AlConstructionPlane::~AlConstructionPlane() Description
Null destructor.

AlObject *AlConstructionPlane::copyWrapper() const Description

Returns an exact copy of the generic wrapper.

statusCode AlConstructionPlane::create( AlPoint *first, AlPoint *second, AlPoint *third ) Description

Create a construction plane specified by 3 points. The first 2 points specific the X axis. The first and last point specify a line that is used in the cross product with the X axis to calculate the Z axis.

Return Codes
sSuccess - the construction plane was created sFailure - the method failed sInvalidArgument - first, second, or third are either NULL or invalid or at least 2 point to the same Alias object sAlreadyCreated - object is already created

statusCode AlConstructionPlane::create( AlPoint *first, AlPoint *second, double normal[3] ) Description

Create a construction plane with 2 points that specify the X axis and a normal (Z axis).

290 | Chapter 2 AlCamera AlCylinderLight

Return Codes
sSuccess - the construction plane was created sFailure - the method failed sAlreadyCreated - object already created sInvalidArgument - one of first, second or normal is NULL, or first and second are NULL or equal

statusCode AlConstructionPlane::create( double[3] first, double[3] second, double[3] normal) Description

Create a construction plane with 2 points that specify the X axis and a normal (Z axis).

Return Codes
sSuccess - the construction plane was created sFailure - the method failed sAlreadyCreated - object already created sInvalidArgument - one of first, second or normal is NULL, or first and second are NULL or equal

AlPoint *AlConstructionPlane::first() Description

Returns the first point of the construction plane. NULL is returned if the method failed.

AlPoint *AlConstructionPlane::second() Description

Returns the second point of the construction plane. NULL is returned if the method failed.

AlConstructionPlane | 291

AlPoint *AlConstructionPlane::third() Description

Returns the third point of the construction plane. NULL is returned if the method failed or if the construction plane was not specified by 3 points.

AlObjectType AlConstructionPlane::type() const Description

Returns the class identifier kConstructionPlaneType.

statusCode AlConstructionPlane::scale( double& x, double& y ) Description

Returns the current scale of the construction plane. Planes only have an x,y scale.

Arguments
> x,y - the scale in x,y

Return Codes
sSuccess - the scale was found sFailure - the method failed sInvalidObject - the object is invalid

statusCode AlConstructionPlane::rotate( double& x, double& y, double& z ) Description

Returns the rotation of the construction plane.

Arguments
> x,y,z - the rotation

292 | Chapter 2 AlCamera AlCylinderLight

Return Codes
sSuccess - the rotation was found sFailure - the method failed sInvalidObject - the object is invalid

statusCode AlConstructionPlane::translate( double&, double&, double& ) Description

Returns the translation of the construction plane.

Arguments
> x,y,z - the translation

Return Codes
sSuccess - the translation was found sFailure - the method failed sInvalidObject - the object is invalid

statusCode AlConstructionPlane::setScale( double x, double y ) Description

Sets the scale for the construction plane.

Arguments
< x,y -

Return Codes
sSuccess - the scale was set sFailure - the method failed sInvalidObject - the object is invalid

AlConstructionPlane | 293

statusCode AlConstructionPlane::transformationMatrix( double matrix[4][4] ) Description

Returns the transformation matrix of the construction plane.

Arguments
> matrix - the matrix

Return Codes
sSuccess - the transformation matrix was returned sFailure - the method failed sInvalidObject - the object is invalid

statusCode AlConstructionPlane::origin( double& x, double& y, double& z ) Description

Returns the origin for the construction plane.

Arguments
> x,y,z - the origin

Return Codes
sSuccess - the origin was returned sFailure - the method failed sInvalidObject - the object is invalid

statusCode AlConstructionPlane::axes( double x[3], double y[3], double z[3] ) Description

Returns the x,y,z axes for the construction plane.

294 | Chapter 2 AlCamera AlCylinderLight

Arguments
> x,y,z - the axes found

Return Codes
sSuccess - the axes were returned sFailure - the method failed sInvalidArgument - x,y or z is NULL sInvalidObject - the object is invalid

AlConstructionVector
Interface to Alias construction vectors.

Synopsis
#include <AlConstructionVector.h> class AlConstructionVector : public AlConstructionEntity AlConstructionVector(); virtual ~AlConstructionVector(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; statusCode create( AlPoint *,double, double, double ); statusCode create( AlPoint *, AlPoint * ); statusCode vector( double&, double&, double& ); statusCode setVector( double, double, double ); AlPoint* origin(); AlPoint* end();

Description
Alias construction vectors can be created with 2 points or with 1 point and a vector. The origin and end points of this object can be queried through the use of this class. If a construction vector is created with 1 point and a vector, the end point will be NULL. In addition, if a construction vector is created with 2 points, the vector cannot be

AlConstructionVector | 295

AlConstructionVector::AlConstructionVector() Description
NULL constructor.

AlConstructionVector::~AlConstructionVector() Description
NULL destructor.

AlConstructionVector::~AlConstructionVector() Description
NULL destructor.

statusCode AlConstructionVector::create( AlPoint *origin, double x, double y , double z ) Description

This method creates a construction vector using one point and a vector.

Return Codes
sSuccess - the construction vector was created sFailure - the method failed sInvalidArgument - the origin ptr is NULL or is invalid sAlreadyCreated - the object is already created

statusCode AlConstructionVector::create( AlPoint *origin, AlPoint *end ) Description

This method creates a construction vector based on two points.

Return Codes
sSuccess - the construction vector was created

296 | Chapter 2 AlCamera AlCylinderLight

sInvalidArgument - origin or end are either NULL or invalid sFailure - the method failed sAlreadyCreated - the object is already created

AlObjectType AlConstructionVector::type() const Description

Returns the class identifier kConstructionPlaneType.

AlPoint *AlConstructionVector::origin() Description

Returns the origin point of the construction vector. NULL is returned if this method fails.

AlPoint *AlConstructionVector::end() Description

Returns the end point of the construction vector. NULL is returned if the method fails or if this construction vector was not specified by two end points.

statusCode AlConstructionVector::vector( double& x, double& y, double& z) Description

Returns the vector of a construction vector if this object was not specified by 2 points.

Arguments
> x,y,z - the vector

Return Codes
sSuccess - the vector was found sFailure - object specified by two end points or internal failure sInvalidObject - the object is invalid

AlConstructionVector | 297

statusCode AlConstructionVector::setVector( double x, double y , double z) Description

Sets the vector of an AlConstructionVector in the case when this object is not specified by 2 points.

Arguments
< x,y,z - the vector to set

Return Codes
sSuccess - the vector was set sInvalidObject - the object is invalid sFailure - object specified by two end points or internal failure

AlCursor
Interface to Alias cursors. Note that some of this classs methods are not available on Windows.

Synposis
#include <AlCursor.h> class AlCursor enum { kArrowSquare=0, kEmpty, kHourGlass, kEyeDropper, kFullEyeDropper, kMove, kSelect, kInsert, kDelete, kCross, kTarget } Predefined; static statusCode push( int id ); static statusCode pop( void ); static int define( const char*,int,int,int,int ); static int define( const char*,int,int,int,int,const char*,int,int ); static statusCode remove( int id );

Description
This class allows you to display and define cursors inside of OpenAlias. Predefined cursors can be used or custom cursors can be created. Cursors are

298 | Chapter 2 AlCamera AlCylinderLight

maintained using a stack of ID numbers. When a cursor image is set, its ID is pushed onto the stack. When a cursor is popped, its image is restored to the previous image.

statusCode AlCursor::push( int id ) Description

Sets the current cursor to the given ID number and pushes the ID onto the stack. ID can be either a custom ID returned by AlCursor::define() or one of the default types (Predefined::kArrowSquare, Predefined::kEmpty, Predefined::kHourGlass, Predefined::kEyeDropper, Predefined::kFullEyeDropper, Predefined::kMove, Predefined::kSelect, Predefined::kInsert, Predefined::kDelete, Predefined::kCross, or Predefined::kTarget).

Arguments
id - the id to set the cursor image to

Return Codes
sSuccess - the cursor image changed sInvalidArgument - the cursor ID value was not valid

statusCode AlCursor::pop( void ) Description

Restores the cursor image to its previous state.

Return Codes
sSuccess - worked

AlCursor | 299

int AlCursor::define( const char* image, int imageWidth, int imageHeight, int imageHotSpotX, int imageHotSpotY, const char* mask, int maskWidth, int maskHeight ) Description
Creates a new cursor using a mask. These parameters are used in conjunction with XCreatePixmapFromBitmapData(). The mask can be used to create a blank region around the image. NOTE: this method always fails on the Windows.

Arguments
image - pointer to the bitmap data imageWidth, imageHeight - image bitmap size imageHotSpotX, imageHotSpotY - where the cursors hot spot is located mask - pointer to the mask data maskWidth, maskHeight - mask bitmap size

Return values
The new ID of the cursor is returned as a positive number. -1 indicates a failure;

int AlCursor::define( const char* image, int imageWidth, int imageHeight, int imageHotSpotX, int imageHotSpotY ) Description
Creates a new cursor (the cursor image is also used as the mask). NOTE: this method always fails on the Windows.

Arguments
image - pointer to the bitmap data imageWidth, imageHeight - image bitmap size imageHotSpotX, imageHotSpotY - where the cursors hot spot is located

300 | Chapter 2 AlCamera AlCylinderLight

Return values
The new ID of the cursor is returned as a positive number. -1 indicates a failure;

statusCode AlCursor::remove( int id ) Description

Deletes the given cursor id.

Arguments
id - the cursor to remove

Return Codes
sSuccess - the cursor image was deleted sInvalidArgument - the cursor ID value was a default cursor sFailure - the cursor ID value could not be found

AlCurve
Interface to Alias NURBS curves geometry.

AlCurve | 301

Synopsis

302 | Chapter 2 AlCamera AlCylinderLight

#include <AlCurve.h> class AlCurve : public AlObject AlCurve(); virtual ~AlCurve(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; statusCode create( int, curveFormType, int, const double[], int, const double[][4], const int[]); statusCode create( int, curveFormType, const double[], int, const double[][4]); statusCode createLine( const double[3], const double[3] ); statusCode createArc( const double[3], const double[3], const double[3], boolean ); statusCode createArc( double *, double *, double *, double,double, double, int=3, boolean=TRUE ); statusCode createConic( double, double, double, double, double, double, const double[3], const double[3] ); statusCode createParabola( const double[3], const double[3], const double[3], const double[3] ); statusCode createEllipse( const double[3], const double[3], const double[3], const double[3], const double[3] ); statusCode createHyperbola( const double[3], const double[3], const double[3], const double[3], const double[3] ); statusCode createPoint( const double[3] ); virtual AlObjectType type() const; AlCurveNode* curveNode() const; curveFormType form() const; int degree() const; int numberOfSpans() const; int numberOfCVs() const; AlCurveCV* firstCV() const; AlCurveCV* getCV( int ) const; AlAttributes* firstAttribute() const; statusCode CVsWorldPosition( double[][4], int[] ) const; statusCode CVsAffectedPosition( const AlTM&, double[][4], int[] ) const; statusCode CVsUnaffectedPosition( double[][4], int[] ) const; statusCode setCVsUnaffectedPosition( const double[][4] ); statusCode length( double& len, boolean worldCoords = TRUE, double tolerance=0.001 ); statusCode eval(double, boolean, double P[3] = NULL, double dP[3] = NULL ) const;

AlCurve | 303

statusCode eval( double dist, double P[3], double &t, boolean worldCoordinates = TRUE, double tolerance = 0.001) const; int numberOfKnots() const; statusCode knotVector( double[] ) const; statusCode setKnotVector( const double[] ); int numberOfCVsInclMultiples() const; statusCode CVsWorldPositionInclMultiples( double[][4] )const; statusCode CVsAffectedPositionInclMultiples( const AlTM&, double[][4] ) const; statusCode CVsUnaffectedPositionInclMultiples( double[][4] ) const; statusCode setCVsUnaffectedPositionInclMultiples( const double[][4] ); int realNumberOfKnots() const; statusCode realKnotVector( double[] ) const; statusCode setRealKnotVector( const double[] ); boolean isDisplayModeSet( AlDisplayModeType ) const; statusCode setDisplayMode( AlDisplayModeType, boolean ); statusCode applyIteratorToCVs( AlIterator*, int& ); statusCode doUpdates( boolean newState = TRUE ); statusCode periodicToNonPeriodic() const; statusCode normal(double [3]) const; statusCode insert( double param ); statusCode append( double pos[4], AlPointType type ); statusCode reverseCurve(); statusCode extendCurve( double , double [4] ); statusCode incrementDegree(); statusCode adjustEndSpan( double ); statusCode trimCurve( double, double );

Description
AlCurve is the interface to the geometric data of Alias NURBS curve objects. To create a curve, first instantiate and create an AlCurve and then instantiate and create an AlCurveNode. For more information on how to create the curve geometry, see the description for the create() method. A curve form can be one of three types: periodic, closed or open. If a curve is "kPeriodic", it is tangent continuous at all points on the curve and its endpoints are coincident. If a curve is "kClosed", it is not periodic but its endpoints are coincident. If the curve is neither closed nor periodic, it is considered to be "kOpen".

304 | Chapter 2 AlCamera AlCylinderLight

There are two ways to delete an AlCurve. If the AlCurve destructor is called, the attached AlCurveNode is deleted. If the AlCurveNode destructor is called, the attached AlCurve is deleted. You should always create a curve node for a curve. If you create a curve with no curve node, the curve is not added to the universe. If you should lose the pointer to the curve, it will become lost memory. There is one limitation to this class: you cannot add or remove individual curve control points (except by changing multiplicity). Curves are made of curve control points (or CVs) which you can traverse as a list by using AlCurve::firstCV() plus the AlCurveCV methods. You can also pack the curve information into an array using methods in this class.

What is multiplicity?
An AlCurveCV object can actually represent multiple CVs, depending on the AlCurveCVs multiplicity and periodicity. Notice that in this class there are two sets of methods - some "InclMultiples" and some not (namely "numberOfCVs", "CVsWorldPosition", "CVsUnaffectedPosition", etc). The set of methods without multiplicity lets you get all curve CVs where a curve CV can have multiplicity of 1, 2 or 3. The set of methods "InclMultiples" lets you get ALL curve CVs including multiples due to a multiplicity > 1 and due to periodicity.

Example 1
If you create a curve in the interactive Alias package with 4 CVs and change the multiplicity of the second CV to 2 (using the "multiplicity" menu item in the Curve Tools menu), then: 1 numberOfCVs() will return 4. 2 CVsWorldPosition must be passed a 4x4 CVs matrix, and a multiplicity vector of length 4. 3 CVsUnaffectedPosition() must be passed the same as item 2. 4 setCVsUnaffectedPosition() must be passed the same as item 2. 5 numberOfCVsInclMultiples() will return 5. 6 CVsWorldPositionInclMultiples() must be passed a 5x4 CVs matrix. You will notice that the 2nd and 3rd points in this matrix are the same. 7 CVsUnaffectedPositionInclMultiples() must be passed the same as item 6. You will notice that the 2nd and 3rd points in this matrix are the same.

AlCurve | 305

8 setCVsUnaffectedPositionInclMultiples() must be passed the same as item 6. The matrix you pass in should have the 2nd and 3rd points the same. What really happens in this method is that the 3rd point is given the same value as the 2nd point. (What you give as the 3rd point is ignored.)

Example 2
If you create a curve in the interactive Alias package with 4 CVs and "close" the curve (using the "close" menu item in the Object Tools menu), you create a periodic curve. Then: 1 numberOfCVs() will return 4. 2 CVsWorldPosition must be passed a 4x4 CVs matrix, and a multiplicity vector of length 4. 3 CVsUnaffectedPosition() must be passed the same as item 2. 4 setCVsUnaffectedPosition() must be passed the same as item 2. 5 numberOfCVsInclMultiples() will return 7. 6 CVsWorldPositionInclMultiples() must be passed a 7x4 CVs matrix. You will notice that in this matrix the 5th, 6th and 7th points are the same as the 1st, 2nd and 3rd points respectively. 7 CVsUnaffectedPositionInclMultiples() must be passed the same as item 6. You will notice that in this matrix the 5th, 6th and 7th points are the same as the 1st, 2nd and 3rd points respectively. 8 setCVsUnaffectedPositionInclMultiples() must be passed the same as item 6. The matrix you pass in should have the 5th, 6th and 7th points the same as the 1st, 2nd and 3rd points respectively. What really happens in this method is that the 5th, 6th and 7th points are assigned the same values as the 1st, 2nd and 3rd points respectively. (What you give for the 5th, 6th and 7th points are ignored.)

AlCurve::AlCurve() Description
Constructs an AlCurve wrapper object.

306 | Chapter 2 AlCamera AlCylinderLight

AlCurve::~AlCurve() Description
Deletes an AlCurve wrapper object.

AlObject *AlCurve::copyWrapper() const Description

Returns an exact copy of the AlCurve wrapper.

statusCode AlCurve::deleteObject() Description

Deletes the AlCurve.

Return Codes
sSuccess - the curve was deleted sInvalidObject - the curve was invalid sInsufficientMemory - ran out of memory

AlObjectType AlCurve::type() const Description

Returns the class identifier kCurveType.

AlCurveNode* AlCurve::curveNode() const Description

Returns the curve node associated with this curve. Returns NULL if there is no attached curve node.

AlCurve | 307

curveFormType AlCurve::form() const Description

When a curve is periodic it means that its endpoints are coincident and that the curve is tangent continuous at the point where its endpoints touch. "kPeriodic" is returned in this case. "kClosed" is returned if the curve is not periodic, but if its endpoints are coincident. If a curve is neither "kPeriodic" nor "kClosed" then "kOpen" is returned. (Note: If you use the "close" menu item in the interactive Alias package, you actually make a curve periodic.)

int AlCurve::degree() const Description

Returns the degree of the curve. -1 is returned if the curve is not valid.

int AlCurve::numberOfSpans() const Description

Returns the number of spans in the curve. -1 is returned if the curve is not valid.

int AlCurve::numberOfCVs() const Description

Returns the number of CVs. -1 is returned if the curve is not valid.

AlCurveCV* AlCurve::firstCV() const Description

Returns a pointer to the first CV in the curve.

AlCurveCV* AlCurve::getCV( int index ) const Description

Returns a pointer to the CV of the given index. Returns NULL if the CV could not be found or the index was negative. The index of the first CV is 0.

308 | Chapter 2 AlCamera AlCylinderLight

AlAttributes* AlCurve::firstAttribute() const Description

Returns the first attribute on this curve if any, otherwise NULL is returned. Note that if CV positions are modified through any of the AlCurve, AlCurveCV, AlCluster, AlSet, and so on, then the attributes are removed from the curve.

statusCode AlCurve::CVsWorldPosition( double CVList[][4], int multiplicity[] ) const Description

Returns the CVs in the given CV array and the multiplicity of each CV in the multiplicity vector. The first dimension of the CV array must be numberOfCVs(). The length of the multiplicity vector must also be numberOfCVs(). The multiplicity vector returned by this function is the same as the one returned by CVsUnaffectedPosition().

Arguments
> CVList - returned CV positions > multiplicity - the multiplicity of each CV

Return Codes
sSuccess - the curve CVs positions were returned sInvalidObject - the curve was not valid sFailure - an error occurred sInvalidArgument - a NULL argument was supplied

statusCode AlCurve::CVsAffectedPosition( const AlTM& tm, double CVList[][4], int multiplicity[] ) const Description
Returns the CVs in the given CV array and the multiplicity of each CV in the multiplicity vector. The first dimension of the CV array must be numberOfCVs(). The length of the multiplicity vector must also be numberOfCVs(). The multiplicity vector returned by this function is the same as the one returned by CVsUnaffectedPosition().

AlCurve | 309

Arguments
< tm - the transformation matrix built by transversing the DAG > CVList - returned CV positions > multiplicity - the multiplicity of each CV

Return Codes
sSuccess - the curve CVs positions were returned sInvalidObject - the curve was not valid sFailure - an error occurred sInvalidArgument - a NULL argument was supplied

statusCode AlCurve::CVsUnaffectedPosition( double CVList[][4],int multiplicity[] ) const Description

Returns the CVs in the given CV array and the multiplicity of each CV in the multiplicity vector. The first dimension of the CV array must be numberOfCVs(). The length of the multiplicity vector must also be numberOfCVs(). The multiplicity vector returned by this function is the same as the one returned by CVsWorldPosition().

Arguments
> CVList - returned CV positions > multiplicity - the multiplicity of each CV

Return Codes
sSuccess - the curve CVs positions were returned sInvalidObject - the curve was not valid sInvalidArgument - a NULL argument was supplied sFailure - an error occurred

310 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCurve::doUpdates( boolean newState ) Description

See AlDagNode on page 381 for information.

statusCode AlCurve::setCVsUnaffectedPosition( const double CVList[][4] ) Description

Sets the CVs of this curve to the values in the given CV array. The first dimension of the CV array must be numberOfCVs().

Arguments
< CVList - CV positions

Return Codes
sSuccess - the curve CVs positions were set sInvalidObject - the curve was not valid sInvalidArgument - a NULL argument was supplied sFailure - an error occurred

statusCode AlCurve::eval(double t, boolean worldCoordinates, double P[3], double dP[3] ) const Description
Determines the 3D coordinate and the derivative of the parameter value on the curve.

Arguments
< t - parameter position on the curve < worldCoordinates - the evaluation is done in world coordinates > P - the local position on the curve (if not NULL) > dP - the derivative of the curve at t (if not NULL)

AlCurve | 311

Return Codes
sSuccess - the coordinate was successfully determined sFailure - the evaluation failed sInvalidObject - the curve was invalid

statusCode AlCurve::eval( double dist, double P[3], double &t, boolean worldCoordinates, double tolerance ) const Description
Determines 3D coordinates of a point at a given distance from the start of a curve. Error tolerance must be greater than zero.

Arguments
< dist - arc length position on the curve > P - position of the point on the curve > t - parameter position on the curve < worldCoordinates - the evaluation is done in world coordinates < tolerance - the error tolerance

Return Codes
sSuccess - the coordinate was successfully determined sFailure - the evaluation failed sInvalidObject - the curve was invalid sInvalidArgument - tolerance was non-positive

int AlCurve::numberOfKnots() const Description

Returns the number of knots in this curve. For more information as to what this number means, see the description for the create() method. -1 is returned if the curve is not valid.

312 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCurve::knotVector( double knotVector[]) const Description

Returns the knot vector in the given vector. This vector must be of length numberOfKnots(). For more information as to what these values mean, see the description for the create() method.

Arguments
> knotVector - returned knot vector

Return Codes
sSuccess - the knot vector was returned sInvalidObject - the curve was not valid sInvalidArgument - a NULL argument was supplied

statusCode AlCurve::setKnotVector( const double knotVector[] ) Description

Sets the knot vector to be the given vector. This vector must be of length numberOfKnots(). For more information as to what these values mean, see the description for the create() method.

Arguments
< knotVector - the knot vector to be the given vector

Return Codes
sSuccess - the knot vector was set sInvalidObject - the curve was not valid sInvalidArgument - a NULL argument was supplied or the knots were not in increasing order

AlCurve | 313

int AlCurve::numberOfCVsInclMultiples() const Description

Returns the number of CVs, including multiples. For more information on what this value means, see the AlCurve on page 301 class documentation. -1 is returned if the curve is not valid.

statusCode AlCurve::CVsWorldPositionInclMultiples( double CVList[][4] ) const Description

Returns the world positions of all CVs in this curve, including multiples. The first dimension of the given CVList must be of length numberOfCVsInclMultiples(). Note that the positions returned are [ x y z w ] and not [ w*x w*y w*z w ].

Arguments
> CVList - the world positions of all CVs

Return Codes
sSuccess - the CVs positions were returned sInvalidObject - the curve was not valid sInvalidArgument - a NULL argument was supplied sFailure - an error occurred

statusCode AlCurve::CVsAffectedPositionInclMultiples( const AlTM& tm, double CVList[][4] ) const Description

Returns the world positions of all CVs in this curve, including multiples. The first dimension of the given CVList must be of length numberOfCVsInclMultiples(). Note that the positions returned are [ x y z w ] and not [ w*x w*y w*z w ].

314 | Chapter 2 AlCamera AlCylinderLight

Arguments
< tm - the transformation matrix built by traversing the DAG > CVList - returned world positions of all CVs

Return Codes
sSuccess - the CVs positions were returned sInvalidObject - the curve was not valid sInvalidArgument - a NULL argument was supplied

statusCode AlCurve::CVsUnaffectedPositionInclMultiples( double CVList[][4] ) const Description

Returns the unaffected positions of all CVs in this curve, including multiples. The first dimension of the given CVList must be of length numberOfCVsInclMultiples().

Arguments
> CVList - returned unaffected positions of all CVs

Return Codes
sSuccess - the CVs positions were returned sInvalidObject - the curve was not valid sInvalidArgument - a NULL argument was supplied sFailure - an error occurred

statusCode AlCurve::setCVsUnaffectedPositionInclMultiples( const double CVList[][4] ) Description

Sets the unaffected positions of all CVs in this curve, including multiples. The first dimension of the given CVList must be of length numberOfCVsInclMultiples(). You cannot give multiples different values. For example, if you have an open curve where numOfCVs() is 6 and

AlCurve | 315

numOfCVsInclMultiples() is 7 because the 2nd point has a multiplicity of 2, then the 2nd and 3rd quadruple in your CVList should be the same. What really happens is that the 3rd point is given the same value as the 2nd point. (What you give as the 3rd point is ignored). For more information see the examples in the class description.

Arguments
< CVList - the unaffected positions of all CVs

Return Codes
sSuccess - the CVs positions were set sInvalidObject - the curve was not valid sInvalidArgument - a NULL argument was supplied sFailure - an error occurred

boolean AlCurve::isDisplayModeSet( AlDisplayModeType mode ) const Description

Returns TRUE if the specified display mode is toggled on for the curve. Returns FALSE otherwise. The only valid AlDisplayModeTypes for an AlCurve are: kDisplayGeomHull kDisplayGeomEditPoints kDisplayGeomKeyPoints kDisplayGeomCVs

Arguments
< mode - display mode of interest

Return Values
FALSE is returned if the curve is not Valid.

316 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCurve::setDisplayMode( AlDisplayModeType mode, boolean on_or_off) Description

For the given display mode, if the flag on_or_off is TRUE then the display mode for the surface is set, otherwise it is unset. The only valid AlDisplayModeTypes for an AlCurve are: kDisplayGeomHull kDisplayGeomEditPoints kDisplayGeomKeyPoints kDisplayGeomCVs

Arguments
< mode - display mode of interest < on_or_off - boolean deciding if this surface will have the display mode set

Return Codes
sSuccess - operation was successful sInvalidObject - the curve was invalid sInvalidArgument - invalid display type

statusCode AlCurve::create( int deg, curveFormType form, int numKnots, const double knotVector[], int numControlPts, const double controlPoint[][4], const int multiplicity[]) Description
Creates the geometric data that represents this curve. Briefly, Alias curves are represented by an array of knots and an array of control points. (For a detailed understanding of NURBs curves, see the book "An Introduction to Splines for use in Computer Graphics and Geometric Modeling" by Bartels, Beatty and Barsky, also known as "The Killer Bs".) The number of spans in a curve is determined by the degree of the curve and the number of control points: namely, there are numControlPts - deg spans. Knot values are associated with the ends of each span. Therefore, numKnots must be equal to number of spans + 1.

AlCurve | 317

The expert will notice that numKnots = number of spans + 1 does not give us enough knots to specify all the basis functions properly. (The correct number of knots required, according to the Killer Bs are numSpans + 2*degree + 1). However since Alias piles knots up at the extreme ends of an open nurbs curve (in order to force the curve to touch each end control point) this method does not require that the user specify the redundant knot values. For example, if the knot vector for a three span open curve contained the knot values [0 1 2 3], the real knot vector would be [0 0 0 0 1 2 3 3 3 3]. In the case of a periodic curve the values of the knots can be determined implicitly from the knots values provided and again dont need to be provided explicitly. For example, if the knot vector for a four span periodic curve contained the knot values [-1 1 2 5 10], the real knot vector would be [-10 -9 -6 -1 1 2 5 10 12 13 16]. If this object was previously referencing some other curve, and this call succeeds, this object will reference the new curve. For more information on multiplicity, see the AlCurve on page 301 description. When you create a curve, you must ensure the following:

Open and closed curves must have at least one span. Periodic curves require that there be at least 3 spans. numKnots must be equal to number of spans + 1 The knot values must be a non-decreasing sequence of values. The first and last span must not be vacuous. That is knotVector[0] < knotVector[1] and knotVector[numKnots-2] < knotVector[numKnots-1] Any knot multiplicity must not exceed the degree of the curve. Periodic curves also require that the number of spans be greater than or equal to the degree of the curve. For open/closed curves the number of control points is the number of spans + degree. For example, one span requires four control points. For periodic curves the number of control points is the same as the number of spans. It isnt necessary to specify any of the overlapping control points. All multiplicity values must be 1, 2 or 3. The first and last multiplicity values must be 1.

Arguments
< deg - the degree of the curve

318 | Chapter 2 AlCamera AlCylinderLight

< form - kOpen, kClosed or kPeriodic < numKnots - the number of knots in the knotVector < knotVector - the sequence of knot values. Must be of length numKnots. < numControlPts - the number of points in controlPoint < controlPoint - the array of control points. Must have size of numControlPts * 4. < multiplicity - the multiplicity values. Must be of length numControlPts. Assumed to be an array of 1s if NULL.

Return code
sSuccess - data created sInsufficientMemory - ran out of memory sInvalidArgument - there are many ways to fail with this return code

Calling this method from AlFace (which derives from AlCurve) with a form of kOpen NULL knot or control point arrays Number of spans <= 0 { for a periodic curve, number of spans = number of control points, for open or closed curves, the number of spans = number of control points - degree Number of knots not equal to the number of spans + 1 Knot vector is not a non-decreasing sequence of values Knots that delimit the first and last spans are non -zero, ie. (knotVector[1] - knotVector[0]) and knotVector[numKnots-1] - knotVector[numKnots-2] are not both zero For a closed curve, the first and last control points are not the same For a periodic curve, the number of spans is less than 3 { leads to geometrically degenerate curves } For a periodic curve, the degree is greater than the number of spans { leads to multiple wrapping of control points }

sFailure - data could not be created

AlCurve | 319

statusCode AlCurve::create( int deg, curveFormType form, const double knotVector[], int numControlPts, const double controlPoint[][4] ) Description
Creates the geometric data that represents this curve according to the standard Killer Bs representation. Note this methods differences from the other create method. This method assumes that the size of the number of knots passed in the knot vector is always numControlPts + deg + 1 (or numSpans + 2*deg + 1, if you prefer, where numSpans = numControlPts - deg). That is, the redundant end knots must be specified. This method assumes that if this object was previously referencing some other curve, and this call succeeds, this object will reference the new curve. For more information on multiplicity, see the AlCurve on page 301 description. When you create a curve, you must ensure the following:

Open and closed curves must have at least one span. Periodic curves require that there be at least 3 spans. The number of knot values must be equal to numControlPts + deg + 1 The knot values must be a non-decreasing sequence of values. Any knot multiplicity must not exceed the degree of the curve. Periodic curves also require that the number of spans be greater than or equal to the degree of the curve. For open/closed/periodic curves the number of control points is the number of spans + degree. For example, one span requires four control points. For periodic curves it is necessary to specify the overlapping control points.

Arguments
< deg - the degree of the curve < form - kOpen, kClosed or kPeriodic < knotVector - the sequence of knot values. Must be of length numControlPts + deg + 1. < numControlPts - the number of points in controlPoint

320 | Chapter 2 AlCamera AlCylinderLight

< controlPoint - the array of control points. Must have size of numControlPts * 4.

Return Codes
sSuccess - data created sInsufficientMemory - ran out of memory sInvalidArgument - there are many ways we can fail with this return code

Calling this method from AlFace (which derives from AlCurve) with a form of kOpen NULL knot vector or control point array Number of spans <= 0 { number of spans = number of control points degree } The knot vector is not a non-decreasing sequence of values For open and closed curves, the knot values bounding the first and last span are different For periodic curves, the last degree knots are not specified correctly. If the knots are specified correctly, the following will be true:
For i = 0 to 2*deg-1 (n = numberSpans) T[i+1] - T[i] = T[i+n+1] - T[i+n]

For a closed curve, the first CV is not the same as the last For a periodic curve, the number of spans is less than 3 For a periodic curve, the degree is greater than the number of spans For a periodic curve, the first CV is not the same as the last CV

sFailure - data could not be created Note: The number of knots = number of control points + degree + 1. The size of the knot vector is not passed into this method so if you dont specify the array correctly, the method can read past the end of the knot vector.

AlCurve | 321

statusCode AlCurve::createLine( const double start[3], const double end[3] ) Description

Creates a straight line using attributes. This method is simpler than the previous create method, requiring you only to specify the beginning and end of the curve. To modify the curve you should retrieve its attributes with the firstAttribute() method and use AlAttribute methods to modify it. Modifying the CVs directly will cause the attributes to be deleted.

Arguments
< start - the coordinates for the start of the curve < end - the coordinates for the end of the curve

Return Codes
sSuccess - curve created sFailure - failed to create the curve sInvalidArgument - start or end was NULL sInsufficientMemory - Ran out of memory

statusCode AlCurve::createArc( const double start[3], const double end[3], const double other[3], boolean circle ) Description
Creates a circular arc using attributes. This method is simpler than the previous create method, requiring you only to specify three points on the curve and whether the curve should be closed to form a circle. To modify the curve you should retrieve its attributes with the firstAttribute() method and use AlAttribute methods to modify it. Modifying the CVs directly will cause the attributes to be deleted.

Arguments
< start - the coordinates for the start of the curve < end - the coordinates for the end of the curve < other - an additional point defining the arc

322 | Chapter 2 AlCamera AlCylinderLight

< circle - if TRUE then a circle will be generated

Return Codes
sSuccess - curve created sFailure - failed to create the curve sInsufficientMemory - ran out of memory sAlreadyCreated - the AlCurve has already been created sInvalidArgument - a NULL argument was supplied

statusCode AlCurve::createArc( double *C, double *N, double *P, double r, double a0, double a1, int dim, boolean make_cubic ) Description
Create a circular arc between two angles.

Arguments
C center N normal to plane of arc (if 3D) P point with zero angle r radius a0, a1 initial and final angles (in radians) dim dimension 2 or 3 make_cubic if true, raise degree to 3 Note: If dim = 2, N is ignored. Point P with zero angle must not be at C. Returns NULL if arc has no length 3D: a0 < a1 and a1-a0 <= 2*PI. Returns a full circle if a1-a0 > 2*PI. To build a arc in the other direction, reverse N.

AlCurve | 323

2D: |a1-a0| <= 2*PI. If a0 < a1 arc is counter clockwise else arc is clockwise. Returns a full circle if |a1-a0| > 2*PI.

Return Codes
sInvalidArgument - a bad argument was supplied sFailure - Failed to create the curve. sSuccess - All ok.

statusCode AlCurve::createConic( double c_a, double c_b, double c_c, double c_d, double c_e, double c_f, const double start[3], const double end[3] ) Description
Creates a conic arc using attributes. This method is simpler than the previous create method, requiring users only to specify the coefficients of the conic and the beginning and end of the curve. The start and end points must lie on the conic. The conic is described by the equation: A * X^2 + B * X * Y + C * Y^2 + D * X + E * Y + F = 0 The conic will be created in the XY plane. It is not possible to modify a conic curve through its attributes.

Arguments
< c_a through c_f - coefficient of the conic < start - the coordinates for the start of the curve < end - the coordinates for the end of the curve

Return Codes
sSuccess - curve created sFailure - failed to create the curve sInsufficientMemory - ran out of memory

324 | Chapter 2 AlCamera AlCylinderLight

sInvalidArgument - a NULL argument was supplied sAlreadyCreated - the AlCurve has already been created

statusCode AlCurve::createParabola( const double vertex[3], const double focus[3], const double start[3], const double end[3] ) Description
Creates a parabolic arc using attributes. This method is simpler than the previous create method, requiring users only to specify the vertex and focus of the parabola and the beginning and end of the curve. The start and end points must lie on the parabola. The parabola will be created in the XY plane. It is not possible to modify a parabolic curve through its attributes.

Arguments
< vertex - the vertex of the parabola < focus - the focus of the parabola < start - the coordinates for the start of the curve < end - the coordinates for the end of the curve

Return Codes
sSuccess - curve created sFailure - failed to create the curve sInsufficientMemory - ran out of memory sInvalidArgument - a NULL argument was supplied sAlreadyCreated - the AlCurve has already been created

statusCode AlCurve::createEllipse( const double center[3], const double major_axis[3], const double minor_axis[3], const double start[3], const double end[3] ) Description
Creates an elliptical arc using attributes. This method is simpler than the previous create method, requiring users only to specify the center, major axis, and minor axis of the ellipse and the beginning and end of the curve. The start and end points must lie on the ellipse and be specified in a

AlCurve | 325

counterclockwise order to indicate the arc. The axes must be perpendicular to each other. When creating an elliptical arc, the axes MUST be specified in the XY plane. It is not possible to modify an elliptical curve through its attributes. It is not possible to create a closed curve with this method, hence it will always fail for AlFaces.

Arguments
< center - the center of the ellipse < major_axis - the direction of the major axis < minor_axis - the direction of the minor axis < start - the coordinates for the start of the curve < end - the coordinates for the end of the curve

Return Codes
sSuccess - curve created sFailure - failed to create the curve sInsufficientMemory - ran out of memory sInvalidArgument - a NULL argument was supplied sAlreadyCreated - the AlCurve has already been created

statusCode AlCurve::createHyperbola( const double center[3], const double major_axis[3], const double minor_axis[3], const double start[3], const double end[3] ) Description
Creates a hyperbolic arc using attributes. This method is simpler than the previous create method, requiring users only to specify the center, major axis, and minor axis of the hyperbola and the beginning and end of the curve. The start and end points must lie on the ellipse and be specified in a counterclockwise order to indicate the arc. The axes must be perpendicular to each other. The hyperbola will be created in the XY plane. It is not possible to modify a hyperbolic curve through its attributes.

Arguments
< center - the center of the hyperbola

326 | Chapter 2 AlCamera AlCylinderLight

< major_axis - the focus of the hyperbola < minor_axis - the focus of the hyperbola < start - the coordinates for the start of the curve < end - the coordinates for the end of the curve

Return Codes
sSuccess - curve created sFailure - failed to create the curve sInsufficientMemory - ran out of memory sInvalidArgument - a NULL argument was supplied sAlreadyCreated - the AlCurve has already been created

statusCode AlCurve::createPoint( const double pt[3] ) Description

Create a "degenerate curve" with a single CV. The coordinates for this CV are provided by the argument pt[]. The created "curve" will be:

rational open degree 1 span 0 dimension 3 knots {0.0} cv {pt[0], pt[1], pt[2], 1.0}

Arguments
< pt - position of the point

AlCurve | 327

Return Codes
sSuccess - the method succeeded sFailure - Failed to create the point. sInvalidArgument - a NULL argument was supplied. sAlreadyCreated - the AlCurve has already been created

int AlCurve::realNumberOfKnots() const Description

Returns the actual number of knots on the curve. That is uNumberOfSpans() + 2*degree() - 1. (Note that two additional knots are required to define a NURBS curve, but they have no effect on the curve so are not included in this count.) This method returns -1 if the curve is not valid.

statusCode AlCurve::realKnotVector( double knotVector[] ) const Description

Returns realNumberOfKnots() in knotVector for the curve.

Arguments
> knotVector - array to place the knot vector into

Return Codes
sSuccess - successfully copied the curves knot vector into knotVector sInvalidArgument - knotVector was NULL sInvalidObject - the curve was invalid sFailure - an error occurred

statusCode AlCurve::setRealKnotVector( const double knotVector[] ) Description

Sets the knots for this curve. The parameter knotVector must be of realNumberofKnots().

328 | Chapter 2 AlCamera AlCylinderLight

Arguments
< knotVector - array of knots

Return Codes
sSuccess - the knots were successfully set sInvalidArgument - knotVector was NULL sInvalidObject - the curve is invalid sFailure - an error occurred

statusCode AlCurve::length(double& len , boolean worldCoordinates, double tolerance ) Description

Determines the length of the curve in either local coordinates or world space coordinates.

Arguments
> len - the returned length > worldCoordinates - the calculation is to be done in world space > tolerance - the error tolerance

Return Codes
sSuccess - the length was successfully determined sFailure - the evaluation failed sInvalidObject - the curve was invalid sInvalidArgument - tolerance was zero or negative

statusCode AlCurve::periodicToNonPeriodic( ) const Description

If a curve is periodic, converts it to a non-periodic curve (closed curve) by giving it multiple end knots.

AlCurve | 329

Note: This method modifies the curve. It will not succeed for an AlCurve that exists in the AlUniverse; that is, it must not have a parent AlCurveNode on page 353.

Return Codes
sInvalidObject - the curve was invalid sFailure - the method did not succeed sSuccess - the curve was converted to a non-periodic one

statusCode AlCurve::normal( double normal[3] ) const Description

Tests if bspline is planar and returns normal. This method finds the first three points that are not co-linear, constructs a normal and tests if the bspline lies in the plane. If the bspline is planar and closed the normal is returned with a clockwise orientation looking down on the plane, and the normal pointing towards you. If the bspline is a line or all the points are co-linear, a unique normal can not be defined.

Arguments
> normal - returned normal vector to the bspline

Return Codes
sSuccess - the normal to the curve was found sFailure - the normal could not be found: the spline is either a point, linear or not planar

statusCode AlCurve::insert( double param ) Description

Inserts an edit point into the curve.

Arguments
< param - parametric value of the new edit point on the curve

330 | Chapter 2 AlCamera AlCylinderLight

Return Codes
sSuccess - the edit point was successfully inserted sInvalidObject - the given object is not valid sInvalidArgument - a parameter is out of bounds sFailure - an error occurred

statusCode AlCurve::append( double pos[4], AlPointType type ) Description

Appends a CV or an edit point to the curve.

Arguments
< pos - position in world space of the new point < type - either kCV or kEditPoint

Return Codes
sSuccess - new point was successfully appended sInvalidObject - the given object is not valid sInvalidArgument - an invalid argument was supplied sFailure - an error occurred

statusCode AlCurve::applyIteratorToCVs( AlIterator* iter, int &rc ) Description

Applies the given iterator to all the CVs in this class. See the documentation for AlIterator on page 544.

Arguments
< iter - the iterator to apply to each CV > rc - the result of the last application of the iterator

AlCurve | 331

Return Codes
sSuccess - the iterator exited normally sFailure - the iterator exited abnormally sInvalidArgument - the iterator iter was NULL sInvalidObject - the curve was not valid

statusCode AlCurve::reverseCurve() Description

Reverses the parameterization of the curve.

Return Codes
sInvalidObject - the curve was not a valid object sSuccess - the curve reversal worked sFailure - the curve reversal failed for internal reasons

statusCode AlCurve::extendCurve(double knot , double newPos[4]) Description

Extends the curve by one span. The existing spans remain unchanged. The new span has C(k-1) and interpolates the given point. This curve must have at least 1 span and at least 4 CVs.

Arguments
< knot - the knot spacing for the new span < newPos - the position of the new CV

Return Codes
sInvalidObject - the curve was an invalid object sSuccess - extending the spline worked sFailure - the curve had less than 1 span, curve had less than 4 CVs, or could not extend the spline because of an internal error

332 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCurve::incrementDegree() Description

Increments the degree of a curve without changing its shape. The curve must have at least 1 span.

Return Codes
sInvalidObject - the curve is not a valid object sSuccess - raising the degree of the curve worked sFailure - the number of spans was less than 1, or there was an internal failure

statusCode AlCurve::adjustEndSpan( double newKnotSpan ) Description

Changes the knot spacing of the last span of the curve, leaving the remainder of the curve unchanged. The end point of the last span is preserved.

Arguments
< double newKnotSpan - the knot spacing for the end span

Return Codes
sInvalidObject - the curve is an invalid object sSuccess - the method worked sFailure - the curve did not have at least one span. The method failed to adjust the end span.

statusCode AlCurve::trimCurve( double param0, double param1 ) Description

Trims the curve at the specified parameters. param0 and param1 are the min and max points. This routine fails if param0 and param1 are the same or if param0 is greater than param1.

AlCurve | 333

Arguments
< param0 - the minimum position along the curve where the curve is to be trimmed < param1 - the maximum position along the curve where the curve is to be trimmed

Return Codes
sInvalidObject - the curve was not a valid object sSuccess - the method worked sFailure - the routine failed. Either param0 equals param1, param0 > param1, or there was an internal failure.

AlCurveAttributes
Interface to Alias curve attributes.

Synopsis
#include <AlCurveAttributes.h> class AlCurveAttributes : public AlAttributes virtual AlObjectType type() const; AlObject* copyWrapper() const; curveFormType form() const; int degree() const; int numberOfSpans() const; int numberOfCVs() const; statusCode CVsUnaffectedPosition( double[][4], int[] ) const; int numberOfKnots() const; statusCode knotVector( double[] ) const;

Description
AlCurveAttributes is a class derived from the AlAttributes class. This class allows access to a curve. This class provides information similar to that of the AlCurve class but without the ability to modify the curve or its CVs.

334 | Chapter 2 AlCamera AlCylinderLight

NOTE: When an AlCurve has just an AlCurveAttribute attribute, the AlCurveAttribute provides no information that the AlCurve doesnt. For this reason, in this case, no information is provided by the AlCurveAttribute, and all methods return null values.

AlObjectType AlCurveAttributes::type() const Description

Returns the class identifier kCurveAttributeType.

AlObject* AlCurveAttributes::copyWrapper() const Description

Makes a copy of the AlAttribute. The returned AlAttribute will reference the same data as the original.

curveFormType AlCurveAttributes::form() const Description

When a curve is periodic it means that its endpoints are coincident and that the curve is tangent continuous at the point where its endpoints touch. "kPeriodic" is returned in this case. "kClosed" is returned if the curve is not periodic, but if its endpoints are coincident. If a curve is neither "kPeriodic" nor "kClosed" then "kOpen" is returned. (Note: If you use the "close" menu item in the interactive Alias package, you actually make a curve periodic.)

Return Values
kOpen - the curve is open kClosed - the curve is closed kPeriodic - the curve is periodic kInvalidCurve - the attribute is not valid

int AlCurveAttributes::degree() const Description

Returns the degree of the curve. Zero will be returned if the attribute is not valid.

AlCurveAttributes | 335

int AlCurveAttributes::numberOfSpans() const Description

Returns the number of spans in the curve. -1 is returned if the attribute is not valid.

int AlCurveAttributes::numberOfCVs() const Description

Returns the number of CVs. -1 is returned if the attribute is not valid.

statusCode AlCurveAttributes::CVsUnaffectedPosition( double CVList[][4], int mult[] ) const Description

Returns the CVs in the given CV array and the multiplicity of each CV in the multiplicity vector. The first dimension of the CV array must be numberOfCVs(). The length of the multiplicity vector must also be numberOfCVs(). The multiplicity vector returned by this function is the same as the one returned by CVsWorldPosition().

Arguments
> CVList - returned CVs > mult - multiplicity of each CV

Return Codes
sSuccess - the CVs unaffected position was successfully returned sInvalidObject - the attribute is not valid sInvalidArgument - one or both of the arguments were NULL sFailure - the position was not returned

336 | Chapter 2 AlCamera AlCylinderLight

int AlCurveAttributes::numberOfKnots() const Description

Returns the number of knots in this curve. For more information as to what this number means, see the description for the create() method. -1 will be returned if the attribute is not valid.

statusCode AlCurveAttributes::knotVector( double knotVector[]) const Description

Returns the knot vector in the given vector. This vector must be of length numberOfKnots(). For more information about what these values mean, see the description for the AlCurve::create() method in AlCurve on page 301.

Arguments
> knotVector - returned knot vector

Return Codes
sSuccess - the knot vector was successfully returned sInvalidObject - the attribute is not valid sInvalidArgument - one or both of the arguments was NULL sFailure - the knot vector could not be returned

AlCurveCV
Encapsulates methods common to curve CVs.

AlCurveCV | 337

Synopsis
#include <AlCurveCV.h> class AlCurveCV : public AlObject, public AlClusterable, public AlAnimatable, public AlSettable, public AlPickable virtual ~AlCurveCV(); virtual AlObject* copyWrapper() const; AlObjectType type() const; AlCurveCV* next() const; AlCurveCV* prev() const; statusCode nextD(); statusCode prevD(); int index() const; int multiplicity() const; statusCode worldPosition( double&, double&, double&, double& ) const; statusCode affectedPosition( const AlTM&, double&, double&, double&, double& ) const; statusCode unaffectedPosition( double&, double&, double&, double& ) const; statusCode setMultiplicity( int ); statusCode setWorldPosition( double, double, double, boolean ); statusCode setWorldPosition( double, double, double, AlTM ); statusCode setUnaffectedPosition( double, double, double, double ); AlCurve* curve() const; statusCode blindData( int, long&, const char *& ); statusCode setBlindData( int, long, const char * ); statusCode removeBlindData( int ); statusCode doUpdates( boolean newState = TRUE );

Description
AlCurveCV is the class used to access and manipulate curve CVs (also referred to as Control Points). There is one AlCurveCV object for each CV of an AlCurve as you see it in the interactive Alias package. You cannot create or delete an AlCurveCV. AlCurveCVs are only created through AlCurves. There are methods to query and set the multiplicity of a CV, and methods to query the world position and the "unaffected" position of a CV. The "unaffected" position of a CV is its position BEFORE any transformations (from its parent DAG node or from affecting clusters) have been applied to it. There is also a method to access the clusters that affect a CV. Methods

338 | Chapter 2 AlCamera AlCylinderLight

setWorldPosition(*) are used for setting either the unaffected or affected(clusters) position of a CV. To print out all CVs of a curve:
AlCurve curve; AlCurveCV *cvPtr; int i = 0; double x, y, z, w; if ( cvPtr = curve>firstCV() ) { do { cvPtr->worldPosi tion( x, y, z, w ); printf("CV %d is at %G, %G, %G with weight %G.\n", i, x, y, z, w ); i++; } while( cvPtr->nextD() == sSuccess ); } delete cvPtr; Example Result: CV 1 is at 0.0, 1.0, 0.0 with weight 1.0 CV 2 is at 0.0, 2.0, 0.0 with weight 1.0 CV 3 is at 0.0, 3.0, 0.0 with weight 1.0 CV 4 is at 0.0, 4.0, 0.0 with weight 1.0

Multiplicity
When an AlCurveCV has a multiplicity > 1, CVs are internally piled up at that position. In this case, an AlCurveCV actually represents more than one CV internally. To access ALL CVs, use the methods in the AlCurve class to query values "including multiplicity", or use the example code below. By representing AlCurveCVs this way, then if an AlCurveCV is moved, the corresponding multiple CVs at that position are moved as well, acting exactly like the Alias interactive package. For example, to print all internal CVs of a curve with 4 AlCurveCVs where the second AlCurveCV has multiplicity = 2, you would do this:
AlCurve curve; AlCurveCV *cvPtr; int i,j = 0; double x, y, z, w; if ( cvPtr = curve->firstCV() ) { do { for( j = 0; j <= cvPtr->multiplicity(); j++, i++ ) { cvPtr->worldPosition( x, y, z, w ); printf("CV %d is at %G, %G, %G with weight %G.\n", i, x, y, z, w ); } i++; } while( cvPtr->nextD() == sSuccess ); } delete cvPtr; Example Result: CV 1 is at 0.0, 1.0, 0.0 with weight 1.0 CV 2 is at 0.0, 2.0, 0.0 with weight 1.0 CV 3 is at 0.0, 2.0, 0.0 with weight 1.0 CV 4 is at 0.0, 3.0, 0.0 with weight 1.0 CV 5 is at 0.0, 4.0, 0.0 with weight 1.0

AlCurveCV | 339

Creation
Note that certain routines require that the given CV be installed in the DAG (that is, that the curve belongs to a AlCurveNode). If any of these are called on a CV that is not part of the DAG, they will simply fail. Routines that require the CV to be in the DAG:
next nextD worldPosition setMultiplicity setUnaffectedPosition setWorldPosition

AlCurveCV::~AlCurveCV() Description
Deletes an AlCurveCV wrapper object.

AlObject* AlCurveCV::copyWrapper() const Description

Makes an exact copy of this AlCurveCV wrapper.

AlObjectType AlCurveCV::type() const Description

Returns the class identifier kCurveCVType.

AlCurveCV *AlCurveCV::asCurveCVPtr() Description

This virtual function returns a non-null pointer to itself, indicating that it is safe to cast to an object of this class.

int AlCurveCV::index() const Description

Returns the index of this CV. Returns -1 if the index could not be found. The index of the first CV is 0.

340 | Chapter 2 AlCamera AlCylinderLight

AlCurveCV* AlCurveCV::next() const Description

Returns a pointer to the next AlCurveCV. Otherwise, returns NULL if there is no next curve CV, or if this CV is not in the DAG.

statusCode AlCurveCV::nextD() Description

Destructively points the current wrapper to the next CV in the curve. This call will also fail if the CV is not in the DAG.

Return Codes
sSuccess - the wrapper now points to the next CV in the curve sInvalidObject - the curve CV was invalid sFailure - there is no next CV in the curve

AlCurveCV* AlCurveCV::prev() const Description

Returns a pointer to the previous AlCurveCV. Otherwise, returns NULL if there is no previous curve CV.

statusCode AlCurveCV::prevD() Description

Destructively points the current wrapper to the previous CV in the curve.

Return Codes
sSuccess - the wrapper now points to the previous CV in the curve sInvalidObject - the curve CV was invalid sFailure - there is no previous CV in the curve

AlCurveCV | 341

int AlCurveCV::multiplicity() const Description

Returns the multiplicity of this curve CV. The returned value is 1, 2 or 3, unless the call fails, in which case it is 0.

statusCode AlCurveCV::worldPosition( double &x, double &y,double &z, double &weight ) const Description
Returns the position of this curve CV in world space. This position includes the transformations of all DAG nodes above this curve and the effects of all clusters. Note that the positions returned are [ x y z w ] and not [ w*x w*y w*z w ].

Arguments
> x - the world position in the x direction > y - the world position in the y direction > z - the world position in the z direction > weight - homogeneous coordinate

Return Codes
sSuccess - the position of this curve CV in world space was returned sInvalidObject - the CV was invalid sFailure - the CV is not created or not in the world

statusCode AlCurveCV::affectedPosition( const AlTM& tm, double &x, double &y,double &z, double &weight ) const Description
Returns the position of this curve CV adjusted by the AlTM. Note that the positions returned are [ x y z w ] and not [ w*x w*y w*z w ].

342 | Chapter 2 AlCamera AlCylinderLight

Arguments
< tm - the transformation matrix which is built traversing the DAG > x - the world position in the x direction > y - the world position in the y direction > z - the world position in the z direction > weight - homogeneous coordinate

Return Codes
sSuccess - the position of this curve CV was returned sInvalidObject - the CV is not created or not in the world

statusCode AlCurveCV::unaffectedPosition( double &x, double &y,double &z, double &weight ) const Description
Returns the position of this curve CV PRIOR TO ANY TRANSFORMATIONS (hence "unaffected"). How are the unaffected position and world position related? The world position is the unaffected position with the inclusive transformation of all DAG nodes above this curve applied to it AND the transformations of all affecting clusters applied to it (in proportion).

Arguments
> x - the unaffected position in the x direction > y - the unaffected position in the y direction > z - the unaffected position in the z direction > weight - homogeneous coordinate

Return Codes
sSuccess - the position of this curve CV was returned sInvalidObject - the CV was invalid sFailure - the CV is not created or not in the world

AlCurveCV | 343

statusCode AlCurveCV::setMultiplicity( int newMultiplicity ) Description

Sets the multiplicity of this curve CV to the given multiplicity. The new multiplicity must be 1, 2, or 3.

Arguments
< int newMultiplicity - the multiplicity to set this AlCurveCV to

Return Codes
sSuccess - the multiplicity was set sInvalidArgument - the multiplicity was not 1, 2 or 3 sInvalidObject - the CV was invalid sInsufficientMemory - there is not enough memory to allocate a new block sFailure - the CV is not created or is not in the world

statusCode AlCurveCV::doUpdates( boolean newState ) Description

See AlDagNode on page 381 for information.

statusCode AlCurveCV::setWorldPosition( double x, double y, double z, boolean includeWorld ) Description

Sets the world position of the CV. The CV may also be in a cluster.

Arguments
< x - the new unaffected position in the x direction < y - the new unaffected position in the y direction < z - the new unaffected position in the z direction < includeWorld - include world transformation in move

344 | Chapter 2 AlCamera AlCylinderLight

Return Codes
sSuccess - the position of this curve CV was set sInvalidObject - the CV was not valid sFailure - the CV is not created or not in the world. The move could not be done.

statusCode AlCurveCV::setWorldPosition( double x, double y, double z, AlTM tm ) Description

Sets the world position of the CV. The CV may also be in a cluster. Note that this method uses the inverse of the transformation matrix that is passed in so that the calling routine does not need to generate it.

Arguments
< x - the new unaffected position in the x direction < y - the new unaffected position in the y direction < z - the new unaffected position in the z direction < tm - users transformation matrix

Return Codes
sSuccess - the position of this curve CV was set sInvalidObject - the CV was not valid sFailure - the CV is not created or not in the world. The move could not be done.

statusCode AlCurveCV::setUnaffectedPosition( double x, double y,double z, double weight ) Description

Sets the unaffected position of a curve CV.

Arguments
< x - the new unaffected position in the x direction

AlCurveCV | 345

< y - the new unaffected position in the y direction < z - the new unaffected position in the z direction < weight - homogeneous coordinate

Return Codes
sSuccess - the position of this curve CV was set sInvalidObject - the CV was not valid sFailure - the CV is not created or not in the world

AlCurve* AlCurveCV::curve() const Description

Returns a pointer to the AlCurve that this curve CV belongs to.

statusCode AlCurveCV::blindData( int user_type, long& size, const char *& data ) Description
Obtains the size and address of a block of data associated with the object. If there is no data, then the size will be zero and the address of the data is NULL. User_types must be reserved. If you would like to reserve a block of "user_types" please contact us.

Arguments
< user_type - user type of the data desired > size - number of characters in the block of data > data - address of the block of data

Return Codes
sSuccess - the blind data was returned sInvalidObject - the curveCV was invalid

346 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCurveCV::setBlindData( int user_type, long size, const char * data ) Description
Associates a block of data with the object. If a block of data is already associated with this object and this user_type, the old block is replaced by a reference to the new block. The old block of data is not deleted.

Arguments
< user_type - user type of the blind data desired < size - number of characters in the block < data - address of the block of data

Return Codes
sSuccess - operation was successful sInsufficientMemory - not enough memory to allocate a new block sInvalidObject - create has not been called on this object yet

statusCode AlCurveCV::removeBlindData( int user_type ) Description

Removes the block of data of the given type from the object. Note that the user is still responsible for the memory associated with this block of data.

Arguments
< user_type - user type of the blind desired

Return Codes
sSuccess - operation was successful sFailure - no such blind data existed sInvalidObject - the given object is not valid

AlCurveCV | 347

AlCurvePoint
Interface to Alias curve points.

Synopsis
#include <AlCurvePoint.h> class AlCurvePoint : public AlPoint AlCurvePoint(); ~AlCurvePoint(); virtual AlObject * copyWrapper() const; virtual AlObjectType type() const; statusCode create(const AlCurve *, double); statusCode setParameter(double); statusCode parameter(double &) const; virtual statusCode worldPosition(double &, double &, double &) const; statusCode tangent(double &, double &, double &) const; statusCode normal1(double &, double &, double &) const; statusCode normal2(double &, double &, double &) const; statusCode radius(double &) const; statusCode arcLength(double &) const; AlCurveNode *attachedTo();

Description
A point can be created in the parametric space of any AlCurve. This point can be queried for the curve normals, tangent, position in world coordinate system, arc length, and curvature information. This class contains methods for creating, and moving the curve point. If the AlCurve is deleted, the curve point created on it is deleted.

AlCurvePoint::AlCurvePoint(void) Description
Constructs an AlCurvePoint wrapper object.

348 | Chapter 2 AlCamera AlCylinderLight

AlCurvePoint::~AlCurvePoint() Description
Deletes an AlCurvePoint wrapper object.

AlObject *AlCurvePoint::copyWrapper() const Description

Returns an exact copy of the AlCurvePoint wrapper.

AlObjectType AlCurvePoint::type() const Description

Returns the class identifier kCurvePointType.

statusCode AlCurvePoint::create(const AlCurve *curve, double u) Description

Creates a point on the given curve

Arguments
< curve - the curve on which the point is created. < u - curve parameter at which point is created

Return Codes
sSuccess - the point was successfully created sAlreadyCreated - object has already been created sFailure - the point could not be created on the curve. sInvalidArgument - the curve is not a valid object

statusCode AlCurvePoint::setParameter(double u) Description

Move the position of a point created on a curve

AlCurvePoint | 349

Arguments
< u - the parameter on the curve where the point has to be moved.

Return Codes
sSuccess - the point was moved sInvalidObject - the point is not valid

statusCode AlCurvePoint::parameter(double &u) const Description

Find the parameter value at which the point is present

Arguments
> u - the curve parameter where point is present

Return Codes
sSuccess - the parameter was found sInvalidObject - the point is not valid

statusCode AlCurvePoint::worldPosition(double &x, double &y, double &z) const Description

Find the world coordinates of the curve point

Arguments
> x, y, z - the world coordinates of the curve point

Return Codes
sSuccess - the coordinates were found. sInvalidObject - the point is not valid

350 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCurvePoint::tangent(double &x, double &y, double &z) const Description

Find the tangent vector to the curve at the point

Arguments
> x, y, z - the X, Y, Z components of the tangent

Return Codes
sSuccess - the tangent was found. sInvalidObject - the point is not valid

statusCode AlCurvePoint::normal1(double &x, double &y, double &z) const Description

Find the normal to the curve at the point

Arguments
> x, y, z - the X, Y, Z components of the normal

Return Codes
sSuccess - the normal was found. sInvalidObject - the point is not valid

statusCode AlCurvePoint::normal2(double &x, double &y, double &z) const Description

Find the second normal to the curve at the point

Arguments
> x, y, z - the X, Y, Z components of the second normal normalized vector.

AlCurvePoint | 351

Return Codes
sSuccess - the normal was found. sInvalidObject - the point is not valid

statusCode AlCurvePoint::radius(double &rad) const Description

Find the radius of the curve at the point

Arguments
> rad - the radius of the curve at the point.

Return Codes
sSuccess - the radius was found. sInvalidObject - the point is not valid

statusCode AlCurvePoint::arcLength(double &arcLen) const Description

Find the length of the curve on which the point is present

Arguments
> arcLen - the length of the curve

Return Codes
sSuccess - the arc length was found. sInvalidObject - the point is not valid

AlCurveNode *AlCurvePoint::attachedTo() Description

Returns the curve node that this point is associated with. NULL is returned if this method fails.

352 | Chapter 2 AlCamera AlCylinderLight

AlCurveNode
A DAG node that refers to a NURB curves geometry.

Synopsis
#include <AlCurveNode.h> class AlCurveNode : public AlDagNode AlCurveNode(); virtual ~AlCurveNode(); virtual AlObject* copyWrapper() const; statusCode create( AlCurve* ); virtual AlObjectType type() const; AlCurve* curve() const; AlCurve* curve(AlTM&) const; AlCurveNodeJoinErrors join(AlCurveNode*); int curvePrecision() const; statusCode setCurvePrecision( int );

Description
AlCurveNode is the class used to access and manipulate curves within a DAG. This class behaves like other DAG nodes (see AlDagNode on page 381 for a description of the usage and purpose of DAG nodes). Users access the geometry of the curve via the curve() method which returns a pointer to an AlCurve object which provides the user with the methods used to modify the geometry of the curve. Curves can be created from scratch by instantiating and creating an AlCurve, and then by instantiating and creating an AlCurveNode (using the AlCurve as a parameter). There are two ways to delete an AlCurveNode. If the AlCurveNode deleteObject() method is called, then the nodes AlCurve is also deleted. If the AlCurve::deleteObject() method is called, then its associated AlCurveNode is also deleted.

AlCurveNode::AlCurveNode() Description
Constructs an AlCurveNode wrapper object.

AlCurveNode | 353

AlCurveNode::~AlCurveNode() Description
Deletes an AlCurveNode wrapper object.

AlObject* AlCurveNode::copyWrapper() const Description

Returns an exact duplicate of this AlCurveNode wrapper.

statusCode AlCurveNode::create( AlCurve *newCurve ) Description

Allocates the DAG node for this object and attaches it to the given AlCurve. This method should only be called once for any AlCurve. It is an error to call this method twice or if the object has been read in from a wire file.

Arguments
< newCurve - the curve to create this curve node from

Return Codes
sSuccess - everything was successful sInvalidArgument - the newCurve was invalid or NULL sAlreadyCreated - the curve was already created elsewhere sInsufficientMemory - not enough memory available

AlObjectType AlCurveNode::type() const Description

Returns the class identifier kCurveNodeType.

354 | Chapter 2 AlCamera AlCylinderLight

AlCurveNode* AlCurveNode::asCurveNodePtr() Description

This virtual function returns a non-null pointer to itself, indicating that it is safe to cast to an object of this class.

AlCurve* AlCurveNode::curve() const Description

Returns a pointer to the curve data structure that can be used to access the geometry of the curve.

AlCurve* AlCurveNode::curve(AlTM& tm) const Description

Returns a pointer to the curve data structure that can be used to access the geometry of the curve. The AlTM will be updated with the curveNodes TM if a curve exists.

Arguments
> tm - the transformation matrix to be updated with the curveNodes TM

AlCurveNodeJoinErrors AlCurveNode::join(AlCurveNode* curveNode) Description

Joins the passed-in curveNodes curve to the end of this curve if the end is coincident with the beginning of the of the curveNodes curve. This is most useful when using curves with attributes.

Warning
This operation will remove this curves CVs from all clusters and sets but not the curveNode that is passed in. This means that all AlClusterMembers and AlSetMembers of this curves CVs will no longer be valid after a join. Further all AlCurveCVs and attributes on this AlCurve will have been deleted and regenerated (the passed curve is unchanged). If the return value is either kJoinSuccess or kJoinFailure so all pointers to this curves AlCurveCVs will be invalid.

AlCurveNode | 355

If the return value is one of kJoinDuplicateCurve, kJoinBadData, kJoinNoAttributes, or kJoinInvalidKeyPoints, the model will not have been modified. If the return value is kJoinBadCluster, all AlCurveCVs below this AlCurveNode will have been removed from all sets and clusters and the cluster effects may have been applied to some CVs. Finally, if the return code is kJoinFailure, all AlCurveCVs below this AlCurveNode will have been removed from all sets and clusters, all AlCurveCVs have been deleted and recreated, existing AlAttributes have been moved to the garbage list and new ones created, and a join was attempted but failed, perhaps because the ends of the two curves did not overlap.

Arguments
< curveNode - a curve that will be added to the end of this curve

Return Values
kJoinSuccess - the join succeeded kJoinFailure - the join failed, perhaps because the end points didnt overlap kJoinBadCluster - failed to remove effect of all clusters kJoinInvalidKeyPoints - one curve may have been a circle kJoinNoAttributes - attributes for a curve could not be found or created kJoinBadData - the model is in an incorrect state kJoinDuplicateCurve - an attempt was made to join a curve to itself

int AlCurveNode::curvePrecision() const Description

Obtains the curve precision for the curve. This method returns -1 if the curve node is invalid.

statusCode AlCurveNode::setCurvePrecision( int precision ) Description

Sets the curve precision for the curve.

356 | Chapter 2 AlCamera AlCylinderLight

Arguments
< precision - the new curve precision (range is 1-129).

Return code
sSuccess - curve precision set sInvalidArgument - value for curve precision was invalid sInvalidObject - this CurveNode is invalid.

AlCurveOnSurface
Interface to curves on surfaces geometry.

AlCurveOnSurface | 357

Synopsis
#include <AlCurveOnSurface.h> class AlCurveOnSurface : public AlObject AlCurveOnSurface(); virtual ~AlCurveOnSurface(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; statusCode create( int, curveFormType, int, const double[], int, const double[][4] ); statusCode create( int, const AlCurve*[] ); statusCode curveOnSurfaceData( double[], double[][4] ) const; statusCode realCurveOnSurfaceData( double[], double[][4] ) const; int degree() const; curveFormType form() const; int numberOfSpans() const; int numberOfKnots() const; int numberOfControlPoints() const; int realNumberOfKnots() const; double knotValue( int ) const; statusCode controlPoint( int, double[4] ) const; statusCode setKnotValue( int, double ); statusCode setControlPoint( int, const double[4] ); boolean inTrim() const; boolean visible() const; statusCode setVisible( boolean ) const; AlSurface* surface() const; statusCode worldSpace3DCopies( int&, AlCurve **& ); statusCode unaffected3DCopies( int&, AlCurve **& ); statusCode affected3DCopies( AlTM&, int&, AlCurve **& ); AlCurveOnSurface* nextCurveOnSurface() const; AlCurveOnSurface* prevCurveOnSurface() const; statusCode nextCurveOnSurfaceD(); statusCode prevCurveOnSurfaceD(); statusCode persistentID( AlPersistentID *&id, int ut = 1 ); statusCode hasPersistentID( int ut = 1 ); statusCode setPersistentID( AlPersistentID &, int ); statusCode insert( double ); statusCode reverse(); statusCode blindData( int, long &, const char *& ); statusCode setBlindData( int, long, const char * ); statusCode removeBlindData( int );

358 | Chapter 2 AlCamera AlCylinderLight

Description
AlCurveOnSurface is the interface to Alias curve on surface data objects. Curves on surfaces are created and added to a surface by allocating an AlCurveOnSurface, then calling the create() method, and then calling AlSurfaceNodes addCurveOnSurface() method to add it to a surface. Curves on surfaces can also be read in from wire file and modified with this class. Curves on surfaces will be deleted when the surface they are attached to is deleted. When constructing a curve on surface, you will notice that you need to specify a matrix that has dimensions [numberOfControlPoints][4]. Each point has 4 values, for u, v, zero and w. The u and v specify the point in U-V parametric space. The third component is zero because this component is not used. The "w" component is the homogeneous value, which is usually 1.0. See the example programs for an example.

AlCurveOnSurface::AlCurveOnSurface() Description
Constructs an AlCurveOnSurface wrapper object.

AlCurveOnSurface::~AlCurveOnSurface() Description
Deletes an AlCurveOnSurface wrapper object.

statusCode AlCurveOnSurface::deleteObject() Description

Deletes the curve on surface. If it is attached to a surface, it is removed from the surface before it is deleted.

Return Codes
sSuccess - the object was deleted sInvalidObject - the curve was invalid

AlCurveOnSurface | 359

AlObject *AlCurveOnSurface::copyWrapper() const Description

Makes an exact copy of the AlCurveOnSurface wrapper.

AlObjectType AlCurveOnSurface::type() const Description

Returns the class identifier kCurveOnSurfaceType.

statusCode AlCurveOnSurface::create(int deg,curveFormType form,int numKnots,const double knotVector[],int numControlPts,const double controlPoint[][4] ) Description
Refer to the AlCurve::create() method for information on the meaning and usage of the parameters. There is one additional constraint placed on this method over and above the AlCurve::create() method. The third component of each control point must be zero, since a curve on surface is expressed only in two dimensions (which is U-V parameter space) plus a homogeneous coordinate (usually 1.0). U and V typically range from 0 to 1. For any control point [u v 0.0 w], "u" and "v" represent the coordinate in U-V parameter space, and "w" represents the homogeneous coordinate.

Arguments
See the description.

Return Codes
sSuccess - the curve on Surface was created sInvalidArgument - an invalid or NULL argument was passed sInsufficientMemory - there was not enough memory to create it sFailure - the curve could not created

360 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCurveOnSurface::create( int nb_curves, const AlCurve *curves[] ) Description

Creates a Closed Curve On Surface from a loop of AlCurve on page 301s. This loop will be re-parameterized, so that the loop will be continuous and the form will be set accordingly. If the resulting curve is not physically closed, it is forced closed with all of the start/end points equal.

Arguments
nb_curves - number of curves curves - array of curves

Return Codes
sInvalidArgument - an invalid or NULL argument was passed sFailure - the AlCurveOnSurface could not be created sSuccess - the AlCurveOnSurface was created

statusCode AlCurveOnSurface::curveOnSurfaceData(double knotVector[],double controlPoint[][4] ) const Description

Assumes that the knotVector array is of length numberOfKnots() and the controlPoint array is of length are studying() and returns the values of the knots and control points in these arrays. Note that in the array of control points, each control point is represented by the quadruple [u v 0.0 w], where "u" and "v" represent the control point in U-V parameter space, the "0.0" doesnt represent anything, and the "w" is the homogeneous coordinate.

Arguments
> knotVector - contains the knots for this curve upon return > controlPoint - contains the control points upon return

AlCurveOnSurface | 361

Return Codes
sSuccess - the knotVector & controlPoint data was returned sInvalidArgument - knotVector or controlPoint was NULL sInvalidObject - the AlCurveOnSurface was invalid sFailure - an error occurred

statusCode AlCurveOnSurface::realCurveOnSurfaceData( double knotVector[], double controlPoint[][4] ) const Description

This method assumes that the knotVector array is of length realNumberOfKnots() and the controlPoint array is of length numberOfControlPoints() and returns the values of the knots and control points in these arrays. Note that in the array of control points, each control point is represented by the quadruple [u v 0.0 w], where "u" and "v" represent the control point in U-V parameter space, the "0.0" doesnt represent anything, and the "w" is the homogeneous coordinate.

Arguments
> knotVector - Contains the knots for this curve upon return. > controlPoint - Contains the control points upon return.

Return Codes
sSuccess - the knotVector & controlPoint data was returned sInvalidArgument - knotVector or controlPoint was NULL sInvalidObject - the AlCurveOnSurface was invalid. sFailure - an error occurred

int AlCurveOnSurface::degree() const Description

Returns the degree of the curve. -1 is returned if the curve is not valid.

362 | Chapter 2 AlCamera AlCylinderLight

curveFormType AlCurveOnSurface::form() const Description

Returns the form of the curve, which is kOpen, kClosed or kPeriodic. If a curve on surface is periodic, it is tangent continuous at the point where it is closed. (If you use the "close" menu item in the interactive Alias package, you actually make a curve periodic.) If a curve is periodic, it implies that it is closed. If a curve is kClosed, then it just means that its endpoints are coincident. Otherwise, the curve is kOpen.

int AlCurveOnSurface::numberOfSpans() const Description

Returns the number of spans in the curve. This method returns -1 if the curve is invalid.

int AlCurveOnSurface::numberOfKnots() const Description

Returns the number of knots (just numberOfSpans() + 1). This method returns -1 if the curve is invalid.

int AlCurveOnSurface::realNumberOfKnots() const Description

Returns the actual number of knots on the curve. That is number_of_spans + 2*degree - 1. A value of -1 will be returned if this method fails.

double AlCurveOnSurface::knotValue( int index ) const Description

Given a valid knot index, returns the value of the knot in knotValue. A valid knot index is one in the range 0 to numberOfKnots()-1.

Arguments
< index - a valid index of the knot value to return

AlCurveOnSurface | 363

statusCode AlCurveOnSurface::setKnotValue( int index, double knotValue ) Description

Given a valid knot index, sets the value of the knot to be knotValue. A valid knot index is one in the range 0 to numberOfKnots()-1.

Arguments
< index - a valid index of the knot value to return < knotValue - returns the knot value of the given index

Return Codes
sSuccess - the knot value was set sInvalidArgument - the index was not in the range 0..#knots-1 sInvalidObject - the curve was invalid sFailure - the curve was already in a trim

int AlCurveOnSurface::numberOfControlPoints() const Description

Returns the number of control points.

statusCode AlCurveOnSurface::controlPoint( int index, double point[4] ) const Description

Given a valid index, returns the value of the control point in point. A valid index is one in the range 0 to numberOfControlPoints()-1. Note the control point is represented by the quadruple [u v 0.0 w], where "u" and "v" represent the control point in U-V parameter space, the "0.0" is unused, and the "w" is the homogeneous coordinate.

Arguments
< index - a valid index of the control point to return

364 | Chapter 2 AlCamera AlCylinderLight

> point - returns the control point at position index

Return Codes
sSuccess - the control point was returned sInvalidArgument - the index was not valid or point was NULL sInvalidObject - the curve was invalid sFailure - an error occurred

statusCode AlCurveOnSurface::setControlPoint( int index, const double point[4] ) Description

Given a valid index, sets the value of the control point to point. A valid index is one in the range 0 to numberOfControlPoints()-1. Note the control point is represented by a quadruple, [u v 0.0 w] where "u" and "v" represent the control point in U-V parameter space, the "0.0" doesnt represent anything, and the "w" is the homogeneous coordinate.

Arguments
< index - a valid index of the control point to return < point - the value to set the control point at position index to

Return Codes
sSuccess - the control point was set sInvalidArgument - the index was not valid or point was NULL sInvalidObject - the curve was invalid sFailure - an error occurred

AlSurface* AlCurveOnSurface::surface() const Description

Returns a pointer to the surface that this curve is on. Otherwise, returns NULL. The surface that this curve-on-surface belongs to MUST have a surface node attached to it.

AlCurveOnSurface | 365

boolean AlCurveOnSurface::inTrim() const Description

Returns TRUE if this curve on surface is being used to trim the surface it is on.

boolean AlCurveOnSurface::visible() const Description

Returns TRUE if the curve is visible (FALSE means the curve is invisible).

statusCode AlCurveOnSurface::setVisible( boolean visible ) const Description

Sets the visibility on the curve on surface.

Return Codes
sSuccess - The visibility is set as given. sFailure - The geometry under the curve on surface is invalid.

AlCurveOnSurface* AlCurveOnSurface::nextCurveOnSurface() const Description

Returns the next curve on surface in the list of curve on surfaces that are attached to a specific surface. Returns NULL if there is no next curve on surface.

statusCode AlCurveOnSurface::nextCurveOnSurfaceD() Description

Destructively points the wrapper to the next curve on surface in the list of curves on surfaces that are attached to a specific surface.

Return Codes
sSuccess - the wrapper now points to the next CurveOnSurface sInvalidObject - the curve was invalid sFailure - there is no next CurveOnSurface

366 | Chapter 2 AlCamera AlCylinderLight

AlCurveOnSurface* AlCurveOnSurface::prevCurveOnSurface() const Description

Returns the previous curve on surface in the list of curves on surfaces that are attached to a specific surface. Returns NULL if there is no previous curve on surface.

statusCode AlCurveOnSurface::prevCurveOnSurfaceD() Description

Destructively points the wrapper to the previous curve on surface in the list of curves on surfaces that are attached to a specific surface.

Return Codes
sSuccess - the wrapper now points to the previous CurveOnSurface sInvalidObject - the curve was invalid sFailure - there is no previous CurveOnSurface

statusCode AlCurveOnSurface::reverse() Description

Reverse the direction of this curve on surface.

Return Codes
sInvalidObject - the curve on surface was invalid. sFailure - the method didnt succeed. sSuccess - the direction of the curve on surface was successfully reversed.

statusCode AlCurveOnSurface::insert( double param ) Description

Inserts an edit point into the curve.

AlCurveOnSurface | 367

Arguments
< param - parametric value of the new edit point on the curve

Return Codes
sSuccess - normal completion sInvalidArgument - param is out of bounds sInvalidObject - the given object was not valid sFailure - an error occurred

statusCode AlCurveOnSurface::worldSpace3DCopies( int& count, AlCurve **&ws_curves ) Description

Returns a pointer via a reference parameter to a temporary curve that represents a world space copy of the curve on surface. The returned curve should be deleted after use. It does not have a parent node and so is not inserted into the DAG hierarchy. This method creates cubic world space versions of a curve on surface. As there may be more than one spline returned, a loop of splines is returned (and should be deleted later).

Arguments
> count - the number of curves returned in the curve array > ws_curves - the array of curves

Return Codes
sSuccess - normal completion sInvalidObject - the given object was not valid sFailure - an error occurred

368 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCurveOnSurface::unaffected3DCopies( int& count, AlCurve **&ws_curves ) Description

Returns a pointer via a reference parameter to a temporary curve that represents a world space copy of the curve on surface. The returned curve should be deleted after use. It does not have a parent node and so is not inserted into the DAG hierarchy. This method creates cubic world space versions of a curve on surface. As there may be more than one spline returned, a loop of splines is returned (and should be deleted later).

Arguments
> count - the number of curves returned in the curve array > ws_curves - the array of curves

Return Codes
sSuccess - normal completion sInvalidObject - the given object was not valid sFailure - an error occurred

statusCode AlCurveOnSurface::affected3DCopies( AlTM& tm, int& count, AlCurve **&ws_curves ) Description

Returns a pointer via a reference parameter to a temporary curve that represents a world space copy of the curve on surface. The returned curve should be deleted after use. It does not have a parent node and so is not inserted into the DAG hierarchy. tm is the transformation matrix generated while walking the DAG. This method creates cubic world space versions of a curve on surface. As there may be more than one spline returned, a loop of splines is returned (and should be deleted later).

Arguments
> tm - transformation matrix generated by walking the DAG > count - the number of curves returned in the curve array > ws_curves - the array of curves

AlCurveOnSurface | 369

Return Codes
sSuccess - normal completion sInvalidObject - the given object was not valid sFailure - an error occurred

statusCode AlCurveOnSurface::persistentID( AlPersistentID *&id, int userType ) Description

Returns a copy of the AlPersistentID associated with this curve on surface. For user type 1, persistent IDs are created if they do not exist already. For all other user types, persistent IDs are not created if they do not exist already, and the method fails. User types between 0 and 9999 are reserved. If you would like to reserve a block of user types please contact us.

Arguments
> id - a copy of the AlPersistentID < userType - user type of the persistent ID desired.

Return Codes
sSuccess - normal completion sInvalidObject - the given object is not valid sFailure - the ID did not exist or could not be created

statusCode AlCurveOnSurface::setPersistentID( AlPersistentID &id, int userType ) Description

Sets the values of the AlPersistentID associated with this curve on surface. This method only allows you to create persistent IDs with user types other than 1. If the persistent ID does not exist, it will be created. User types between 0 and 9999 are reserved. If you would like to reserve a block of user types please contact us.

370 | Chapter 2 AlCamera AlCylinderLight

Arguments
< userType - user type of the persistent ID desired > id - a copy of the AlPersistentID

Return Codes
sSuccess - normal completion sInvalidObject - the given object is not valid sInvalidArgument - the given user type is not valid sFailure - the ID did not exist or could not be created

statusCode AlCurveOnSurface::hasPersistentID( int userType ) Description

Checks to see if the Curve On Surface has a persistent ID associated with it.

Arguments
< userType - user type of the persistent ID desired

Return Codes
sSuccess - the node has a persistent ID sFailure - the node does not have a persistent ID sInvalidObject - the given object is not valid

statusCode AlCurveOnSurface::blindData( int userType, long& blindDataSize, const char *&blindData ) Description
Get the blind data packet of the specified type from an AlCurveOnSurface.

Return code
sInvalidObject - the surface was invalid. sSuccess - blind data successfully retrieved.

AlCurveOnSurface | 371

sFailure - blind data not found.

statusCode AlCurveOnSurface::setBlindData( int userType, long blindDataSize, const char *blindData ) Description
Add the passed blind data packet to an AlCurveOnSurface.

Return code
sInvalidObject - the surface was invalid. sSuccess - blind data successfully added. sFailure - blind data not added

statusCode AlCurveOnSurface::removeBlindData( int user_type ) Description

Removes the block of data of the given type from the object. Note that the user is still responsible for the memory associated with this block of data.

Arguments
< user_type - user type of the blind desired.

Return Codes
sSuccess - everything is okay sFailure - no such blind data existed sInvalidObject - the given object is not valid

AlCurveOnSurfacePoint
Interface to Alias curve on surface points.

372 | Chapter 2 AlCamera AlCylinderLight

Synopsis
#include <AlCurveOnSurfacePoint.h> class AlCurveOnSurfacePoint : public AlPoint AlCurveOnSurfacePoint(); ~AlCurveOnSurfacePoint(); virtual AlObject * copyWrapper() const; virtual AlObjectType type() const; statusCode create(const AlCurveOnSurface *, double); statusCode setParameter(double); statusCode parameter(double &) const; virtual statusCode worldPosition(double &, double &, double &) const; statusCode tangent(double &, double &, double &) const; statusCode normal1(double &, double &, double &) const; statusCode normal2(double &, double &, double &) const; statusCode arcLength(double &) const; AlCurveOnSurface * attachedTo();

Description
A point can be created in the parametric space of a AlCurveOnSurface. This point can be queried for the curve normals, tangent, and position in world coordinate system. This class contains methods for creating, and moving the point in the parametric space of the curve on surface. If the AlCurveOnSurface or its AlSurface is deleted, the curve on surface point created on it is deleted.

AlCurveOnSurfacePoint::AlCurveOnSurfacePoint(void) Description
Constructs an AlCurveOnSurfacePoint wrapper object.

AlCurveOnSurfacePoint::~AlCurveOnSurfacePoint() Description
Deletes an AlCurveOnSurfacePoint wrapper object.

AlCurveOnSurfacePoint | 373

AlObject *AlCurveOnSurfacePoint::copyWrapper() const Description

Returns an exact copy of the AlCurveOnSurfacePoint wrapper.

statusCode AlCurveOnSurfacePoint::create(const AlCurveOnSurface *curveOnSurface, double u) Description

Creates a point on the given curve on surface

Arguments
< curveOnSurface - the curve on surface on which the point is to be created. < u - the parameter at which point is to be created

Return Codes
sSuccess - the point was successfully created sAlreadyCreated - object has already been created sFailure - the point could not be created on the curve on surface. sInvalidArgument - the curve is not a valid object

statusCode AlCurveOnSurfacePoint::setParameter(double u) Description

Move the position of a point created on a curve on surface

Arguments
< u - the parameter on the curve on surface where the point has to be moved.

Return Codes
sSuccess - the point was moved sInvalidObject - the point is not valid

374 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCurveOnSurfacePoint::parameter(double &u) const Description

Find the parameter value at which the point is present

Arguments
> u - the curve parameter where point is present

Return Codes
sSuccess - the parameter was found sInvalidObject - the point is not valid

statusCode AlCurveOnSurfacePoint::worldPosition(double &x, double &y, double &z) const Description

Find the world coordinates of the point

Arguments
> x, y, z - the world coordinates of the point

Return Codes
sSuccess - the coordinates were found. sInvalidObject - the point is not valid

statusCode AlCurveOnSurfacePoint::tangent(double &x, double &y, double &z) const Description

Find the tangent vector to the curve at the point

Arguments
> x, y, z - the X, Y, Z components of the tangent

AlCurveOnSurfacePoint | 375

Return Codes
sSuccess - the tangent was found. sInvalidObject - the point is not valid

statusCode AlCurveOnSurfacePoint::normal1(double &x, double &y, double &z) const Description

Find the normal to the curve on surface at the point

Arguments
> x, y, z - the X, Y, Z components of the normal

Return Codes
sSuccess - the normal was found. sInvalidObject - the point is not valid

statusCode AlCurveOnSurfacePoint::normal2(double &x, double &y, double &z) const Description

Find the second normal to the curve on surface at the point

Arguments
> x, y, z - the X, Y, Z components of the second normal normalized vector.

Return Codes
sSuccess - the normal was found. sInvalidObject - the point is not valid

statusCode AlCurveOnSurfacePoint::arcLength(double &arcLen) const Description

Find the length of the curve on surface on which the point is present

376 | Chapter 2 AlCamera AlCylinderLight

Arguments
> arcLen - the length of the curve

Return Codes
sSuccess - the arc length was found. sInvalidObject - the point is not valid

AlObjectType AlCurveOnSurfacePoint::type() const Description

Returns the class identifier kCurveOnSurfacePointType.

AlCurveOnSurface * AlCurveOnSurfacePoint::attachedTo() Description

Returns the curve on surface that this point is associated with. NULL is returned if this method fails.

AlCylinderLight
Adds parameters for cylinder volume lights.

Synopsis
#include <AlCylinderLight.h> class AlCylinderLight: public AlVolumeLight AlCylinderLight(); virtual ~AlCylinderLight(); virtual AlObject* copyWrapper() const; statusCode create(); AlObjectType type() const; double arc() const; statusCode setArc(double);

Description
A cylinder light creates light within a cylinder.

AlCylinderLight | 377

AlCylinderLight::AlCylinderLight() Description
Constructs an AlCylinderLight wrapper object.

AlCylinderLight::~AlCylinderLight() Description
Deletes an AlCylinderLight wrapper object.

statusCode AlCylinderLight::create() Description

Creates all the DAG nodes for this light and adds them to the universe. The DAG nodes are for position, look at and up, and another DAG node that groups these three together.

Return Codes
sSuccess - the DAG nodes were created sInsufficientMemory - not enough memory available sAlreadyCreated - the light is already created

AlObjectType AlCylinderLight::type() const Description

Returns the class identifier kCylinderLightType.

double AlCylinderLight::arc() const Description

Returns the sphere lights arc (that is, how much of the sphere we actually have). This method returns -1 if the light is invalid.

378 | Chapter 2 AlCamera AlCylinderLight

statusCode AlCylinderLight::setArc( double arc ) Description

Sets the arc of the light. The given arc must be in the range 0 to 360.

Arguments
< double arc - portion of the sphere to use

Return Codes
sSuccess - setting arc succeeded sInvalidObject - not a valid volume light sInvalidArgument - arc out of the range 0..360 sFailure - an error occurred

AlCylinderLight | 379

380

AlDagNode AlLocator

AlDagNode
Basic Interface to Alias DAG node objects.

381

Synopsis

382 | Chapter 3 AlDagNode AlLocator

#include <AlDagNode.h> class AlDagNode : public AlObject , public AlClusterable , public AlAnimatable , public AlSettable , public AlPickable virtual ~AlDagNode(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; AlDagNode* copyObject( AlCopyOptions* = NULL ); AlDagNode* copyObject( AlCopyOptions*, int, int * ); virtual AlObjectType type() const; virtual const char* name() const; virtual statusCode setName( const char* ); AlGroupNode* parentNode() const; AlDagNode* nextNode() const; AlDagNode* prevNode() const; virtual boolean isInstanceable(); statusCode addSiblingNode( AlDagNode* ); statusCode comment( long&, const char*& ); statusCode setComment( long, const char* ); statusCode removeComment( void ); statusCode blindData( int, long&, const char*& ); statusCode setBlindData( int, long, const char* ); statusCode removeBlindData( int ); statusCode persistentID( AlPersistentID *&, int ); statusCode hasPersistentID( int ); statusCode localTransformationMatrix( double[4][4] ) const; statusCode globalTransformationMatrix( double[4][4] ) const; statusCode inverseGlobalTransformationMatrix( double[4][4] ) const; statusCode affectedTransformationMatrix( const AlTM&, double[4][4] ) const; statusCode localTransformationMatrix( AlTM& ) const; statusCode globalTransformationMatrix( AlTM& ) const; statusCode inverseGlobalTransformationMatrix( AlTM& ) const; statusCode affectedTransformationMatrix( const AlTM&, AlTM& ) const; statusCode translation( double&, double&, double& ) const; statusCode rotation( double&, double&, double& ) const; statusCode scale( double&, double&, double& ) const; statusCode rotatePivot( double&, double&, double& ) const; statusCode scalePivot( double&, double&, double& ) const; statusCode rotatePivotIn( double &x, double &y, double &z ) const; statusCode rotatePivotOut( double &x, double &y, double &z ) const; statusCode scalePivotIn( double &x, double &y, double &z ) const; statusCode scalePivotOut( double &x, double &y, double &z ) const;

AlDagNode | 383

statusCode setTranslation( double, double, double ); statusCode setWorldTranslation( double, double, double ); statusCode setRotation( double, double, double ); statusCode setScale( double, double, double ); statusCode setRotatePivot( double, double, double ); statusCode setScalePivot( double, double, double ); statusCode localRotationAxes( double[3], double[3], double[3] ) const; statusCode setLocalRotationAxes(double[3], double[3], double[3]); statusCode localRotationAngles( double&, double&, double& ) const; statusCode setLocalRotationAngles( double, double, double ); statusCode localRotateBy(double , double ,double ); statusCode localTranslateBy(double , double ,double ); statusCode boundingBox( double[8][4] ) const; boolean isDisplayModeSet( AlDisplayModeType ) const; statusCode setDisplayMode( AlDisplayModeType, boolean ); AlJoint* joint() const; statusCode addJoint(); statusCode removeJoint(); AlDagNode* searchBelow( const char * ) const; AlDagNode* searchAcross( const char * ) const; statusCode updateDrawInfo( void ) const; statusCode sendGeometryModifiedMessage(); statusCode doUpdates( boolean newState = TRUE ); AlConstraint* firstConstraint( void ) const; AlLayer* layer() const; statusCode setLayer( const AlLayer * ); boolean isAConstructionPlane(); AlList* clusterPreTransformationMatrices() const; statusCode createSymmetricGeometry(); statusCode createSymmetricGeometry( AlDagNode *& ); unsigned int version( void ) const; class AlCopyOptions AlCopyOptions(); virtual ~AlCopyOptions(); boolean instanceCopy() const; statusCode setInstanceCopy( boolean ); boolean copyAnimation() const; statusCode setCopyAnimation( boolean ); boolean copyClusters() const; statusCode setCopyClusters( boolean ); int numCopies() const; statusCode setNumCopies( int );

384 | Chapter 3 AlDagNode AlLocator

AlParamControlType parameterControl() const; statusCode setParameterControl( AlParamControlType ); AlHierarchyType hierarchy() const; statusCode setHierarchy( AlHierarchyType ); double timeOffset() const; statusCode setTimeOffset( double ); statusCode translation( double&, double&, double& ) const; statusCode setTranslation( double, double, double ); statusCode rotation( double&, double&, double& ) const; statusCode setRotation( double, double, double ); statusCode scale( double&, double&, double& ) const; statusCode setScale( double, double, double );

Description
This class encapsulates the basic functionality for creating, manipulating and deleting a DAG node. A DAG node is part of a tree-like hierarchical structure known as a directed acyclic graph or DAG. All DAG nodes belong to a single DAG which is contained in the current universe. The head of the DAG is accessible by calling the AlUniverse on page 993::firstDagNode() static method. Each DAG node can be mutually attached to a previous and next DAG node to form a list of DAG nodes. This list can belong to a group (or parent) DAG node. This list of DAG nodes that belong to a group node are called "children" of the group node. A DAG node contains information that defines particular affine transformations such as scale, rotation and translation. There is a specific fixed order in which the transformations are combined. There are methods for accessing each particular transformation and a method exists for obtaining the local transformation matrix built from these transformations. For more information, see the description for the method localTransormationMatrix(). Classes derived from this class will refer to a particular type of object. For example, the AlCameraNode class is derived from AlDagNode and refers to AlCamera objects only. The shape, position and/or orientation of the object referred to is defined by combining the transformations for the DAG node with all the transformations inherited from the DAG nodes above it in the DAG. There is a method for obtaining the global transformation matrix, which is built from the local transformations and all inherited transformations. For example, if DAG node A is a parent of DAG node B which is a parent of DAG node C, then the global transformation of C is the matrix product [C]*[B]*[A], where [C], [B], and [A] are local transformations of each DAG node.

AlDagNode | 385

A DAG node can have some user-defined text associated with it and so there are methods for getting and setting the text. Users cannot instantiate an AlDagNode directly. A derived class of an AlDagNode must be instantiated and then if required the create() method of the class must be called. This will insert the DAG node into the DAG as a parent-less node. A DAG node can be moved so that it is a sibling of any DAG node in the DAG. Deleting a DAG node removes the node from its list of siblings. For derived classes, deletion of a DAG node will cause the deletion of the object that it refers to. Since an AlDagNode simply contains transformations but does not refer to any transformable object, this class is of little practical use on its own. It is primarily an abstract base class from which other DAG node classes are derived. Note that NULL DAG nodes created in the Alias Interactive package are retrieved by this library as group nodes without children. What does a transformation matrix mean? This matrix is the product of matrices for scale, rotate and translate. One useful piece of information from this matrix is the POSITION of an object. The first three values in the bottom row of the matrix (indices (3,0), (3,1), and (3,2)) represent the translation of the origin (0,0,0) in the x, y, and z directions. For instance, if you placed a sphere at (20, 30, 16) in the Alias interactive package, then moved it to (-30, 16, 28), you would notice that its global transformation matrix would have (-30, 16, 28) in the bottom row. Additionally, AlDagNode includes AlCopyOptions as a nested class. This class allows for the querying and setting of options for AlDagNode::copyObject(). When first instantiated, an instance of AlCopyOptions will have its values set according to the values in Edit->Duplicate Object option box. It is not possible to set the values in this option box through this class.

AlDagNode::~AlDagNode() Description
Deletes an AlDagNode wrapper object.

statusCode AlDagNode::deleteObject() Description

Destructor for AlDagNode. The entire DAG branch rooted at this node will be deleted. For each delete DAG node its animation will be deleted and the DAG node will be removed from all clusters or sets it is in. Some DAG nodes cannot

386 | Chapter 3 AlDagNode AlLocator

be deleted (for example, AlTextureNodes), in which case this method will return sFailure.

Return Codes
sSuccess - the DAGnode and all associated objects were deleted sFailure - the DAG node could not be deleted sInvalidObject - the DAG node was not valid

AlObject *AlDagNode::copyWrapper() const Description

Returns an exact duplicate of this AlDagNode wrapper.

AlDagNode *AlDagNode::copyObject( AlCopyOptions* options ) Description

Copies this AlDagNode returning a pointer to the new copy. If "options" is not NULL then the given copy options will be used in making copies, otherwise the options as they exist in the Duplicate object option box will be used. If multiple copies are made, a reference to the last copy will be returned. AlUniverse::redrawScreen() must be called once the copy is complete to see the results.

AlObjectType AlDagNode::type() const Description

Returns the class identifier kDagNodeType.

const char* AlDagNode::name() const Description

Returns the name of the object.

AlDagNode | 387

statusCode AlDagNode::setName( const char *newName) Description

Changes the name of the DAG node to a new name. If the given name is not unique, then a unique name is generated based on the given name and assigned to the DAG node. In this case, a status code of sNameChangedToUniqueOne is returned. It is illegal for the new name to be NULL.

Arguments
< newName - new name of the object

Return Codes
sSuccess - name was changed sInvalidArgument - newName was NULL sFailure - the request could not be completed sInvalidObject - the DAG node was invalid sNameChangedToUniqueOne - name was changed to be a unique version of the given name

AlGroupNode* AlDagNode::parentNode() const Description

Returns a pointer to the parent AlGroupNode or NULL if there is no parent.

AlDagNode* AlDagNode::nextNode() const Description

Returns a pointer to the objects next sibling AlDagNode or NULL if there is no next sibling.

388 | Chapter 3 AlDagNode AlLocator

AlDagNode* AlDagNode::prevNode() const Description

Returns a pointer to the objects previous sibling AlDagNode or NULL if there is no previous sibling.

statusCode AlDagNode::addSiblingNode( AlDagNode *sibling ) Description

Inserts an AlDagNode as the next sibling of this AlDagNode object. If the AlDagNode is already a sibling of this object, then nothing is done and the AlDagNode is left where it is in the list of siblings. Otherwise, the AlDagNode is removed from the list of siblings it belongs to and added to the list of siblings for this object. If the AlDagNode is an AlGroupNode and it has siblings which are instanced AlGroupNodes, those instanced siblings are also made siblings of this object.

Arguments
< sibling - the AlDagNode to be inserted

Return Codes
sSuccess - the AlDagNode is now a sibling of this object sInvalidArgument - sibling was invalid or NULL sFailure - the AlDagNode could not be made a sibling of this object sInvalidObject - the DAG node was invalid

boolean AlDagNode::isInstanceable() Description

Returns TRUE. An AlDagNode is instanceable but derived classes that are not instanceable DAG nodes will redefine this method.

AlDagNode | 389

statusCode AlDagNode::comment( long &size, const char* &data ) Description

Obtains the size and address of a block of textual data associated with the object. If there is no textual data, then the size will be zero and the address of the data is NULL. Note that the comment is NOT a null terminated string.

Arguments
> size - number of characters in the block of text > data - address of the block of text

Return Codes
sSuccess - normal completion sInvalidObject - the given object is not valid

statusCode AlDagNode::blindData( int user_type, long &size, const char* &data ) Description
Obtains the size and address of a block of data associated with the object. If there is no data, then the size will be zero and the address of the data is NULL. User_types must be reserved. If you would like to reserve a block of "user_types" please contact us. User_types less than zero indicate that the blind data is not persistent. As such, when the model is stored, blind data with a negative user_type will not be stored.

Arguments
< user_type - user type of the data desired > size - number of characters in the block of text > data - address of the block of text

Return Codes
sSuccess - normal completion

390 | Chapter 3 AlDagNode AlLocator

sInvalidObject - the given object is not valid

statusCode AlDagNode::persistentID( AlPersistentID *&id, int userType ) Description

Returns a copy of the AlPersistentID associated with this node. If one does not exist one is created. User_types between 0 and 9999 are reserved. If you would like to reserve a block of "user_types" please contact us.

Arguments
> id - a copy of the AlPersistentID < userType - user type of the persistent ID desired

Return Codes
sSuccess - normal completion sInvalidObject - the given object is not valid sFailure - the ID did not exist or could not be created

statusCode AlDagNode::setPersistentID( AlPersistentID &id, int userType ) Description

Sets the values of the AlPersistentID associated with this node. This method only allows you to create persistent IDs with user types other than 1. If the persistent ID does not exist, it will be created. User types between 0 and 9999 are reserved. If you would like to reserve a block of user types please contact us.

Arguments
< userType - user type of the persistent ID desired > id - a copy of the AlPersistentID

Return Codes
sSuccess - normal completion

AlDagNode | 391

sInvalidObject - the given object is not valid sInvalidArgument - the given userType is not valid sFailure - the ID did not exist or could not be created

statusCode AlDagNode::hasPersistentID( int userType ) Description

Checks to see if the DagNode has a persistent ID associated with it.

Arguments
< userType - user type of the persistent ID desired

Return Codes
sSuccess - node has a persistent ID sFailure - node does not have a persistent ID sInvalidObject - the given object is not valid

statusCode AlDagNode::setComment( long size, const char* data ) Description

Associates a block of textual data with the object. If a block of text is already associated with the object, the reference to the old block of text is replaced by a reference to the new block of text. The old block of text is not deleted. It is up to the user to manage the deletion of the old block of text.

Arguments
< size - number of characters in the block of text < data - address of the block of text

Return Codes
sSuccess - operation was successful sInsufficientMemory - not enough memory sInvalidObject - the given object is not valid

392 | Chapter 3 AlDagNode AlLocator

statusCode AlDagNode::setBlindData( int user_type, long size, const char* data ) Description
Associates a block of data with the object. If a block of data is already associated with the object, the reference to the old block of data is replaced by a reference to the new block of data. The old block of data is not deleted. It is up to the user to manage the deletion of the old block of data. The user_type may be user defined to add more than one blind data block to any one object (see blindData() above for additional information).

Arguments
< user_type - desired user type of the blind data < size - number of characters in the block of text < data - address of the block of text

Return Codes
sSuccess - the blind data was set sInsufficientMemory - there is not enough memory sInvalidObject - the given object is not valid

statusCode AlDagNode::removeComment( void ) Description

Removes the block of text associated with this object from the object itself. Note that the user is still responsible for the memory associated with the block of text.

Return Codes
sSuccess - text was removed sFailure - there was no comment to remove sInvalidObject - the given object is not valid

AlDagNode | 393

statusCode AlDagNode::removeBlindData( int user_type ) Description

Removes the block of data of the given type from the object. Note that the user is still responsible for the memory associated with this block of data.

Arguments
< user_type - user type of the blind desired

Return Codes
sSuccess - data was removed sFailure - no such blind data existed sInvalidObject - the given object is not valid

statusCode AlDagNode::localTransformationMatrix( AlTM& matrix ) const Description

Computes the local transformation matrix for the object. This version of the function takes an AlTM matrix instead of a 4x4 matrix of doubles.

Arguments
> matrix - the matrix to contain the local transformation

Return Codes
sSuccess - the transformation was successfully computed sInvalidArgument - the matrix was NULL sFailure - the request could not be completed sInvalidObject - the DAG node was invalid

394 | Chapter 3 AlDagNode AlLocator

statusCode AlDagNode::localTransformationMatrix( double matrix[4][4] ) const Description

Computes the local transformation matrix for the object. The matrix is oriented such that to transform a point, the point must be pre-multiplied by the matrix. The local transformation matrix is defined by seven triples which specify components for scale, rotation, and translation transformations. It is computed by doing the following transformations: local transform = T1 * T2 * T3 * T4 * T5 * T6 * T7 * T8 * T9 - (T1) translation by x,y,z of scalePivotIn vector - (T2) scale by x,y,z of scale vector - (T3) translation by x,y,z of scalePivotOut vector - (T4) translation by x,y,z of rotatePivotIn vector - (T5) x-axis rotation by x component of rotation vector - (T6) y-axis rotation by y component of rotation vector - (T7) z-axis rotation by z component of rotation vector - (T8) translation by x,y,z of rotatePivotOut vector - (T9) translation by x,y,z of translation vector This order reflects the order in which a point would be transformed by each transformation. When setting and querying the rotate pivot and the scale pivot, you only need to worry about setting the pivot in world space. The methods setRotatePivot() and setScalePivot() will calculate the corresponding In and Out transformations (T1,T3,T4,T8).

Arguments
> matrix - the matrix to contain the local transformation

Return Codes
sSuccess - the transformation was successfully computed sInvalidArgument - matrix was NULL sFailure - the request could not be completed sInvalidObject - the DAG node was invalid

AlDagNode | 395

statusCode AlDagNode::globalTransformationMatrix( AlTM& matrix ) const Description

Computes the global transformation matrix for the object, which is obtained by post multiplying the local transformation matrix with the global transformation matrix of the parent AlGroupNode. This version of the function takes an AlTM matrix instead of a 4x4 matrix of doubles.

Arguments
> matrix - the matrix to contain the global transformation

Return Codes
sSuccess - the global transformation matrix was computed sInvalidArgument - matrix was NULL sInvalidObject - this DagNode is invalid

statusCode AlDagNode::globalTransformationMatrix( double matrix[4][4] ) const Description

Computes the global transformation matrix for the object, which is obtained by post-multiplying the local transformation matrix with the global transformation matrix of the parent AlGroupNode. For more information, see the AlDagNode on page 381 class description.

Arguments
> matrix - the matrix to contain the global transformation

Return Codes
sSuccess - the global transformation matrix was computed sInvalidArgument - matrix was NULL sInvalidObject - this DagNode is invalid

396 | Chapter 3 AlDagNode AlLocator

statusCode AlDagNode::inverseGlobalTransformationMatrix( AlTM& matrix ) const Description

Computes the inverse of the global transformation matrix for the object, which is obtained by post-multiplying the local transformation matrix with the global transformation matrix of the parent AlGroupNode. This version of the function takes an AlTM matrix instead of a 4x4 matrix of doubles. You will want to use this method to transform normals. There is a routine in AlTM called AlTM::transNormal, however it may not be numerically stable. Normals are transformed by the equation n = n * trans(inv(M)). To transform a normal (nx,ny,nz), the following code fragment can be used:
AlTM invTM; dagNode->inverseGlobalTransformMatrix( invTM ); invTM.transpose().transVector( nx, ny, nz );

Arguments
> matrix - the matrix to contain the global transformation

Return Codes
sSuccess - the global transformation matrix was computed sInvalidArgument - matrix was NULL sInvalidObject - this DagNode is invalid

statusCode AlDagNode::inverseGlobalTransformationMatrix( double matrix[4][4] ) const Description

Computes the inverse of the global transformation matrix for the object, which is obtained by post-multiplying the local transformation matrix with the global transformation matrix of the parent AlGroupNode. For more information, see the AlDagNode on page 381 class description.

Arguments
> matrix - the matrix to contain the global transformation

AlDagNode | 397

Return Codes
sSuccess - the global transformation matrix was computed sInvalidArgument - matrix was NULL sInvalidObject - this DagNode is invalid

statusCode AlDagNode::affectedTransformationMatrix( const AlTM& tm, AlTM& matrix ) const Description

Computes the transformation matrix for the object, which is obtained by post-multiplying the local transformation matrix with the given AlTM tm.

Arguments
< tm - the transformation matrix generated while walking the DAG > matrix - the matrix to contain the affected transformation

Return Codes
sSuccess - the transformation matrix was computed sInvalidObject - this DagNode is invalid

statusCode AlDagNode::affectedTransformationMatrix( const AlTM& tm, double matrix[4][4] ) const Description

Computes the transformation matrix for the object, which is obtained by post-multiplying the local transformation matrix with the given AlTM.

Arguments
< tm - the transformation matrix generated while walking the DAG > matrix - the matrix to contain the affected transformation

Return Codes
sSuccess - the transformation matrix was computed

398 | Chapter 3 AlDagNode AlLocator

sInvalidArgument - matrix was NULL sInvalidObject - this DagNode is invalid

statusCode AlDagNode::translation( double &x, double &y, double &z ) const Description
Gets the final local translation vector.

Arguments
> x, y, z - components of the translation vector

Return Codes
sSuccess - the final local translation vector was returned sInvalidObject - this DagNode is invalid

statusCode AlDagNode::rotation( double &x, double &y, double &z ) const Description
Gets the amount of rotation (in degrees ) about the x, y, and z axes.

Arguments
> x, y, z - amount of rotation about the x, y, z axis

Return Codes
sSuccess - the rotation was returned sInvalidObject - this DagNode is invalid

statusCode AlDagNode::scale( double &x, double &y, double &z ) const Description
Gets the amount of scale in the x, y, and z direction.

AlDagNode | 399

Arguments
> x, y, z - components of the scale transformation

Return Codes
sSuccess - the scale amount was returned sInvalidObject - this DagNode is invalid

statusCode AlDagNode::rotatePivot( double &x, double &y, double &z ) const Description
Returns the rotate pivot position in world space. The rotate pivot is the point about which rotations take place. For more information, see the description for the method localTransformationMatrix().

Arguments
> x, y, z - components of the translation vector

Return Codes
sSuccess - the rotate pivot was returned sInvalidObject - this DagNode is invalid

statusCode AlDagNode::scalePivot( double &x, double &y, double &z ) const Description
Returns the scale pivot position in world space. The scale pivot is the point about which scaling take place. For more information, see the description for the method localTransformationMatrix().

Arguments
> x, y, z - components of the translation vector

Return Codes
sSuccess - the scale pivot was returned

400 | Chapter 3 AlDagNode AlLocator

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::doUpdates( boolean newState ) Description

Notifies the system that you are finished performing. If this flag is true, it is equivalent to sending out a geometry modified message to the rest of the system. When the system receives the update message, operations such as construction history, and so on, are done. This feature is important when using construction history plug-ins. Construction history plug-ins should always set the doUpdate flag to FALSE when doing updates (otherwise an infinite update loop will result, usually ending in a core dump). The update can be explicitly forced using the AlDagNode::sendGeometryModifiedMessage() method. This flag DOES NOT UPDATE THE SCREEN. Use the AlUniverse::redrawScreen to do the screen refresh. If the previous state of the flag was FALSE and the new state is TRUE, an update will be done at this point and on each subsequent DAG modification.

Return Codes
sSuccess - the new state was set sInvalidObject - this DagNode is invalid

statusCode AlDagNode::setTranslation( double x, double y, double z ) Description

Sets the final local translation vector. The translation transformation is done after rotations. This method takes advantage of the doUpdate mechanism to control whether updates happen immediately or are batched until the end of an operation. NOTE: If this DAG node is a surface made from construction history, then the construction history will be broken. To find out if this surface is created by construction history, cast this DAG node to a surface. If it is a surface, call the method AlSurface on page 858::isConstructionHistoryResultingSurface().

Arguments
< x, y, z - components of the translation vector

AlDagNode | 401

Return Codes
sSuccess - the final local translation vector was set sInvalidObject - this DagNode is invalid

statusCode AlDagNode::setWorldTranslation( double x, double y, double z) Description

Sets the final world translation vector (by appropriately modifying the local translation). See setTranslation() for notes on construction history. See setTranslation() for notes on doUpdates().

Arguments
< x, y, z - components of the translation vector

Return Codes
sSuccess - the final local translation vector was set sInvalidObject - this DagNode is invalid

statusCode AlDagNode::sendGeometryModifiedMessage() Description

Sends out an update message notifying that the geometry of this dagNode has been modified. This function is intended to be used after a series of geometry changes have been done with the doUpdate parameter set to FALSE. Note that updates should not be done during construction history plug-ins (an infinite loop will result).

Return Codes
sSuccess - the message was sent sInvalidObject - this DagNode is invalid

402 | Chapter 3 AlDagNode AlLocator

statusCode AlDagNode::setRotation( double x, double y, double z ) Description

Sets the amount of rotation (in degrees) about the x, y, and z axes. The rotations will be done after the scale transformation and before the final local translation. See setTranslation for notes on doUpdate. See setTranslation() for notes on construction history and on doUpdates().

Arguments
< x, y, z - amount of rotation about the x, y, z axis

Return Codes
sSuccess - the amount of rotation was set sInvalidObject - this DagNode is invalid

statusCode AlDagNode::setScale( double x, double y, double z ) Description

Sets the local scale vector. The scale transformation will be done before the local rotations. There is no restriction on the values of the components of the scale vector. See setTranslation() for notes on construction history and on doUpdates().

Arguments
< x, y, z - components of the scale transformation

Return Codes
sSuccess - the local scale vector was set sInvalidObject - this DagNode is invalid

AlDagNode | 403

statusCode AlDagNode::setRotatePivot( double x, double y, double z ) Description

Changes the rotate pivot to the world space position given by x, y, and z. The rotate pivot is the point about which rotations take place.

Arguments
< x, y, z - components of the translation vector

Return Codes
sSuccess - the rotate pivot was set sInvalidObject - this DagNode is invalid

statusCode AlDagNode::setScalePivot( double x, double y, double z) Description

Changes the scale pivot to the world space position given by x, y, and z. The scale pivot is the point about which scaling take place.

Arguments
< x, y, z - components of the translation vector

Return Codes
sSuccess - the scale pivot was set sInvalidObject - this DagNode is invalid

statusCode AlDagNode::localRotationAxes( double x[3], double y[3], double z[3] ) const Description
Returns vectors representing the local rotation axes for this node. These axes are the three axes vectors in world space co-ordinates.

404 | Chapter 3 AlDagNode AlLocator

Arguments
> x, y, z - three vectors representing the 3 axes

Return Codes
sSuccess - the local rotation axes were returned sInvalidArgument - x, y or z was NULL sInvalidObject - this DagNode is invalid

statusCode AlDagNode::setLocalRotationAxes(double x[3], double y[3], double z[3]) Description

Sets the local rotation axes of this DAG node to the given world space vectors. Note that you must ensure that the three vectors x, y and z are orthogonal, otherwise you may get unpredictable results. Also, note that if they are orthogonal, that all three axes are not needed, and in fact this method does not use the z vector.

Arguments
> x, y, z - three vectors representing the 3 axes

Return Codes
sSuccess - the local rotation axes were returned sInvalidArgument - x, y or z was NULL sInvalidObject - this DagNode is invalid

statusCode AlDagNode::localRotationAngles( double& x, double& y, double& z ) const Description

These angles allow you to determine how the local rotation axis have been rotated from their initial position. For example the x value indicates how much the y and z axes have been rotated about the x axis.

AlDagNode | 405

Arguments
> x, y, z - rotation angles about the three axes

Return Codes
sSuccess - the local rotation angles were returned sInvalidObject - this DagNode is invalid

statusCode AlDagNode::setLocalRotationAngles( double x, double y, double z) Description

Setting the local rotation angles is the only means by which the local rotations axes can be modified. Each angle represents how much the other two axes are rotated about itself from their initial position. For example the value for x will determine how much the y and z axes are rotated about the x axis.

Arguments
> x, y, z - rotation angles about the three axes

Return Codes
sSuccess - the local rotation angles were set sInvalidObject - this DagNode is invalid sFailure - the local rotation angle could not be set

statusCode AlDagNode::localRotateBy(double x, double y,double z) Description

Does a DAG node rotation based on the setting of the local axes. This function is additive or relative. Rotations are applied against previous rotations. The current rotation in world space is returned by AlDagNode::rotation().

Parameters:
> x,y,z - amount to rotate by

406 | Chapter 3 AlDagNode AlLocator

Return Codes
sSuccess - the method succeeded sFailure - the method failed sInvalidObject - the DAG node was invalid

statusCode AlDagNode::localTranslateBy(double x, double y,double z) Description

Does a DAG node translation based on the setting of the local axes. This function is additive or relative. Translations are applied against previous translations. The current translation in world space is returned by AlDagNode::translation().

Parameters
> x,y,z - amount to translate by

Return Codes
sSuccess - the method succeeded sFailure - the method failed sInvalidObject - the DAG node was invalid

statusCode AlDagNode::boundingBox( double corners[8][4] ) const Description

Returns the eight corners of the bounding box in world space. These corners are exactly like the bounding boxes drawn in the interactive Alias package. This DAG node must be in bounding box mode before this method is called.

Arguments
> corners - a matrix to hold the eight corners of the bounding box. Each corner has an x, y, z and homogeneous component.

Return Codes
sSuccess - the bounding box was returned

AlDagNode | 407

sInvalidArgument - corners was NULL sFailure - the display mode was set or the box could not be determined sInvalidObject - the DAG node was invalid

boolean AlDagNode::isDisplayModeSet( AlDisplayModeType mode ) const Description

Returns TRUE if the specified display mode is toggled on for the DAG node. Returns FALSE otherwise. The only valid AlDisplayModeTypes for an AlDagNode are

kDisplayModeBoundingBox kDisplayModeInvisible kDisplayModeTemplate kDisplayModeDashed kDisplayModeConstructionPlane kDisplayModeCompressedSbd

Arguments
< mode - display mode of interest

statusCode AlDagNode::setDisplayMode( AlDisplayModeType mode, boolean on_or_off) Description

For the given display mode, if the flag is TRUE then the display mode for the DAG node is set; otherwise it is unset. The only valid AlDisplayModeTypes for an AlDagNode are

kDisplayModeBoundingBox kDisplayModeInvisible kDisplayModeTemplate kDisplayModeDashed

408 | Chapter 3 AlDagNode AlLocator

kDisplayModeConstructionPlane kDisplayModeCompressedSbd

Arguments
< mode - display mode of interest < on_or_off - TRUE means that this DAG node will have the display mode set. FALSE means it will be unset.

Return Codes
sSuccess - operation was successful sInvalidArgument - invalid display type sInvalidObject - the DAG node was invalid sFailure - the display mode could not be set

statusCode AlDagNode::rotatePivotIn( double &x, double &y, double &z ) const Description
Gets the local pre-rotation translation vector.

Arguments
> x, y, z - components of the translation vector

Return Codes
sSuccess - the local pre-rotation translation vector was returned sInvalidObject - this DagNode is invalid

statusCode AlDagNode::rotatePivotOut( double &x, double &y, double &z ) const Description
Gets the local post-rotation translation vector.

AlDagNode | 409

Arguments
> x, y, z - components of the translation vector

Return Codes
sSuccess - the local post-rotation translation vector was returned sInvalidObject - this DagNode is invalid

statusCode AlDagNode::scalePivotIn( double &x, double &y, double &z ) const Description
Gets the local pre-scale translation vector.

Arguments
> x, y, z - components of the translation vector

Return Codes
sSuccess - the local pre-scale translation vector was returned sInvalidObject - this DagNode is invalid

statusCode AlDagNode::scalePivotOut( double &x, double &y, double &z ) const Description
Gets the local post-scale translation vector.

Arguments
> x, y, z - components of the translation vector

Return Codes
sSuccess - the local post-scale translation vector was returned sInvalidObject - this DagNode is invalid

410 | Chapter 3 AlDagNode AlLocator

AlJoint* AlDagNode::joint() const Description

Gets the IK joint node if one exists.

statusCode AlDagNode::addJoint() Description

Adds an AlJoint to this DAG node to maintain IK information. Note that an AlDagNode may have only one AlJoint. If the AlDagNode already has an AlJoint when this method is called nothing will be done, and sSuccess will be returned.

Return Codes
sSuccess - the operation succeeded sInvalidObject - the DAG node was invalid sFailure - it was not possible to add an AlJoint

statusCode AlDagNode::removeJoint() Description

Removes the AlJoint to this DAG node to maintain IK information.

Return Codes
sSuccess - the operation succeeded sInvalidObject - the DAG node was invalid sFailure - it was not possible to remove the AlJoint

AlDagNode * AlDagNode::searchBelow( const char * name ) const Description

Searches the DAG tree (rooted at the child of the current node) for a DAG node with a specific name. A pointer to the DAG node is returned if it is found. NULL is returned if no such DAG node exists.

AlDagNode | 411

Arguments
name - the name to look for

AlDagNode * AlDagNode::searchAcross( const char * name ) const Description

Searches across the DAG tree (starting at the current node), for a DAG node with a specific name. A pointer to the DAG node is returned if it is found. NULL is returned if no such DAG node exists.

Arguments
name - the name to look for

statusCode AlDagNode::updateDrawInfo( void ) const Description

Forces the internal draw information to be updated to match the DagNodes geometry.

Return Codes
sSuccess - the draw information was updated sInvalidObject - the DAG node was invalid sFailure - this call is not valid in OpenModel

AlLayer* AlDagNode::layer() const Description

Gets the layer of an AlDagNode.

statusCode AlDagNode::setLayer(const AlLayer *layerObj) Description

Sets the layer on a DAG node. When a layer is set to an AlDagNode, the following settings are assigned: 1 All the child nodes of the current node are assigned to the layerObj layer.

412 | Chapter 3 AlDagNode AlLocator

2 All the parent nodes are assigned to the default layer. 3 All the sibling nodes are unaffected.

Arguments
< layerObj - the layer object to be assigned to the AlDagNode

Return Codes
sSuccess - the layer was assigned successfully sInvalidArgument - the layer is invalid sInvalidObject - the DAG node was invalid

AlConstraint* AlDagNode::firstConstraint( void ) const Description

Returns a pointer to the first constraint on this DAG node.

boolean AlDagNode::isAConstructionPlane() Description

Returns TRUE if the DAG node is a construction plane.

AlList* AlDagNode::clusterPreTransformationMatrices() const Description

Returns a list of AlClusterPreTMItem on page 255, which contains the transformation matrices of the geometry DAG node for clusters. NULL is returned for non_leaf or null DAG nodes, or if a DAG node does not involve with any cluster. Note: you must delete the AlList object.

AlDagNode | 413

AlDagNode *AlDagNode::copyObject( AlCopyOptions* options, int numOfBlindDataIDsToCopy, int *blindDataIDsToCopy ) Description

This method is similar to the ::copyObject() method above. In addition, blind data IDs to be copied are specified with this method.

Arguments
< - numOfBlindDataIDsToCopy contains the number of elements of array blindDataIDsToCopy[] < - blindDataIDsToCopy is an array of IDs to copy NULL will be returned if numOfBlindDataIDsToCopy < 1 or blindDataIDsToCopy is NULL. Warning: we suggest only copying blind data IDs that are managed by your code. Copying blind data IDs out of your range may lead to program errors.

statusCode AlDagNode::createSymmetricGeometry( ) Description

Creates the symmetric geometry for this node if it is on a symmetric plane.

Return code
sSuccess - the method succeeded sFailure - the method failed sInvalidObject - invalid dag node

statusCode AlDagNode::createSymmetricGeometry( AlDagNode *&symmGeomDag ) Description

Creates the symmetric geometry for this node if it is on a symmetric plane.

Return code
sSuccess - the method succeeded

414 | Chapter 3 AlDagNode AlLocator

sFailure - the method failed sInvalidObject - invalid dag node

unsigned int AlDagNode::version( void ) const Description

Returns the version of the DagNode

AlDagNode::AlCopyOptions::AlCopyOptions() Description
This constructor initializes the instance to the current Duplicate options, or in OpenModel to the defaults for the Duplicate operation.

copyAnimation set to FALSE. instanceCopy set to FALSE copyClusters set to TRUE. numCopies set to 1. parameters set to ALL. hierarchy set to BOTH. timeOffset set to 0. translate, rotate set to 0. scale set to 1.

By default, copies will be grouped with the original AlDagNode.

AlDagNode::AlCopyOptions::~AlCopyOptions() Description
Deletes this instance of the AlDagNode::AlCopyOptions class.

AlDagNode | 415

boolean AlDagNode::AlCopyOptions::copyAnimation() const Description

Returns TRUE if copying of an AlDagNodes animation is enabled.

statusCode AlDagNode::AlCopyOptions::setCopyAnimation( boolean animation ) Description

If "animation" is TRUE, animation data on the AlDagNode will be copied.

Return Codes
sSuccess - the flag was correctly set sInvalidObject - the AlCopyOptions object was not properly created

boolean AlDagNode::AlCopyOptions::instanceCopy() const Description

Returns TRUE if the copies are to be instances of the AlDagNode rather than new objects.

statusCode AlDagNode::AlCopyOptions::setInstanceCopy( boolean instance ) Description

If "instance" is TRUE, instances of the AlDagNode will be created rather than new objects.

Return Codes
sSuccess - the flag was correctly set sInvalidObject - the AlCopyOptions object was not properly created

416 | Chapter 3 AlDagNode AlLocator

boolean AlDagNode::AlCopyOptions::copyClusters() const Description

Returns TRUE if new copies of clusters should be made of clusters that reference geometry below the AlDagNode.

statusCode AlDagNode::AlCopyOptions::setCopyClusters( boolean clusters ) Description

If "clusters" is TRUE, new copies of clusters will be created for clusters that reference geometry below the AlDagNode.

Return Codes
sSuccess - the flag was correctly set

int AlDagNode::AlCopyOptions::numCopies() const Description

Returns the number of copies to be created. Zero will be returned if the AlDagNode::AlCopyOptions object wasnt properly created.

statusCode AlDagNode::AlCopyOptions::setNumCopies( int copies ) Description

Sets the number of copies to create.

Return Codes
sSuccess - the flag was correctly set sInvalidObject - the AlCopyOptions object was not properly created

AlDagNode | 417

AlParamControlType AlDagNode::AlCopyOptions::parameterControl() const Description

Returns the current parameter control setting. This will be one of kPARAMETER_ALL, kPARAMETER_GLOBAL, or kPARAMETER_LOCAL as defined in AlAnim.h.

statusCode AlDagNode::AlCopyOptions::setParameterControl( AlParamControlType control ) Description

Sets the parameter control to one of kPARAMETER_ALL, kPARAMETER_GLOBAL, or kPARAMETER_LOCAL as defined in AlAnim.h.

Return Codes
sSuccess - the flag was successfully set sInvalidArgument - control was not one of the three possibilities sInvalidObject - the AlCopyOptions object was not properly created

AlHierarchyType AlDagNode::AlCopyOptions::hierarchy() const Description

Returns the current hierarchy setting. This will be one of kHIERARCHY_NONE, kHIERARCHY_ABOVE, kHIERARCHY_BELOW, or kHIERARCHY_BOTH as defined in AlAnim.h.

statusCode AlDagNode::AlCopyOptions::setHierarchy( AlHierarchyType hier ) Description

Sets the hierarchy to one of kHIERARCHY_NONE, kHIERARCHY_ABOVE, kHIERARCHY_BELOW, or kHIERARCHY_BOTH as defined in AlAnim.h.

Return Codes
sSuccess - the flag was successfully set

418 | Chapter 3 AlDagNode AlLocator

sInvalidArgument - control was not one of the three possibilities sInvalidObject - the AlCopyOptions object was not properly created

double AlDagNode::AlCopyOptions::timeOffset() const Description

Returns the time offset for the copies if animation is being copied.

statusCode AlDagNode::AlCopyOptions::setTimeOffset( double offset ) Description

Sets the time offset for copies when copying animation

Return Codes
sSuccess - the offset was correctly set sInvalidObject - the AlCopyOptions object was not properly created

statusCode AlDagNode::AlCopyOptions::translation( double& x, double& y, double& z ) const Description

Returns the translation which will be applied to copies of the AlDagNode.

Return Codes
sSuccess - the translation was successfully determined sInvalidObject - the AlCopyOptions object was not properly created

statusCode AlDagNode::AlCopyOptions::setTranslation( double x, double y, double z ) Description

Sets the translation, which will be applied to copies of the AlDagNode.

Return Codes
sSuccess - the translation was successfully set

AlDagNode | 419

sInvalidObject - the AlCopyOptions object was not properly created

statusCode AlDagNode::AlCopyOptions::rotation( double& x, double& y, double& z ) const Description

Returns the rotation, which will be applied to copies of the AlDagNode.

Return Codes
sSuccess - the rotation was successfully determined sInvalidObject - the AlCopyOptions object was not properly created

statusCode AlDagNode::AlCopyOptions::setRotation( double x, double y, double z ) Description

Sets the rotation, which will be applied to copies of the AlDagNode.

Return Codes
sSuccess - the rotation was successfully set sInvalidObject - the AlCopyOptions object was not properly created

statusCode AlDagNode::AlCopyOptions::scale( double& x, double& y, double& z ) const Description

Returns the scale, which will be applied to copies of the AlDagNode.

Return Codes
sSuccess - the scale was successfully determined sInvalidObject - the AlCopyOptions object was not properly created

420 | Chapter 3 AlDagNode AlLocator

statusCode AlDagNode::AlCopyOptions::setScale( double x, double y, double z ) Description

Sets the scale, which will be applied to copies of the AlDagNode.

Return Codes
sSuccess - the scale was successfully set sInvalidObject - the AlCopyOptions object was not properly created

AlDebug
Base class for OpenAlias/Model debugging utilities.

Synopsis
#include <AlDebug.h> class AlDebug static statusCode cleanUpUniverse( void ); static statusCode applyIteratorToValid( AlIterator*, int& ); static statusCode applyIteratorToInvalid( AlIterator*, int& ); static statusCode applyIteratorToAll( AlIterator*, int& ); static statusCode outputWrapperUsage( AlOutputType ); static statusCode setErrorReportingFunction( AlErrorReporter* ); static void checkpoint( void );

Description
This class provides a set of routines which may help in debugging Alias API applications and plug-ins. Most of these functions are intended for debugging purposes only and should not be used in a release product. These methods can only be used to debug a single plugin module (if multiple plugins are used, then debugging information will be printed for ALL of the wrappers that have been created or deleted). The cleanUpUniverse method provides a way to delete all of the wrappers that have not been deleted. It may be possible to use this method in an OpenModel application if no wrappers are created on the user stack.

AlDebug | 421

The applyIterator methods apply an iterator to every wrapper that is created (or that is possibly invalid). The setErrorReportingFunction method sets the function that is used to display errors. The following assertion condition macros output errors to stderr before Alias exits:

AL_ASSERT(condition,msg) - prints out msg if the condition fails AL_CREATED() - prints out any error message created twice (if the AlObject has already been created) AL_NOT_CREATED() - if the object has not been created, an error is printed AL_CASE_ERR(caseValue, msg) - used to print out an error msg if an unknown case value is detected in a switch statement AL_ELSE_ERR() - used to print out an error message if an impossible else branch is reached AL_MEMERR() - prints out a memory error AL_ASSERT_COND(condition) - if the given condition fails, then an assertion error message is printed

void AlDebug::checkpoint( void ) Description

Lets you set a breakpoint at a certain point in Alias. Debugging the initialization of plugins is difficult because the plugin executable is not present until it is loaded. To use the checkpoint facility, use your debugger to place a breakpoint at the AlDebug::checkpoint function and make an explicit call to this function in the startup code of the plugin. This will allow you to stop your plugin before it begins to fully execute. Note that static initializers will have already been executed by the time the plugin reaches the breakpoint.

statusCode AlDebug::cleanUpUniverse() Description

Deletes all wrappers that have become invalid.

422 | Chapter 3 AlDagNode AlLocator

Note that this method could cause core dumps if not used properly. For example, there will be a core dump if this method is called when there are any invalid objects allocated on the stack. Your application will core dump if it references any pointers to invalid objects after this method is called. If you call this method from OpenAlias, you may invalidate memory belonging to other plugins wrappers. In general, to be safe, never allocate wrappers on the stack, and always assume all pointers are gone after this method is used.

Return Codes
sSuccess - the universe was properly cleaned up

statusCode AlDebug::applyIteratorToValid( AlIterator* iter, int& rc ) Description

Applies the iterator to every valid wrapper that has been created. The return code of the iterator is placed into the variable rc. This routine should only be called when no other plugins are present and all wrappers have been allocated using the new operator. The behavior of this function is undefined for wrappers which have been allocated on the user stack.

Return Codes
sSuccess - the iterator was applied to every valid wrapper sFailure - the universe has not been initialized sInvalidArgument - the given iterator was NULL

statusCode AlDebug::applyIteratorToInvalid( AlIterator* iter, int& rc ) Description

Applies the iterator to every deleted or invalid wrapper. The return code of the iterator is placed into the variable rc. This routine should only be called when no other plugins are present and all wrappers have been allocated using the new operator. The behavior of this function is undefined for wrappers which have been allocated on the user stack and then deleted.

Return Codes
sSuccess - the iterator was applied to every valid wrapper

AlDebug | 423

sFailure - the universe has not been initialized sInvalidArgument - the given iterator was NULL

statusCode AlDebug::applyIteratorToAll( AlIterator* iter, int& rc ) Description

Applies the iterator to all valid and invalid wrappers. The return code of the iterator is placed into the variable rc.

Return Codes
sSuccess - the iterator was applied to every valid wrapper sFailure - the universe has not been initialized sInvalidArgument - the given iterator was NULL

int AlDebugOutputIterator::func( AlObject* obj ) Description

Applies the iterator to the AlObject. This is an internal routine.

statusCode AlDebug::outputWrapperUsage( AlOutputType tp ) Description

Outputs information about the current wrapper usage. Note that this function can only be called when no other plugins are in use. For every wrapper (either valid or invalid), the objects address, its type and its name are printed out to the indicated output type.

Return Codes
sSuccess - the iterator was applied to every valid wrapper sFailure - the universe has not been initialized sInvalidArgument - the given iterator was NULL

424 | Chapter 3 AlDagNode AlLocator

statusCode AlDebug::setErrorReportingFunction( AlErrorReporter* rep ) Description

Sets the callback function that is used to report errors. The current error reporting function is replaced with the given function. The supplied pointer rep should point to a user-defined printf style function. (See stdarg.h for more information on parsing the arguments.) This method is only available in OpenModel.

Return Codes
sSuccess - the error reporting function was set sFailure - OpenAlias is currently being used

AlDeviationLocator
Interface to Alias deviation locator.

AlDeviationLocator | 425

Synopsis
#include <AlDeviationLocator.h> class AlDeviationLocator : public AlLocator AlDeviationLocator(); virtual ~AlDeviationLocator(); virtual AlObject * copyWrapper() const; virtual AlObjectType type() const; statusCode create(const AlCurve *, const AlCurve *, double = 0.0); statusCode create(const AlCurveOnSurface *, const AlCurve *, double = 0.0); statusCode create(const AlCurveOnSurface *, const AlCurveOnSurface *, double = 0.0); statusCode deviation(double &) const; statusCode deviationComponents(double &, double &, double &) const; statusCode setParameter(double); statusCode parameter(double &) const; statusCode parameterTargetCurve(double &) const; statusCode setOffset(double, double, double); statusCode offset(double &, double &, double &) const; statusCode setLength(double); statusCode length(double &) const; statusCode setLeftJustify(boolean); statusCode leftJustify(boolean &) const; statusCode attachedTo( AlObject *&, AlObject *& );

Description
A deviation locator finds and displays the shortest distance between two curves, from a given point on the first curve to the second curve. The two curves can be any of the AlCurve on page 301 or AlCurveOnSurface on page 357 curves. This class contains methods to create the locator, query the minimum distance, and set the display attributes in the Alias windows. If any two curves on which this locator depends is deleted, this locator is deleted.

AlDeviationLocator::AlDeviationLocator(void) Description
Constructs an AlDeviationLocator wrapper object.

426 | Chapter 3 AlDagNode AlLocator

AlDeviationLocator::~AlDeviationLocator() Description
Deletes an AlDeviationLocator wrapper object.

AlObject *AlDeviationLocator::copyWrapper() const Description

Returns an exact copy of the AlDeviation wrapper.

AlObjectType AlDeviationLocator::type() const Description

Returns the class identifier kDeviationLocatorType.

statusCode AlDeviationLocator::create(const AlCurve *baseCurve, const AlCurve *targetCurve, double baseParameter) Description
Creates a Deviation locator between two curves.

Arguments
< baseCurve - the curve from which the deviation is calculated < targetCurve - the curve to which the minimum deviation is calculated < baseParameter - the parameter on baseCurve from which the minimum deviation to the target curve is calculated

Return Codes
sSuccess - the deviation locator was successfully created sFailure - the locator was not created sAlreadyCreated - the object was already created sInvalidArgument - the baseCurve or targetCurve is not valid

AlDeviationLocator | 427

statusCode AlDeviationLocator::create(const AlCurveOnSurface *baseCurve, const AlCurve *targetCurve, double baseParameter) Description
Creates a deviation locator between a curve on surface and a curve.

Arguments
< baseCurve - the curve on surface from which the deviation is calculated < targetCurve - the curve to which the minimum deviation is calculated < baseParameter - the parameter on baseCurve from which the minimum deviation to the target curve is calculated

Return Codes
sSuccess - the deviation locator was successfully created sFailure - the locator was not created sAlreadyCreated - the object has already been created sInvalidArgument - the baseCurve or targetCurve is not valid

statusCode AlDeviationLocator::create(const AlCurveOnSurface *baseCurve, const AlCurveOnSurface *targetCurve, double baseParameter) Description
Creates a Deviation locator between two curves on surface.

Arguments
< baseCurve - the curve on surface from which the deviation is calculated < targetCurve - the curve on surface to which the minimum deviation is calculated < baseParameter - the parameter on baseCurve from which the minimum deviation to the target curve is calculated

Return Codes
sSuccess - the deviation locator was successfully created

428 | Chapter 3 AlDagNode AlLocator

sFailure - the locator was not created sAlreadyCreated - the object has already been created sInvalidArgument - the baseCurve or targetCurve is not valid

statusCode AlDeviationLocator::deviation(double &dev) const Description

Finds the minimum deviation as calculated by the deviation locator.

Arguments
> dev - the minimum deviation

Return Codes
sSuccess - the deviation was found sInvalidObject - the object is not valid

statusCode AlDeviationLocator::deviationComponents(double &x, double &y, double &z) const Description

Finds the components of minimum deviation as calculated by the deviation locator.

Arguments
> x, y, z - the x, y, and z components of minimum deviation

Return Codes
sSuccess - the deviation was found sInvalidObject - the object is not valid

AlDeviationLocator | 429

statusCode AlDeviationLocator::setParameter(double param) Description

Sets the parameter on the baseCurve from which the minimum deviation to targetCurve is calculated.

Arguments
< param - the parameter on baseCurve to be set

Return Codes
sSuccess - the parameter was set successfully sInvalidObject - the object is not valid

statusCode AlDeviationLocator::parameter(double &param) const Description

Finds the parameter on the baseCurve from which the minimum deviation to targetCurve is calculated.

Arguments
> param - the parameter on baseCurve

Return Codes
sSuccess - the parameter was found successfully sInvalidObject - the object is not valid

statusCode AlDeviationLocator::parameterTargetCurve(double &param) const Description

Finds the parameter on the targetCurve which is at the minimum deviation to the baseCurve.

430 | Chapter 3 AlDagNode AlLocator

Arguments
> param - the parameter on targetCurve

Return Codes
sSuccess - the parameter was found successfully sInvalidObject - the object is not valid

statusCode AlDeviationLocator::setOffset(double x, double y, double z) Description

Sets the components of display offset in the deviation locator. The display offset is the relative vector between the deviation locator and start of the leader line which displays the deviation value.

Arguments
> x, y, z - the offset components

Return Codes
sSuccess - the components were found successfully sInvalidObject - the object is not valid

statusCode AlDeviationLocator::offset(double &x, double &y, double &z) const Description

Finds the components of display offset in the deviation locator.

Arguments
> x, y, z - the x, y, and z components of the display offset

Return Codes
sSuccess - the offset was found successfully sInvalidObject - the object is not valid

AlDeviationLocator | 431

statusCode AlDeviationLocator::setLength(double len) Description

Sets the length of the leader line in the deviation display in the modeling windows.

Arguments
< len - the length of the leader line

Return Codes
sSuccess - the length was set successfully sInvalidObject - the object is not valid

statusCode AlDeviationLocator::length(double &len) const Description

Finds the length of the leader line in the deviation locator.

Arguments
> len - the length of the leader line

Return Codes
sSuccess - the length was found successfully sInvalidObject - the object is not valid

statusCode AlDeviationLocator::setLeftJustify(boolean leftJustify) Description

Aligns text for the deviation locator. The text can be aligned to the right or to the left.

Arguments
< leftJustify - a value of true aligns text to the left, while a value of false aligns text to the right.

432 | Chapter 3 AlDagNode AlLocator

Return Codes
sSuccess - setting was successful sInvalidObject - the object is not valid

statusCode AlDeviationLocator::leftJustify(boolean &leftJustify) const Description

Determines whether the deviation locator text is aligned to the left or right.

Arguments
> leftJustify - a value of true indicates that it is aligned to the left; false indicates that it is aligned to the right.

Return Codes
sSuccess - the alignment was found sInvalidObject - the object is not valid

statusCode AlDeviationLocator::attachedTo( AlObject *&objectOne, AlObject *& objectTwo ) Description

Returns the two objects that are used to create the deviation locator. This locator can be attached to curves on surfaces or curve nodes.

Arguments
> objectOne, objectTwo - locator is attached to these objects

Return Codes
sSuccess - the attached to objects were found sInvalidObject - the object is not valid sFailure - the method failed

AlDeviationLocator | 433

AlDirectionLight
Encapsulates the functionality common to all directional lights.

Synopsis
#include <AlDirectionLight.h> class AlDirectionLight: public AlNonAmbientLight AlDirectionLight(); virtual ~AlDirectionLight(); virtual AlObject* copyWrapper() const; statusCode create(); AlObjectType type() const; AlLightNode* lookAtNode() const; AlLightNode* upNode() const; virtual statusCode direction( double&, double&, double& ) const; virtual statusCode setDirection( double, double, double );

Description
There are two ways that this class is used. If the user instantiates and calls the create method on an AlDirectionLight, the resulting object is a light that has color, intensity, and direction but no obvious source in a scene. This type of direction light does not decay with distance. Sunlight is a direction light of this type. Alternatively, the user could instantiate and create an AlSpotLight, AlLinearLight, or AlAreaLight (which are all considered "directional" and which are all derived from this light class). Although all direction lights can access the "look at" and "up" nodes of a light, only the spot light uses these nodes.

AlDirectionLight::AlDirectionLight() Description
Constructs an AlDirectionLight wrapper object.

AlDirectionLight::~AlDirectionLight() Description
Deletes an AlDirectionLight wrapper object.

434 | Chapter 3 AlDagNode AlLocator

statusCode AlDirectionLight::create() Description

Creates all the DAG nodes for this light and adds them to the universe. The DAG nodes are for position, look at and up, and another DAG node that groups these three together.

Return Codes
sSuccess - everything was successful sInsufficientMemory - not enough memory available sAlreadyCreated - light is already created

AlObjectType AlDirectionLight::type() const Description

Returns the class identifier, kDirectionLightType.

AlLightNode *AlDirectionLight::lookAtNode() const Description

Returns a pointer to the lights "look at" node. This node is an AlLightNode (which is a DAG node).

AlLightNode *AlDirectionLight::upNode() const Description

Returns a pointer to the lights "up" node. This node is an AlLightNode (which is a DAG node).

statusCode AlDirectionLight::direction( double &x, double &y, double &z ) const Description
Returns a world space vector indicating the direction that this light is pointing. The default direction for the light is (0,0,-1)

AlDirectionLight | 435

Arguments
> x - the direction vector in x > y - the direction vector in y > z - the direction vector in z

Return Codes
sSuccess - the direction was returned sFailure - the direction could not be determined sInvalidObject - the light was invalid

statusCode AlDirectionLight::setDirection( double x, double y, double z ) Description

This is a convenience function. It calculates rotations in the DAG node to set the world direction of the light. This will overwrite the current rotations in the light node. The default direction for the light is (0,0,-1)

Arguments
< x - the direction vector in x < y - the direction vector in y < z - the direction vector in z

Return Codes
sSuccess - the direction was returned sFailure - the direction could not be determined sInvalidObject - the light was invalid

AlDistanceLocator
Displays the distance between two locators.

436 | Chapter 3 AlDagNode AlLocator

Synopsis
#include <AlDistanceLocator.h> class AlDistanceLocator : public AlLocator AlDistanceLocator(); virtual ~AlDistanceLocator(); virtual AlObject * copyWrapper() const; virtual AlObjectType type() const; statusCode create(const AlPointLocator *, const AlPointLocator *, boolean trueDisplay = TRUE); AlPointLocator * startLocator() const; AlPointLocator * endLocator() const; statusCode trueDisplay(boolean &) const; statusCode setTrueDisplay(boolean); statusCode offset(double &) const; statusCode setOffset(double); statusCode distance(double &, double &, double &) const;

Description
Use this locator to display and find the distance between any two point locators (AlPointLocator). If any of the two point locators on which this locator depends is deleted, this locator is deleted as well. This class contains methods to create the locator, query the distance, and set the display attributes of the locator.

AlDistanceLocator::AlDistanceLocator(void) Description
Constructs an AlDistanceLocator wrapper object.

AlDistanceLocator::~AlDistanceLocator() Description
Deletes an AlDistanceLocator wrapper object.

AlObject *AlDistanceLocator::copyWrapper() const Description

Returns an exact copy of the AlDistanceLocator wrapper.

AlDistanceLocator | 437

AlObjectType AlDistanceLocator::type() const Description

Returns the class identifier kDistanceLocatorType.

statusCode AlDistanceLocator::create(const AlPointLocator *startPointLocator, const AlPointLocator *endPointLocator, boolean trueDisplay) Description
Creates a distance locator to measure the distance between two point locators.

Arguments
< startLocator - the starting point locator < endLocator - the ending point locator < displayType - specifies whether the true value or projection of the true value in the Alias window should be shown. The default is true display.

Return Codes
sSuccess - the distance locator was successfully created sAlreadyCreated - the object has already been created sFailure - the distance locator could not be created sInvalidArgument - either one or both the point locators whose distance is measured are not valid

AlPointLocator *AlDistanceLocator::startLocator() const Description

Returns the starting point locator of this distance locator. If the distance locator is not valid, NULL is returned.

438 | Chapter 3 AlDagNode AlLocator

AlPointLocator *AlDistanceLocator::endLocator() const Description

Returns the ending point locator of this distance locator. If the distance locator is not valid, NULL is returned.

statusCode AlDistanceLocator::trueDisplay(boolean &trueDisplay) const Description

Determines if the distance locator is depicting the true length in the Alias Modeling windows.

Arguments
> trueDisplay - the value is true if the distance locator displays true distance as opposed to projected distance in a modeling window

Return Codes
sSuccess - the display mode was found sInvalidObject - the locator is not valid

statusCode AlDistanceLocator::setTrueDisplay(boolean trueDisplay) Description

Sets the mode to display the distance locator as either true distance or projected distance in the Alias Modeling windows.

Arguments
< trueDisplay - if true, the distance locator displays true distance; if false, projected distance is displayed.

Return Codes
sSuccess - the display mode was found sInvalidObject - the locator is not valid

AlDistanceLocator | 439

statusCode AlDistanceLocator::setOffset(double offset) Description

Sets the offset of the distance locator display.

Arguments
< offset - the offset value

Return Codes
sSuccess - the offset value was set sInvalidObject - the locator is not valid

statusCode AlDistanceLocator::offset(double &offset) const Description

Finds the offset of the distance locator display.

Arguments
> offset - the offset value

Return Codes
sSuccess - the offset value was found sInvalidObject - the locator is not valid

statusCode AlDistanceLocator::distance(double &x, double &y, double &z) const Description

Finds the distance vector of the distance locator from the start locator to the end locator.

Arguments
> x, y, z - the x, y, and z components of the distance vector

440 | Chapter 3 AlDagNode AlLocator

Return Codes
sSuccess - the distance was found sInvalidObject - the locator is not valid

AlEditor
An interface to Alias UI editing boxes.

AlEditor | 441

Synopsis

442 | Chapter 3 AlDagNode AlLocator

#include <AlEditor.h> class AlEditor AlEditor( void ); ~AlEditor( void ); statusCode create( const char *title ); statusCode deleteEditor( void ); statusCode open( void ); statusCode close( void ); statusCode update( void ); statusCode toggle( void ); statusCode enableItem( ComponentId itemId, boolean enable ); boolean isEnabled( ComponentId itemId ); boolean isOpen( void ); statusCode addSeparator( ComponentDescriptor *descriptor ); statusCode addGrouping( ComponentDescriptor *descriptor ); statusCode addString( ComponentDescriptor *descriptor, const char *value, IdStringCallback callback ); statusCode addInt( ComponentDescriptor *descriptor, int &reference, IntComponentData *data, IdCallback callback = NULL ); statusCode addFloat( ComponentDescriptor *descriptor, float &ref erence, FloatComponentData *data, IdCallback callback = NULL ); statusCode add3Floats( ComponentDescriptor *descriptor, float (&reference)[3], IdCallback callback = NULL ); statusCode addCheckBox( ComponentDescriptor *descriptor, int &reference, IdCallback callback = NULL ); statusCode addCheckBoxes( ComponentDescriptor *descriptor, int &reference, ComponentDescriptor *descriptor2, int &reference2, IdCallback callback = NULL ); statusCode addButton( ComponentDescriptor *descriptor, IdCallback callback ); statusCode addRadioGroup( ComponentDescriptor *descriptor, AlEdit orRadioGroupStyle style, ComponentDescriptor *subComponent DescriptorList, IdCallback callback ); statusCode addPulldownMenu( ComponentDescriptor *descriptor, Com ponentDescriptor *subComponentDescriptorList, IdCallback callback ); class ComponentDescriptor ComponentDescriptor( const char *label ); ~ComponentDescriptor( void ); ComponentId id( void ); const char *label( void ); void setLabel( const char *label ); void setId( ComponentId id );

AlEditor | 443

ComponentDescriptor *next( void ); void setNext( ComponentDescriptor *descriptor ); ComponentDescriptorType type( void ); class IntComponentData IntComponentData( int minValue, int maxValue ); ~IntComponentData( void ); int minValue( void ); int maxValue( void ); private: int fMinValue; int fMaxValue; class FloatComponentData FloatComponentData( float minValue, float maxValue ); ~FloatComponentData( void ); float minValue( void ); float maxValue( void );

Description
This class provides an interface to Alias user interface. It allows the building of dynamic editors within a plug-in. Standard operations are supported, such as open, close, toggle, and a basic set of user interface components. A reference variable is used as a parameter in a number of the user interface components. This reference maintains the state of the component and must be in permanent storage. If you allocate this variable on the stack, program errors will occur. In some cases, a user interface component will contain multiple parts. In this situation, a list of component descriptors will be used to describe this object to the class. Descriptors are used to describe the components to be created. A label is set in the descriptor object as input. The AlEditor class will dynamically allocate a component ID and set it in the descriptor. Individual components of an editor cannot be deleted. Instead, the entire editor must be de-allocated all at once.

Description
Constructor for a new AlEditor object.

444 | Chapter 3 AlDagNode AlLocator

AlEditor::AlEditor( void ) Description

Destruct an AlEditor object.

AlEditor::~AlEditor( void ) Description

Create a new editor. First create an editor, then add components to it and then call the open method.

Arguments
< title - title of the editor

Return Codes
sFailure - the method failed sAlreadyCreated - the editor is already created sSuccess - the create worked

statusCode AlEditor::create( const char *title ) Description

De-allocate the storage for the editor once it has been closed. All components will be de-allocated and callbacks will be removed.

Return Codes
sFailure - the method failed sSuccess - the delete worked

statusCode AlEditor::deleteEditor( void ) Description

Open/display the editor window. The editor should already be created and have had components added to it.

AlEditor | 445

Return Codes
sFailure - no components added or the method failed sSuccess - the open worked

statusCode AlEditor::open( void ) Description

Close/remove the editor window. The editor will need to be deleted to properly clean up its storage.

Return Codes
sFailure - the method failed sSuccess - the close worked

statusCode AlEditor::close( void ) Description

Returns TRUE if the editor is open. FALSE is returned otherwise.

boolean AlEditor::isOpen( void ) Description

Force the editor window to update/redraw itself. This call should be made if a reference variable is modified by the plug-in's code.

Return Codes
sFailure - the method failed sSuccess - the update worked

statusCode AlEditor::update( void ) Description

Toggle the editor window. If the window is open, it will be closed. If the window is closed, it will be opened. Toggle can be used to temporarily close the window, if the plug-in will need to re-open it.

446 | Chapter 3 AlDagNode AlLocator

Return Codes
sFailure - the method failed sSuccess - the toggle worked

statusCode AlEditor::toggle( void ) Description

Enables or disables the component that is described by itemId. NOTE This call will always fail on subcomponents of default style radio group buttons.

Arguments
< itemId - unique id associated with a component < enable - TRUE or FALSE

Return Codes
sInvalidArgument - itemId cannot be found sFailure - method failed sSuccess - the item's enable state was changed

statusCode AlEditor::enableItem( ComponentId itemId, boolean enable ) Description

Returns TRUE if the item described by itemId is enabled. FALSE is returned otherwise. NOTE See the documentation in AlEditor::enableItem() for information on how this method can fail.

Arguments
< itemId - unique id associated with a component boolean AlEditor::isEnabled( ComponentId itemId )

AlEditor | 447

Description
Adds a separator to the editor. Separators can be used to provide a logical grouping of components.

Arguments
< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label setting is not required in the descriptor parameter class.

Return Codes
sInvalidArgument - descriptor is NULL or descriptor id is already in use sFailure - method failed sSuccess - the separator was created

statusCode AlEditor::addSeparator( ComponentDescriptor *descriptor ) Description

Adds a grouping to the editor. All components added after this call will be placed under this grouping until another grouping is added.

Arguments
< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class.

Return Codes
sInvalidArgument - descriptor or its label is NULL or descriptor id is already in use sFailure - method failed sSuccess - the grouping was created

448 | Chapter 3 AlDagNode AlLocator

statusCode AlEditor::addGrouping( ComponentDescriptor *descriptor ) Description

Adds a float component to the editor.

Arguments
< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class. < reference - variable that tracks the state of the float. This variable must be in permanent storage for the life of the plug-in. < data - currently used to specify min and max ranges for component < callback - optional function to be called when the float is modified

Return Codes
sInvalidArgument - descriptor or its label is NULL or descriptor id is already in use or data is NULL sFailure - method failed sSuccess - the float was created

statusCode AlEditor::addFloat( ComponentDescriptor *descriptor, float &value, FloatComponentData *data, IdCallback callback ) Description
Adds an string entry component to the editor.

Arguments
< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class. < callback - optional function to be called when the float is modified

AlEditor | 449

Return Codes
sInvalidArgument - descriptor or its label is NULL or descriptor id is already in use sFailure - method failed sSuccess - the float was created

statusCode AlEditor::addString( ComponentDescriptor *descriptor, const char *value, IdStringCallback callback ) Description
Adds an integer component to the editor.

Arguments
< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class. < reference - variable that tracks the state of the integer. This variable must be in permanent storage for the life of the plug-in. < data - currently used to specify min and max ranges for component < callback - optional function to be called when the integer is modified

Return Codes
sInvalidArgument - descriptor or its label is NULL or descriptor id is already in use or data is NULL sFailure - method failed sSuccess - the integer was created

statusCode AlEditor::addInt( ComponentDescriptor *descriptor, int &value, IntComponentData *data, IdCallback callback ) Description
Adds a float triple to the editor.

450 | Chapter 3 AlDagNode AlLocator

Arguments
< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class. < reference - variable that tracks the state of the float triple. This variable must be in permanent storage for the life of the plug-in. < callback - optional function to be called when the float triple is modified

Return Codes
sInvalidArgument - descriptor or its label is NULL or descriptor id is already in use sFailure - method failed sSuccess - the float triple was created

statusCode AlEditor::add3Floats( ComponentDescriptor *descriptor, float (&reference)[3], IdCallback callback ) Description

Adds a check box to the editor.

Arguments
< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class. < reference - variable that tracks the state of the check box. This variable must be in permanent storage for the life of the plug-in. < callback - optional function to be called when the check is pressed

Return Codes
sInvalidArgument - descriptor or its label is NULL or descriptor id is already in use sFailure - method failed sSuccess - the check box was created

AlEditor | 451

statusCode AlEditor::addCheckBox( ComponentDescriptor *descriptor, int &reference, IdCallback callback ) Description

Adds two check boxes to the editor.

Arguments
< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class. < reference - variable that tracks the state of the check box associated with itemId This variable must be in permanent storage for the life of the plug-in. < descriptor2 - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class. < reference2 - variable that tracks the state of the check box associated with itemId2 This variable must be in permanent storage for the life of the plug-in. < callback - optional function to be called when one of the checks is pressed

Return Codes
sInvalidArgument - descriptor or its label is NULL or descriptor2 or its label2 is NULL sFailure - method failed sSuccess - the check boxes were created

statusCode AlEditor::addCheckBoxes( ComponentDescriptor *descriptor, int &reference, ComponentDescriptor *descriptor2, int &reference2, IdCallback callback ) Description
Adds a button to the bottom of the editor. Note that an editor can either have a pull down menu or buttons on the bottom of the editor. Both cannot be created at the same time.

452 | Chapter 3 AlDagNode AlLocator

Arguments
< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class. < callback - function to be called when the button is selected

Return Codes
sInvalidArgument - descriptor or its label is NULL or callback is NULL sFailure - pulldown menu already created or method failed or the editor already has a maximum of 4 buttons sSuccess - the button was created

statusCode AlEditor::addButton( ComponentDescriptor *descriptor, IdCallback callback ) Description

Adds a radio group selector. Radio group selectors allow a user to pick a single item out of a list.

Arguments
< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class. < style - the style of the radio group < subComponentDescriptorList - list of descriptors( currently label and an id that is returned by the class ) that describes the subcomponent < callback - function to be called when the radio group item is selected

Return Codes
sInvalidArgument - descriptor or its label is NULL or subComponentDescriptorList is NULL or callback is NULL sFailure - method failed

AlEditor | 453

sSuccess - the radio group was created

statusCode AlEditor::addRadioGroup( ComponentDescriptor *descriptor, AlEditorRadioGroupStyle style, ComponentDescriptor *subComponentDescriptorList, IdCallback callback ) Description
Adds a pull down menu to the editor. Pull down menus are added at the top of the editor window. Note that an editor can either have a pull down menu or buttons on the bottom of the editor. Both cannot be created at the same time.

Arguments
< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class. < subComponentDescriptorList - list of descriptors( currently label and an id that is returned by the class ) that describes the subcomponent < callback - function to be called when a menu item is selected

Return Codes
sInvalidArgument - descriptor or its label is NULL or subComponentDescriptorList is NULL or callback is NULL sFailure - buttons already created or method failed sSuccess - the pull down menu was created

statusCode AlEditor::addPulldownMenu( ComponentDescriptor *descriptor, ComponentDescriptor *subComponentDescriptorList, IdCallback callback ) Description

Adds a pull down menu to the editor. Pull down menus are added at the top of the editor window. Note that an editor can either have a pull down menu or buttons on the bottom of the editor. Both cannot be created at the same time.

454 | Chapter 3 AlDagNode AlLocator

Arguments
< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class. < subComponentDescriptorList - list of descriptors( currently label and an id that is returned by the class ) that describes the subcomponent < callback - function to be called when a menu item is selected

Return Codes
sInvalidArgument - descriptor or its label is NULL or subComponentDescriptorList is NULL or callback is NULL sFailure - buttons already created or method failed sSuccess - the pull down menu was created

ComponentDescriptor::ComponentDescriptor( const char *label ) Description

Constructs a ComponentDescriptor.

Argument
The name label of the component descriptor.

ComponentDescriptor::~ComponentDescriptor( void ) Description

Destruct a component descriptor.

void ComponentDescriptor::setLabel( const char *label ) Description

Set the label name of the component descriptor.

Argument
< label - label name

AlEditor | 455

void ComponentDescriptor::setId( ComponentId id ) Description

Set the component identifier of the descriptor. Alias is most cases will automatically assign an identifier to the descriptor.

Argument
< id - the component id

ComponentId ComponentDescriptor::id( void ) Description

Returns the current identifier for the component.

const char *ComponentDescriptor::label( void ) Description

Returns the current label name for the descriptor.

ComponentDescriptor *ComponentDescriptor::next( void ) Description

Returns the next component descriptor.

void ComponentDescriptor::setNext( ComponentDescriptor *descriptor ) Description

Add a component descriptor to the end of the descriptor list.

Argument
< descriptor - the new descriptor to add to the list

456 | Chapter 3 AlDagNode AlLocator

ComponentDescriptorType ComponentDescriptor::type( void ) Description

Return the type of the descriptor.

IntComponentData::IntComponentData( int minValue, int maxValue ) Description

Construct a similar Int data class to hold on to minimum and maximum values.

Argument
< minValue - the minimum integer to keep track of < maxValue - the maximum integer to keep track of

IntComponentData::~IntComponentData( void ) Description

Destroy the Int data class

int IntComponentData::minValue( void ) Description

Return the min value.

int IntComponentData::maxValue( void ) Description

Return the max value.

FloatComponentData::FloatComponentData( float minValue, float maxValue ) Description

Construct a simple Float class that tracks minimum and maximum values.

AlEditor | 457

Argument
< minValue - the minimum float value to track < maxValue - the maximum float value to track

FloatComponentData::~FloatComponentData( void ) Description

Destroy the float class object.

float FloatComponentData::minValue( void ) Description

Return the minimum float value.

float FloatComponentData::maxValue( void ) Description

Return the maximum float value.

AlEnvironment
Base object for representing shader environment data.

458 | Chapter 3 AlDagNode AlLocator

Synopsis
#include <AlEnvironment.h> class AlEnvironment : public AlObject, virtual ~AlEnvironment(); virtual AlObjectType type() const; virtual const char* name() const; virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; AlTexture* firstTexture() const; AlTexture* nextTexture( AlTexture* ) const; statusCode nextTextureD( AlTexture* ) const; statusCode parameter( const AlShadingFields, double& ) const; statusCode setParameter( const AlShadingFields, const double ); AlList* fields() const; AlList* mappedFields() const; statusCode addTexture( const char*, const char*, AlTexture** = NULL ); statusCode removeTexture( const char* ); statusCode applyIteratorToTextures( AlIterator *, int& );

Description
This class encapsulates the basic functionality for checking and setting the name of an environment. It also encapsulates accessing the textures that a particular environment refers to, and the animation on the environment. When the wire file is read, the environment contained therein are created as an AlEnvironment class object. This environment object is accessible through the AlUniverse class. An environment object may reference textures. The firstTexture and nextTexture methods are used to access these textures. firstTexture() returns the first texture that the environment object references. nextTexture() moves from a given referenced texture to the next texture in order, as related to the environment object. (See the similar methods for the AlTexture on page 933/AlShader on page 816 classes.) The animation on the environment can be accessed through the firstChannel() and nextChannel() methods. All the channels on the environment can be deleted by calling deleteAnimation(). The environment parameters can be accessed through the parameter() and setParameter() methods. Each shader has a specific set of parameters that are valid for it that depend on its type. The full list of environment parameters

AlEnvironment | 459

can be seen in the file AlAnim.h. For example, all parameters specific to the Blinn shader have names of the form kFLD_SHADING_BLINN_*. Parameters common to all shaders have the form kFLD_SHADING_COMMON_*. All parameters are treated as doubles even though this may not necessarily be what they are. This is done to make the interface as simple and consistent as possible. The user can neither create nor destroy an AlEnvironment class object at this time.

AlEnvironment::~AlEnvironment() Description
Deletes the AlEnvironment wrapper object. It is not possible to delete an environment.

statusCode AlEnvironment::deleteObject() Description

It is not possible to delete the environment shader. This method always returns sFailure.

Return Codes
sFailure - always returned

AlObject *AlEnvironment::copyWrapper() const Description

Creates an exact copy of the AlEnvironment wrapper.

AlObjectType AlEnvironment::type() const Description

Returns the class identifier kEnvironmentType.

460 | Chapter 3 AlDagNode AlLocator

const char* AlEnvironment::name() const Description

Returns the name of the environment shader (it is constant for now).

statusCode AlEnvironment::parameter( const AlShadingFields field, double& result ) const Description

Finds the value of a given environment field.

Arguments
< field - environment field type > result - Returned result of the field

Return Codes
sSuccess - the value of the field was returned sInvalidArgument - the field was not legal for this environment or result was NULL sFailure - the value of the field could not be returned sInvalidObject - the environment was invalid

statusCode AlEnvironment::setParameter( const AlShadingFields field,const double value ) Description

Changes the value of the environment field.

Arguments
< field - environment field type < value - new value that the environment field is to take

Return Codes
sSuccess - the value of the field was changed

AlEnvironment | 461

sInvalidArgument - the field was not legal for this environment sFailure - the value of the field could not be changed sInvalidObject - the environment was invalid

AlTexture* AlEnvironment::firstTexture() const Description

Returns the first texture that this environment object references. If there are none then NULL is returned.

AlTexture* AlEnvironment::nextTexture( AlTexture* last_texture ) const Description

Returns the texture after the given one in the environments texture list. Specifying NULL as parameter will return the first texture.

Arguments
< last_texture - the texture from which to walk forward

statusCode AlEnvironment::nextTextureD( AlTexture* last_texture ) const Description

Destructively points last_texture to the texture after the given one in the shaders texture list.

Arguments
<> last_texture - the texture from which to walk forward

Return Codes
sSuccess - last_texture now points to the next texture sInvalidArgument - last_texture was not valid or was NULL sFailure - there is no next texture sInvalidObject - the environment was invalid

462 | Chapter 3 AlDagNode AlLocator

AlList* AlEnvironment::fields() const Description

Returns an AlList of AlShadingFieldItems, each of which contains an AlShadingFields value valid for this environment. Note that this list is allocated and must be freed using delete AlList*.

AlList* AlEnvironment::mappedFields() const Description

Returns an AlList of AlMappedFieldItems, each of which contains a character string identifier identifying a field on this environment which may be texture mapped. Note that these strings are identical to the SDL identifiers and the complete list can be found in the SDL manual.

statusCode AlEnvironment::removeTexture( const char* fieldName ) Description

Removes a texture from a particular field of the AlEnvironment. The first argument is the name of the field which will have the texture applied to it. Only those fields valid for this shader should be provided; any others will cause this method to fail. Valid fields are any returned by the fields() method.

Arguments
< fieldName - name of the field which will have the texture removed from it

Return Codes
sSuccess - the texture was added successfully sFailure - no texture was present sCannotDelete - a texture already existed on the field which could not be deleted sInvalidArgument - the argument was not valid for the shader sInvalidObject - the shader is invalid

AlEnvironment | 463

statusCode AlEnvironment::addTexture( const char* fieldName, const char* textureName, AlTexture** returnCreatedTexture ) Description
Adds a texture to a particular field of the AlEnvironment. The first argument is the name of the field that will have the texture applied to it. Only those fields valid for this environment should be provided; any others will cause this method to fail. Valid fields are any returned by the fields() method. The second argument is the name of the texture type to apply to the field. The complete list of names is available in the SDL manual.

Arguments
< fieldName - name of the field which will have the texture applied to it < textureName - name of the texture type to apply to the field returnCreatedTexture - if not NULL, then the created texture is returned

Return Codes
sSuccess - the texture was added successfully sFailure - the texture was not added sCannotDelete - a texture already existed on the field which could not be deleted sInvalidArgument - either argument was not valid for the environment sInvalidObject - the environment was invalid

statusCode AlEnvironment::applyIteratorToTextures( AlIterator *iter, int &rc ) Description

Applies the given AlIterator to all textures of this environment. The second argument will be set to the return value of the last application of the iterators function. See the AlIterator on page 544 class for more information.

Arguments
< iter - the iterator to apply to each texture > rc - the return value of the last application of the iterator

464 | Chapter 3 AlDagNode AlLocator

Return Codes
sSuccess - the application of the iterator terminated normally sFailure - the application of the iterator terminated abnormally sInvalidArgument - the iterator was NULL sInvalidObject - the environment was not valid

AlFace
Interface to Alias face curves.

Synopsis
#include <AlFace.h> class AlFace : public AlCurve AlFace(); virtual ~AlFace(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; statusCode create( int, curveFormType, int, const double[], int, const double[][4], const int[] ); virtual AlObjectType type() const; AlFaceNode* faceNode() const; AlFace* prevFace() const; AlFace* nextFace() const; statusCode prevFaceD(); statusCode nextFaceD(); statusCode area( double&, boolean = TRUE, double = 0.001 ); AlShader* firstShader() const; AlShader* nextShader( AlShader* ) const; statusCode nextShaderD( AlShader* ) const; statusCode renderInfo( AlRenderInfo& ) const; statusCode setRenderInfo( const AlRenderInfo& ) const; statusCode normal( double[3] ) const;

Description
An AlFace is derived from AlCurve and inherits AlCurves public methods. AlFace objects are created independently from the AlFaceNode, and then added to the AlFaceNode afterwards. An AlFaceNode requires one valid AlFace

AlFace | 465

object in order for it to be created. Other faces can be added to the list of faces under the AlFaceNode afterwards using AlFaceNode::addFace(). Deleting a face can cause one of two things to happen. If the AlFace is not under an AlFaceNode, or it is one of several faces under an AlFaceNode, then only the face will be deleted. If the AlFace is the only face under the AlFaceNode, then the AlFaceNode will also be deleted. Each face curve must be planar and each face curve must lie in the same plane as all the others. In addition to the parent class (AlCurve) methods this class allows you to walk through the list of the face curves that make up the face. All AlFace objects will have at least one shader attached to them. These can be accessed through the firstShader and nextShader methods.

AlFace::AlFace() Description
Constructs an AlFace wrapper object.

AlFace::~AlFace() Description
Deletes an AlFace wrapper object.

AlObject *AlFace::copyWrapper() const Description

Creates an exact copy of the AlFace wrapper.

AlFaceNode* AlFace::faceNode() const Description

Returns the face node associated with this face.

statusCode AlFace::deleteObject() Description

If this face isnt the last face under the parent face node, then this face is removed from the parent node and deleted. If this face is the last face under

466 | Chapter 3 AlDagNode AlLocator

the parent node, then the face node is deleted as well. If this face doesnt have a parent node, then only the face is deleted.

Return Codes
sSuccess - the face was successfully removed sInvalidObject - the face object was invalid sFailure - the face could not be removed

statusCode AlFace::create( int degree, curveFormType form,int lengthKnotVector, const double knotVector[],int lengthControlP, const double controlPoints[][4],const int multiplicity[] ) Description
Similar to the AlCurve::create() method except that the form can only be either closed or periodic (kClosed or kPeriodic). See the description in AlCurve on page 301 of the AlCurve::create() method for more details.

Arguments
See AlCurve::create().

Return Codes
sSuccess - the face was successfully created sInvalidArgument - one of the arguments was NULL or out of range sFailure - the face could not be created

AlObjectType AlFace::type() const Description

Returns the class identifier kFaceType.

AlFace* AlFace::prevFace() const Description

Returns a pointer to the previous face in the list of faces. Returns NULL for the end of the list.

AlFace | 467

statusCode AlFace::prevFaceD() Description

Destructively points the current wrapper to the previous face in the list of faces.

Return Codes
sSuccess - the wrapper now points to the previous face sFailure - there is no previous face sInvalidObject - the face is invalid

AlFace* AlFace::nextFace() const Description

Returns a pointer to the previous face in the list of faces. Returns NULL for the end of the list.

statusCode AlFace::nextFaceD() Description

Destructively points the current wrapper to the next face in the list of faces.

Return Codes
sSuccess - the wrapper now points to the next face sFailure - there is no next face in the list sInvalidObject - this face is invalid

AlShader* AlFace::firstShader() const Description

Returns the first shader that this face object references. Note that only the first AlFace of an AlFaceNode has valid render information.

468 | Chapter 3 AlDagNode AlLocator

AlShader* AlFace::nextShader( AlShader* last_shader ) const Description

Returns the shader after the given shader in the shader list. Specifying NULL as parameter will return the first shader. Note that only the first AlFace of an AlFaceNode has valid render information.

Arguments
< last_shader - shader from which to walk forward

statusCode AlFace::nextShaderD( AlShader* last_shader ) const Description

Destructively points last_shader to the shader after the given shader in the shader list.

Arguments
< last_shader - shader from which to walk forward

Return Codes
sSuccess - last_shader now points to the next shader sInvalidArgument - last_shader was invalid or NULL sInvalidObject - the current face was invalid sFailure - there was no next shader

statusCode AlFace::renderInfo( AlRenderInfo &render ) const Description

Fills in the renderInfo structure with the render info for this face. If there wasnt any render information, in which case the renderInfo is unchanged. NOTE that ONLY the first AlFace of an AlFaceNode has valid render information.

Arguments
> renderInfo - the structure to fill in

AlFace | 469

Return Codes
sSuccess - getting the render information was successful sFailure - there wasnt any render information sInvalidObject - the face was invalid

statusCode AlFace::setRenderInfo( const AlRenderInfo &render ) const Description

Sets the render info for this face to the contents of the renderInfo structure. NOTE that ONLY the first AlFace of an AlFaceNode has valid render information.

Arguments
< renderInfo - the structure to take the render information from

Return Codes
sSuccess - setting the render information was successful sFailure - setting the render information failed sInvalidObject - the face is invalid sInvalidArgument - one of the parameters in render was invalid

statusCode AlFace::normal( double norm[3] ) const Description

Returns the normal for a curve on a face. The normal for an AlFaceNode is the normal of the first AlFace.

Arguments
> norm - returned normal

Return Codes
sSuccess - getting the normal was successful sInvalidArgument - the parameter norm was NULL

470 | Chapter 3 AlDagNode AlLocator

sFailure - the normal couldnt be determined sInvalidObject - the face was invalid

statusCode AlFace::area( double& area, boolean worldCoordinates, double tolerance ) Description

Determines the area of the face sSuccess will be returned if the evaluation succeeded. sFailure will be returned if the evaluation failed.

Arguments
> area - the returned value < worldCoordinates - the evaluation is to be in world coordinates < tolerance - the error tolerance

Return Codes
sSuccess - the coordinate was successfully determined sFailure - the evaluation failed, or the face was linear or not planar sInvalidObject - the surface is invalid

AlFaceNode
Interface to the DAG node that gives access to faces.

AlFaceNode | 471

Synopsis
#include <AlFaceNode.h> class AlFaceNode : public AlCurveNode AlFaceNode(); virtual ~AlFaceNode(); virtual AlObject* copyWrapper() const; statusCode create( AlFace * ); virtual AlObjectType type() const; AlFace* firstFace() const; AlFace* firstFace(AlTM&) const; statusCode addFace( AlFace* ); statusCode removeFace( AlFace* ); AlSurface* convertToTrimmedSurface( boolean = FALSE )const; statusCode normal( double &, double &, double & ) const;

Description
AlFaceNode is the class used to access faces in the DAG. Faces can be created from scratch or read in from a wire file and accessed via the firstFace() method. A Face is a collection of closed curves that all lie in the same plane. An AlFaceNode points to an AlFace, which points to the next face in the collection and so on... Add faces to the collection with the addFace() method and remove them with the removeFace() method. In order to access the list of faces, you walk through the face list with AlFace methods nextFace() and prevFace(). There are two ways to delete an AlFaceNode. If the AlFaceNode::deleteObject() method is called, then this nodes AlFace objects are all deleted. If this node only has one face and its deleteObject() method is called, then this node is deleted as well.

AlFaceNode::AlFaceNode() Description
Constructs an AlFaceNode wrapper object.

AlFaceNode::~AlFaceNode() Description
Deletes an AlFaceNode wrapper object.

472 | Chapter 3 AlDagNode AlLocator

AlObject* AlFaceNode::copyWrapper() const Description

Returns an exact duplicate of this AlFaceNode wrapper.

statusCode AlFaceNode::create( AlFace *face ) Description

Allocates the DAG node for the AlFaceNode. It adds the given face as the first face of the face node.

Arguments
< face - the first face to belong under the AlFaceNode

Return Codes
sSuccess - the face node was created sInvalidArgument - face was invalid or NULL sAlreadyCreated - the face node was already created elsewhere sInsufficientMemory - out of memory sFailure - the face node could not be created

AlObjectType AlFaceNode::type() const Description

Returns the class identifier kFaceNodeType.

AlFace* AlFaceNode::firstFace() const Description

Returns the first face in the list of faces. Access the remainder of the faces in the list with AlFace methods. This method returns NULL if the list is empty.

AlFaceNode | 473

AlFace* AlFaceNode::firstFace(AlTM& tm) const Description

Returns the first face in the list of faces. Access the remainder of the faces in the list with AlFace methods. This method returns NULL if the list is empty. The AlTM will be updated with the faceNodes TM if a face exists.

Arguments
> tm - the transformation matrix to be updated with the faceNodes TM

statusCode AlFaceNode::addFace( AlFace* face ) Description

Adds a face to the end of the list of faces. The face must not already belong to another AlFaceNode.

Arguments
< face - AlFace to add to list of AlFaceNodes faces

Return Codes
sSuccess - the face was successfully added to the list of faces sInvalidArgument - face was invalid or NULL sInvalidObject - the face node object was invalid sFailure - an error occurred

statusCode AlFaceNode::removeFace( AlFace* alFace ) Description

Removes a face from the list of faces. This must not be the last face under the face node. When the face is removed from under the face node, it is no longer part of the universe that would be stored. Any animation on the CVs of the face will be deleted, and the CVs will be removed from any clusters or sets they are in.

474 | Chapter 3 AlDagNode AlLocator

Arguments
< alFace - the face to remove from the AlFaceNodes list of faces

Return Codes
sSuccess - the face was removed from the list of faces sInvalidArgument - alFace was invalid or NULL sInvalidObject - the face node object was invalid sFailure - an error occurred

AlSurface * AlFaceNode::convertToTrimmedSurface( boolean worldSpace ) const Description

Returns an AlSurface that represents the AlFace geometry converted to a trimmed surface. Returns NULL if the AlFace geometry is invalid for any reason. A trimmed surface will not be created if the AlFace curves are non-planar or intersecting. The AlSurface created does NOT have a parent AlSurfaceNode. The AlSurface will be constructed in object space if worldSpace is FALSE (the default) or in world space if worldSpace is TRUE. As well only the geometry information will be converted. Shader information, and so on, will not be copied over to the new surface.

statusCode AlFaceNode::normal( double &x, double &y, double &z ) const Description
Attempts to calculate the overall normal of all of the face curves in this face. If the faces are not coplanar, then sFailure will be returned. This is an expensive function to execute. Note that this function is implicitly called by convertToTrimmedSurface.

Arguments
> x,y,z, - the returned normal

Return Codes
sInvalidObject - the facenode was invalid

AlFaceNode | 475

sFailure - the faces were not planar sSuccess - the faces were planar and the normal was returned sInsufficientMemory

AlFunction
Class for creating the OpenAlias interface to Alias.

476 | Chapter 3 AlDagNode AlLocator

Synopsis

AlFunction | 477

#include <AlFunction.h> class AlFunction virtual ~AlFunction(); statusCode deleteObject(); virtual AlMomentaryFunction* asMomentaryFunctionPtr(); virtual AlContinuousFunction* asContinuousFunctionPtr(); const char * name(); class AlMomentaryFunction : public AlFunction virtual AlMomentaryFunction* asMomentaryFunctionPtr(); statusCode create( const char *, void (*)( void )); statusCode create( void (*)(void) ); class AlContinuousFunction : public AlFunction virtual AlContinuousFunction* asContinuousFunctionPtr(); statusCode create( void (*)( void ), AlMouseButtonFunction *, AlMouseButtonFunction *, AlMouseButtonFunction *, void (*)( void ), boolean = FALSE ); statusCode create( const char *, void (*)( void ), AlMouseButton Function *, AlMouseButtonFunction *, AlMouseButtonFunction *, void (*)( void ), boolean = FALSE ); statusCode setPreInitFunction( void (*)() ); statusCode setPostCleanupFunction( void (*)() ); statusCode setPrompt( const char *, char *, AlFilterType ); statusCode setPrompt( const char *(*)(), char *, AlFilterType ); statusCode setBehaviour( AlBehaviourType ); statusCode setMouseCoordinateType( AlCoordinateType ); AlBehaviourType behaviour() const; static statusCode createGoButton( void (*)( void ) ); static statusCode createGoButton( int (*pressed)( void ), boolean persistence, const char *button1, const char *button2 = NULL, const char *button3 = NULL, const char *button4 = NULL, const char *button5 = NULL ); static statusCode clearGoButton( boolean ); static const char * goButtonPressed( void ); static statusCode setUndoFunction( AlUndoCallbackType ); static AlUndoCallbackType undoFunction( void ); boolean isActiveContinuousFunction(); static AlCoordinateType keyboardCoordinateMode(); static AlInputType translateInput( int, int & ); static int inputModifierMask(); // see kModifier_xxxx statusCode finished();

478 | Chapter 3 AlDagNode AlLocator

Description
This class provides a means to interface the OpenAlias application to the Alias user interface. The UI interacts with the plug-in through the use of callback functions. The plug-in supplies pointers to functions that are called whenever a menu button is pressed or the mouse moves. There are two classes of UI functions (the set of callbacks associated with a menu button): momentary functions and continuous functions. A true momentary function just executes an operation and then returns to the previous function. Momentary functions are used for one shot type operations. The function does not require any user input, and simply returns after it is done. An example of a momentary function is Transform->Undo. A continuous function is a set of 5 callback functions that correspond to the stages involved in a mouse interaction. They are the init function, the mouse down function, the mouse move function, the mouse up function and the cleanup function. The init function is called when you first switch to the UI function by clicking on the menu item. It does not take any arguments, and is intended for setting up any data required for the operation (for example, reading option box values, making a list of picked items and so on). The cleanup function is called when the user leaves this UI function by selecting another menu item. You will usually clean up the data structures that are set up in the init function. The mouse down function is called when the user depresses the mouse button. The mouse move function is called each time the mouse is moved from its current position. Note that this function will be called immediately after the init function. A mouse session will always contain one call to the down function, one or more calls to the move function followed by a call to the mouse up function. The mouse up function is called when the mouse button is released. The mouse down/move/up functions are passed by three arguments: the event information (a packed value containing information about the mouse buttons, keyboard keys and so on) and the x/y position of the mouse when the event occurred (use AlContinousFunction::translateInput to extract the values). If a keyboard event is read, then use scanf() to process the values read from the command line. Otherwise, the mouse was clicked down on the screen. The button in question can be determined by examining the Modifier masks on the value returned by translateInput.

AlFunction | 479

Hybrid functions: Pseudo-momentary

By definition, a momentary function just does an action and then returns to the previous function. No user input (mouse or keyboard) should be processed in a momentary function. A continuous function does the action, and that function stays current until you select another function. These types of functions can have mouse or keyboard input. There are circumstances which require a momentary style function but we want to also provide mouse or keyboard input. For example set keyframe requires keyboard input, so it should be continuous. However, it can become cumbersome for the user to use. Consider the following sequence of events to set the keyframe while Transform->move is selected. 1 Transform->move is used to move a sphere 2 set keyframe is selected and becomes the current function 3 a value is entered into set keyframe 4 the user must now click on Transform->move again to move the sphere. This is the purpose behind the AlFunction::setBehaviour method. It makes a continuous function behave as a momentary function, but also allows the users to provide us with keyboard or mouse input. After the function has been executed, it switches back to the previous function. Instead of declaring the set keyframe function using ..
AlMomentaryFunction::create( do_set_keyframe );

We would use:
AlContinuousFunction::create( NULL, // init. down_set_keyframe, // reads the keyboard input NULL, up_set_keyframe, NULL // cleanup ); AlContinuousFunction::setPrompt( "Enter frame: %f", frame_buff, kFilterNone );

Then call:
AlContinousFunction::setBehaviour( kBehaviourMomentary );

480 | Chapter 3 AlDagNode AlLocator

Pre-init and post-cleanup callbacks:

There are also settable pre-init and post-cleanup routines. The pre-init is called before the init but it is only called on the initial selection of the function and not when you bounce back to the function after selecting a function (for example, another momentary style function). Note: Due to the original design of the UI, there is no way to pass a user data pointer to the five functions without using globals.

AlFunction::~AlFunction() Description
Deletes a function wrapper object.

AlMomentaryFunction* AlFunction::asMomentaryFunctionPtr() Description

Type casts the given object to a momentary function.

AlContinuousFunction* AlFunction::asContinuousFunctionPtr() Description

Type casts the given object to a continuous function.

const char *AlFunction::name() Description

Returns the name of the function.

statusCode AlFunction::deleteObject() Description

Frees the memory used by the given function.

Return Codes
sSuccess - the function was removed

AlFunction | 481

sFailure - the function could not be removed sObjectInvalid - this function is not valid

AlMomentaryFunction* AlMomentaryFunction::asMomentaryFunctionPtr() Description

Type casts the given object to a momentary function.

statusCode AlMomentaryFunction::create( const char *funcName, void (*action)(void)) Description

Creates a momentary function by creating an association of the given name with the given function. NOTE - to get an icon to load with your function, the name of the icon file must be the same as the function name with a .S or .M appended. If the return code sNameChangedToUniqueOne is returned, then your function name will be altered slightly, to prevent a collision. As a result, it is possible that it does not match your icon filename so the icon may not appear. that is, If you name your function fuzzyNavel, then the icon file should be called fuzzyNavel.S

Arguments
< funcName - the name for the function < action - the action function to attach the name to

Return Codes
sInvalidArgument - name or function was NULL sSuccess - the momentary function was created sFailure - the momentary function could not be created sNameChangedToUniqueOne - the given function name was changed to a unique name. Use name() to find out what.

482 | Chapter 3 AlDagNode AlLocator

statusCode AlMomentaryFunction::create( void (*action)(void) ) Description

Creates a momentary function from the given function. (No icon will be shown by default).

Arguments
< name - the name of the function

Return Codes
sInvalidArgument - name or function was NULL sSuccess - the momentary function was created sFailure - the momentary function could not be created

AlContinuousFunction* AlContinuousFunction::asContinuousFunctionPtr() Description

Type casts the given object to a continuous function.

statusCode AlContinuousFunction::create( void (*init)( void ), AlMouseButtonFunction *down, AlMouseButtonFunction *move, AlMouseButtonFunction *up, void (*cleanup)( void ), boolean manipulatesPickList ) Description
Creates a continuous function. Action functions may be NULL. If this continuous function will modify the pick list, then set the manipulatesPickList parameter to TRUE. This will turn off the triggering of unwanted internal Alias events when the picklist is modified and will make the continuous function safer.

Arguments
< init - the routine to be called when the function is invoked < down - the routine to be called when the mouse button is depressed

AlFunction | 483

< move - the routine to be called when the mouse is moved with the button depressed < up - the routine to be called when the mouse button is released < cleanup - the routine called when the interaction is completed < manipulatesPickList - TRUE or FALSE

Return Codes
sInvalidArgument - one of the parameters was null sFailure - the function could not be created sNameChangedToUniqueOne - success but the name was altered sSuccess - the function was created

statusCode AlContinuousFunction::create( const char *name, void (*init)( void ), AlMouseButtonFunction *down, AlMouseButtonFunction *move, AlMouseButtonFunction *up, void (*cleanup)( void ), boolean manipulatesPickList ) Description
Creates a continuous function. Action functions may be NULL. If this continuous function will modify the pick list, then set the manipulatesPickList parameter to TRUE. This will turn off the triggering of unwanted internal Alias events when the picklist is modified and will make the continuous function safer. See the note in AlMomentaryFunction::create() on naming functions.

Arguments
< name - the name of the function < init - the routine to be called when the function is invoked < down - the routine to be called when the mouse button is depressed < move - the routine to be called when the mouse is moved with the button depressed < up - the routine to be called when the mouse button is released < cleanup - the routine called when the interaction is completed

484 | Chapter 3 AlDagNode AlLocator

< manipulatesPickList - TRUE or FALSE

Return Codes
sInvalidArgument - one of the parameters was null sFailure - the function could not be created sNameChangedToUniqueOne - success but the name was altered sSuccess - function was created

statusCode AlContinuousFunction::setMouseCoordinateType( AlCoordinateType type ) Description

Selects relative or absolute mouse coordinate types.

Arguments
< type - kCoordinateAbsolute or kCoordinateRelative

Return Codes
sInvalidArgument - type was not a valid coordinate type sFailure - coordinate type could not be set sSuccess - coordinate type was set sInvalidObject - the function was not created

statusCode AlContinuousFunction::finished( ) Description

Used in conjunction with the setBehaviour() method to allow a continuous function to act like a momentary function. Calling this function will pop the current function back to which function was set before this function was invoked.

Return Codes
sFailure - function could not be set sSuccess - function was set

AlFunction | 485

statusCode AlContinuousFunction::setBehaviour( AlBehaviourType type ) Description

Selects the continuous behaviour type (either continuous or pseudo momentary). This function makes it possible to have a continuous function act like a momentary function. A call to setBehaviour() would be made setting the type to be kBehaviourMomentary and when the continuous function operation is completed (mouse up or after go pressed), the finished() method would need to be called.

Arguments
< type - kBehaviourContinuous or kBehaviourMomentary

Return Codes
sInvalidArgument - type was not a valid behaviour type sFailure - behaviour type could not be set sSuccess - behaviour type was set sInvalidObject - the function was not created

AlBehaviourType AlContinuousFunction::behaviour() const Description

Returns the functions behaviour types.

statusCode AlContinuousFunction::setPreInitFunction( void (*preInit)() ) Description

Sets the function that is called when this function is selected. It behaves as a pre-init function.

Arguments
< preInit- the function to call when this function is selected

Return Codes
sInvalidArgument - a parameter was NULL

486 | Chapter 3 AlDagNode AlLocator

sSuccess - the set call worked sFailure - the method failed sInvalidObject - the continuous function was invalid

statusCode AlContinuousFunction::setPostCleanupFunction( void (*postCleanup)() ) Description

Sets the function that is called when this function is unselected. It behaves as a post-cleanup function. Post-cleanup functions are not called during momentary function interruptions

Arguments
< postCleanup - the function to call when this function is selected

Return Codes
sInvalidArgument - a parameter was NULL sSuccess - the set call worked sFailure - the method failed sInvalidObject - the continuous function was invalid

statusCode AlContinuousFunction::setPrompt( const char *(*outputStringFunc)(), char *inputBuffer, AlFilterType filter ) Description
Sets the function to create the string that will be placed into the prompt line. It is also used to determine how data is retrieved from the prompt line. The text up to the first % is printed to the prompt line. The remaining text is used to control the input. For example, if the outputStringFunc() returns the string, "Enter the coordinate: %f %f %f", then "Enter the coordinate:" is printed to the prompt line, and three doubles are read in from the user. inputString is a pointer to a character buffer that is filled when the user types information into the prompt line. For example,
char *outputStringFunc() { return "Enter coordinate: %f %f %f"; } char inputBuffer[200]; /* accepts the coordinate */

AlFunction | 487

Arguments
< outputStringFunc - a function which returns the string to be printed on the command line < inputBuffer - buffer to be used for input < filter - the units filter for the input

Return Codes
sInvalidArgument - a parameter is null sInvalidObject - the continuous function is invalid sSuccess - the method worked

statusCode AlContinuousFunction::setPrompt( const char *staticPrompt, char *inputBuffer, AlFilterType filter ) Description
Sets a static prompt instead of a computable prompt.

Arguments
< staticPrompt - the static string to display in the prompt line < inputBuffer - buffer to be used for input < filter - the unit filter for the string

Return Codes
sInvalidArgument - a parameter is null sInvalidObject - the continuous function is invalid sSuccess - the method worked

AlInputType AlContinuousFunction::translateInput( int event, int &button ) Description

Interprets an input event. This method translates the raw event information into API input types. In addition, if the input type was a button then the

488 | Chapter 3 AlDagNode AlLocator

button pressed would be returned via the reference parameter. Keyboard input is handled by using sscanf() on your inputDataBuffer. The input buffer is installed by using the AlContinuousFunction::setPrompt() method.

Arguments
< event - input event(first parameter) of the continuous function callbacks. > button - if the event type is kInputButton, then the button reference is a bitwise OR of the following values:

kModifierButton1 - button 1 was depressed kModifierButton2 - button 2 was depressed kModifierButton3 - button 3 was depressed kModifierButton4 - button 4 was depressed kModifierButton5 - button 5 was depressed
Example code: AlContinuousFunction hFunc; hFunc.setPrompt( my_prompt, inbuf, kFilterNone ); ...... char dataBuffer[200]; promptInfo( "Input offset %f", dataBuffer ); case kInputKey board sscanf( dataBuffer, "%lf", &newOffset ); break;

Return Values
kInputAbort - the abort key was hit kInputKeyboard - keyboard input was detected (see the above source example) kInputButton - input was from a button.

int AlContinuousFunction::inputModifierMask() Description

Examines the current state of the modifier keys and button states. Note that this value is only updated between X events, hence it cannot be polled.

Return Values
A bitwise OR of the following values kModifierButton1 - button 1 was depressed

AlFunction | 489

kModifierButton2 - button 2 was depressed kModifierButton3 - button 3 was depressed kModifierButton4 - button 4 was depressed kModifierButton5 - button 5 was depressed kModifierControl - the Control key was depressed kModifierShift - the Shift key was depressed kModifierAlt - the Alt key was depressed

AlCoordinateType AlContinuousFunction::keyboardCoordinateMode() Description

Returns the coordinate type of the users numerical input (either kCoordinateAbsolute or kCoordinateRelative).

statusCode AlContinuousFunction::createGoButton( void (*pressed)( void )) Description

Creates a Go button for the user to press. The given function is called when the button is pressed.

Arguments
pressed - the callback to call

Return Codes
sInvalidArgument - pressed was NULL sSuccess - a Go button is now displayed statusCode AlContinuousFunction::createGoButton( int (*pressed)( void ), boolean persistence, const char *button1, const char *button2, const char *button3, const char *button4, const char *button5 ) Description:

490 | Chapter 3 AlDagNode AlLocator

Creates a Go button for the user to press. The given function is called when the button is pressed. Arguments: pressed - the callback to call Return codes: sInvalidArgument - pressed was NULL sSuccess - a Go button is now displayed const char *AlContinuousFunction::goButtonPressed( void ) Description Return the label name of the go button that was pressed.

statusCode AlContinuousFunction::clearGoButton( boolean do_redraw ) Description

Clears the Go button if it is displayed.

Arguments
do_redraw - a redraw should be done to update the display

Return Codes
sSuccess - the Go button was cleared

statusCode AlContinuousFunction::setUndoFunction( AlUndoCallbackType funcPtr ) Description

This method sets an undo function for the plug-in and will only work if called when a continuous plug-in is active. With a non-null funcPtr, the Undo menu item will be enabled and funcPtr will be called when the menu it is invoked. Calling this function with a NULL funcPtr will disable the undo menu entry. The plug-in must keep track of its private undo stack in order to determine when the undo entry should be disabled. Note: funcPtr is defined to return an int. This return value is currently unused in Alias.

AlFunction | 491

Arguments
< funcPtr - callback for undo function

Return Codes
sFailure - could not set the undo callback. This could be due to not being in an active continuous plug-in sSuccess - the method succeeded

AlUndoCallbackType AlContinuousFunction::undoFunction( ) Description

Returns the current undo function. This method should be used in conjunction with setUndoFunction() in order to preserve any existing undo function pointers.

boolean AlContinuousFunction::isActiveContinuousFunction() Description

Returns true if this continuous function is currently active. False is returned otherwise.

AlFunctionHandle
Class for creating the OpenAlias interface to Alias

492 | Chapter 3 AlDagNode AlLocator

Synopsis
#include <AlFunctionHandle.h> class AlFunctionHandle AlFunctionHandle(); virtual ~AlFunctionHandle(); statusCode create( const char*, const char* ); statusCode create( const char*, AlFunction * ); AlFunctionHandle& operator =( const AlFunctionHandle& ); int operator !() const; statusCode setAttributeString( const char * ); statusCode setOptionBox( const char *, const char *, const char * = NULL ); statusCode setIconPath( const char* ); statusCode setHelpFile( const char* ); statusCode addToMenu( const char * ); statusCode appendToMenu( const char * ); statusCode installOnSubmenu( const char * ); statusCode removeFromMenu(); statusCode deleteObject(); class AlSubmenu AlSubmenu(); ~AlSubmenu(); statusCode createSubmenu( const char *, const char * ); statusCode removeSubmenu( );

Description
This class provides a means to interface the OpenAlias application to the Alias user interface. An AlFunction class or one of its derivatives (AlMomentaryFunction, AlContinuousFunction) is required by the create method. Note that the string name of an Al*Function could also be specified in the create() method. The class AlSubmenu is used for creating submenus in Alias. Create a new submenu on an existing Alias menu and then use the AlFunctionHandle::installOnSubmenu() method to add a new item. Note: avoid attaching submenu items to submenus created by other plug-ins since your submenu item will disappear when the other plug-in is unloaded.

AlFunctionHandle | 493

AlFunctionHandle::AlFunctionHandle() Description
Constructor for the AlFunctionHandle class.

AlFunctionHandle::~AlFunctionHandle() Description
Destructor for the AlFunctionHandle class.

AlFunctionHandle& AlFunctionHandle::operator =( const AlFunctionHandle& f) Description

Assignment operator for the AlFunctionHandle class.

int AlFunctionHandle::operator !() const Description

Allows you to use statements to check the validity of the handle, such as
if( functionhandle ) ....

statusCode AlFunctionHandle::create( const char * popupLabel, const char * command ) Description

Initializes the function handle given a popupLabel and a momentary function name (command).

Arguments
< popupLabel - the string that will appear on the menu pop-up for this plug-in < command - a character string which is the name of the momentary command. It must be unique.

494 | Chapter 3 AlDagNode AlLocator

Return Codes
sInvalidArgument - name or command was NULL sAlreadyCreated - the handle has already been created sSuccess - the handle was created sFailure - the handle could not be created sObjectInSet - a command with name command already exists

statusCode AlFunctionHandle::create( const char * popupLabel, AlFunction *func ) Description

Initializes the function handle given a name and a momentary function name (command).

Arguments
< popupLabel - the string that will appear on the menu pop-up for this plug-in < func - the set of functions (momentary or continuous)

Return Codes
sInvalidArgument - name or command was NULL sAlreadyCreated - the handle has already been created sSuccess - the handle was created sFailure - the handle could not be created

statusCode AlFunctionHandle::setAttributeString( const char * str ) Description

Sets the string that will appear on the attribute line below the prompt line when the plug-in is selected from the menu.

Arguments
< str - the string to appear in the attribute line

AlFunctionHandle | 495

Return Codes
sInvalidArgument - str was NULL sInvalidObject - the function handle has not been initialized sSuccess - the attribute string was set successfully

statusCode AlFunctionHandle::setOptionBox( const char * schemeFileName, const char * editorName, const char * schemeFileNamePrefix ) Description
Sets the option box for the plug-in. If the plug-in has no option box, then do not call this method. This method will fail if the scheme file described by the name and prefix does not exist. Normally, the schemeFileName is the name of the file which defines the option box.

If the schemeFileNamePrefix parameter is NULL, then the schemeFileName will be loaded relative to the path defined by the environment variable ALIAS_WORKENV. If the schemeFileNamePrefix parameter is not NULL, then it will be added to the start of the schemeFileName.

The string formed by concatenating schemeFileName to schemeFileNamePrefix will be used as the filename that will be loaded, that is, the actual scheme file that is loaded will be equivalent to schemeFileNamePrefix/schemeFileName.

Arguments
< schemeFileName - name of the Scheme file which defined the option box < editorName - the name given to the ui-editor function in the Scheme file < schemeFileNamePrefix - the name of the directory to prefix to schemeFileName

Return Codes
sInvalidObject - function handle is invalid sInvalidArgument - one of the arguments was NULL or the file does not exist sFailure - the function handle is already attached to a menu

496 | Chapter 3 AlDagNode AlLocator

sSuccess - the option box was successfully set for the plug-in

statusCode AlFunctionHandle::addToMenu( const char * menuname ) Description

Adds a plug-in to the bottom of the menu.

Arguments
< menuname - the name of the menu the plug-ins will be added to

Return Codes
sInvalidArgument - menuname was NULL sAlreadyCreated - the function handle is already attached to a menu sObjectNotAMember - the menu name was not valid sFailure - failed to attach the plug-in to the menu

statusCode AlFunctionHandle::appendToMenu( const char * menuname ) Description

Adds a plug-in to the top of the menu.

Arguments
< menuname - the name of the menu the plug-ins will be added to

Return Codes
sInvalidArgument - menuname was NULL sAlreadyCreated - the function handle is already attached to a menu sObjectNotAMember - the menu name was not valid sFailure - failed to attach the plug-in to the menu

AlFunctionHandle | 497

statusCode AlFunctionHandle::installOnMenu( const char * menuname, boolean topOfMenu ) Description

This method installs a plug-in on a menu.

Arguments
< menuname - the name of the menu the plugins will be placed on. < topOfMenu - if TRUE, the plug-in is placed at the top of the menu. If FALSE, the plug-in is placed at the bottom of the menu.

Return Codes
sInvalidArgument - menuname was NULL sAlreadyCreated - The function handle is already attached to a menu. sObjectNotAMember - The menu name was not valid. sFailure - Failed to attach the plugin to the menu. sSuccess - it worked

statusCode AlFunctionHandle::installOnSubmenu( const char *subMenuName ) Description

This method allows the installation of plug-ins on submenus. The submenu may already exist in Alias or could have been created by the plug-in with the AlSubmenu class. NOTE: items are always added to the end of a submenu.

Arguments
< subMenuName - the name of the submenu to attach on

Return Codes
sInvalidArgument - subMenuName was NULL sAlreadyCreated - The function handle is already attached to a menu

498 | Chapter 3 AlDagNode AlLocator

sFailure - Failed to attach the plugin to a submenu sSuccess - it worked

statusCode AlFunctionHandle::removeFromMenu() Description

Removes the function handle from its previously attached menu.

Return Codes
sFailure - the handle is not attached to a menu sSuccess - the handle was removed from the menu

statusCode AlFunctionHandle::setIconPath( const char* path ) Description

Sets the pathname to load the icon files from. Normally icons are loaded from ALIAS_BITMAP_LOCATION. In the specified path, there should be two directories:
small medium

In the small/ directory, there should be an icon file ending in the function name followed by .S In the medium/ directory, there should be an icon file ending in the function name followed by .M For example, if the function name is MySphere and the icon path is /usr/myicons, then the following files should exist:
/usr/myicons/small/MySphere.S /usr/myicons/medium/MySphere.M

Return Codes
sFailure - the path could not be set sSuccess - the path was set for this function handle

statusCode AlFunctionHandle::setHelpFile( const char* file ) Description

Sets the filename to load the help file from.

AlFunctionHandle | 499

Return Codes
sFailure - the file could not be set sSuccess - the file was set for this function handle

statusCode AlFunctionHandle::deleteObject() Description

Removes the function handle from the menu and invalidates it.

Return Codes
sFailure - the handle could not be removed from the menu sSuccess - the handle was successfully removed

AlSubmenu::AlSubmenu() Description
Constructor for the AlSubmenu class.

AlSubmenu::~AlSubmenu() Description
Destructor for the AlSubmenu class.

statusCode AlSubmenu::createSubmenu( const char *menuname, const char *submenuname ) Description

This method creates a submenu on an existing menu.

Arguments
< menuname - the name of the menu the submenu will be added to < submenuname - the name of the submenu to create

500 | Chapter 3 AlDagNode AlLocator

Return Codes
sInvalidArgument - NULL parameter sAlreadyCreated - the submenu has already been created sSuccess - the submenu was created sFailure - the creation of the submenu failed

statusCode AlSubmenu::removeSubmenu( ) Description

Removes plug-in created submenus.

Return Codes
sInvalidObject - the submenu has not been created sSuccess - the remove worked sFailure - the remove failed

AlGroupNode
A DAG node that can contain a list of DAG nodes.

AlGroupNode | 501

Synopsis
#include <AlGroupNode.h> class AlGroupNode : public AlDagNode AlGroupNode(); virtual ~AlGroupNode(); virtual AlObject* copyWrapper() const; statusCode create(); virtual AlObjectType type() const; AlDagNode* childNode() const; AlDagNode* childNode(AlTM&) const; AlGroupNode* nextInstance() const; AlGroupNode* prevInstance() const; statusCode nextInstanceD(); statusCode prevInstanceD(); boolean isInstanceable(); boolean isInstanceNode(); boolean isAncestorAnInstance(); statusCode addChildNode( AlDagNode* ); statusCode applyIteratorToChildren( AlIterator*, int& );

Description
This class encapsulates the functionality for creating, manipulating and deleting a group node. A group node is a DAG node that refers to a list of child DAG nodes. It is this type of DAG node that allows the hierarchical grouping of DAG nodes. The transformations that can be defined for a group node are inherited by each child DAG node. This means that a group nodes transformations are combined with a child nodes transformations to define a global transformation for the object that the child node refers to. A group nodes list of child DAG nodes can be shared by more than one group node. If a group nodes list of child nodes is shared by another group node, both group nodes are considered "instanced". This can be achieved by using the AlDagNode::copyObject() method to create an instanced group node from another group node. The instanced group node is created as a sibling of the group node. There are methods for finding the next and previous instanced group node among its siblings and for determining whether a group node is an instanced node. To create a group node, the user must call the constructor and then the create method for an AlGroupNode object. If a group node is not an instanced group node, deleting it will cause the deletion of all the child DAG nodes and the

502 | Chapter 3 AlDagNode AlLocator

deletion of any objects the child DAG nodes refer to. Deleting an instanced group node will not cause all of its child nodes to be deleted since the list of child nodes is shared by another instanced group node.

Note on AlGroupNode::deleteObject()
If a group node is an instanced group node, then only the group node is removed from its list of siblings and is deleted. The list of child DAG nodes an instanced DAG node refers to is not deleted. If this group node is not an instanced group node (that is, none of its siblings share its list of child DAG nodes), then the group node is removed from the list of siblings it belongs to and the group node and every child node of the group node is deleted.

AlGroupNode::AlGroupNode() Description
Constructs an AlGroupNode wrapper object. Use the create() method to initialize an AlGroupNode. Use the create() method to allocate a Dag_node data structure

AlGroupNode::~AlGroupNode() Description
Destructor for AlGroupNode wrapper object.

AlObject* AlGroupNode::copyWrapper() const Description

Returns an exact duplicate of this AlGroupNode wrapper.

statusCode AlGroupNode::create() Description

Creates a new group node with no children.

Return Codes
sSuccess - group node was successfully created sFailure - group node could not be created

AlGroupNode | 503

AlObjectType AlGroupNode::type() const Description

Returns the class identifier kGroupNodeType.

boolean AlGroupNode::isInstanceable() Description

Returns FALSE if this group node contains a non-instanceable DAG node. Otherwise it returns TRUE.

boolean AlGroupNode::isInstanceNode() Description

Returns TRUE if this object shares its list of children with another sibling AlGroupNode.

boolean AlGroupNode::isAncestorAnInstance() Description

Returns TRUE if this group node or one of its ancestors is an instance group node.

AlDagNode* AlGroupNode::childNode() const Description

Returns a pointer to the first AlDagNode of its list of child AlDagNodes. Returns NULL if the list of children is empty.

AlDagNode* AlGroupNode::childNode(AlTM& tm) const Description

Returns a pointer to the first AlDagNode of its list of child AlDagNodes. Returns NULL if the list of children is empty. The AlTM will be updated with the groupNodes TM if a childNode exists.

504 | Chapter 3 AlDagNode AlLocator

Arguments
> tm - the transformation matrix to be updated with the groupNodes TM

AlGroupNode* AlGroupNode::nextInstance() const Description

Returns a pointer to the objects next sibling node in the list that is an instanced group node. Returns NULL if there is no next instanced sibling.

AlGroupNode* AlGroupNode::prevInstance() const Description

Returns a pointer to the objects previous sibling node in the list that is an instanced group node. Returns NULL if there is no previous instanced sibling.

statusCode AlGroupNode::nextInstanceD() Description

Destructively points this wrapper to the objects next sibling node in the list that is an instanced group node.

Return Codes
sSuccess - wrapper now points to the next sibling sFailure - there is no next instanced sibling sInvalidObject - the groupnode was invalid

statusCode AlGroupNode::prevInstanceD() Description

Destructively points this wrapper to the objects previous sibling node in the list that is an instanced group node.

Return Codes
sSuccess - wrapper now points to the previous sibling sFailure - there is no previous instanced sibling

AlGroupNode | 505

sInvalidObject - the groupnode was invalid

statusCode AlGroupNode::addChildNode( AlDagNode *child ) Description

Adds an AlDagNode to the end of the list of child AlDagNodes. If the AlDagNode is already a child of this object, then nothing is done. Otherwise, the AlDagNode is removed from the list of siblings it belongs to and added to the end of this objects list of children. If the AlDagNode is an AlGroupNode and it has siblings that are instanced AlGroupNodes, those instanced siblings are also made children of this object. It is illegal for the AlDagNode argument to be NULL or for it to not have had its create() method called.

Arguments
< child - the AlDagNode to be made a child of this object

Return Codes
sSuccess - the argument is now a child of this object sInvalidArgument - child was not valid sFailure - the AlDagNode could not be made a child of this object sInvalidObject - the groupnode was invalid

statusCode AlGroupNode::applyIteratorToChildren( AlIterator* iter, int& rc ) Description

Applies the passed-in AlIterator to each of the children of this object.

Arguments
< iter - the iterator to apply to each child > rc - the result of the last application of the iterator

Return Codes
sSuccess - the iterator was successfully applied sInvalidObject - the groupnode was invalid

506 | Chapter 3 AlDagNode AlLocator

AlIKHandle
Interface to Inverse Kinematics Handles.

AlGroupNode | 507

Synopsis

508 | Chapter 3 AlDagNode AlLocator

#include <AlIKHandle.h> class AlIKHandle : public AlObject , public AlAnimatable AlIKHandle( void ); virtual ~AlIKHandle(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; statusCode createSingle( AlJoint*, AlJoint* ); statusCode createMulti( AlJoint*, AlJoint*, AlIKHandleGoalType ); statusCode createSpline (AlJoint*, AlJoint*, AlCurveNode*, AlIKHandle*); statusCode createSpline (AlJoint*, AlJoint*, AlCurveNode*); boolean on( void ) const; AlIKHandleSolverType solverType( void ) const; AlIKHandleGoalType goalType( void ) const; double weight( void ) const; AlIKHandleRotationOrder rotationOrder( void ) const; boolean worldOrientation( void ) const; statusCode restRotation( double[3] ) const; AlJoint* root( void ) const; AlJoint* endEffector( void ) const; AlDagNode* rootNode( void ) const; AlDagNode* endEffectorNode( void ) const; AlIKHandlePositionType positionType( void ) const; AlIKHandleTwistType twistType( void ) const; AlCurveNode* curveNode( void ) const; boolean oneJointHandle( void ) const; boolean touchRootHandle( void ) const; AlIKHandlePositionType splineChainPosition( double* ) const; AlIKHandleTwistType splineChainTwist( double* ) const; double splineChainRoll( void ) const; statusCode setOn( boolean ); statusCode setGoalType( AlIKHandleGoalType ); statusCode setWeight( double ); statusCode setRotationOrder( AlIKHandleRotationOrder ); statusCode setWorldOrientation( boolean ); statusCode setRestRotation( const double[3] ); statusCode assumeRestRotation( void ); statusCode setPositionType( AlIKHandlePositionType ); statusCode setTwistType ( AlIKHandleTwistType ); AlIKHandleNode* handleNode( void ) const;

AlGroupNode | 509

Description
A skeleton is a collection of joint DAG nodes that have no particularly special behavior until IK handles are applied to them. In order to use inverse kinematics in Alias, you must create IK handles that define paths along skeletons to be constrained by IK. An IK handle is defined by two joints. The end effector is the point on the skeleton that is free to move, and the root is the anchor point on the skeleton. When the end effector is moved, the rotations on all joints leading up to the root are constrained to provide an IK solution. The IK handle also specifies the solver that will be used. There are two kinds of IK solvers in Alias:

The single-chain solver is analytic and always produces a unique solution. Single-chain handles are never allowed to overlap other IK handles, except when the root of one handle meets the end effector of another. Single-chain IK handles are always position handles - the rotations of the joints above the end-effector, and below or at the root, are transformed to meet the position of the end-effector. The multi-chain solver is iterative, and the solution depends on the starting state. Multi-chain handles are allowed to interfere with one another, the result being a best-possible IK solution. Multi-solver IK handles can be position or orientation goals or both. An orientation goal will try to match the orientation of the bone immediately above the end-effector to the orientation of the IK handle. Multi-solver IK handles also have weights. When several multi-solver IK handles overlap, the weights on these handles are used to determine the relative effect each solution has on the overall rotation of the joints in the affected skeleton.

AlIKHandle::AlIKHandle() Description
Constructs an AlIKHandle wrapper object.

AlIKHandle::~AlIKHandle() Description
Deletes an AlIKHandle wrapper object.

510 | Chapter 3 AlDagNode AlLocator

AlObject *AlIKHandle::copyWrapper() const Description

An object wrapper duplicator for AlIKHandle.

AlObjectType AlIKHandle::type() const Description

Returns the class identifier kIKHandleType;

statusCode AlIKHandle::deleteObject( void ) Description

Deletes the actual handle corresponding to this AlIKHandle.

statusCode AlIKHandle::createSingle( AlJoint* root, AlJoint* end ) Description

Builds a new single-chain IK handle when given the root and end effector joints. Single-chain IK handles are always position handles. Note: The chain from the root to the end should be on its rest pose before the single chain IK handle is created.

Arguments
< root - the root joint of the handle < end - the end effector joint of the handle

Return Codes
sSuccess - successful completion sInvalidArgument - either the root or the end was not valid sFailure - the request could not be completed

AlGroupNode | 511

statusCode AlIKHandle::createMulti(AlJoint* root, AlJoint* end, AlIKHandleGoalType goal ) Description

Builds a new multi-IK handle, given the root and end effector nodes and the goal type of the handle. Returns statusCode, indicating whether the IK handle was successfully constructed.

Arguments
< root - the root joint of the handle < end - the end effector joint of the handle < tp - the solver type for the handle: kSingleChain or kMultiSolver < goal - specifies the kind of goal to give this handle: kPositionGoal, kOrientationGoal, or kBothGoal (position and orientation)

Return Codes
sSuccess - successful completion sInvalidArgument - one of root or end was not valid sFailure - the request could not be completed

statusCode AlIKHandle::createSpline(AlJoint* root, AlJoint* end, AlCurveNode* curve, AlIKHandle*& rHandle) Description
Builds a pair of new spline IK handles: master spline handle and its root spline handle. You must specify the root, end joints and the curve to be matched with. The rHandle must be a NULL AlIKHandle pointer which is to be set with an associated one-joint spline handle for 'this' handle. A root spline handle EQUALS a one-joint handle. It can only be created when a master spline handle is created. (That is, it cannot be created separately.) A one-joint spline handle can be set to different position types with AlIKHandlePositionType. A master spline handle can be set to different twist types with AlIKHandleTwistType.

512 | Chapter 3 AlDagNode AlLocator

This function creates spline handles in default position type (kParameter) and twist type (kTwist_Linear). They can be changed later by setPositionType() and setTwistType().

Arguments
<root - the root joint of the handle <end - the end joint of the handle <curve - the target of the handle <rHandle - a reference for an empty AlIKHandle pointer

When return code is sSuccess:

>rHandle - may or may not be set. If set, the rHandle is a pointer to a created root spline handle.

Return Codes
sSuccess - successful completion sInvalidArgument - one of root or end was not valid sFailure - the request could not be completed

statusCode AlIKHandle::createSpline( AlJoint* root, AlJoint* end, AlCurveNode* curve) Description

Builds a master spline handle without root spline handle. Requires the root and end joints, also the curve to be matched with. This function creates a spline handle in default position type (kParameter) and twist type (kTwist_Linear). They can be changed later by setPositionType() and setTwistType().

Arguments
< root - the root joint of the handle < end - the end joint of the handle < curve - the target of the handle

AlGroupNode | 513

Return Codes
sSuccess - successful completion sInvalidArgument - one of root or end was not valid sFailure - the request could not be completed

boolean AlIKHandle::on( void ) const Description

Returns whether or not this IK handle is currently enabled.

AlIKHandleSolverType AlIKHandle::solverType( void ) const Description

Returns the IK algorithm being used on this handle, multi-solver or single chain. If the object is not valid, single chain is returned.

AlIKHandleGoalType AlIKHandle::goalType( void ) const Description

Returns the goal type of this AlIKHandle: kPositionGoal, kOrientationGoal, or kBothGoal.

double AlIKHandle::weight( void ) const Description

Returns the weight on this IK handle. If the AlIKHandle is invalid, or not a multi-handle, -1 is returned.

AlIKHandleRotationOrder AlIKHandle::rotationOrder( void ) const Description

Returns the rotation order applied to this IK handle. This method only applies to single-chain IK handles.

514 | Chapter 3 AlDagNode AlLocator

boolean AlIKHandle::worldOrientation( void ) const Description

Returns true if this single-chain IK handle controls its rotate_plane in world space. Returns false if this IK handle is not a single-chain handle or controls its rotate plane in local space.

statusCode AlIKHandle::restRotation( double restRot[3] ) const Description

Returns the rest rotation of the single-chain IK handle.

Arguments
> restRot - rest rotation of the single-chain IK handle.

Return Codes
sSuccess - the rest rotation was found sInvalidArgument - the rest rotation is null sInvalidObject - invalid IK handle

AlJoint* AlIKHandle::root( void ) const Description

Gets the root AlJoint in the chain referenced by this IK handle.

AlJoint* AlIKHandle::endEffector( void ) const Description

Gets the end effector AlJoint in the chain referenced by this IK handle.

AlDagNode* AlIKHandle::rootNode( void ) const Description

Gets the AlDagNode corresponding to the root AlJoint in the chain referenced by this IK handle.

AlGroupNode | 515

AlDagNode* AlIKHandle::endEffectorNode( void ) const Description

Gets the AlDagNode corresponding to the end effector AlJoint in the chain referenced by this IK handle.

AlIKHandlePositionType AlIKHandle::positionType( void ) const Description

Returns the position type of this AlIKHandle. This method only applies to spline handles.

AlIKHandleTwistType AlIKHandle::twistType( void ) const Description

Returns the twist type of this AlIKHandle. This method only applies to spline handles.

AlCurveNode* AlIKHandle::curveNode( void ) const Description

Gets the curve node (AlCurveNode) defined by this spline handle. This function only applies to spline handles.

boolean AlIKHandle::oneJointHandle( void ) const Description

Returns true if this IK handle is a spline handle and is one joint handle.

boolean AlIKHandle::touchRootHandle( void ) const Description

Returns true if this handle is a spline handle and directly under a one-joint spline handle.

516 | Chapter 3 AlDagNode AlLocator

AlIKHandlePositionType AlIKHandle::splineChainPosition(double* pos) const Description

Returns the spline chain position in curve space.

AlIKHandleTwistType AlIKHandle::splineChainTwist(double *twist) const Description

Returns the spline handle twist angle and type.

double AlIKHandle::splineChainRoll() const Description

Returns the roll angle of a spline handle.

statusCode AlIKHandle::setOn( boolean f ) Description

Sets the IK handle on.

statusCode AlIKHandle::setGoalType( AlIKHandleGoalType tp ) Description

Sets the goal type of this IK handle to kPositionGoal, kOrientationGoal or kBothGoal. This method can only be used on multi-handles.

statusCode AlIKHandle::setWeight( double d ) Description

Sets the weight of this AlIKHandle to the passed-in value. Note that this can only be done for AlIKHandles that have a solver type of kMultiSolver.

AlGroupNode | 517

statusCode AlIKHandle::setRotationOrder( AlIKHandleRotationOrder ro ) Description

Sets the rotation order of this IK handle to the passed-in value. This method only applies to single-chain IK handles.

statusCode AlIKHandle::setWorldOrientation( boolean set ) Description

If set to true, sets this single-chain IK handle to control its rotate-plane in world space. Otherwise, the rotate-plane is controlled in local space. This method only applies to single-chain IK handles.

statusCode AlIKHandle::setRestRotation( const double restRot[3] ) Description

Sets a new rest rotation for the single-chain IK handle.

Arguments
< restRot - rest rotation for this single-chain IK handle.

Return Codes
sSuccess - the rest rotation was set sInvalidArgument - the value of the rest rotation was null sInvalidObject - the single-chain IK handle is not valid

statusCode AlIKHandle::assumeRestRotation( void ) Description

Returns the single-chain IK handle to its rest pose.

Return Codes
sSuccess - the handle was returned to its rest pose sInvalidObject - the single-chain IK handle is not valid

518 | Chapter 3 AlDagNode AlLocator

statusCode AlIKHandle::setPositionType( AlIKHandlePositionType type ) Description

Sets this spline handles position type. This method only applies to root spline handles (one-joint handles).

statusCode AlIKHandle::setTwistType( AlIKHandleTwistType type ) Description

Sets this spline handles twist type. This method only applies to master spline handles.

AlIKHandleNode* AlIKHandle::handleNode( void ) const Description

Returns the IK handle node associated with this IK handle. Returns NULL if there is no attached IK handle node.

AlIKHandleNode
Interface to DAG nodes of IK handles.

Synopsis
#include <AlIKHandleNode.h> class AlIKHandleNode : public AlDagNode virtual ~AlIKHandleNode(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; AlIKHandle* IKHandle() const; AlIKHandle* IKHandle(AlTM&) const;

Description
All IK handles (AlIKHandle) have associated DAG nodes (AlDagNode) that define their position and orientation. The AlIKHandleNode class provides an interface to the DAG node above an IK handle.

AlIKHandleNode | 519

The position of this DAG node defines the goal position for solving inverse kinematics. The rotation of the AlDagNode has a special function depending on the solver type of the IK handle below.

For single-chain: the three rotational axes get mapped to a single plane rotation and two pole rotations, depending on the rotation order defined for this IK handle. In particular, the first axis in the handle's rotation order controls the rotation of the plane passing through the root and end-effector nodes. This axis is used to orient the single-chain solution. The second and third axes in the rotation order reorient the up vector of the IK handle. The IK handle up vector defines the axis around which the single-chain IK solution will flip when the end-effector crosses over the line passing through the root and the end-effector. The IK handle rotation order can be accessed through the AlIKHandle class. For multi-solver: if the IK handle has an orientation goal, rotating the IK handle controls the orientation of the bone directly above the end-effector. A solution will be found such that the local axes of the end-effector joint attempt to match the local axes of the IK handle.

AlIKHandleNode::~AlIKHandleNode() Description
Deletes an AlIKHandleNode wrapper object.

AlObject* AlIKHandleNode::copyWrapper() const Description

Returns an exact duplicate of this AlIKHandleNode wrapper.

AlObjectType AlIKHandleNode::type() const Description

Returns the class identifier kIKHandleNodeType.

520 | Chapter 3 AlDagNode AlLocator

AlIKHandle* AlIKHandleNode::IKHandle() const Description

Returns a pointer to the IKHandle data structure which can be used to access the geometry of the IKHandle.

AlIKHandle* AlIKHandleNode::IKHandle(AlTM& tm) const Description

Returns a pointer to the IKHandle data structure which can be used to access the geometry of the IKHandle. The AlTM will be updated with the handle nodes TM.

AlImagePlane
Interface to Alias image planes.

AlImagePlane | 521

Synopsis

522 | Chapter 3 AlDagNode AlLocator

#include <AlImagePlane.h> class AlImagePlane : public AlObject , public AlAnimatable , public AlPickable enum AlDisplayMode { kDisplayOff, kDisplayUnknown, kRGB, kColourMap, kOutline, kFilled }; enum AlFrameType { kFrameOff, kRegular, kKeyframe }; union AlFrameTypeParams { struct { int start; int end; int by; int offset; } regular; struct { int frame; double offset; } keyframe; }; enum AlDepthType { kDepthOff, kDepthUnknown, kPriority }; enum AlMaskType { kMaskOff, kMaskUnknown, kImage, kFile, kChromaKey }; union AlMaskTypeParams { struct { const char *name;

AlImagePlane | 523

AlFrameType frameType; AlFrameTypeParams *params; } file; struct { double r; double g; double b; double hue_range; double sat_range; double val_range; double threshold; } chroma_key; }; enum AlImageSpaceType { kScreen, kFields, k01, kWorld }; union AlImageSpaceTypeParams { struct { int size; } fields; struct { int origin_x; int origin_y; int size_x; int size_y; } screen; struct { double tran_x; double tran_y; double size_x; double size_y; } zero_one; struct { double tran_x; double tran_y; double size_x; double size_y; double pivot_x; double pivot_y; } world;

524 | Chapter 3 AlDagNode AlLocator

}; struct AlImageSpaceParams { boolean wrap_horiz; boolean wrap_vert; int offset_x; int offset_y; int coverage_x; int coverage_y; }; AlImagePlane(); virtual ~AlImagePlane(); virtual AlObject* copyWrapper() const; virtual statusCode deleteObject(); virtual AlObjectType type() const; virtual const char* name() const; virtual statusCode setName( const char * ); AlImagePlane* next() const; AlImagePlane* nextInCamera() const; AlImagePlane* prev() const; AlImagePlane* prevInCamera() const; statusCode nextD(); statusCode nextInCameraD(); statusCode prevD(); statusCode prevInCameraD(); const char* imageFile(); statusCode setImageFile( const char * ); statusCode displayMode( AlDisplayMode & ); statusCode setDisplayMode( AlDisplayMode ); statusCode RGBMult( double&, double&, double&, double& ); statusCode setRGBMult( double, double, double, double ); statusCode RGBOffset( double&, double&, double&, double& ); statusCode setRGBOffset( double, double, double, double ); statusCode frameType( AlFrameType&, AlFrameTypeParams* = NULL ); statusCode setFrameType( AlFrameType, AlFrameTypeParams* = NULL ); statusCode imageSize( int&, int& ); statusCode imageData( void*& ); // The next four functions are not fully supported. statusCode maskType( AlMaskType&, AlMaskTypeParams* = NULL ); statusCode setMaskType( AlMaskType, AlMaskTypeParams* = NULL ); statusCode maskInvert( boolean& ); statusCode setMaskInvert( boolean ); statusCode depthType( AlDepthType&, double* = NULL );

AlImagePlane | 525

statusCode setDepthType( AlDepthType, double* = NULL ); // The next two functions are not fully supported. statusCode imageSpace( AlImageSpaceType, AlImageSpaceTypeParams* = NULL, AlImageSpaceParams* = NULL ); statusCode setImageSpace( AlImageSpaceType, AlImageSpaceTypeParams* = NULL, AlImageSpaceParams* = NULL ); // use kScreen X/Y origin to set the position of the image // in pixels. Use these to set the pivot (in pixels) statusCode pivot( double&, double & ); statusCode setPivot( double, double );

Description
Image planes are full colour images that are attached to a camera. If the view from that camera is rendered, they get rendered into the background of the resulting image. This class deals with setting the various parameters of image planes and their associations to cameras. To create an image plane, you must use the addImagePlane function of AlCamera. That function will return to you a new AlImagePlane object that you can use to set the image planes parameters. Given a pointer to an AlImagePlane, you can delete it from Alias using the deleteObject method. To walk the list of all the image planes in Alias, use AlUniverse::firstImagePlane. You can move from image plane to image plane in the current stage or in a camera, by using the appropriate next method. For more information about image planes in general, see the online documentation for the camera editor.

AlImagePlane::AlImagePlane() Description
Constructs an AlImagePlane wrapper object.

AlImagePlane::~AlImagePlane() Description
Deletes an AlImagePlane wrapper object.

526 | Chapter 3 AlDagNode AlLocator

AlObject* AlImagePlane::copyWrapper() const Description

Makes a copy of the AlImagePlane. The returned AlCamera will reference the same data as the original.

AlObjectType AlImagePlane::type() const Description

Returns the class identifier kImagePlaneType.

statusCode AlImagePlane::deleteObject() Description

Deletes the image object.

AlImagePlane* AlImagePlane::next() const Description

Returns the next image plane in the universe.

AlImagePlane* AlImagePlane::nextInCamera() const Description

Returns the next ImagePlane in the who universe, no for the given camera. The best way to walk the ImagePlanes for a camera is AlCamera::applyIteratorToImagePlanes.

AlImagePlane* AlImagePlane::prev() const Description

Returns the previous ImagePlane in the who universe.

AlImagePlane | 527

AlImagePlane* AlImagePlane::prevInCamera() const Description

Returns the previous ImagePlane in the universe for the given camera. The best way to walk the ImagePlanes for a camera is AlCamera::applyIteratorToImagePlanes.

statusCode AlImagePlane::nextD() Description

Returns the next ImagePlane in the universe by pointing the current wrapper to the next image plane object.

Return Codes
sSuccess - the wrapper now points to the next object sFailure - there is no next imageplane sInvalidObject - the image plane was invalid

statusCode AlImagePlane::nextInCameraD() Description

Returns the next ImagePlane in the universe that is associated with the same camera. The current wrapper will now point to the next image plane object in the list.

Return Codes
sSuccess - the wrapper now points to the next object sFailure - there is no next imageplane sInvalidObject - the image plane was invalid

statusCode AlImagePlane::prevD() Description

Returns the previous ImagePlane in the universe by pointing the current wrapper to the previous image plane object.

528 | Chapter 3 AlDagNode AlLocator

Return Codes
sSuccess - the wrapper now points to the previous object sFailure - there is no previous imageplane before the current one sInvalidObject - the image plane was invalid

statusCode AlImagePlane::prevInCameraD() Description

Returns the previous ImagePlane in the universe that is associated with the same camera. The current wrapper will now point to the previous image plane object in the list.

Return Codes
sSuccess - the wrapper now points to the previous object sFailure - there is no next imageplane sInvalidObject - the image plane was invalid

const char* AlImagePlane::name() const Description

Returns the name of the image plane.

statusCode AlImagePlane::setName( const char * newName ) Description

Sets the name of the image plane.

Arguments
< newName - the new name for the image plane

Return Codes
sSuccess - the name was set sFailure - the name could not be changed

AlImagePlane | 529

const char* AlImagePlane::imageFile() Description

Returns the filename of the image plane.

statusCode AlImagePlane::setImageFile( const char * name ) Description

Sets the filename of the image plane.

Arguments
< newName - the new filename for the image plane

Return Codes
sSuccess - the name was set sFailure - the name could not be changed

statusCode AlImagePlane::displayMode( AlDisplayMode & dm ) Description

Returns the display mode of the image plane.

Arguments
> dm - the variable to place the result in

Return Codes
sSuccess - the display mode was returned sInvalidObject - the image plane was invalid

statusCode AlImagePlane::setDisplayMode( AlDisplayMode dm ) Description

Sets the display mode of the image plane. The available display modes are kDisplayOff, kRGB, kColourMap, kOutline, kFilled

530 | Chapter 3 AlDagNode AlLocator

Arguments
< dm - the new display mode

Return Codes
sSuccess - the display mode was set sInvalidArgument - an unknown display mode was specified sInvalidObject - the image plane was invalid

statusCode AlImagePlane::RGBMult( double& r, double& g, double& b, double& a ) Description

Returns the RGBA multipliers of the image plane. Values of 1,1,1,1 will produce no change. 0,0,0,0 will result in a black image.

Arguments
> r,g,b,a - the returned red, green, blue and alpha values

Return Codes
sSuccess - the multipliers were retrieved sInvalidObject - the image plane was invalid sFailure - the rgba values could not be read

statusCode AlImagePlane::setRGBMult( double r, double g, double b, double a) Description

Sets the RGB multiplier of the image plane.

Arguments
< r,g,b,a - the new red, green, blue and alpha values

AlImagePlane | 531

Return Codes
sSuccess - the multipliers were set sInvalidObject - the image plane was invalid sFailure - the rgba values could not be set

statusCode AlImagePlane::RGBOffset( double& r, double& g, double& b, double& a ) Description

Returns the RGBA offsets of the image plane. These values are added to each RGBA value.

Arguments
> r,g,b,a - the returned red, green, blue and alpha values

Return Codes
sSuccess - the offset was retrieved sInvalidObject - the image plane was invalid sFailure - the rgba values could not be read

statusCode AlImagePlane::setRGBOffset( double r, double g, double b, double a ) Description

Sets the RGB multiplier of the image plane.

Arguments
< r,g,b,a - the red, green, blue and alpha values

Return Codes
sSuccess - the multipliers were set sInvalidObject - the image plane was invalid sFailure - the rgba values could not be set

532 | Chapter 3 AlDagNode AlLocator

statusCode AlImagePlane::frameType(AlFrameType& ft,AlFrameTypeParams* ftp) Description

Returns the frame type parameters of the image plane.

Arguments
> ft - the returned type of the frame parameters > ftp - the returned values for the parameters

Return Codes
sSuccess - the parameters were retrieved sInvalidObject - the image plane was invalid sFailure - the parameters could not be retrieved

statusCode AlImagePlane::setFrameType(AlFrameType ft,AlFrameTypeParams* ftp ) Description

Sets the frame type parameters of the image plane. The frame type must be one of kFrameOff, kRegular or kKeyframe.

Arguments
< ft - the type of the frame parameters < ftp - the values for the parameters

Return Codes
sSuccess - the parameters were set sInvalidObject - the image plane was invalid sFailure - the parameters could not be set sInvalidArgument - an invalid frame type was given

AlImagePlane | 533

statusCode AlImagePlane::imageSize( int& x, int& y ) Description

Returns the width and height in pixels of the underlying image.

statusCode AlImagePlane::imageData( void*& data ) Description

Returns a pointer to the internal image data. The size of the data referenced by the pointer can be determined from imageSize(x,y) above and the type of image. If it is an RGB image the number of bytes in the image is 4 * x * y. The data should be treated as read only. Note: Under no circumstances should the returned pointer be freed.

statusCode AlImagePlane::maskType(AlMaskType& mt,AlMaskTypeParams* mtp ) Description

Returns the mask type parameters of the image plane.

Arguments
> ft - the returned type of the mask parameters > ftp - the returned values for the parameters

Return Codes
sSuccess - the parameters were retrieved sInvalidObject - the image plane was invalid sFailure - the parameters could not be retrieved

statusCode AlImagePlane::setMaskType(AlMaskType mt,AlMaskTypeParams* mtp ) Description

Sets the mask type parameters of the image plane. The frame type must be one of kMaskOff, kImage, kKeyframe or kFile.

534 | Chapter 3 AlDagNode AlLocator

Arguments
< ft - the type of the mask parameters < ftp - the values for the parameters

Return Codes
sSuccess - the parameters were set sInvalidObject - the image plane was invalid sFailure - the parameters could not be set sInvalidArgument - an invalid mask type was given

statusCode AlImagePlane::maskInvert( boolean& b ) Description

Returns the state of the mask invert flag.

Arguments
> b - the returned state of the flag

Return Codes
sSuccess - the state was returned sInvalidObject - the image plane was invalid

statusCode AlImagePlane::setMaskInvert( boolean b ) Description

Sets the state of the mask invert flag.

Arguments
< b - the new state of the flag

Return Codes
sSuccess - the state was set

AlImagePlane | 535

sInvalidObject - the image plane was invalid sFailure - the flag could not be set

statusCode AlImagePlane::depthType(AlDepthType& dt,double* depth ) Description

Returns the state and value of the depth type.

Arguments
> dt - the returned depth type > depth - a pointer to a variable to place the depth (if not NULL)

Return Codes
sSuccess - the type was returned sInvalidObject - the image plane was invalid sFailure - the type could not be determined

statusCode AlImagePlane::setDepthType(AlDepthType dt,double* depth ) Description

Sets the state and value of the depth type.

Arguments
< dt - the new depth type < depth - if non-NULL, then this points to the value of the depth

Return Codes
sSuccess - the depth type was returned sInvalidObject - the image plane was invalid sFailure - the depth type could not be set

536 | Chapter 3 AlDagNode AlLocator

statusCode AlImagePlane::imageSpace(AlImageSpaceType spaceType,AlImageSpaceTypeParams* spaceTypeParams,AlImageSpaceParams* spaceParams ) Description

Returns the parameters of the image plane (refer to the camera editor for more details). Use the spaceType to denote the type of parameters that you are requesting information on. This can be kFields (if the image is in the perspective window), k01, kScreen or kWorld.

Arguments
< spaceType - the space type parameters to return > spaceTypeParams - the returned values of the space type > spaceParams - the returned values of the wrap and origin values

Return Codes
sSuccess - the parameters were returned sInvalidObject - the image plane was invalid sFailure - the parameters could not be read

statusCode AlImagePlane::setImageSpace(AlImageSpaceType spaceType,AlImageSpaceTypeParams* spaceTypeParams,AlImageSpaceParams* spaceParams ) Description

Sets the parameters of the image plane. The spaceType must be one of kFields, kScreen, kWorld, k01. (This denotes the set of parameters that you want to set. Several calls to this routine may be required to set all of the parameters. Please refer to the camera editor for more details). Note that world space is only allowed in orthographic windows but not in perspective windows.

Arguments
< spaceType - the set of space parameters to set

AlImagePlane | 537

< spaceTypeParams - the new values of the space type < spaceParams - the new values of the wrap and origin values

Return Codes
sSuccess - the parameters were set sInvalidObject - the image plane was invalid sFailure - the parameters could not be set

AlIntersect
Support for intersection of objects.

538 | Chapter 3 AlDagNode AlLocator

Synopsis
#include <AlIntersect.h> class AlIntersect static statusCode intersect( AlCurve*, AlCurve*, AlList* & ); static statusCode intersect( AlCurve*, AlSurface*, AlList* & ); static statusCode intersect( AlSurface*, AlSurface*, AlIntersect SurfSurfInfo& ); static statusCode intersect( AlSurface *surface, double point[3], double planeNormal[3], AlIntersectSurfSurfInfo &ss ); static statusCode intersect( AlSurface *surface, double point[3],double planeNormal[3], double boundingBoxTol, boolean & noIntersect, boolean &intersectWithinTol, double &x, double &y, double &z ); class AlIntersectCurveCurveInfo : public AlLinkItem AlIntersectCurveCurveInfo* nextItem() const; AlIntersectCurveCurveInfo* prevItem() const; double tCurve1, tCurve2; double point[3]; class AlIntersectCurveSurfInfo : public AlLinkItem AlIntersectCurveSurfInfo* nextItem() const; AlIntersectCurveSurfInfo* prevItem() const; double t; double pointOnCurve[3]; double u,v; double pointOnSurface[3]; class AlIntersectSurfSurfInfo ~AlIntersectSurfSurfInfo(); int numberIsolatedPoints; double3* isolatedPoints; int numberIntersectionCurves; AlCurve** intersectionCurves; int numberBoundaryCurves; AlCurve** boundaryCurves;

Description
This collection of classes provides the programmer with the ability to determine points of intersection between two curves, a curve and a surface, or two surfaces. Each type of intersection responds with its own class of results: AlIntersectCurveCurveInfo, AlIntersectCurveSurfInfo, and

AlIntersect | 539

AlIntersectSurfSurfInfo. The first two of these are simple AlList classes. The last one is a structure storing pointers to AlCurves and (x/y/z) points.

AlIntersectCurveCurveInfo* AlIntersectCurveCurveInfo::nextItem() const Description

Returns the next item in the AlIntersectCurveCurveInfo list.

AlIntersectCurveCurveInfo* AlIntersectCurveCurveInfo::prevItem() const Description

Returns the previous item in the AlIntersectCurveCurveInfo list.

AlIntersectCurveSurfInfo* AlIntersectCurveSurfInfo::nextItem() const Description

Returns the next item in the AlIntersectCurveSurfInfo list.

AlIntersectCurveSurfInfo* AlIntersectCurveSurfInfo::prevItem() const Description

Returns the previous item in the AlIntersectCurveSurfInfo list.

AlIntersectSurfSurfInfo::~AlIntersectSurfSurfInfo() Description
Destructor for AlIntersectSurfSurfInfo. Only deletes the isolatedPoints[] array, so that the user may choose which AlCurves to keep.

statusCode AlIntersect::intersect( AlCurve* curve, AlSurface* surface,AlList* &list ) Description

Intersects a curve with a surface. Points of intersection are returned in a AlIntersectCurveSurfInfo list, giving (x,y,z) coordinates, (u,v) parameters, and (t) parameters.

540 | Chapter 3 AlDagNode AlLocator

Arguments
< curve - a valid AlCurve to intersect < surface - a valid surface to intersect > list - the points of intersection (see AlIntersectCurveSurfInfo)

Return Codes
sSuccess - successful intersection (not necessarily any points of intersection) sInvalidArgument - the curve/surface was invalid sFailure - the intersection failed

statusCode AlIntersect::intersect( AlCurve* curve1, AlCurve* curve2,AlList* &list ) Description

Intersects a curve with another curve. Points of intersection are returned in a AlIntersectCurveCurveInfo list, giving (x,y,z) coordinates and (t) parameters.

Arguments
< curve1 - a valid AlCurve to intersect < curve2 - a valid AlCurve to intersect > list - the points of intersection (see AlIntersectCurveCurveInfo)

Return Codes
sSuccess - successful intersection (not necessarily any points of intersection) sInvalidArgument - a curve was invalid sFailure - the intersection failed

statusCode AlIntersect::intersect( AlSurface *surface, double point[3], double planeNormal[3], AlIntersectSurfSurfInfo &ss ); Description
This method intersects a surface and an infinite plane. As in t

AlIntersect | 541

he other surface/surface intersection method, an AlIntersectSurfSurfInfo is returned.

Arguments
< surface - the surface to intersect < point - point on the plane of intersection < planeNormal - normal of the plane of intersection > ss - the points of intersection (see AlIntersectSurfSurfInfo)

Return Codes
sSuccess - the intersection worked( does not imply intersection) sInvalidArgument - the surface pointer is null sInvalidObject - the surface is an invalid wrapper sFailure - intersection failed

:statusCode AlIntersect::intersect( AlSurface *surface, double point[3], double planeNormal[3], double boundingBoxTol, boolean &noIntersect, boolean &intersectWithinTol, double &x, double &y, double &z ); Description
This method intersects a surface and a plane. The result of surface and plane intersection are curves. This method will find the curves of intersection, sum the bounding boxes of the curves and find the mid point of the joined bounding box. This method can be used to evaluate intersection points where the surface is discontinuous. Through iteration, you can find a point where the bounding box tolerance(distance from min to max points) is less than the parameter passed in.

Arguments
< surface - the surface to intersect < point - point on the plane of intersection /< planeNormal - normal of the plane of intersection < boundingBoxTolerance - smallest distance between the min and max points of a bounding box required

542 | Chapter 3 AlDagNode AlLocator

> noIntersect - set to TRUE or FALSE depending on if the intersection was found >intersectWithTol - set to TRUE if the intersection was in a bounding box matching the specified tolerance. Set to FALSE otherwise. > x,y,z - the mid point of the bounding box built from the curves of intersection

Return Codes
sSuccess - the intersection worked sInvalidArgument - the surface pointer is null sInvalidObject - the surface is an invalid wrapper sFailure - intersection failed

statusCode AlIntersect::intersect( AlSurface* surface1, AlSurface* surface2,AlIntersectSurfSurfInfo &ss ) Description

Intersects a surface with another surface. Points of intersection are returned in a AlIntersectSurfSurf list, giving AlCurves and (x,y,z) points.

Arguments
< surface1 - a valid AlCurve to intersect < surface2 - a valid AlCurve to intersect > ss - the points of intersection (see AlIntersectSurfSurfInfo)

Return Codes
sSuccess - successful intersection (not necessarily any points of intersection) sInsufficientMemory - not enough memory to perform intersection sInvalidArgument - a surface was invalid sFailure - the intersection failed

AlIntersect | 543

AlIterator
Pure virtual base classes used to derive iterators for doing tasks on elements of a list.

Synopsis
#include <AlIterator.h> class AlIterator virtual int func( AlObject* ) = 0; class AlIteratorWithParent virtual int func( AlObject* , AlDagNode* ) = 0;

Description
Many classes return the first element of a list, which is then traversed with some operation done on each element of the list. This class encapsulates this functionality making it very easy to write code that does operations on members of a list. To use this class the method "func" should be overloaded. On success, func() should return zero which will cause the iteration to continue with the next element in the list. A non-zero return value will cause the iteration to stop. The returned value will be returned through the second reference argument in the applyIterator() method. In general the applyIterator() methods return sSuccess even when func() returns non-zero. A return other than sSuccess indicates that the applyIterator() method failed to function properly. Two types of iterators are defined. The first passes in an AlObject* to the func(). The second iterator AlIteratorWithParent passes in the AlObject* and the AlDagNode* parent of the object. Note that if an AlIteratorWithParent is used and the AlObject is a shader then the AlDagNode pointer will be null. Iterators should be used to examine or set data in the visited objects, but should not be used to delete the objects. For example: class countIterator : public AlIterator { public: countIterator() : count( 0 ); ~countIterator() {}; virtual int func( AlObject* ) { count++; }; int result() { return count; }; private: int count; };

AlJoint
Interface to joint node data.

544 | Chapter 3 AlDagNode AlLocator

Synopsis
#include <AlJoint.h> class AlJoint : public AlObject virtual ~AlJoint(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; AlIKHandle* endEffectorHandle( void ) const; AlIKHandle* firstRootHandle( void ) const; AlIKHandle* nextRootHandle( const AlIKHandle* ) const; statusCode nextRootHandleD( AlIKHandle* ) const; statusCode applyIteratorToRootHandles( AlIterator*, int& ); statusCode useTransforms( boolean[3], boolean[3] ) const; statusCode useLimits( boolean[3], boolean[3] ) const; statusCode rotation( double[3], double[3], int[3] ) const; statusCode translation( double[3], double[3], int[3] ) const; statusCode restPose( double[3], double[3] ) const; statusCode setUseTransforms( const boolean[3], const boolean[3] ); statusCode setUseLimits( const boolean[3], const boolean[3] ); statusCode setRotation( const double[3], const double[3], const int[3] ); statusCode setTranslation( const double[3], const double[3], const int[3] ); statusCode setRestPose( const double[3], const double[3] ); statusCode assumeRestPose( void ); boolean charJoint() const; statusCode charJointLimits(double&, double&, AlJointInterpolation Type&) const; boolean useBulge() const; statusCode bulgeAttributes(int*, int*, double*, AlBulgeSections*, int*, int*, AlDagNodeFields*, AlBulgeRelateTo*, char*, double*) const; statusCode setCharJoint(boolean); statusCode setCharJointLimits(double, double, AlJointInterpolation Type); statusCode setUseBulge(boolean); statusCode setBulgeAttributes(int, int, double, AlBulgeSections, int, int, AlDagNodeFields, AlBulgeRelateTo, const char *, double); AlDagNode* dagNode( void ) const;

AlJoint | 545

Description
The AlJoint class allows access to the joint information on an AlDagNode. The joint node is used by the inverse kinematic algorithm to define properties of a joint. The character joint attributes are used to define properties of the bone below the joint for skinning operations. See the Alias reference books for information on skeletons, joints, constraints, IK, and character builder. In general, minimum values must be less than maximum values and stiffness values must be between 0 and 100 inclusive.

AlJoint::~AlJoint() Description
Deletes an AlJoint wrapper object.

AlObject *AlJoint::copyWrapper() const Description

Object wrapper duplicator for AlJoint.

AlObjectType AlJoint::type() const Description

Returns the class identifier kJointType;

AlJoint* AlJoint::asJointPtr() Description

This virtual function returns a non-null pointer to itself, indicating that it is safe to cast to an object of this class.

AlIKHandle* AlJoint::endEffectorHandle( void ) const Description

If this joint is the end effector in some IK chain, this method will return the AlIKHandle corresponding to that end effector. If the joint is not an end effector, or if the wrapper is not valid, this method will return NULL.

546 | Chapter 3 AlDagNode AlLocator

AlIKHandle* AlJoint::firstRootHandle( void ) const Description

If this joint is the root in some IK chain, this method will return the AlIKHandle corresponding to that root. If the joint is not a root, or the wrapper is not valid, this method will return NULL.

AlIKHandle* AlJoint::nextRootHandle( const AlIKHandle* ali ) const Description

Given that this joint is a root handle in some collection of IK chains, and the passed-in AlIKHandle refers to one of those root handles, this method will return an AlIKHandle corresponding to the next root handle in the collection.

Arguments
< ali - IK handle from which to walk forward

statusCode AlJoint::nextRootHandleD( AlIKHandle* ali ) const Description

Like AlJoint::nextRootHandle, but destructively sets the passed in AlIKHandle to point to the next root handle in the collection of handles with roots at this joint. If this operation cannot be completed, the contents of the argument will be left unchanged and sFailure will be returned.

Arguments
< ali - IK handle from which to walk forward

Return Codes
sSuccess - the method was successful sInvalidArgument - the passed-in AlIKHandle is not valid sInvalidObject - the joint is not valid sFailure - the next root handle could not be obtained

AlJoint | 547

statusCode AlJoint::applyIteratorToRootHandles( AlIterator* iter, int& rc ) Description

Applies the passed-in iterator (AlIterator) to the collection of AlIKHandles that have their roots at this AlJoint. See the documentation for AlIterator on page 544 for more information.

statusCode AlJoint::useTransforms( boolean translations[3], boolean rotations[3]) const Description

Used to determine which transformations may be used on the joint. Transformations may be toggled on or off using the setUseTransforms() method. If this joint is the root of a single chain IK handle, then all three rotations must be used.

Arguments
> translations - boolean array of states for the translations > rotations - boolean array of states for the rotations

Return Codes
sSuccess - successful sInvalidArgument - translations/rotations is NULL sInvalidObject - invalid joint sFailure - transformations could not be determined

statusCode AlJoint::useLimits( boolean translations[3], boolean rotations[3]) const Description

Used to determine whether the limits for the joint transformations should be used. The use of the limits can be toggled on or off using the setUseLimits() method.

548 | Chapter 3 AlDagNode AlLocator

Arguments
> translations - boolean array of limits for the translations > rotations - boolean array of limits for the rotations

Return Codes
sSuccess - successful sInvalidArgument - translations/rotations is NULL sInvalidObject - invalid joint

statusCode AlJoint::rotation( double Min[3], double Max[3], int stiffness[3] ) const Description
Used to determine min and max rotations for this joint, as well as the stiffness of the rotations. These values can be set using the setRotation() method.

Arguments
> Min - minimum rotation angles > Max - maximum rotation angles > stiffness - stiffness of rotations

Return Codes
sSuccess - successful sInvalidArgument - Min/Max/stiffness is NULL sInvalidObject - invalid joint

statusCode AlJoint::translation( double Min[3], double Max[3], int stiffness[3] ) const Description
Used to determine min and max translations for this joint, as well as the stiffness of the translations. These values can be set using the setTranslation() method.

AlJoint | 549

Arguments
> Min - minimum translations for the joint > Max - maximum translation for the joint > stiffness - stiffness of the translations

Return Codes
sSuccess - successful sInvalidArgument - Min/Max/stiffness is NULL sInvalidObject - invalid joint

statusCode AlJoint::restPose( double rotRest[3], double transRest[3] ) const Description

Used to get rest pose of rotations and translations for this joint. These values can be set using the setRestPose() method.

Arguments
> rotRest - rest pose of rotations for the joint > transRest - rest pose of translation for the joint

Return Codes
sSuccess - successful sInvalidArgument - Min/Max/stiffness is NULL sInvalidObject - invalid joint

statusCode AlJoint::setUseTransforms( const boolean translations[3], const boolean rotations[3] ) Description

Used to toggle on or off which transformations may be used on the joint. TRUE means that the transformation is toggled on and FALSE means that it is toggled off.

550 | Chapter 3 AlDagNode AlLocator

Arguments
< translations - boolean array of states for the translations < rotations - boolean array of states for the rotations

Return Codes
sSuccess - successful sInvalidArgument - NULL argument passed sInvalidObject - invalid joint sFailure - transformations could not be set

statusCode AlJoint::setUseLimits(const boolean translations[3], const boolean rotations[3] ) Description

Used to toggle on or off whether the limits for the joint transformations should be used. TRUE means that the transformation limits are toggled on and FALSE means that they are toggled off.

Arguments
< translations - boolean array of states for the translations < rotations - boolean array of states for the rotations

Return Codes
sSuccess - successful sInvalidArgument - NULL argument passed sInvalidObject - invalid joint sFailure - limits could not be set

AlJoint | 551

statusCode AlJoint::setRotation( const double Min[3], const double Max[3], const int stiffness[3] ) Description
Used to set min and max rotations for this joint, as well as the stiffness of the rotations. The min must be less than the max, and the stiffness must be between 0 and 100 inclusive.

Arguments
< Min - minimum rotation angles < Max - maximum rotation angles < stiffness - stiffness of the rotations

Return Codes
sSuccess - successful sInvalidArgument - NULL argument passed sInvalidObject - invalid joint sFailure - rotations could not be set

statusCode AlJoint::setTranslation( const double Min[3], const double Max[3], const int stiffness[3] ) Description
Used to set min and max translations for this joint, as well as the stiffness of the translations. The min must be less than the max, and the stiffness must be between 0 and 100 inclusive.

Arguments
< Min - minimum for the translations < Max - maximum for the translations < stiffness - stiffness of the translations

Return Codes
sSuccess - successful

552 | Chapter 3 AlDagNode AlLocator

sInvalidArgument - NULL argument passed sInvalidObject - invalid joint

statusCode AlJoint::setRestPose( const double rot_rest[3], const double trans_rest[3] ) Description

Used to set rest pose of rotations and translations for this joint. If the min and max are out of rest pose, they will be adjusted to the rest pose. Note: If this function is used on a hierarchy of joints (a skeleton), single-chain IK handles attached to this skeleton may also need to be set with proper rest poses by using AlIKHandle::setRestRotation().

Arguments
< rot_rest - rest pose for the rotations < trans_rest - rest pose for the translations

Return Codes
sSuccess - successful sInvalidArgument - NULL argument passed sInvalidObject - invalid joint

statusCode AlJoint::assumeRestPose( void ) Description

Used to resume rest pose of rotations and translations for this joint. Note: If this function is used on a hierarchy of joints (a skeleton), single-chain IK handles attached to this skeleton may also need to be set to their rest poses by using AlIKHandle::assumeRestRotation().

Return Codes
sSuccess - successful

AlJoint | 553

sInvalidObject - invalid joint

boolean AlJoint::charJoint() const Description

Used to determine whether this particular joint is a character joint, and thus has character joint attributes. If this joint is a character joint, TRUE is returned; otherwise, FALSE is returned.

statusCode AlJoint::charJointLimits(double &upper, double &lower, AlJointInterpolationType &interpolation) const Description

Returns the upper and lower limits of the character joint bounds around this joint. It also returns the interpolation type used to interpolate cluster percentages on the CVs between the lower and upper bound.

Arguments
> double &upper - upper limit of the joint bound > double &lower - lower limit of the joint bound > &interpolation - interpolation type

Return Codes
sSuccess - successful sInvalidObject - invalid joint sFailure - the limits could not be set

boolean AlJoint::useBulge() const Description

Returns TRUE if the character joint specifies there to be bulging effects in the bone(s) below this joint. Otherwise, this method returns FALSE.

statusCode AlJoint::bulgeAttributes(int *bulgeCode, int *bulgeOrient, double *bulgeScale, AlBulgeSections *bulgeSections, int *sectionsAround,

554 | Chapter 3 AlDagNode AlLocator

int *sectionsAlong, AlDagNodeFields *relateToParameter, AlBulgeRelateTo *relateTo, char *relateToNode, double *bulgeRange) const Description
Used to get the bulge attributes on a character joint. If any argument is NULL, then the attributes are not returned. Note that if the relateToNode parameter is non-NULL, then a strcpy() will be used to assign the name of the node. It is up to the caller of this routine to ensure that enough memory is allocated by relateToNode.

Arguments
See the method AlJoint::setBulgeAttributes().

Return Codes
sSuccess - successful sInvalidObject - invalid joint sFailure - the attributes could not be returned

statusCode AlJoint::setCharJoint(boolean isCharJoint) Description

If isCharJoint is TRUE, this method makes this joint into a character joint. If isCharJoint is FALSE, the joint becomes just an ordinary non-character joint.

Arguments
< isCharJoint - boolean to decide whether to make this a character joint

Return Codes
sSuccess - successful sInvalidObject - invalid joint

AlJoint | 555

statusCode AlJoint::setCharJointLimits(double upper, double lower,AlJointInterpolationType interpolation) Description

Sets the upper and lower joint bounds limits on the character joint. These bounds are the percentage along the bone above and below the joint. The values must be between 0 and 1. It also sets the interpolation type to be used between these two bounds.

Arguments
< upper - upper joint bounds limit < lower - lower joint bounds limit < interpolation - interpolation type

Return Codes
sSuccess - successful sInvalidArgument - upper or lower is outside of [0..1] sInvalidObject - invalid joint sFailure - the limits could not be set

statusCode AlJoint::setUseBulge(boolean useBulge) Description

Used to describe this character joint as one defining a bulge or not. If useBulge is TRUE, then the bones below this joint will receive bulging effects.

Return Codes
sSuccess - successful sInvalidObject - invalid joint sFailure - the bulge could not be set

statusCode AlJoint::setBulgeAttributes(int bulgeCode, int bulgeOrient, double bulgeScale, AlBulgeSections bulgeSections, int sectionsAround, int

556 | Chapter 3 AlDagNode AlLocator

sectionsAlong, AlDagNodeFields relateToParameter, AlBulgeRelateTo relateTo, const char *relateToNode, double bulgeRange) Description
Used to set the bulge attributes for a character joint. The bulge attributes apply to the bone(s) below this joint. Each of the bulge attributes are described below
bulgeCode this is the code that identifies which bulge type will be used to create the bulge on the bone below this character joint. The bulge code can be found in the "bulge_types" file in the misc_data directory of the current project. this value should be 0 (X), 1 (Y) or 2 (Z). It represents the local axis to be used to specify the direction around the bone that should be considered 0 degrees, when defining a particular bulge type. The local axis associated with a bone is at the lower end of the bone. Thus, these bulging attributes define the bulge on the bone below this character joint, and the axis used is the local axis from the joint at the other (lower) end of this bone. this value will scale the value of the bulge at any point by this amount. when doing a character builder "attach", the clusters that do the bulge can be placed one per "knot" on the defining bulge type (kBulgeDefinition), or evenly spaced around and along the bone (kBulgeEvenlySpaced). In the latter case, the number of clusters created will be up to sectionsAround*sectionsAlong.

bulgeOrient

bulgeScale

bulgeSections

AlJoint | 557

sectionsAround

if bulgeSections is kBulgeEvenlySpaced, this defines the number of subdivisions around the bone. if bulgeSections is kBulgeEvenlySpaced, this defines the number of subdivisions along the bone. when a bulge is created on a skin, expressions are created on clusters. This parameter defines the animation parameter of the node which the expression will use. if relateTo is kBulgeLowerJoint, then the expression on the cluster defining the bulge will be the joint node that is at the other end of the bone from this character joint. If relateTo is kBulgeOtherNode, then the node used in the expression will be the one defined by relateToNode. See explanation for relateTo. A copy of this string is made. When an expression is created, the bulging on the bone will occur when the value of the joint used in the expression is between its current value, and its current value plus bulgeRange.

sectionsAlong

relateToParameter

relateTo

relateToNode

bulgeRange

Return Codes
sSuccess - successful sInvalidArgument - an argument is out of range sInvalidObject - invalid joint sFailure - the bulge could not be set

558 | Chapter 3 AlDagNode AlLocator

AlDagNode * AlJoint::dagNode( void ) const Description

Returns the DAG node that this joint refers to.

AlKeyframe
Basic interface to Alias keyframes on parameter.

Synopsis
#include <AlKeyframe.h> class AlKeyframe : public AlObject AlKeyframe(); virtual ~AlKeyframe(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; boolean isLocked() const; statusCode setLock(boolean); AlKeyframe* prev() const; AlKeyframe* next() const; statusCode prevD(); statusCode nextD(); double value() const; double location() const; double inTangent() const; double outTangent() const; statusCode tangentTypes( AlTangentType&, AlTangentType& ) const; statusCode setValue(double, boolean = TRUE ); statusCode setLocation(double, boolean = TRUE ); statusCode setInTangent(double); statusCode setOutTangent(double); statusCode setTangentTypes(AlTangentType, AlTangentType, boolean = TRUE );

Description
AlKeyframe represents a keyframe belonging to an AlParamAction. The keyframe class does not have a create method. New keyframes are created

AlKeyframe | 559

using the AlParamAction::addKeyframe() methods (this is faster than creating the keyframes, then adding them to the paramaction). A keyframe cannot belong to more than one action. Thus attempting to add a keyframe that has already been added to an AlParamAction will fail. If an AlKeyframe is deleted and if the AlKeyframe belongs to an AlParamAction and it is the last keyframe of that parameter curve action, then the AlParamAction will also be deleted. This ensures that no AlParamAction parameter curves will exist with no keyframes. If a keyframe is added to an AlParamAction, and another keyframe already exists in that AlParamAction with the same location as the keyframe to be added, then the existing keyframe in the AlParamAction will be deleted. The method that applies tangent types to a keyframe (that is, setTangentTypes()) does not make much sense if the keyframe is not part of an AlParamAction. It is best to add all the desired keyframes to an AlParamAction, and then walk the list of keyframes, and call the tangent methods. You can lock a keyframe by calling the method AlKeyframe::setLock(TRUE). If an AlKeyframe is locked, then none of the AlKeyframe methods that change its location, value, or tangents will succeed. The keyframe is non-modifiable. You can unlock the keyframe again by calling AlKeyframe::setLock(FALSE).

AlKeyframe::AlKeyframe() Description
Constructs an AlKeyframe wrapper object.

AlKeyframe::~AlKeyframe() Description
Deletes an AlKeyframe wrapper object.

statusCode AlKeyframe::deleteObject() Description

Deletes a keyframe. If the keyframe is part of an action, then the keyframe will be removed from the actions list of keyframes. If the keyframe is the last keyframe in an action, the action will also be deleted.

560 | Chapter 3 AlDagNode AlLocator

Return Codes
sSuccess - the object was deleted sFailure - the object could not be deleted sInvalidObject - the object was invalid

AlObject *AlKeyframe::copyWrapper() const Description

Return an exact duplicate of this AlKeyframe wrapper.

AlObjectType AlKeyframe::type() const Description

Returns the class identifier kKeyframeType.

double AlKeyframe::location() const Description

Returns the time value for this keyframe, or 0.0 if the keyframe is invalid.

statusCode AlKeyframe::setLocation(double newTime, boolean recompute) Description

Sets the time of the keyframe to be the value given by newTime. If this keyframe is part of a parameter curve action, the list of keyframes may be reordered to reflect the new position of the keyframe. If the given newTime has the same value as the time of an existing keyframe, then this keyframe will not be moved.

Arguments
< newTime - the new value for the time of the keyframe < recompute - whether or not to recompute tangents now

Return Codes
sSuccess - keyframes time was successfully changed

AlKeyframe | 561

sFailure - keyframe is locked, thus cannot be changed sInvalidObject - the keyframe was invalid

double AlKeyframe::value() const Description

Returns the value of this keyframe, or 0.0 if the keyframe is not valid.

statusCode AlKeyframe::setValue(double newVal, boolean recompute) Description

Sets the value of the keyframe to be the value given by newVal.

Arguments
< newVal - the new value for the value of the keyframe < recompute - whether to recompute the tangents or not.

Return Codes
sSuccess - keyframes value was successfully changed sFailure - keyframe is locked, thus cannot be changed sInvalidObject - the keyframe was invalid

double AlKeyframe::inTangent() const Description

Returns the value of the in-tangent of the keyframe. The value will be between 90.0 and -90.0, where 0.0 represents a flat (horizontal) tangent pointing to the left, 90.0 means the tangent points straight up, and -90.0 means the tangent points straight down. 0.0 is returned in the case of an error.

statusCode AlKeyframe::setInTangent(double inTangent) Description

Sets the in-tangent of the keyframe to the given value. The tangent value must be in the range -90.0 < inTangent < 90.0.

562 | Chapter 3 AlDagNode AlLocator

If the given tangent value is outside this range, it is clamped to within this range. This method requires the AlKeyframe to have been attached to an AlParamAction; otherwise, an assertion will fail.

Arguments
< inTangent - the angle in degrees to which the keyframes in tangent should be set

Return Codes
sSuccess - keyframes inTangent was successfully changed sFailure - keyframe is locked, thus cannot be changed or failed to make tangent FIXED sInvalidObject - the keyframe was invalid

double AlKeyframe::outTangent() const Description

Returns the value of the out-tangent of the keyframe. The value will be between 90.0 and -90.0, where 0.0 represents a flat (horizontal) tangent pointing to the right, 90.0 means the tangent points straight up, and -90.0 means the tangent points straight down. This method returns 0.0 if the keyframe is invalid.

statusCode AlKeyframe::setOutTangent(double outTangent) Description

Sets the out-tangent of the keyframe to the given value. The tangent value must be in the range -90.0 < outTangent < 90.0. If the given tangent value is outside this range, it is clamped to within this range. This method requires the AlKeyframe to have been attached to an AlParamAction; otherwise, an assertion will fail.

AlKeyframe | 563

Arguments
< outTangent - the angle in degrees to which the keyframes out tangent should be set

Return Codes
sSuccess - keyframes outTangent was successfully changed sFailure - keyframe is locked, thus cannot be changed or failed to make tangent FIXED sInvalidObject - the keyframe was invalid

boolean AlKeyframe::isLocked() const Description

Returns TRUE if the keyframe is locked, FALSE if it is not. A locked keyframe means that you cannot change its time, value or tangents. FALSE is returned in the case of an error.

statusCode AlKeyframe::setLock(boolean flag) Description

Sets the lock flag of a keyframe. If the keyframe is locked, its time, value, and tangents will not be modifiable.

Arguments
< flag - TRUE (if the keyframe should be locked) or FALSE (if not)

Return Codes
sSuccess - normal completion sInvalidObject - object is invalid

AlKeyframe *AlKeyframe::prev() const Description

If this keyframe belongs to a parameter curve action (AlParamAction), then this method will return the previous AlKeyframe in the action (or NULL if

564 | Chapter 3 AlDagNode AlLocator

this keyframe is the first keyframe in the action). If this keyframe does not belong to an action, NULL is returned.

AlKeyframe *AlKeyframe::next() const Description

If this keyframe belongs to a parameter curve action (AlParamAction), then this method will return the next AlKeyframe in the action (or NULL if this keyframe is the last keyframe in the action). If this keyframe does not belong to an action, NULL is returned.

statusCode AlKeyframe::prevD() Description

If this keyframe belongs to a parameter curve action (AlParamAction), and it is not the first keyframe in that action, this function will set the information for this AlKeyframe to refer to the previous keyframe in the action, and return sSuccess. Otherwise, the information in this object is unchanged and sFailure is returned.

Return Codes
sSuccess - this wrapper points to the next keyframe sInvalidObject - object is invalid

statusCode AlKeyframe::nextD() Description

If this keyframe belongs to a parameter curve action (AlParamAction), and it is not the last keyframe in that action, this function will set the information for this AlKeyframe to refer to the next keyframe in the action, and return sSuccess. Otherwise, the information in this object is unchanged and sFailure is returned.

Return Codes
sSuccess - this wrapper points to the previous keyframe sFailure - there was no next keyframe sInvalidObject - object is invalid

AlKeyframe | 565

statusCode AlKeyframe::setTangentTypes(AlTangentType inTangentType, AlTangentType outTangentType, boolean recompute ) Description

Sets the in and out tangents of this keyframe to a specific type. Use kTangentUnchanged if you want either to remain unchanged. This method requires the AlKeyframe to have been attached to an AlParamAction, otherwise an assertion will fail. Note that this function sets the tangents on a segment. So depending on your choice of tangents, the tangents of the keyframes neighbors may be changed.

Arguments
< inTangentType - the type of the in tangent < outTangentType - the type of the out tangent < recompute - recompute the spline

Return Codes
sSuccess - keyframes tangents were successfully changed sFailure - keyframe is locked, thus cannot be changed sInvalidObject - the keyframe was invalid

statusCode AlKeyframe::tangentTypes(AlTangentType& inTangentType, AlTangentType& outTangentType) const Description

Gets the in and out tangent types of this keyframe. If this method fails to determine the type of either the in or out tangent, sFailure is returned, and either or both of the arguments are set to kTangentUnchanged.

Arguments
> inTangentType - returned inTangents type > outTangentType - returned outTangents type

566 | Chapter 3 AlDagNode AlLocator

Return Codes
sSuccess - successfully determined keyframes tangents sFailure - failed to determine one of the keyframes tangents sInvalidObject - the keyframe was invalid

AlLayer
An interface to Alias layer objects.

AlLayer | 567

Synopsis

568 | Chapter 3 AlDagNode AlLocator

#include <AlLayer.h> class AlLayer : public AlObject enum AlLayerPickType { kLayerPickable, kLayerReference, kLayerInactive }; AlLayer(); virtual ~AlLayer(); virtual AlObject* copyWrapper() const; virtual statusCode deleteObject(); virtual AlObjectType type() const; statusCode create(const char * = NULL); statusCode create(int&, const char * = NULL); statusCode create(int); boolean invisible() const; statusCode setInvisible( boolean ); int number() const; const char * name() const; statusCode setName( const char * ); statusCode pickability( AlLayerPickType& ) const; statusCode setPickability( AlLayerPickType ); boolean playback() const; statusCode setPlayback( boolean ); boolean drawInstances() const; statusCode setDrawInstances( boolean ); boolean visibleInLayerBar() const; statusCode setVisibleInLayerBar( boolean ); int color() const; statusCode setColor( int ); boolean isPicked() const; statusCode pick(); statusCode unpick(); static boolean startNumber(); static statusCode setStartNumber( boolean ); // Symmetric layer support statusCode setSymmetric( boolean ); boolean isSymmetric() const; statusCode setSymmetricOrigin( double, double, double statusCode setSymmetricNormal( double, double, double statusCode symmetricOrigin( double&, double&, double& statusCode symmetricNormal( double&, double&, double&

); ); ); );

AlLayer | 569

Description
Layers provide a way of organizing models to improve the workflow. The layers have attributes such as visibility and pickability that apply to all the DAG nodes which refer to them. The AlDagNode has methods to get the AlLayer it is in and set to a new AlLayer. Each AlLayer has a unique identifying number and a name. By default, the layer gets the unique name based on its number; however, the user is free to change it to any name. Layer names provided by the user do not have to be unique. The types of layers are:

Default Layer: There is always a default layer in the AlUniverse with a number 0. Its attributes can never be changed. Any object of a class derived from the AlDagNode class can be assigned to an AlLayer. Creation Layer: Any new AlDagNode is automatically assigned to the creation layer. Any existing layer can be made into the creation layer, including the default layer. When a layer is made a creation layer, its attributes such as invisibility temporarily become ineffective and it gets the same attributes as the default layer. These attributes become effective again, as soon as another layer is made a creation layer.

A DAG node (AlDagNode) can be transferred from one layer to another but can exist on only one layer at a time. When an AlDagNode is assigned to a non-default layer:

all of its children are assigned to the non-default layer all the parents are assigned to the default layer all instances of the AlDagNode are also assigned to the same layer siblings of the AlDagNode remain unaffected.

All attributes in an AlLayer can be obtained and set with the methods in this class. By default, all the layers have a corresponding menu in the Alias interface and are visible in the layer bar in the Alias interface. However, if you want to work with a partial list of layers you can make them visible using the visibleInLayerBar() method. The change in visibility in the layer bar does not change the other attributes of the AlLayer. All existing layers in an AlUniverse can be accessed through methods in AlUniverse. The layer functionality can be temporarily disabled through the static method setLayersEnabled() in the AlUniverse class. When the layer

570 | Chapter 3 AlDagNode AlLocator

functionality is disabled or turned off, all the layer attributes temporarily become similar to the default layer. However, the layer references of the AlDagNode are not changed. Symmetric layers are also supported in the API. Methods available allow the developer to turn symmetric layers on, find out if a layer is symmetric, set/query the origin and normal parameters of the symmetric plane and create the symmetric geometry. Symmetric layers are specified by a normal and a point(origin). Note: creation of symmetric geometry is done by the AlDagNode class. The complete layer interface is available in Open Model as well.

AlLayer::AlLayer(void) Description
Constructs an AlLayer wrapper object.

AlLayer::~AlLayer() Description
Deletes an AlLayer wrapper object.

statusCode AlLayer::deleteObject() Description

This method deletes the layer.

Return Codes
sSuccess - the object was deleted sInvalidObject - the locator was not valid

AlObject* AlLayer::copyWrapper() const Description

Returns an exact copy of the AlLayer wrapper.

AlLayer | 571

AlObjectType AlLayer::type() const Description

Returns the class identifier kLayerType.

statusCode AlLayer::create( const char* name) Description

Creates a new layer

Arguments
> number - the number of the new layer < name - the name of the new layer

Return Codes
sSuccess - the layer was created sFailure - the layer was not created because either the maximum number of layers were already created or the layer functionality is turned off sAlreadyCreated - the object has already been created

statusCode AlLayer::create( int& number, const char* name) Description

Creates a new layer.

Arguments
> number - the number of the new layer < name - the name of the new layer

Return Codes
sSuccess - the layer was created sFailure - the layer was not created because either the maximum number of layers were already created or the layer functionality is turned off

572 | Chapter 3 AlDagNode AlLocator

sAlreadyCreated - the object has already been created

statusCode AlLayer::create( int number) Description

Create a new layer with the given number

Arguments
> number - the number of the new layer

Return Codes
sSuccess - the layer was created sFailure - the layer was not created because either the maximum number of layers had already created or the layer functionality is turned off. sAlreadyCreated - object has already been created

boolean AlLayer::invisible() const Description

Checks if the layer is invisible. Note that if an invisible layer is made the creation layer, it temporarily becomes visible while it is the creation layer.

Return Values
true - the layer is invisible false - the layer is visible or the object is invalid or layer functionality is turned off

statusCode AlLayer::setInvisible(boolean invisible) Description

Changes the visibility of the layer. If a creation layer is made invisible, the default layer becomes the creation layer.

AlLayer | 573

Arguments
< invisible - a value of true makes the layer invisible and false makes it visible

Return Codes
sSuccess - the layer visibility attribute was set sFailure - the attribute was not set (perhaps the layer functionality was turned off) sInvalidObject - the object is not valid

statusCode AlLayer::pickability (AlLayerPickType& pickType) const Description

Checks the pickability of the layer.

Arguments
> pickType - shows whether the layer is inactive, reference or pickable

Return Codes
sSuccess - the layer pickability attribute was found sInvalidObject - the object is not valid.

statusCode AlLayer::setPickability (AlLayerPickType pickType) Description

Changes the pickability of the layer. If a creation layer is made referenced or inactive, the default layer becomes the creation layer.

Arguments
< pickability - kLayerInactive makes the layer unpickable and unsnappable, kLayerReference makes the layer unpickable but snappable, and kLayerPickable makes the layer both pickable and snappable.

Return Codes
sSuccess - the layer pickability attribute was set

574 | Chapter 3 AlDagNode AlLocator

sFailure - the layers have been turned off sInvalidObject - the object is not valid

int AlLayer::number() const Description

Gets the number of the layer. This number is fixed and unique. It cannot be set to another value. A value of 0 is returned if this is the default layer. -1 is returned if the object is not valid.

const char * AlLayer::name() const Description

Returns the name of the object.

statusCode AlLayer::setName (const char *newName) Description

Sets the name of a layer. By default the name of the layer is determined by its number. For example, a layer with a number 3 is named layer#3 by default

Arguments
< newName - the new name of the layer

Return Codes
sSuccess - the name was set sFailure - the layer is a default layer or the name length exceeded 255 characters, or the layers functionality is disabled. sInvalidArgument - newName was NULL sInvalidObject - the object is not valid

AlLayer | 575

boolean AlLayer::drawInstances() const Description

Returns true if the instances are drawn in the modeling windows and false otherwise. False is also returned if the layer is invalid.

statusCode AlLayer::setDrawInstances (boolean draw) Description

Sets the drawability of instance nodes in the Alias modeling windows.

Arguments
< draw - a value of true enables the drawing of instances and a value of false disables it

Return Codes
sSuccess - the drawing of instances was set sFailure - the layer is a default layer or the layer functionality is disabled sInvalidObject - the object is not valid

boolean AlLayer::playback() const Description

Returns true if the layer can be played back and false otherwise. False is also returned if the layer is invalid.

statusCode AlLayer::setPlayback (boolean enablePlayback) Description

Sets whether or not a layer can play back.

Arguments
< enablePlayback - a value of true enables the layer to play back; false prevents it from playing back

576 | Chapter 3 AlDagNode AlLocator

Return Codes
sSuccess - the playback setting was enabled sFailure - the layer is a default layer or the layer functionality is disabled sInvalidObject - the object is not valid

int AlLayer::color() const Description

Returns the color index for inactive modeling in the Alias interface. Color indexes are defined in AlUserColors.h.

Return Values
kUserInactiveModelColor - the layer does not have a color and it uses the default Alias colors kUserInactiveLayerUser1, kUserInactiveLayerUser2, ..., kUserInactiveLayerUser15 - the color index of the Alias inactive modeling colors -1 - the object is invalid

statusCode AlLayer::setColor (int colorField) Description

Sets the layer color by colorField, as defined in AlUserColors.h. The valid color indices vary from kUserInactiveLayerUser1Color to kUserInactiveLayerUser15Color, providing 15 valid colors which can be set for the layers. The definition of these colors can be changed with AlUniverse::setUserPrefColor().

Arguments
< colorField - kUserInactiveLayerUser1Color to kUserInactiveLayerUser15Color - the layer uses colors 1 through 15, depending on which value you specify, or kUserInactiveModelColor - the layer uses the default Alias model color

Return Codes
sSuccess - the color was set

AlLayer | 577

sFailure - the layer functionality is disabled sInvalidArgument - the color index was out of range sInvalidObject - the object is not valid

boolean AlLayer::isPicked() const Description

Returns true if the layer is picked. FALSE is returned if the layer is not picked or if the object is invalid.

statusCode AlLayer::unpick() Description

Unpicks the layer.

Return code
sSuccess - the unpick was successfully sFailure - the unpick operation failed because layers have been disabled sInvalidObject - the object is not valid

statusCode AlLayer::pick() Description

Picks the layer.

Return code
sSuccess - the pick was successful sFailure - the pick operation failed because layers have been disabled sInvalidObject - the object is not valid

578 | Chapter 3 AlDagNode AlLocator

boolean AlLayer::visibleInLayerBar() const Description

Determines whether or not the layer is visible in the layer bar in the Alias window

statusCode AlLayer::setVisibleInLayerBar (boolean visibility) Description

Sets whether or not the layer menu should appear in the layer bar.

Arguments
< visibility - a value of true makes the layer bar visible and false makes it invisible

Return Codes
sSuccess - the visibility in the layer bar was set sFailure - the layers functionality is turned off

int AlLayer::startNumber() Description

Provides the number of the layer which will be added with the create() method.

statusCode AlLayer::setStartNumber(int newStart) Description

Sets the number which a new layer created with create() method will get. Further create() invocations will increment the number by one for each new layer. Once the layer is created its number cannot be changed. Also if the layer by that number already exists, the number is incremented until a layer by that number does not exist.

Arguments
< newStart - the new layer will get the layer of this number. newStart can range from 1 to 65,023.

AlLayer | 579

Return Codes
sSuccess - the layer start number was set sFailure - the layer could not be set sInvalidArgument - the number was outside the range of 1 to 65,023

statusCode AlLayer::setSymmetric(boolean symm) Description

Sets this layer to be symmetric or turns layer symmetry off.

Arguments
< symm - true if symmetry is required, false to turn symmetry off

Return code
sSuccess - the method was successful sFailure - the method failed sInvalidObject - the layer is invalid

boolean AlLayer::isSymmetric() const Description

Returns TRUE if this layer is symmetric. FALSE will be returned if the layer is not symmetric of if the method failed.

statusCode AlLayer::setSymmetricOrigin(double x, double y, double z) Description

This methods sets the location of the origin of the symmetric layer.

Arguments:
< x,y,z -coordinates of the symmetric layers origin

580 | Chapter 3 AlDagNode AlLocator

Return code
sSuccess - the method succeeded sFailure - the method failed sInvalidObject - the layer is invalid or is not symmetric

statusCode AlLayer::setSymmetricNormal(double x, double y, double z) Description

This method sets the normal of the symmetric plane.

Arguments:
< x,y,z - the normal of the symmetric plane.

Return code
sSuccess - the method succeeded sFailure - the method failed sInvalidObject - the layer is invalid or is not symmetric

statusCode AlLayer::symmetricOrigin(double& x, double& y, double& z) Description

Returns the symmetric origin of the layer.

Arguments
> x,y,z - components of the symmetric origin

Return code
sSuccess - the method succeeded sFailure - the method failed sInvalidObject - the layer is invalid or is not symmetric

AlLayer | 581

statusCode AlLayer::symmetricNormal(double& x, double& y, double& z) Description

Returns the symmetric normal of the layer.

Arguments
> x,y,z - the components of the normal

Return code
sSuccess - the method succeeded sFailure - the method failed sInvalidObject - the layer is invalid or is not symmetric

AlLight
Encapsulates methods common to all lights.

582 | Chapter 3 AlDagNode AlLocator

Synopsis
#include <AlLight.h> class AlLight : public AlObject , public AlAnimatable virtual ~AlLight(); virtual statusCode deleteObject(); virtual AlObjectType type() const; virtual const char* name() const; virtual statusCode setName( const char* ); statusCode parameter( const AlLightFields, double& ) const; statusCode setParameter( const AlLightFields, const double ); AlLightNode* lightNode() const; virtual AlLightNode* lookAtNode() const; virtual AlLightNode* upNode() const; boolean hasLinkedObjects() const; AlObject* firstLinkedObject() const; AlObject* nextLinkedObject( AlObject * ) const; statusCode applyIteratorToLinkedObjects( AlIterator *iter, int& rc ); statusCode linkObjectToLight( AlObject * ); statusCode unlinkObjectFromLight( AlObject * ); boolean exclusivity() const; statusCode setExclusivity( boolean ); statusCode color( double&, double&, double& ) const; statusCode setColor( double, double, double ); statusCode worldPosition( double&, double&, double& ) const;

Description
This virtual class contains methods which are common to all types of lights. This includes color, linkage to objects and exclusivity. To create a light, the user must instantiate and call the create method of a specific type of light (eg. a point light or a spot light). When a light is created, three light nodes are created, grouped under a group node, which is inserted into the universes DAG. These light nodes represent the position, "look at" and "up" points of the light. Even though three light nodes are created for all lights, only the spot light class uses the information in the "look at" and "up" nodes. All other classes either dont have a direction or store direction in a different manner. The direction vector of a spot light is the vector between its position point and its "look at" point. The "up" direction vector of a spot light is the vector between its position point and its "up" point.

AlLight | 583

There are two ways to delete a light object. When an AlLight object is deleted, its three light nodes are deleted. Alternatively, when a light node is deleted, its associated light (and other light nodes) are deleted. The group node that originally grouped the position, "look at" and "up" nodes is not deleted. The light classes are derived as follows, where a class inherits the functionality defined in the class above it. The user can only instantiate ambient, point, direction, spot, linear and area lights.

For directional lights, the light positions are (in Z-up coordinate system) position at (0,0,0), view at (0,0,-1), and up at (0,1,-1). For linear lights, the axis by default starts at the position point and extends (2,0,0). For area lights, the short axis starts at the position point and extends (0,1,0); the long axis starts at the position point and extends (2,0,0). All lights have an "exclusive" flag. If this flag is TRUE, then the light will only illuminate objects to which it is linked. If the flag is FALSE, the light will illuminate objects that have no light links. The default for new lights is FALSE.

AlLight::~AlLight() Description
Deletes an AlLight wrapper object.

statusCode AlLight::deleteObject() Description

Deletes the lights associated nodes (for position, look at and up) and deletes the light. A light can be deleted in two ways. If AlLight::deleteObject() is called, it deletes the associated AlLightNodes. If AlLightNode::deleteObject() is called, it deletes the associated AlLight.

584 | Chapter 3 AlDagNode AlLocator

Return Codes
sSuccess - the light and its associated light nodes were deleted sInvalidObject - light was invalid sFailure - the light could not be deleted

AlObjectType AlLight::type() const Description

Returns the class identifier, which could be any one of kAmbientLightType, kAreaLightType, kSpotLightType, kPointLightType, kDirectionLightType, kLinearLightType.

const char* AlLight::name() const Description

Returns a pointer to this lights name.

statusCode AlLight::setName(const char *newName) Description

Changes the camera DAG nodes name to the given name. If the given name is not unique, then a unique name is generated based on the given name and assigned to the camera. In this case, a status code of sNameChangedToUniqueOne is returned.

Arguments
< cost char* newName - the name to be assigned to this light

Return Codes
sSuccess - everything was successful sInsufficientMemory - not enough memory available sInvalidObject - the light was invalid sNameChangedToUniqueOne - the objects name was changed to be a unique version of the given name

AlLight | 585

statusCode AlLight::parameter( const AlLightFields field, double& result ) const Description

Finds the value of a given light field.

Arguments
< field - light field type > result - returned result of the field

Return code
sSuccess - field was returned sInvalidArgument - field was not legal for this light sFailure - field could not be returned sInvalidObject - the light was invalid

statusCode AlLight::setParameter( const AlLightFields field,const double value) Description

Changes the value of the light field. If the given field is not valid then a status code of sFailure is returned.

Arguments
< field - light field type < value - new value that the light field is to take

Return Codes
sSuccess - field was changed sInvalidArgument - field was not legal for this light sFailure - field could not be changed sInvalidObject - the light was invalid

586 | Chapter 3 AlDagNode AlLocator

AlLightNode *AlLight::lightNode() const Description

Returns a pointer to the DAG node that represents the lights position.

AlLightNode *AlLight::lookAtNode() const Description

Returns a pointer to the look at node attached to this light. This method does not apply to all lights (eg. a point light doesnt have a look at direction).

AlLightNode *AlLight::upNode() const Description

Returns a pointer to the up node attached to this light. This method doesnt apply to all lights (eg. a point light doesnt have a up direction).

statusCode AlLight::color( double &r, double &g, double &b) const Description
Returns the color of the light in r,g & b, (for red, green and blue). Valid values for r,g & b are between 0.0 and 255.0.

Arguments
> r - is the current red value of the light > g - is the current green value of the light > b - is the current blue value of the light

Return Codes
sSuccess - color retrieved sInvalidObject - object is invalid

AlLight | 587

boolean AlLight::exclusivity() const Description

Returns TRUE if the exclusive flag of this light is TRUE. Otherwise, returns FALSE. If a lights exclusive flag is TRUE, then the light will only illuminate objects to which it is linked. If the flag is FALSE, the light will illuminate objects that have no light links. Default is FALSE.

statusCode AlLight::setColor( double r, double g, double b) Description

Sets the color of the light to be r,g & b (for red, green and blue). Valid values for r,g & b are between 0.0 and 255.0.

Arguments
< r - is the new red value < g - is the new green value < b - is the new blue value

Return Codes
sSuccess - the color was set sInvalidObject - invalid light sInvalidArgument - color out of range

boolean AlLight::hasLinkedObjects() const Description

Returns TRUE if this light has any objects linked to it. Otherwise, returns FALSE.

AlObject* AlLight::firstLinkedObject() const Description

Returns a pointer to the first object that is linked to this light. If there are no objects linked to this light, then NULL is returned. Only objects with 3D

588 | Chapter 3 AlDagNode AlLocator

geometry can be linked to a light. Cameras, lights, curves and CVs cannot be linked to a light. Surfaces and faces can be linked to a light.

AlObject* AlLight::nextLinkedObject( AlObject* toThis ) const Description

Returns a pointer to the object following the given object that is linked to this light. NULL is returned if there is no following object. NULL is returned if the given AlObject wasnt found in the light list. Only objects with 3D geometry can be linked to a light. Cameras, lights, curves and CVs cannot be linked to a light. Surfaces and faces can be linked to a light.

Arguments
< toThis - the object whose following linked object is returned.

statusCode AlLight::applyIteratorToLinkedObjects( AlIterator *iter, int& rc ) Description

Applies an iterator to each linked object.

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

Return Codes
sSuccess - the iterator was successfully applied to each object sInvalidArgument - iter was NULL

statusCode AlLight::linkObjectToLight( AlObject *obj ) Description

Links the given object to the light. If the lights exclusive flag is on, then the light will only illuminate objects to which it is linked. Only objects with 3D geometry can be linked to a light. Cameras, lights, curves and CVs cannot be linked to a light. Surfaces, faces, and shells can be linked to a light.

AlLight | 589

Arguments
< obj - the object to link to the light

Return Codes
sSuccess - linking object to this light was successful sAlreadyCreated - this object was already linked to this light sInvalidObject - light is invalid sInvalidArgument - object was NULL or not a face, surface, or shell

statusCode AlLight::unlinkObjectFromLight( AlObject *obj ) Description

Unlinks the given object from the light. If the lights exclusive flag is on, then the light will only illuminate objects to which it is linked.

Arguments
< AlObject *obj - the object to link to the light

Return Codes
sSuccess - linking object to this light was successful sObjectNotFound - this object wasnt linked to this light sInvalidObject - light is invalid sInvalidArgument - object was NULL or not a face, surface, or shell

statusCode AlLight::setExclusivity( boolean newExclusive ) Description

Sets the exclusive flag of this light. If a lights exclusive flag is TRUE, then the light will only illuminate objects to which it is linked. If the flag is FALSE, the light will illuminate objects that have no light links. Default is FALSE.

Arguments
< newExclusive - is the new value of the exclusive flag

590 | Chapter 3 AlDagNode AlLocator

Return Codes
sSuccess - exclusivity set sInvalidObject - object invalid

statusCode AlLight::worldPosition( double &x, double &y, double &z ) const Description
Returns the point in world space where this light is positioned. This is the same as the position of the position light node.

Arguments
> x - the x coordinate of the light position > y - the y coordinate of the light position > z - the z coordinate of the light position

Return Codes
sSuccess - world Position retrieved sInvalidObject - object invalid sFailure - an error occurred

AlLightNode
The DAG node class for lights.

AlLightNode | 591

Synopsis
#include <AlLightNode.h> class AlLightNode: public AlDagNode virtual ~AlLightNode(); virtual AlObject * copyWrapper() const; statusCode deleteObject(); AlObjectType type() const; AlLight* light() const; AlLight* light(AlTM&) const; virtual boolean isInstanceable(); boolean isLookAtNode() const; boolean isUpNode() const; boolean isPositionNode() const;

Description
This class is a DAG node class used specifically for lights. Each AlLight object has three light nodes for position, look at and up points. (For more information on how AlLights and AlLightNodes work together, see the class description for the AlLight on page 582 object.) To create a light node, the user must create a specific type of light, which creates the necessary light nodes. These light nodes are grouped and inserted into the universes DAG. The user cannot directly instantiate a light node. To figure out whether or not a light node represents a position, a look at or an up point, the user can use: 1) the isPositionNode(), isLookAtNode(), isUpNode() methods, or 2) the type() method of the attached AlLight object. A light node can be deleted in two ways. When a light node is deleted, its associated light (and other light nodes) are deleted. Alternatively, when a light is deleted, its light nodes are also deleted.

AlLightNode::~AlLightNode() Description
Deletes an AlLightNode wrapper object.

592 | Chapter 3 AlDagNode AlLocator

AlObject *AlLightNode::copyWrapper() const Description

Returns an exact duplicate of this AliLightNode.

statusCode AlLightNode::deleteObject() Description

Deletes all objects associated with this light node. It deletes the attached light object, which in turn deletes the other attached light DAG nodes. A light can be deleted in two ways. If AlLight::deleteObject() is called, it deletes the associated AlLightNodes. If AlLightNode::deleteObject() is called, it deletes the associated AlLight.

Return Codes
sSuccess - the light node and light were deleted sInvalidObject - light node is invalid sFailure - an error occurred

AlObjectType AlLightNode::type() const Description

Returns the light node type, kLightNodeType (for the lights position node), kLightUpNodeType (for the lights up node), and kLightLookAtNodeType (for the lights look at node).

AlLight *AlLightNode::light() const Description

Returns a pointer to the attached light object. If the light does not exist or is not the right type, then NULL is returned.

AlLightNode | 593

AlLight *AlLightNode::light(AlTM& tm) const Description

Returns a pointer to the attached light object. If the light does not exist or is not the right type, then NULL is returned. The AlTM will be updated with the lightNodes TM if a light exists.

Arguments
> tm - the transformation matrix to update with the lightnodes TM

boolean AlLightNode::isInstanceable() Description

Returns FALSE. An AlLightNode is not an instanceable DAG node.

boolean AlLightNode::isLookAtNode() const Description

Returns TRUE if this node is a look at node.

boolean AlLightNode::isUpNode() const Description

Returns TRUE if this node is a up node.

boolean AlLightNode::isPositionNode() const Description

Returns TRUE if this node is a position node.

AlLinearLight
Encapsulates the creation, deletion, and manipulation of linear lights.

594 | Chapter 3 AlDagNode AlLocator

Synopsis
#include <AlLinearLight.h> class AlLinearLight: public AlDirectionLight AlLinearLight(); virtual ~AlLinearLight(); virtual AlObject* copyWrapper() const; statusCode create(); AlObjectType type() const; statusCode axis( double&, double&, double& ) const; statusCode setAxis( double, double, double ); statusCode endpoint( double&, double&, double& ) const;

Description
A linear light emits light in all directions. A linear light would be used, for instance, to simulate a fluorescent light tube. The length of the line is defined by the lights axis. To determine the endpoints of this light, use the worldPosition() method and the endpoint() method. Although this class inherits methods to access the look at and up nodes of a light, they are not used. The direction and twist of an area light is changed by translating and rotating the transformation of the lights position node.

AlLinearLight::AlLinearLight() Description
Constructs an AlLinearLight wrapper object.

AlLinearLight::~AlLinearLight() Description
Deletes an AlLinearLight wrapper object.

AlLinearLight | 595

statusCode AlLinearLight::create() Description

Creates all the DAG nodes for this light and adds them to the universe. The DAG nodes are for position, look at and up, and another DAG node that groups these three together.

Return Codes
sSuccess - everything was successful sInsufficientMemory - not enough memory available sAlreadyCreated - light is already created

AlObjectType AlLinearLight::type() const Description

Returns the class identifier kLinearLightType.

statusCode AlLinearLight::axis( double &x, double &y, double &z) const Description
Returns the linear lights axis in x,y & z.

Arguments
> x - is the lights axis in the x direction > y - is the lights axis in the y direction > z - is the lights axis in the z direction

Return Codes
sSuccess - axis returned sInvalidObject - the light was not valid sFailure - an error occurred

596 | Chapter 3 AlDagNode AlLocator

statusCode AlLinearLight::setAxis( double x, double y, double z ) Description

Sets the axis of the light to be x,y, & z. The given axis must be non-zero.

Arguments
< x - is the lights new axis in the x direction < y - is the lights new axis in the y direction < z - is the lights new axis in the z direction

Return Codes
sSuccess - axis set sInvalidArgument - the (x,y,z) forms a zero (or nearly zero) vector sInvalidObject - the light was not valid sFailure - an error occurred

statusCode AlLinearLight::endpoint( double &x, double &y, double &z ) const Description
Returns the endpoint of this linear light in world space. This point and the world position of this light form the line that makes this light a linear light.

Arguments
> x - is the endpoint in the x direction > y - is the endpoint in the y direction > z - is the endpoint in the z direction

Return Codes
sSuccess - endpoint retrieved sInvalidObject - object invalid sFailure - an error occurred

AlLinearLight | 597

AlLineAttributes
Interface to Alias line attributes.

Synopsis
#include <AlLineAttributes.h> class AlLineAttributes : public AlAttributes virtual AlObjectType type() const; AlObject* copyWrapper() const; statusCode startPoint(double&, double&, double&) const; statusCode endPoint(double&, double&, double&) const; statusCode setStartPoint(double, double, double); statusCode setEndPoint(double, double, double);

Description
AlLineAttributes is a class derived from the AlAttributes class. This class allows access to the attributes for a line. The attributes which define a line are just its start point and its end point. Coordinates are given in object space, and not world space.

AlObjectType AlLineAttributes::type() const Description

Returns the class identifier kLineAttributeType.

AlObject* AlLineAttributes::copyWrapper() const Description

Makes a copy of the AlLineAttributes. The returned AlLineAttributes will reference the same data as the original.

statusCode AlLineAttributes::startPoint( double& x, double& y, double& z ) const Description

Gets the start point for the line.

598 | Chapter 3 AlDagNode AlLocator

Arguments
> x, y, z - the returned 3D coordinates of the start point

Return Codes
sSuccess - the start point was successfully returned sInvalidObject - the attribute was not valid sFailure - an error occurred.

statusCode AlLineAttributes::endPoint( double& x, double& y, double& z ) const Description

Gets the end point for the line.

Arguments
> x, y, z - the returned 3D coordinates of the end point

Return Codes
sSuccess - the end point was successfully returned sInvalidObject - the attribute was not valid sFailure - an error occurred.

statusCode AlLineAttributes::setStartPoint( double x, double y, double z ) Description

Sets the start point for the line.

Arguments
< x, y, z - the 3D coordinates of the start point

Return Codes
sSuccess - setting the start point succeeded sFailure - setting the start point failed

AlLineAttributes | 599

sInvalidObject - the attribute was invalid

statusCode AlLineAttributes::setEndPoint( double x, double y, double z ) Description

Sets the end point for the line.

Arguments
< x, y, z - the 3D coordinates of the end point

Return Codes
sSuccess - setting the end point succeeded sFailure - setting the end point failed sInvalidObject - the attribute was invalid

AlLinkItem
Base class for objects contained in an AlList.

Synopsis
#include <AlLinkItem.h> class AlLinkItem // All methods are protected. AlLinkItem(); virtual ~AlLinkItem(); AlLinkItem* next( void ); AlLinkItem* prev( void ); void append( AlLinkItem* ); void remove();

Description
This is an abstract base class which classes will derive from so that the objects can be contained in AlList objects. All methods and variables of this class are protected or private.

600 | Chapter 3 AlDagNode AlLocator

AlLinkItem::~AlLinkItem() Description
Destructor for AlLinkItem class.

void AlLinkItem::append( AlLinkItem* item ) Description

Inserts an AlLinkItem object after this object. The object is connected to this object's next object.

Arguments
< item - The object to be appended.

void AlLinkItem::remove() Description

Removes this object from the list. Sets the pointers of its neighbors correctly, and its own to NULL.

AlList
Simple list class for AlLinkItem objects.

Synopsis
#include <AlList.h> class AlList AlList( AlLinkItem *item = (AlLinkItem*)0 ); virtual ~AlList(); AlLinkItem* first( void ) const AlLinkItem* last( void ) const void append( AlLinkItem* ); int remove( AlLinkItem* ); void clear();

AlList | 601

Description
This simple container class provides the ability to create and access a list of objects derived from the AlLinkItem class.

AlList::AlList( AlLinkItem *item ) Description

Constructor for AlList class.

Arguments
< item - the first object to be added to the list

AlList::~AlList() Description
Destructor for AlList class.

AlLinkItem *AlList::first(void) Description

Returns the first AlLinkItem in the list.

AlLinkItem *AlList::last(void) Description

Returns the last AlLinkItem in the list.

void AlList::append( AlLinkItem *item ) Description

Adds an AlLinkItem object to the end of the list.

Arguments
< item - the object to be appended

602 | Chapter 3 AlDagNode AlLocator

int AlList::remove( AlLinkItem *item ) Description

Removes an AlLinkItem object from the AlList. Returns TRUE if the item was removed, FALSE if it was not (because it did not belong in this list).

Arguments
< item - the object to be appended

void AlList::clear() Description

Clears the list as an empty list but does not free any of its members.

AlLiveData
Utility functions for OpenAlias. These functions do not belong to a class.

AlLiveData | 603

Synopsis

604 | Chapter 3 AlDagNode AlLocator

#include <AlLiveData.h> Enumeration types: typedef enum { kFileBrowseRead, kFileBrowseWrite } AlFileBrowseMode; typedef enum { kOK_Cancel, kYes_No_Cancel, kOK_Only, kYes_No } AlConfirmType; typedef enum { kOK, kYes, kNo, kCancel } AlAnswerType; void AlAllowMenuRebuilds( boolean ); void AlRebuildMenus( void ); void AlResetAllMenus( void ); statusCode AlDebugResetOptionBox( const char * ); const char* AlInvokeSchemeCommand( const char * ); const char* AlInvokeSchemeFile( const char*, const char * = NULL ); statusCode AlFileBrowser( AlFileBrowseMode, char **, const char *, boolean, const char * ); statusCode AlFileBrowser( AlFileBrowseMode, char **, const char *, boolean, const char *, const char * ); boolean AlEscapeKeyPressed( void ); statusCode AlPromptBox( AlConfirmType, char*, AlAnswerType*, short, short ); statusCode AlScrollablePromptBox( AlConfirmType , char *, char *, AlAnswerType * ); statusCode AlStringPromptBox( AlConfirmType type, char *, AlAnswerType *,char *& ); statusCode AlGetInteger( const char *, int& ); statusCode AlGetDouble( const char *, double& ); statusCode AlGetString( const char *, const char *& ); statusCode AlSetInteger( const char *, int );

AlLiveData | 605

statusCode AlSetDouble( const char *, double ); statusCode AlSetString( const char *, const char* ); void AlPrintf( unsigned int, const char*, ... ); void AlVprintf( unsigned int, const char*, va_list ap ); char *makeAltPath(const char *dirName, const char *suffix);

Description
These functions are support functions for use with OpenAlias plug-ins.

void AlAllowMenuRebuilds( boolean on_or_off ) Description

Controls if AlRebuildMenus() will execute.

void AlRebuildMenus( void ) Description

Rebuilds the Alias menus.

void AlResetAllMenus( void ) Description

Forces a rebuild of all of the menus

const char* AlInvokeSchemeFile( const char * filename, const char *filenamePrefix ) Description
Executes a Scheme file and returns back the string from the execution. NULL is returned if the file could not be found. Usually an empty string indicates success. This routine will also search in a "scm" subdirectory for the filename. This feature allows existing plug-ins to keep working with the new "scm" subdirectory setup being used.

Arguments
< filename - the name of the file to execute < filenamePrefix - if not NULL, the pathname to prefix to the filename

606 | Chapter 3 AlDagNode AlLocator

Return Values
NULL - the file could not be found "" - the command succeeded

const char * AlInvokeSchemeCommand( const char *command ) Description

Executes a Scheme command. The string result is returned.

Arguments
< command - the command string to execute

statusCode AlGetInteger( const char * name, int& value ) Description

Retrieves the value of the named integer from the Scheme environment

Arguments
< name - the name of the Scheme variable > value - the returned value

Return Codes
sInvalidArgument - name was NULL sSuccess - the value was returned sFailure - the variable could not be found

statusCode AlGetDouble( const char * name, double& value ) Description

Retrieves the value of the named double from the Scheme environment

Arguments
< name - the name of the Scheme variable

AlLiveData | 607

> value - the returned value

Return Codes
sInvalidArgument - name was NULL sSuccess - the value was returned sFailure - the variable could not be found

statusCode AlGetString( const char * name, const char *& value ) Description
Retrieves the value of the named string from the Scheme environment. Note that as with all other strings in the API, this one must not be deleted.

Arguments
< name - the name of the Scheme variable > value - a pointer to the resulting string

Return Codes
sInvalidArgument - name was NULL sSuccess - the value was returned sFailure - the variable could not be found

statusCode AlSetInteger( const char *name, int val ) Description

Sets the value of the named integer in the Scheme environment.

Arguments
< name - the name of the Scheme variable < value - the int value

Return Codes
sSuccess - the value was set

608 | Chapter 3 AlDagNode AlLocator

sFailure - the variable could not be found

statusCode AlSetDouble( const char *name, double val ) Description

Sets the value of the named double in the Scheme environment.

Arguments
< name - the name of the Scheme variable < value - the double value

Return Codes
sSuccess - the value was set sFailure - the variable could not be found

statusCode AlSetString( const char *name, const char *val ) Description

Sets the value of the named string in the Scheme environment.

Arguments
< name - the name of the Scheme variable < value - a pointer to the string value

Return Codes
sSuccess - the value was set sFailure - the variable could not be found

const char * AlGetAliasPreference( const char * pref ) Description

Gets the Alias preference (from the .AliasPrefs file) associated with the string passed in. The returned value is the value of the preference, or NULL if the given entry does not exist. The string returned does not have to be deallocated.

AlLiveData | 609

statusCode AlPromptBox( AlConfirmType type, char *msg, AlAnswerType* answer,short x, short y ) Description
Invokes a dialog box, prompting the user for confirmation. The width of the dialog box is set to accommodate the longest sentence in the specified message (msg). Sentences in 'msg' should be delineated by new-line characters (that is, '\n'). To invoke the dialog box at the current cursor location, pass in -1 and -1 for x and y.

Arguments
< type - the type of prompt box to create < msg - the text to place in the prompt box > answer - a code for which button was pressed < x - the x location for the confirm box < y - the y location for the confirm box

Return Codes
sSuccess - the confirm box executed successfully sFailure - the confirm box failed to execute successfully. Note that in this case, the value of answer is undefined.

statusCode /*::*/ AlScrollablePromptBox( AlConfirmType type, char *msg, char *scrollMsg, AlAnswerType *answer ) Description
Bring up a dialog box, prompting the user for confirmation. The width of the confirm box will be set to accommodate the longest sentence in staticMsg. Sentences in staticMsg should be delineated by new-line characters, that is, \n. A scrollable widget will contain the text of scrollMsg. Sentences in scrollMsg should also be delineated with new-line characters. The width of the scrollable widget is fixed and does not grow with the size of the confirm box. The dialog box will come up at the current cursor location. Use this method to display short fixed messages above a longer free-form message.

610 | Chapter 3 AlDagNode AlLocator

Arguments
< type - the type of prompt box to create < staticMsg - the static text to place in the prompt box < scrollMsg - the scrollable text to place in the prompt box > answer - a code for which button was pressed

Return Codes
sSuccess - the confirm box executed successfully sFailure - the confirm box failed to execute successfully. This could be due to being too early in Alias initialization state as plug-ins are autoloading. Note: the value of answer is undefined. sInvalidArgument - null parameter enter

statusCode /*::*/ AlStringPromptBox( AlConfirmType type,char *msg, AlAnswerType *answer, char *& msgResponse ) Description
Bring up a dialog box which allows the user to prompt for a user string response. Instructions to the user can be specified with the msg parameter. Notes: 1. The dialog box will come up at the current cursor location. 2. The msgResponse string is owned by Alias and should not be freed by the API application. 3. If several calls to this function will be done one after the other, then the msgResponse should be copied since it will be overwritten in the following call.

Arguments
< type - the type of prompt box to create < msg - static text information for the user > answer - a code for which button was pressed > msgResponse - the text that the user entered

AlLiveData | 611

Return Codes
sSuccess - the confirm box executed successfully sFailure - the confirm box failed to execute successfully. This could be due to being too early in Alias initialization state as plug-ins are autoloading. Note: the value of answer is undefined. sInvalidArgument - msg is NULL or answer is NULL

statusCode AlDebugResetOptionBox( const char *editorName ) Description

Resets the editor option box. It is intended to be used by people who modify the option box and want to see the changes (that is, debugging). This may create a severe memory leak.

Arguments
< editorName - the name of the editor to reset

Return Codes
sSuccess - the editor was reset sFailure - the editor could not be reset

statusCode AlFileBrowser( AlFileBrowseMode mode, char **returnFilename, const char *acceptString, boolean showSample, const char *fileExtension ) Description
Prompts the user with a file browser to select a filename. If the mode is kFileBrowseWrite, then the browser will prompt the user with a blank filename. The browser will allocate a string (using strdup) for the return filename and point returnFilename to it. It is up to the caller to free it, using free(). The acceptString is the text that is printed on the accept button. This will be a string such as "Load", "Okay", "Accept" and so on.

612 | Chapter 3 AlDagNode AlLocator

Example code char *filename; statusCode stat = AlFileBrowser( kFileBrowseRead, &filename, "Okay String", FALSE, "myextension" ); if( stat == sSuccess ) { .. do something with filename ... free( filename ); }

Arguments
< mode - this is either kFileBrowseRead or kFileBrowseWrite > returnFilename - address of the string pointer that is to be set to the file name < acceptString - the non-NULL string that is printed on the accept button < showSample - if TRUE, icon sized samples of the data files will be shown < fileExtension - the extension for the file. Setting this has no effect.

Return Codes
sInvalidArgument - an invalid argument was given sSuccess - a filename was selected (*returnFileName will point to the string) sFailure - an error occurred or no filename was selected

statusCode /*::*/ AlFileBrowser( AlFileBrowseMode mode, char **returnFilename, const char *acceptString, boolean showSample, const char *fileExtension, const char *defaultPath ) Description
Same as the other AlFileBrowser method with the addition that a defaultPath can be specified. If defaultPath is NULL or the length of defaultPath is greater than FILENAME_MAX, then sInvalidArgument will be returned.

boolean AlEscapeKeyPressed( void ) Description

Checks if the Escape key has been pressed. Can be used to allow the user to abort an operation.

AlLiveData | 613

Example code: for ( int i = 0; i < 40000; i++ ) { FractalImage( i ); if ( AlEscapeKeyPressed() ) sFailure; }

rebuild return

Return Values
TRUE - Escape key has been pressed FALSE - Escape key has not been pressed

char * makeAltPath(const char *dirName, const char *suffix) Description

Directory name utility for converting a path to a sibling directory. This function is used by plug-ins for finding sibling directories such as scm, help and so on. For example, makeAltPath ("/usr/aw/plugins/lib", "scm") will return "/usr/aw/plugins/scm".

Arguments
< dirName - plug-in path name < suffix - directory name of the sibling

AlLocator
Contains functionality common to all the Alias locators.

Synopsis
#include <AlLocator.h> class AlLocator : public AlObject virtual ~AlLocator(); virtual statusCode deleteObject(); virtual AlObject * copyWrapper() const = 0; virtual AlObjectType type() const; statusCode pick(); statusCode unpick(); statusCode isPicked(boolean &) const; statusCode templated(boolean &) const;

614 | Chapter 3 AlDagNode AlLocator

Description
This virtual class encapsulates methods common to all the Alias locators (spaceLocator, curveLocator, curveOnSurfaceLocator, surfaceLocator, annotationLocator, distanceLocator, angleLocator, radialLocator, deviation Locator and minmaxLocator) for picking and unpicking locators. This class also contains static methods for the display of all locators. To create a locator, the user must instantiate and call the create method of a specific type of locator (for example, a curve locator or a distance locator). The annotation, distance and angle locators depend on one or more point type locators, such as a curve locator. If a point locator is deleted, its dependent annotation, distance and angle locators are deleted. Similarly, the radial, deviation and minmax locators are dependent on other objects. If those objects are deleted, the dependent radial, deviation, and minmax locators are also deleted. The locator classes are derived as follows, where a class inherits the functionality defined in the class above it. The user can not instantiate the locator (AlLocator) and point locator (AlPointLocator) classes.

AlLocator::AlLocator(void) Description
Constructs an AlLocator wrapper object.

AlLocator::~AlLocator() Description
Deletes an AlLocator wrapper object.

statusCode AlLocator::deleteObject() Description

Deletes the locator wrapper.

Return Codes
sSuccess - the object was deleted sInvalidObject - the locator was invalid

AlLocator | 615

AlObjectType AlLocator::type() const Description

Returns the class identifier kLocatorType.

statusCode AlLocator::pick() Description

Picks a locator. The function does nothing if the locator is already picked. Similarly, unpick does nothing if the locator is unpicked.

Return Codes
sSuccess - the picking was successful sInvalidObject - the object is not valid

statusCode AlLocator::unpick() Description

Unpicks a locator. Unpick does nothing if the locator is already unpicked.

Return Codes
sSuccess - the unpicking was successful sInvalidObject - the object is not valid

statusCode AlLocator::isPicked(boolean &picked) const Description

Checks whether the locator is picked or unpicked.

Arguments
> picked - is set to true if the locator is picked, and set to false otherwise

Return Codes
sSuccess - the value was set successfully

616 | Chapter 3 AlDagNode AlLocator

sInvalidObject - the object is not valid

statusCode AlLocator::templated(boolean &tmpl) const Description

Checks whether the object on which a locator depends is templated. If a locator does not depend on any other object, the argument is set to false.

Arguments
> tmpl - is set to true if the object on which a locator depends is templated. Otherwise, tmpl is set to false

Return Codes
sSuccess - the value was set successfully sInvalidObject - the object is not valid

AlLocator | 617

618

AlMappedFieldItem AlRevSurfAttributes

AlMappedFieldItem
Items for maintaining texture mapped fields.

Synopsis
#include <AlMappedFieldItem.h> class AlMappedFieldItem : public AlLinkItem const char* field() const; AlMappedFieldItem* nextField() const; AlMappedFieldItem* prevField() const;

Description
This class is derived from the AlLinkItem class, and is used to maintain one element of a list of fields that may be texture mapped for a particular AlShader, AlTexture, or AlEnvironment.

const char* AlMappedFieldItem::field() const Description

Returns the character string identifier value identifying the field that may have a texture map applied. These identifiers are identical to those used by SDL, and the complete list can be found in the SDL manual.

619

AlMappedFieldItem* AlMappedFieldItem::nextField() const Description

Returns the next field in this list of fields. NULL may be returned if there is no next field.

AlMappedFieldItem* AlMappedFieldItem::prevField() const Description

Returns the prev field in this list of fields. NULL may be returned if there is no prev field.

AlMeasure
Support for measurement of distances between objects.

Synopsis
#include <AlMeasure.h> class AlMeasure static double minDist( AlSurface*, AlSurface*, double* = NULL, double* = NULL, double[]= NULL, double* = NULL, double* = NULL, double[] = NULL, int = 20, int = 20 ); static double minDist( AlSurface*, AlCurve*, double* = NULL, double* = NULL, double[] = NULL, double* t2=NULL, double[] = NULL, int = 100 ); static double minDist( AlSurface*, double[3], double* = NULL, double* = NULL, double[] = NULL); static double minDist( AlCurve*, AlCurve*, double* = NULL, double[] = NULL, double* = NULL, double[] = NULL, int = 100); static double minDist( AlCurve*, double[3], double* = NULL, double[] = NULL);

Description
The following are a series of overloaded functions named minDist(). These can be used to find the closest points between any two surfaces, curves, and/or points.

620 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

The minDist() functions will return a negative value if and only if the objects it is given do not exist. For the sake of continuity, the order of the two objects to be measured is always highest dimensionality to lowest.

double AlMeasure::minDist( AlSurface* surface1, AlSurface* surface2, double* u1, double* v1, double P1[], double* u2, double* v2, double P2[], int interval_u, int interval_v) Description
Determines the minimum distance between two AlSurfaces. Extra information about the points on each surface that are closest to each other is available. The accuracy of the search for the minimum distance is modifiable through the interval arguments.

Arguments
< surface1 - the first AlSurface < surface2 - the second AlSurface > u1, v1 - u,v values of the closest point on surface1 to surface2 > P1[3] - x,y,z values of the closest point on surface1 to surface2 > u2, v2 - u,v values of the closest point on surface2 to surface1 > P2[3] - x,y,z values of the closest point on surface2 to surface1 < interval_u - number of intervals into which surface1 will be split in the u direction (defines the accuracy of the search) < interval_v - number of intervals into which surface1 will be split in the v direction (defines the accuracy of the search)

Return Values
< 0 - one or both of the AlSurfaces were not valid => 0 - the distance between the two closest points

AlMeasure | 621

double AlMeasure::minDist( AlSurface* surface1, AlCurve* curve2, double* u1, double* v1, double P1[], double* t2, double P2[], int interval) Description
Determines the minimum distance between an AlSurface and an AlCurve. Extra information about the points on each object that are closest to each other is available. The accuracy of the search for the minimum distance is modifiable through the interval argument.

Arguments
< surface1 - the AlSurface < curve2 - the AlCurve > u1, v1 - u,v values of the closest point on surface1 to curve2 > P1[3] - x,y,z values of the closest point on surface1 to curve2 > t2 - t value of the closest point on curve2 to surface1 > P2[3] - x,y,z values of the closest point on curve2 to surface1 < interval - number of intervals into which curve2 will be split (defines the accuracy of the search)

Return Values
< 0 - either surface1 or curve2 was not valid => 0 - the distance between the two closest points

double AlMeasure::minDist( AlSurface* surface1, double P2[3], double* u1, double* v1, double P1[]) Description
Determines the minimum distance from an AlSurface and a point. Extra information about the point on the surface that is closest to the given point is available.

Arguments
< surface1 - the AlSurface < P2[3] - x,y,z values of the point

622 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

> u1, v1 - u,v values of the closest point on surface1 to P2 > P1[3] - x,y,z values of the closest point on surface1 to P2

Return Values
< 0 - surface1 was not a valid AlSurface => 0 - the distance between the two closest points.

double AlMeasure::minDist( AlCurve* curve1, AlCurve* curve2, double* t1, double P1[], double* t2, double P2[], int interval) Description
Determines the minimum distance between two AlCurves. Extra information about the points on each curve that are closest to each other is available. The accuracy of the search for the minimum distance is modifiable through the interval argument.

Arguments
< curve1 - the first AlCurve < curve2 - the second AlCurve > t1 - t value of the closest point on curve1 to curve2 > P1[3] - x,y,z values of the closest point on curve1 to curve2 > t2 - t value of the closest point on curve2 to curve1 > P2[3] - x,y,z values of the closest point on curve2 to curve1 < interval - number of intervals into which curve1 will be split (defines the accuracy of the search)

Return Values
< 0 - one or both of the AlCurves were not valid => 0 - the distance between the two closest points

AlMeasure | 623

double AlMeasure::minDist( AlCurve* curve1, double P2[3], double* t1, double P1[]) Description
Determines the minimum distance between an AlCurve and a point. Extra information about the point on the curve that is closest to the given point is available.

Arguments
< curve1 - the AlCurve < P2[3] - x,y,z values of the point > t1 - t value of the closest point on curve1 to P2 > P1[3] - x,y,z values of the closest point on curve1 to P2

Return Values
< 0 - curve1 is not a valid AlCurve => 0 - the distance between the two closest points.

AlMesh
Interface to Alias meshes.

624 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Synopsis
#include <AlMesh.h> class AlMesh : public AlObject AlMesh(); virtual ~AlMesh(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; AlMeshNode* meshNode() const; statusCode create( int numVertices, const float* vertices, int numTriangles, const int* triangles, const float* normals = 0, const float* uvs = 0); int numberOfVertices() const; int numberOfTriangles() const; const float* vertices() const; const int* triangles() const; const float* normals() const; const float* uvs() const; void uvRange( float* ) const; statusCode setUVRange( float * ); int drawFlag() const; API_BOOLEAN isDrawFlag( int ) const; statusCode setDrawFlag( int, bool ); statusCode setDrawFlag( int ); API_BOOLEAN isFlatShaded() const; statusCode setFlatShaded( bool ); float* affectedVertices( const AlTM& tm ); float* affectedNormals( const AlTM& tm ); statusCode removeDuplicateTris(); statusCode compact(); statusCode transform( double [4][4] ) const; statusCode boundingBox( double *min, double *max ) const; AlShader* firstShader() const; AlShader* nextShader( AlShader* ) const; statusCode nextShaderD( AlShader *) const; statusCode assignShader( AlShader* ); statusCode layerShader( AlShader* ); statusCode renderInfo( AlRenderInfo& ) const; statusCode setRenderInfo( const AlRenderInfo& ) const;

AlMesh | 625

Description
AlMesh is the interface to meshes and their data in Alias. This class lets a developer create and manipulate mesh objects. Data access methods to all properties are provided. The following properties are used throughout the mesh class. vertices Vertices are passed by this class using an array of floating point values. A vertex consists of three values; x,y,z respectively. Refer to the definition of triangles for a description of the relationship between vertices and triangles. numVertices The number of vertices is equivalent to the number of x,y,z triplets stored in the vertices array. The total number of floats in the vertices array is equivalent to three times the number of vertices. triangles Triangles are passed by this class using an array of integer values. A triangle consists of three integer indices. These indices reference a vertex in the vertices array such that vertices[3*index] returns the x coordinate of the vertex. Similarly, vertices[3*index+1] and vertices[3*index+2] return the y and z coordinate respectively. Indices are to be specified in counter clockwise order relative to the front of their face. numTriangles The number of triangles is equivalent to the number of integer triplets stored in the triangles array. The total number of integers in the triangles array is equivalent to three times the number of triangles. normals Normals are passed by this class using an array of floating point values. They consist of three values; x,y,z respectively. Normals are per vertex. They are referenced by triangles in the same manner that vertices are referenced. uvs UVs are passed by this class using an array of float values. They consist of two floating point values; u,v respectively. UVs are per vertex. They are referenced by triangles in the same manner that vertices are referenced.

AlMesh::AlMesh() Description
Constructs an AlMesh wrapper object.

AlMesh::~AlMesh() Description
Deletes an AlMesh wrapper object.

626 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlMesh::deleteObject() Description

This method deletes the AlMesh, and its parent AlMeshNode.

Return Codes
sSuccess - the mesh was deleted. sInvalidObject - the mesh was invalid.

AlObject * AlMesh::copyWrapper() const Description

Makes an exact copy of the AlMesh wrapper.

AlObjectType AlMesh::type() const Description

Returns the class identifier kMeshExtType.

AlMeshNode * AlMesh::meshNode() const Description

Returns a pointer to the AlMeshNode for this mesh. Returns NULL if there is not an attached mesh node.

statusCode AlMesh::create( int numVertices, const float* vertices, int numTriangles, const int* triangles, const float* normals, const float* uvs) Description
Creates a mesh object with the supplied data. The user This is expected to allocate memory and seed data for the various arrays. Refer to the description of this class for detailed information on the arguments passed. Passing a uv array is optional. Passing a normal array is optional. Note that normals are recalculated as the mesh is changed.

AlMesh | 627

Return Codes
sSuccess - The mesh was successfully created. sInsufficientMemory - Sufficient memeory for the provided mesh could not be allocated. sFailure - Failed to complete request. This result may occur because of insufficient memory.

int AlMesh::numberOfVertices() const Description

Returns the number of vertices currently stored in the mesh. The function will return -1 if the mesh was not created properly.

int AlMesh::numberOfTriangles() const Description

Returns the number of triangles currently stored in the mesh. The function will return -1 if the mesh was not created properly.

const float * AlMesh::vertices() const Description

Returns a const pointer to the mesh's vertex data. The function will return 0 if the mesh was not created properly. Refer to the description of this class for more information.

const int * AlMesh::triangles() const Description

Returns a const pointer to the mesh's triangle data. The function will return 0 if the mesh was not created properly. Refer to the description of this class for more information.

628 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

const float * AlMesh::normals() const Description

Returns a const pointer to the mesh's normal data. The function will return 0 if the mesh was not created properly. Refer to the description of this class for more information.

const float * AlMesh::uvs() const Description

Returns a const pointer to the mesh's uv data. The function will return 0 if the mesh was not created properly. Refer to the description of this class for more information.

void AlMesh::uvRange( float* range ) const Description

Stores the uv range of the mesh in 'range'. 'range' is an array with four elements; minu, minv, maxu, maxv respectively.The function will return if the mesh was not created properly leaving 'range' unaltered.

statusCode AlMesh::setUVRange( float *uvrange ) Description

Sets the uv range of the mesh. 'uvrange' is an array with four elements; minu, minv, maxu, maxv respectively.

Return Codes
sSuccess - The range was properly set. sInvalidObject - Returned if uvrange is 0 or the mesh was not created properly. sFailure - Unable to process request.

AlMesh | 629

int AlMesh::drawFlag() const Description

Returns the mesh's draw flags. The function will return 0 if the mesh was not created properly.

boolean AlMesh::isDrawFlag( int flag ) const Description

Returns TRUE if 'flag' is set in the mesh's draw flag. FALSE otherwise. The function will return FALSE if the mesh was not created properly.

statusCode AlMesh::setDrawFlag( int flag, bool on ) Description

Sets the 'flag' bit to the value of 'on' in the mesh's draw flag.

Return Codes
sSuccess - The flag was properly set. sInvalidObject - The mesh was not created properly. sFailure - Unable to process request.

statusCode AlMesh::setDrawFlag( int flag ) Description

Directly assigns 'flag' to the mesh's draw flag.

Return Codes
sSuccess - The flag was properly set. sInvalidObject - The mesh was not created properly. sFailure - Unable to process request.

630 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

boolean AlMesh::isFlatShaded() const Description

Returns TRUE if the mesh is flat shaded. FALSE otherwise. The function will return FALSE if the mesh was not created properly.

statusCode AlMesh::setFlatShaded( bool flat ) Description

Sets the mesh's flat shading property to the value of 'flat'.

Return Codes
sSuccess - Flat shading was properly set. sInvalidObject - The mesh was not created properly. sFailure - Unable to process request.

statusCode AlMesh::transform( double tm[4][4] ) const Description

Transforms the mesh by the matrix 'tm'.

Return Codes
sSuccess - The mesh was properly transformed. sInvalidObject - The mesh was not created properly. sFailure - Unable to process request.

statusCode AlMesh::removeDuplicateTris() Description

Removes duplicate triangles from the mesh.

Return Codes
sSuccess - Duplicate triangles were removed successfully. sInvalidObject - The mesh was not created properly.

AlMesh | 631

sFailure - Unable to process request.

float * AlMesh::affectedVertices( const AlTM& tm ) Description

Returns a pointer to a float array of affected vertices. Refer to vertices in the description of this class for more information on the format of the array. The function will return 0 if the mesh was not created properly.

float * AlMesh::affectedNormals( const AlTM& tm ) Description

Returns a pointer to a float array of affected normals. Refer to normals in the description of this class for more information on the format of the array. The function will return 0 if the mesh was not created properly.

statusCode AlMesh::compact() Description

This algorithm compacts the mesh by eliminating numerically identical vertices. This algorithm is useful when processing STL files, which duplicate vertex coordinates for adjacent triangles.

Return Codes
sSuccess - The mesh was successfully compacted. sInvalidObject - The mesh was not created properly. sFailure - Unable to process request.

statusCode AlMesh::boundingBox( double *min, double *max ) const Description

Retrieves the bounding box of the mesh. The 'min' and 'max' arguments are arrays that contain the min or max x,y,z values respectively.

Return Codes
sSuccess - The bounding box was successfully sent to minimum and maximum.

632 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

sInvalidObject - The mesh was not created properly. The arguments remain unaltered. sFailure - Unable to process request. The arguments remain unaltered.

AlShader * AlMesh::firstShader() const Description

Returns the first shader that this mesh object references. The function will return 0 if there are no shaders or the mesh was not created properly.

AlShader * AlMesh::nextShader( AlShader* shader ) const Description

Returns the shader after the one specified by 'shader'. The function will return 0 if:

the end of the shading list has been reached. the argument, 'shader', is 0. the mesh was not created properly. there are no shaders.

statusCode AlMesh::nextShaderD( AlShader* shader ) const Description

Destructively points the argument 'shader' to the shader that follows.

Return Codes
sSuccess - The 'shader' was properly set to the next shader in the list. sFailure - Unable to process request. Refer to AlMesh::nextShader for possible reasons for a failure.

statusCode AlMesh::assignShader( AlShader* shader ) Description

Assigns 'shader' to the mesh.

AlMesh | 633

Return Codes
sSuccess - The shader was successfully assigned to the mesh. sInvalidArgument - 'shader' is invalid. sInvalidObject - The mesh was not created properly. sFailure - Unable to process request.

statusCode AlMesh::layerShader( AlShader* shader ) Description

Layers the 'shader' on the mesh.

Return Codes
sSuccess - the shader was successfully layered on the mesh. sInvalidArgument - 'shader' is invalid. sInvalidObject - The mesh was not created properly. sFailure - Unable to process request.

statusCode AlMesh::renderInfo( AlRenderInfo& renderInfo ) const Description

Fills in 'renderInfo' with the render info for this mesh.

Return Codes
sSuccess - 'renderInfo' was properly set. sInvalidArgument - 'renderInfo' is NULL. sInvalidObject - The mesh was not created properly. sFailure - Unable to process request.

statusCode AlMesh::setRenderInfo( const AlRenderInfo& renderInfo ) const Description

Sets the render info for this mesh to the contents of 'renderInfo'.

634 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Return Codes
sSuccess - The mesh's render info was properly set. sInvalidArgument - 'renderInfo' is NULL or a parameter in renderInfo is out of range. sInvalidObject - The mesh was not created properly. sFailure - Unable to process request.

AlMeshNode
A DAG node that refers to a mesh's geometry.

Synopsis
#include <AlMeshNode.h> class AlMeshNode : public AlDagNode virtual ~AlMeshNode(); virtual AlObject *copyWrapper() const; virtual AlObjectType type() const; AlMesh* mesh() const; AlPolysetNode* copyAsPolyset() const;

Description
AlCurveNode is the class used to access and manipulate meshes within the dag. This class behaves like other dag nodes (see AlDagNode for a description of the usage and purpose of dag nodes). Users access the geometry of the curve via the 'mesh()' method which returns a pointer to an AlMesh object.

AlMeshNode::~AlMeshNode() Description
Deletes an AlMeshNode wrapper object. Note that this destructor will not delete the associated mesh. To properly remove a node/geometry from the DAG use AlDagNode::deleteObject().

AlMeshNode | 635

AlObject * AlMeshNode::copyWrapper() const Description

Makes an exact copy of the AlMeshNode wrapper.

AlObjectType AlMeshNode::type() const Description

Returns the class identifier kMeshNodeType.

AlMesh * AlMeshNode::mesh() const Description

Returns a pointer to the AlMesh data structure, which can be used to access the geometry of the mesh.

AlMessage
Encapsulates the handling of object messages.

636 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Synopsis
#include <AlMessage.h> class AlMessageTypeHandle AlMessageTypeHandle( void ); AlMessageTypeHandle( const AlMessageTypeHandle& ); ~AlMessageTypeHandle(); AlMessageTypeHandle& operator =( const AlMessageTypeHandle& ); boolean isValid( void ) const; int type( void ) const; statusCode setPrologue( int (*)( int, void * ) ); statusCode setEpilogue( int (*)( int, void * ) ); statusCode addLock( boolean& ); statusCode setAddLock( boolean ); statusCode sendLock( boolean& ); statusCode setSendLock( boolean ); class AlMessage enum AlPriorityType { kImmediate, kQueue, kIdleQueue }; static statusCode addMessageHandler( int, void * ); static statusCode removeMessageHandler( int, void * ); static AlMessageTypeHandle addMessageType( const char * ); static int getMessageType( const char * ); static statusCode sendMessage( int, void*, AlPriorityType = kImme diate );

Description
This file contains the definitions required to handle object messages for Alias objects. A message handler is a user supplied function that is called when an event occurs. A message handler is installed using the AlMessage::addMessageHandler() function. Below is a sample message handler to handle the deleting of DagNodes:
void myDagNodeDeleteHandler( int msgtype, AlDagNode *dagnode ) { do_something_before_its_deleted( dagnode ); }

AlMessage | 637

To install the handler into the universe, the following function call would be made in the applications initialization code:
AlMessage::addMessageHandler( kMessageDagNodeDeleted, myDagNodeDeleteHandler );

If either Alias or the application deletes a DAG node by using AlDagNode.deleteObject(), the message handler will be called with a pointer to the dagnode before the dagnode is removed. In addition to being able to receive standard messages from inside Alias, it is possible to define custom message types that extend the default set. Of course, Alias has no prior knowledge of these new types, so hooks cannot be added into existing code to send new messages, but plug-ins can define messages that can then be received by either the same plug-in, or different plug-ins altogether.This allows a collaborative paradigm between plug-ins, such as sharing code or data. To create a custom message type, call AlMessage::addMessageType. You must supply a name for this type, which is then used by others to find the type. You are returned an AlMessageTypeHandle, a receipt which the creator of the message type can then use to define specific properties of the message type. In particular, the owner can lock a message type against the addition of handlers, lock the type against the sending of messages, and set prologue and epilogue functions, which get called before and after the sending of a message. See the documentation for the individual member functions for more details. Note that while a method is supplied to send a message, this method applies only to user-defined messages. Predefined Alias messages cannot be sent.

AlMessageTypeHandle::AlMessageTypeHandle( void ) Description

Default constructor.

AlMessageTypeHandle::AlMessageTypeHandle( const AlMessageTypeHandle& h ) Description

Copy constructor.

638 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlMessageTypeHandle::~AlMessageTypeHandle() Description
Destructor.

AlMessageTypeHandle& AlMessageTypeHandle::operator =(const AlMessageTypeHandle& h ) Description

Assignment operator.

int AlMessageTypeHandle::type( void ) const Description

Returns the integer type associated with this message type. This is the equivalent of calling AlMessage::getMessageType with the name of the message type. This type can then be used to send messages.

boolean AlMessageTypeHandle::isValid( void ) const Description

Determines whether the given AlMessageTypeHandle represents a valid message type. This function should be called to verify that a call to AlMessage::addMessageType succeeded.

statusCode AlMessageTypeHandle::setPrologue( int (*func)( int, void * ) ) Description

Sets the prologue function for this message type. The holder of the AlMessageTypeHandle is allowed to define a function which gets called before any of the message handlers are called. If the prologue returns a non-zero value, the message handlers will not be called at all.

Arguments
< func - A pointer to the function to use as the prologue, or NULL to turn off the prologue

AlMessage | 639

statusCode AlMessageTypeHandle::setEpilogue( int (*func)( int, void * ) ) Description

Like the setPrologue, this allows the creator of the message type to set a function that gets called after the message handlers are all called.

statusCode AlMessageTypeHandle::addLock( boolean& b ) Description

Message types can be locked by the creator against the adding of handlers. This allows the creator to control who is able to receive the given message type. This function places the current state of the add lock into the passed-in argument.

statusCode AlMessageTypeHandle::setAddLock( boolean b ) Description

Sets the add lock for this message type.

statusCode AlMessageTypeHandle::sendLock( boolean& b ) Description

Message types can be locked by the creator against the sending of messages. This allows the creator to control who is able to send a message of the given type. This function places the current state of the send lock into the passed-in argument.

statusCode AlMessageTypeHandle::setSendLock( boolean b ) Description

Sets the send lock for this message type.

640 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlMessage::addMessageHandler( int msg, void * func ) Description

Adds a message handler for the given message type. Only certain message types will actually be recognized and allowed for external use. Some message types simply do not make sense in OpenModel.

Arguments
< msg - The type of the message for which to install a handler. For a list of types, see the AlMessage on page 636 type enumerated type. < func - A pointer to the function to install as a handler. Ensure the argument list of the handler matches this message type!

Return Codes
sSuccess - handler installed successfully sFailure - invalid message type, or installation of a duplicate handler sInsufficientMemory - not enough memory

Comments
Below is a list of prototypes to use for the handler function for the various message types.
Message Handler prototype (see AlMessage.h)

kMessageAnimPlayback

AlCallbackInt

kMessageAttributesDelete

AlCallbackAttributes

kMessageCameraModified

AlCallbackOneCamera

kMessageClMemberModified

AlCallbackOneDagNode

kMessageCloudDeleted

AlCallbackOneCloud

AlMessage | 641

kMessageCnetDeleted

--- (*)

kMessageCommandFree

--- (*)

kMessageCommandInstall

--- (*)

kMessageCommandUnInstall

--- (*)

kMessageCosDeleted

AlCallbackCurveOnSurface

kMessageCosModified

AlCallbackCurveOnSurface

kMessageCosVisible

AlCallbackCurveOnSurface

kMessageTextureModified

AlCallbackOneTexture

kMessageTextureAdded

AlCallbackOneTexture

kMessageTextureDeleted

AlCallbackOneTexture

kMessageShaderAdded

AlCallbackOneShader

kMessageShaderDeleted

AlCallbackOneShader

kMessageDagInserted

AlCallbackOneDagNode

kMessageDagNameModified

AlCallbackOneDagNode

kMessageDagNodeApplyTransform ation

AlCallbackDagNodeAndMatrix

kMessageDagNodeDeleted

AlCallbackOneDagNode

642 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

kMessageDagNodeInstanced

AlCallbackTwoDagNodes

kMessageDagNodeModified

AlCallbackOneDagNode

kMessageDagNodeModifiedCon straint

AlCallbackOneDagNode

kMessageDagNodeModifiedGeo metry

AlCallbackOneDagNode

kMessageDagNodePreReplaceGeo metry

AlCallbackOneDagNode

kMessageDagNodeReplaceGeo metry

AlCallbackOneDagNode

kMessageDagNodeVisible

AlCallbackOneDagNode

kMessageDeleteAll

AlCallbackInt

kMessageExprModified

AlCallbackOneDagNode

kMessageHierarchyModified

AlCallbackOneDagNode

kMessageJointModified

AlCallbackOneDagNode

kMessageLightModified

AlCallbackOneLight

kMessageListModifiedNodes

AlCallbackPickListModified (1)

kMessagePickListModified

AlCallbackVoid

kMessagePlotRefresh

--- (*)

AlMessage | 643

kMessagePostRetrieve

AlCallbackVoid

kMessagePostStore

AlCallbackVoid

kMessagePostUpdate

AlCallbackInt

kMessagePreRefresh

AlCallbackVoid

kMessagePreRetrieve

AlCallbackString

kMessagePreStore

AlCallbackStringInt

kMessagePreUpdate

AlCallbackInt

kMessageQuit

AlCallbackVoid

kMessageRefresh

--- (*)

kMessageStageActive

AlCallbackVoid

kMessageStageCreated

AlCallbackVoid

kMessageStageDeleted

AlCallbackVoid

kMessageStageMerged

AlCallbackVoid

kMessageTrimSurface

AlCallbackSurface

kMessageUntrimSurface

AlCallbackSurface

kMessageUpdate

AlCallbackUpdate

For custom message types, the type of the function is always the same

644 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

void (*)( int type, void * data )

where type is the type of the message and data is the data to send with the message.

Notes
(*) not currently available (1) see the AlNotifyDagNode on page 663 class for documentation

statusCode AlMessage::removeMessageHandler( int msg, void * func ) Description

Removes the callback handler corresponding to func, if it exists.

Arguments
< msg - the type of the message for which func was installed. For a list of types, see the AlMessage on page 636Type enumerated type. < func - a pointer to the function to attempt to remove

Return Codes
sSuccess - handler removed successfully sInvalidArgument - invalid message type, or handler does not exist

AlMessageTypeHandle AlMessage::addMessageType( const char * name ) Description

Creates a custom message type. Calling this function introduces a new message type of the given name into Alias, provided a message type of that name does not already exist. The caller is returned a receipt which can then be used to fine-tune the message-passing capabilities of this message type (see AlMessage on page 636TypeHandle).

AlMessage | 645

int AlMessage::getMessageType( const char * name ) Description

Searches the list of existing custom named message types for the given name. If a message type of that name is found, its number is returned, which can then be used to send and receive messages of that type. Otherwise, this function returns -1.

statusCode AlMessage::sendMessage( int type, void *data,AlMessage::AlPriorityType p ) Description

Sends a message.

Arguments
< type - The type of the message to send. The type must correspond to a custom message type. < data - The data to send with the message. All the message handlers in the message types list will receive a pointer to this data when the message is sent. < p - The priority of the message. Messages marked kImmediate will be sent immediately - that is, through function call. kQueue messages go into Aliass internal event queue, and the message handlers will all be queued when the event corresponding to sending the message is processed. kIdleQueue messages go into Aliass internal idle queue. Messages in the idle queue get processed when Alias is waiting for events. Note that only kImmediate is available in OpenModel.

AlMinmaxLocator
An interface to Alias Min Max locators.

646 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Synopsis
#include <AlMinmaxLocator.h> class AlMinmaxLocator : public AlLocator AlMinmaxLocator(); virtual ~AlMinmaxLocator(); virtual AlObject * copyWrapper() const; virtual AlObjectType type() const; statusCode create(const AlCurve *, const AlCurve *); statusCode create(const AlCurve *, const AlCurveOnSurface *); statusCode create(const AlCurveOnSurface *, const AlCurveOnSurface *); statusCode create(const AlSurface *, const AlSurface *); statusCode create(const AlCurve *, const AlSurface *); statusCode create(const AlCurveOnSurface *, const AlSurface *); statusCode setCombDisplay (boolean) ; statusCode combDisplay (boolean &) const; statusCode setCombScale (double) ; statusCode combScale (double &) const; statusCode setCombThreshold (double) ; statusCode combThreshold (double &) const; statusCode setCombDensity (double) ; statusCode combDensity (double &) const; statusCode minimumDistance (double &) const; statusCode maximumDistance (double &) const; statusCode setLeftJustifyMinDistance(boolean); statusCode leftJustifyMinDistance(boolean &) const; statusCode setLeftJustifyMaxDistance(boolean); statusCode leftJustifyMaxDistance(boolean &) const; statusCode attachedTo( AlObject *&, AlObject *& );

Description
A min max locator finds and displays the minimum and maximum distance between any two of: curves, curves on surface, or surfaces. This class contains methods to create, query the distance and set the display attributes in the Alias windows.

AlMinmaxLocator::AlMinmaxLocator(void) Description
Constructs an AlMinmaxLocator wrapper object.

AlMinmaxLocator | 647

AlMinmaxLocator::~AlMinmaxLocator() Description
Deletes an AlMinmaxLocator wrapper object.

AlObject *AlMinmaxLocator::copyWrapper() const Description

Returns an exact copy of the AlMinmax wrapper.

AlObjectType AlMinmaxLocator::type() const Description

Returns the class identifier kMinmaxLocatorType.

statusCode AlMinmaxLocator::create(const AlCurve *curve1, const AlCurve *curve2) Description

Creates a Minmax locator between two curves.

Arguments
< curve1 - the first curve < curve2 - the second curve

Return Codes
sSuccess - the minmax locator was created sFailure - the minmax locator was not created sInvalidArgument - either one or both curves were invalid sAlreadyCreated - object has already been created

648 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlMinmaxLocator::create(const AlCurveOnSurface *curve1, const AlCurveOnSurface *curve2) Description

Creates a Minmax locator between two curves on surface.

Arguments
< curve1 - the first curve on surface < curve2 - the second curve on surface

Return Codes
sSuccess - the minmax locator was created sFailure - the minmax locator was not created sInvalidArgument - either one or both curves on surface were invalid sAlreadyCreated - object has already been created

statusCode AlMinmaxLocator::create(const AlCurve *curve1, const AlCurveOnSurface *curve2) Description

Creates a Minmax locator between a curve and a curve on surface.

Arguments
< curve1 - the first curve < curve2 - the second curve on surface

Return Codes
sSuccess - the minmax locator was created sFailure - the minmax locator was not created sInvalidArgument - either one or both curves were invalid sAlreadyCreated - object has already been created

AlMinmaxLocator | 649

statusCode AlMinmaxLocator::create(const AlSurface *surface1, const AlSurface *surface2) Description

Creates a Minmax locator between two surfaces.

Arguments
< surface1 - the first surface < surface2 - the second surface

Return Codes
sSuccess - the minmax locator was created sFailure - the minmax locator was not created sInvalidArgument - either one or both surfaces were invalid sAlreadyCreated - object has already been created

statusCode AlMinmaxLocator::create(const AlCurve *curve1, const AlSurface *surface2) Description

Creates a Minmax locator between a curve and a surface.

Arguments
< curve1 - the first curve < surface2 - the second surface

Return Codes
sSuccess - the minmax locator was created sFailure - the minmax locator was not created sInvalidArgument - either one or both curves or surfaces were invalid sAlreadyCreated - object has already been created

650 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlMinmaxLocator::create(const AlCurveOnSurface *curve1, const AlSurface *surface2) Description

Creates a Minmax locator between a curve on surface and a surface.

Arguments
< curve1 - the first curve on surface < surface2 - the second surface

Return Codes
sSuccess - the minmax locator was created sFailure - the minmax locator was not created sInvalidArgument - either one or both curves or surfaces were invalid sAlreadyCreated - object has already been created

statusCode AlMinmaxLocator::setCombDisplay(boolean display) Description

Sets the display of comb in the Alias modeling window for the Minmax locator.

Arguments
< display - a value of true sets comb display and false turns the display off

Return Codes
sSuccess - the display mode was set successfully sInvalidObject - the object is not valid

statusCode AlMinmaxLocator::combDisplay(boolean &display) const Description

Determines whether the comb of the Minmax locator is displayed in the Alias modeling windows.

AlMinmaxLocator | 651

Arguments
> display - it is true if the comb is displayed, false otherwise

Return Codes
sSuccess - the display mode was found sInvalidObject - the object is not valid

statusCode AlMinmaxLocator::setCombScale(double scale) Description

Sets the scale of the comb display for Minmax locator in the Alias modeling window.

Arguments
< scale - the scale of the comb display

Return Codes
sSuccess - the scale of the comb was set successfully sInvalidObject - the object is not valid

statusCode AlMinmaxLocator::combScale(double &scale) const Description

Finds the scale of the comb display for Minmax locator in the Alias modeling windows.

Arguments
> scale - the scale of the comb display

Return Codes
sSuccess - the comb scale was found sInvalidObject - the object is not valid

652 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlMinmaxLocator::setCombThreshold(double threshold) Description

Sets the threshold of the comb display for Minmax locator in the Alias modeling window.

Arguments
< threshold - the threshold of the comb display

Return Codes
sSuccess - the threshold of the comb was set successfully sInvalidObject - the object is not valid

statusCode AlMinmaxLocator::combThreshold(double &threshold) const Description

Finds the threshold of the comb display for Minmax locator in the Alias modeling windows.

Arguments
> threshold - the threshold of the comb display

Return Codes
sSuccess - the comb threshold was found sInvalidObject - the object is not valid

statusCode AlMinmaxLocator::setCombDensity(double density) Description

Sets the density of the comb display for Minmax locator in the Alias modeling window.

Arguments
< density - the density of the comb display

AlMinmaxLocator | 653

Return Codes
sSuccess - the density of the comb was set successfully sInvalidObject - the object is not valid

statusCode AlMinmaxLocator::combDensity(double &density) const Description

Finds the density of the comb display for Minmax locator in the Alias modeling windows.

Arguments
> density - the density of the comb display

Return Codes
sSuccess - the comb density was found sInvalidObject - the object is not valid

statusCode AlMinmaxLocator::minimumDistance(double &dist) const Description

Finds the minimum distance for the Minmax locator.

Arguments
> dist - the minimum distance

Return Codes
sSuccess - the minimum distance was found sInvalidObject - the object is not valid

statusCode AlMinmaxLocator::maximumDistance(double &dist) const Description

Finds the maximum distance for the Minmax locator.

654 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Arguments
> dist - the maximum distance

Return Codes
sSuccess - the maximum distance was found sInvalidObject - the object is not valid

statusCode AlMinmaxLocator::setLeftJustifyMinDistance(boolean leftJustify) Description

Sets the justification of the text for the minimum distance for minmax locator. The text can be right justified or left justified.

Arguments
< leftJustify - a value of true makes the text left justified and a value false makes it right justified

Return Codes
sSuccess - setting was successful sInvalidObject - the object is not valid

statusCode AlMinmaxLocator::leftJustifyMinDistance(boolean &leftJustify) const Description

Finds whether the text of minimum distance in minmax locator is left justified or right justified.

Arguments
> leftJustify - a value of true indicates that it is left justified and false indicates that it is right justified.

AlMinmaxLocator | 655

Return Codes
sSuccess - the justification was found sInvalidObject - the object is not valid

statusCode AlMinmaxLocator::setLeftJustifyMaxDistance(boolean leftJustify) Description

Sets the justification of the text for the maximum distance for minmax locator. The text can be right justified or left justified.

Arguments
< leftJustify - a value of true makes the text left justified and a value false makes it right justified

Return Codes
sSuccess - setting was successful sInvalidObject - the object is not valid

statusCode AlMinmaxLocator::leftJustifyMaxDistance(boolean &leftJustify) const Description

Finds whether the text of maximum distance in minmax locator is left justified or right justified.

Arguments
> leftJustify - a value of true indicates that it is left justified and false indicates that it is right justified

Return Codes
sSuccess - the justification was found sInvalidObject - the object is not valid

656 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlMinmaxLocator::attachedTo( AlObject *& objectOne, AlObject *& objectTwo ) Description

Returns the objects that are used to create the min/max locator. The objects returned can be curves on surfaces, curve nodes or surface nodes.

Arguments
> objectOne, objectTwo - attached to objects

Return Codes
sSuccess - the attached to objects were found sInvalidObject - the object is not valid sFailure - the method failed

AlMotionAction
Basic interface to derived class of actions for motion path actions.

Synopsis
#include <AlMotionAction.h> class AlMotionAction : public AlAction AlMotionAction(); virtual ~AlMotionAction(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; statusCode create(AlCurveNode *); AlCurveNode* motionCurve() const;

Description
An AlMotionAction is derived from an AlAction. This particular kind of action uses an AlCurve (a 3-D NURBS curve) to evaluate itself at different times. The AlMotionAction is defined over the range of 0 to 100 (the pre- and post-extrapolation types of the action apply to the evaluation of times before 0 and after 100). An AlMotionAction is evaluated by interpreting the "time" between 0 and 100 as a percentage arc length along the AlCurve used by this

AlMotionAction | 657

action. This results in an (x, y, z) point on the curve from which one of the components is extracted into a double value using an "extract" component. When this action is used in a channel, the channel will also supply an "extract" component (kX_COMPONENT, kY_COMPONENT or kZ_COMPONENT) to determine which of the (x, y, z) values to use as the final evaluation of the action. In order to create an AlMotionAction, you must have a valid AlCurveNode with an AlCurve below it. If you delete the AlMotionAction, the AlCurveNode will not be deleted. However, if you delete the AlCurveNode (or the AlCurve below the curve node), this will delete the AlMotionAction that uses that AlCurveNode.

AlMotionAction::AlMotionAction() Description
Constructs an AlMotionAction wrapper object. Use the create() method to initialize the AlMotionAction.

AlMotionAction::~AlMotionAction() Description
Deletes an AlMotionAction wrapper object.

AlObject * AlMotionAction::copyWrapper() const Description

Returns an exact duplicate of this AlMotionAction wrapper.

statusCode AlMotionAction::create(AlCurveNode *path) Description

Creates a motion path action that uses the curve below the specified AlCurveNode as its path. The path curve must already be a valid, created curve. It cannot be a face. The curve or any of its ancestor DAG nodes must not be animated.

658 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Arguments
< path - the node above the curve to use for the motion path

Return Codes
sSuccess - motion path action was successfully created sFailure - the curve is animated and cannot be used as a motion path action sInvalidArgument - path was not valid sInsufficientMemory - not enough memory

AlObjectType AlMotionAction::type() const Description

Returns the class identifier kMotionActionType.

AlCurveNode* AlMotionAction::motionCurve() const Description

Returns the curve node above the curve that this action uses as a motion path.

AlNameItem
List items used for lists of names (strings).

Synopsis
#include <AlNameItem.h> class AlNameItem : public AlLinkItem AlNameItem( const char * ); virtual ~AlNameItem(); const char* name() const; AlNameItem* nextItem() const; AlNameItem* prevItem() const;

AlNameItem | 659

Description
This class is derived from the AlLinkItem class, and is used to maintain one element of a list of names.

AlNameItem::AlNameItem( const char * name ) Description

Constructor.

AlNameItem::~AlNameItem() Description
Destructor.

const char * AlNameItem::name() const Description

Gets the name.

AlNameItem* AlNameItem::nextItem() const Description

Gets the next item in the list.

AlNameItem* AlNameItem::prevItem() const Description

Gets the previous item in the list.

AlNonAmbientLight
Contains functionality common to non-ambient lights.

660 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Synopsis
#include <AlNonAmbientLight.h> class AlNonAmbientLight: public AlLight virtual ~AlNonAmbientLight(); virtual AlObject* copyWrapper() const = 0; AlObjectType type() const; double intensity() const; int decay() const; boolean shadows() const; statusCode setIntensity( double ); statusCode setDecay( int ); statusCode setShadows( boolean );

Description
This virtual class encapsulates all methods that are common to non-ambient lights such as point, directional, spot, linear, and area lights. All non-ambient lights have variable intensity and decay and all have a shadows flag. To create a non-ambient light, the user must instantiate and call the create method on a specific type of light (as listed above). For more information on lights in general, see the Class Description of the AlLight on page 582 object.

AlNonAmbientLight::~AlNonAmbientLight() Description
Deletes an AlNonAmbientLight wrapper object.

AlObjectType AlNonAmbientLight::type() const Description

Returns the class identifier, kNonAmbientLightType.

double AlNonAmbientLight::intensity() const Description

Returns the lights intensity. Allowable range is from 0.0 to infinity. This method returns -1 if the light is invalid.

AlNonAmbientLight | 661

int AlNonAmbientLight::decay() const Description

Returns the lights decay. Decay controls how quickly the light fades with distance; that is, how far it reaches. It can be set to 0, 1, 2, or 3. A value of 0 means no decay - the light reaches everything. A value of 1 is standard decay. Higher values increase the decay exponentially: 2 squares it; 3 cubes it. The initial default is 1. Decay has no effect at distances less than one unit. This method returns -1 if the light is invalid or if there is an error.

boolean AlNonAmbientLight::shadows() const Description

Returns the lights shadow flag. If the shadows flag is TRUE, then this light will cast shadows if ray tracing is used to render an image. Default is FALSE.

statusCode AlNonAmbientLight::setIntensity( double newIntensity) Description

Sets the lights intensity. The allowable range for the intensity is from 0.0 to infinity.

Arguments
< double newIntensity - the new light intensity

Return Codes
sSuccess - setting intensity succeeded sInvalidObject - not a valid ambient light sInvalidArgument - the intensity was less than 0

statusCode AlNonAmbientLight::setDecay( int newDecay ) Description

Sets the lights decay. The decay controls how quickly the light fades with distance; that is, how far it reaches. It can be set to 0, 1, 2, or 3. A value of 0 means no decay - the light reaches everything. A value of 1 is a standard linear

662 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

decay. Higher values increase the decay exponentially, that is, 2 squares it and 3 cubes it. The initial default is 1. The decay has no effect at distances less than one unit.

Arguments
< int newDecay - the new decay value

Return Codes
sSuccess - setting decay succeeded sInvalidObject - not a valid ambient light sInvalidArgument - decay out of range 0..3

statusCode AlNonAmbientLight::setShadows( boolean shadows ) Description

Sets the lights shadow flag. If the shadows flag is TRUE, then this light will cast shadows if ray tracing is used to render an image. The default state is FALSE.

Arguments
< boolean shadows - the new value of the shadow flag

Return Codes
sSuccess - shadows set sInvalidObject - object is invalid

AlNotifyDagNode
Encapsulates the handling of DAG node notifications.

Synopsis
#include <AlNotifyDagNode.h> class AlNotifyDagNode virtual statusCode notify( AlDagNode * ) const;

AlNotifyDagNode | 663

Description
This class provides a means for an application function to notify Alias of a list of possible DAG nodes that will be affected if an object is modified. This class is passed to the application function along with an AlObject. For each DAG node that is affected if the AlObject is modifed, the application should call AlNotifyDagNode::notify. This is a restricted version of an iterator which can only be applied to AlDagNodes.

statusCode AlNotifyDagNode::notify( AlDagNode *dag ) const Description

Used by the AlMessage class and the AlCommand class in conjunction with the kMessagePickListModified message type in the AlMessage class. The AlPickListModified message handler is passed two arguments: an AlListModified handle and an AlObject.
statusCode AlPickListModHandler( const AlListModified *dagMod, AlObject *obj )

For the given object, the handler should call dagMod->notify for every DAG node which would be modified if the object were modified (there could be more than one). The handler routine for a kMessagePickListModified message handler will resemble the following code segment:
void myPickHandler( AlMessageType msgType, const AlNotifyDagNode *dagMod, AlObject *obj ) { for every dagnode adag that would be affected if obj were modified { dagMod->notify( adag ); } }

For a construction history command, the listModifiedDagNodes routine will be similar in form:
void myUserCmd::listModifiedDagNodes( const AlNotifyDagNode *dagMod, AlObject *obj ) { for every dagnode adag that would be affected if obj were modified { dagMod->notify( adag ); } }

Arguments
< dag - the dagnode which will be affected

664 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Return Codes
sSuccess - modification notification was accepted sFailure - the notification was rejected sInvalidArgument - DAG was NULL or DAG was not a DAG node

AlObject
Base class for all Alias Data types.

AlObject | 665

Synopsis

666 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

#include <AlObject.h> class AlObject : protected AlHashable virtual ~AlObject(); virtual AlObjectType type() const = 0; virtual const char* name() const; virtual statusCode setName( const char* ); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; // Down casting methods AlAnimatable* asAnimatablePtr(); AlClusterable* asClusterablePtr(); AlSettable* asSettablePtr(); AlPickable* asPickablePtr(); AlCamera* asCameraPtr(); AlCameraNode* asCameraNodePtr(); AlCluster* asClusterPtr(); AlClusterNode* asClusterNodePtr(); AlClusterMember* asClusterMemberPtr(); AlCurveCV* asCurveCVPtr(); AlCurve* asCurvePtr(); AlCurveNode* asCurveNodePtr(); AlCurveOnSurface* asCurveOnSurfacePtr(); AlDagNode* asDagNodePtr(); AlFace* asFacePtr(); AlFaceNode* asFaceNodePtr(); AlGroupNode* asGroupNodePtr(); AlLight* asLightPtr(); AlLightNode* asLightNodePtr(); AlAmbientLight* asAmbientLightPtr(); AlAreaLight* asAreaLightPtr(); AlDirectionLight* asDirectionLightPtr(); AlLinearLight* asLinearLightPtr(); AlNonAmbientLight* asNonAmbientLightPtr(); AlPointLight* asPointLightPtr(); AlSpotLight* asSpotLightPtr(); AlVolumeLight* asVolumeLightPtr(); AlSphereLight* asSphereLightPtr(); AlCylinderLight* asCylinderLightPtr(); AlBoxLight* asBoxLightPtr(); AlConeLight* asConeLightPtr(); AlTorusLight* asTorusLightPtr(); AlSurfaceCV* asSurfaceCVPtr(); AlSurface* asSurfacePtr();

AlObject | 667

AlSurfaceNode* asSurfaceNodePtr(); AlSet* asSetPtr(); AlSetMember* asSetMemberPtr(); AlShader* asShaderPtr(); AlTexture* asTexturePtr(); AlEnvironment* asEnvironmentPtr(); AlKeyframe* asKeyframePtr(); AlChannel* asChannelPtr(); AlAction* asActionPtr(); AlParamAction* asParamActionPtr(); AlMotionAction* asMotionActionPtr(); AlAttributes* asAttributesPtr(); AlArcAttributes* asArcAttributesPtr(); AlLineAttributes* asLineAttributesPtr(); AlCurveAttributes* asCurveAttributesPtr(); AlPlaneAttributes* asPlaneAttributesPtr(); AlConicAttributes* asConicAttributesPtr(); AlRevSurfAttributes* asRevSurfAttributesPtr(); AlJoint* asJointPtr(); AlConstraint* asConstraintPtr(); AlPointConstraint* asPointConstraintPtr(); AlOrientationConstraint* asOrientationConstraintPtr(); AlAimConstraint* asAimConstraintPtr(); AlTextureNode* asTextureNodePtr(); AlShellNode* asShellNodePtr(); AlShell* asShellPtr(); AlTrimRegion* asTrimRegionPtr(); AlTrimBoundary* asTrimBoundaryPtr(); AlTrimCurve* asTrimCurvePtr(); AlContact* asContactPtr(); AlCommandRef* asCommandRefPtr(); AlCommand* asCommandPtr(); AlLayer* asLayerPtr(); AlOrthographicCamera* asOrthographicCameraPtr(); AlPerspectiveCamera* asPerspectiveCameraPtr(); AlWindow* asWindowPtr(); AlImagePlane* asImagePlanePtr(); AlCharacterSpace* asCharacterSpacePtr(); AlCharacter* asCharacterPtr(); AlCharSnippet* asCharSnippetPtr(); AlCharTransition* asCharTransitionPtr(); AlIKHandle* asIKHandlePtr(); AlIKHandleNode* asIKHandleNodePtr();

668 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlLocator* asLocatorPtr(); AlAnnotationLocator* asAnnotationLocatorPtr(); AlDistanceLocator* asDistanceLocatorPtr(); AlAngleLocator* asAngleLocatorPtr(); AlRadialLocator* asRadialLocatorPtr(); AlDeviationLocator* asDeviationLocatorPtr(); AlMinmaxLocator* asMinmaxLocatorPtr(); AlPointLocator* asPointPtr(); AlSpaceLocator* asSpacePointPtr(); AlCurveLocator* asCurvePointPtr(); AlCurveOnSurfaceLocator* asCurveOnSurfacePointPtr(); AlSurfaceLocator* asSurfacePointPtr(); AlConstructionEntity* asConstructionEntityPtr(); AlConstructionVector* asConstructionVectorPtr(); AlConstructionPlane* asConstructionPlanePtr(); AlCloud* asCloudPtr(); AlBlendCurve* asBlendCurvePtr(); AlBlendPoint* asBlendPointPtr(); AlCategory* asCategoryPtr(); // Functions that operate on AlObjects that are not a part of the class: boolean AlIsValid( const AlObject* ); boolean AlAreEqual( const AlObject*, const AlObject* );

Description
This is an abstract base class which holds a reference to an anonymous data structure. Derived classes will initialize the reference to refer to a particular data structure. This class provides a mechanism for completely hiding the internal data structures from the user. This class gives some homogeneity between several different classes by providing methods that derived classes will redefine so that the name and type of the object can be obtained and so that object downcasting can be done safely. There are a group of functions (the downcasting methods) for casting an AlObject to one of its derived classes. They have the form
Al{DerivedObject} *AlObject::as{DerivedObject}Ptr()

where {DerivedObject} is the name of the derived class. In this way, safe typecasting can be maintained.

AlObject | 669

AlObject::~AlObject() Description
Destructor for AlObject class.

const char* AlObject::name() const Description

Returns the name of the AlObject.

statusCode AlObject::setName( const char* name ) Description

Sets the name for an AlObject.

Arguments
< name - the new name for the object

Return Codes
sSuccess - name set sFailure - the name could not be set

statusCode AlObject::deleteObject() Description

Default deletion method for Alias objects. In general, calling this method on any object should delete the associated Alias object, and invalidate any OpenModel objects you have active that may reference that object.

Return Codes (see individual classes for more detailed information)

sSuccess - object deleted sFailure - object not deleted

670 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlObject *AlObject::copyWrapper() const Description

Returns a copy of the object upon which the method was called. The copy will have identical semantics to the passed-in object. Note that both OpenModel objects will still refer to the same Alias object. No new Alias data is created.

boolean AlIsValid( AlObject* obj ) Description

Central function that checks that a given OpenModel pointer is in fact a valid object. Three checks will be done. The first is done here, and simply checks that the pointer is non-null. The other two checks are done in the isValid method, which checks that the objects data field is valid, and finally that the object is in the currently active stage (universe).

Return Codes
TRUE - the object is valid FALSE - the object is invalid

boolean AlAreEqual( const AlObject*, const AlObject* ); Description

Checks whether two OpenModel pointers are referencing the same Alias object. Note that the two pointers may reference different OpenModel objects, but those objects may both reference the same Alias object. Use this function instead of just checking for pointer equality. Note: if both pointers are NULL (and equal), FALSE is returned since we are not testing valid API objects.

Returns
TRUE - the two objects point to the same Alias object FALSE - the two objects point to different Alias objects or both of the object pointers are NULL

AlObject | 671

AlAction* AlObject::asActionPtr() Description

Returns a non-null pointer to an AlAction if it is safe to downcast the AlObject to it.

AlAimConstraint* AlObject::asAimConstraintPtr() Description

Returns a non-null pointer to an AlAimConstraint if it is safe to downcast the AlObject to it.

AlAmbientLight* AlObject::asAmbientLightPtr() Description

Returns a non-null pointer to an AlAmbientLight if it is safe to downcast the AlObject to it.

AlAnimatable* AlObject::asAnimatablePtr() Description

Returns a non-null pointer to an AlAnimatable if it is safe to downcast the AlObject to it.

AlArcAttributes* AlObject::asArcAttributesPtr() Description

Returns a non-null pointer to an AlArcAttributes if it is safe to downcast the AlObject to it.

AlAreaLight* AlObject::asAreaLightPtr() Description

Returns a non-null pointer to an AlAreaLight if it is safe to downcast the AlObject to it.

672 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlAttributes* AlObject::asAttributesPtr() Description

Returns a non-null pointer to an AlAttributes if it is safe to downcast the AlObject to it.

AlBoxLight* AlObject::asBoxLightPtr() Description

Returns a non-null pointer to an AlBoxLight if it is safe to downcast the AlObject to it.

AlCamera* AlObject::asCameraPtr() Description

Returns a non-null pointer to an AlCamera if it is safe to downcast the AlObject to it.

AlCameraNode* AlObject::asCameraNodePtr() Description

Returns a non-null pointer to an AlCameraNode if it is safe to downcast the AlObject to it.

AlChannel* AlObject::asChannelPtr() Description

Returns a non-null pointer to an AlChannel if it is safe to downcast the AlObject to it.

AlCharSnippet* AlObject::asCharSnippetPtr() Description

Returns a non-null pointer to an AlCharSnippet if it is safe to downcast the AlObject to it.

AlObject | 673

AlCharTransition* AlObject::asCharTransitionPtr() Description

Returns a non-null pointer to an AlCharTransition if it is safe to downcast the AlObject to it.

AlCharacter* AlObject::asCharacterPtr() Description

Returns a non-null pointer to an AlCharacter if it is safe to downcast the AlObject to it.

AlCharacterSpace* AlObject::asCharacterSpacePtr() Description

Returns a non-null pointer to an AlCharacterSpace if it is safe to downcast the AlObject to it.

AlClusterable* AlObject::asClusterablePtr() Description

Returns a non-null pointer to an AlClusterable if it is safe to downcast the AlObject to it.

AlCluster* AlObject::asClusterPtr() Description

Returns a non-null pointer to an AlCluster if it is safe to downcast the AlObject to it.

AlClusterMember* AlObject::asClusterMemberPtr() Description

Returns a non-null pointer to an AlClusterMember if it is safe to downcast the AlObject to it.

674 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlClusterNode* AlObject::asClusterNodePtr() Description

Returns a non-null pointer to an AlClusterNode if it is safe to downcast the AlObject to it.

AlCommand* AlObject::asCommandPtr() Description

Returns a non-null pointer to an AlCommand if it is safe to downcast the AlObject to it.

AlCommandRef* AlObject::asCommandRefPtr() Description

Returns a non-null pointer to an AlCommandRef if it is safe to downcast the AlObject to it.

AlConeLight* AlObject::asConeLightPtr() Description

Returns a non-null pointer to an AlConeLight if it is safe to downcast the AlObject to it.

AlConicAttributes* AlObject::asConicAttributesPtr() Description

Returns a non-null pointer to an AlConicAttributes if it is safe to downcast the AlObject to it.

AlConstraint* AlObject::asConstraintPtr() Description

Returns a non-null pointer to an AlConstraint if it is safe to downcast the AlObject to it.

AlObject | 675

AlContact* AlObject::asContactPtr() Description

Returns a non-null pointer to an AlContact if it is safe to downcast the AlObject to it.

AlCurve* AlObject::asCurvePtr() Description

Returns a non-null pointer to an AlCurve if it is safe to downcast the AlObject to it.

AlCurveAttributes* AlObject::asCurveAttributesPtr() Description

Returns a non-null pointer to an AlCurveAttributes if it is safe to downcast the AlObject to it.

AlCurveCV* AlObject::asCurveCVPtr() Description

Returns a non-null pointer to an AlCurveCV if it is safe to downcast the AlObject to it.

AlCurveNode* AlObject::asCurveNodePtr() Description

Returns a non-null pointer to an AlCurveNode if it is safe to downcast the AlObject to it.

AlCurveOnSurface* AlObject::asCurveOnSurfacePtr() Description

Returns a non-null pointer to an AlCurveOnSurface if it is safe to downcast the AlObject to it.

676 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlCylinderLight* AlObject::asCylinderLightPtr() Description

Returns a non-null pointer to an AlCylinderLight if it is safe to downcast the AlObject to it.

AlDagNode* AlObject::asDagNodePtr() Description

Returns a non-null pointer to an AlDagNode if it is safe to downcast the AlObject to it.

AlDirectionLight* AlObject::asDirectionLightPtr() Description

Returns a non-null pointer to an AlDirectionLight if it is safe to downcast the AlObject to it.

AlEnvironment* AlObject::asEnvironmentPtr() Description

Returns a non-null pointer to an AlEnvironment if it is safe to downcast the AlObject to it.

AlFace* AlObject::asFacePtr() Description

Returns a non-null pointer to an AlFace if it is safe to downcast the AlObject to it.

AlFaceNode* AlObject::asFaceNodePtr() Description

Returns a non-null pointer to an AlFaceNode if it is safe to downcast the AlObject to it.

AlObject | 677

AlGroupNode* AlObject::asGroupNodePtr() Description

Returns a non-null pointer to an AlGroupNode if it is safe to downcast the AlObject to it.

AlIKHandle* AlObject::asIKHandlePtr() Description

Returns a non-null pointer to an AlIKHandle if it is safe to downcast the AlObject to it.

AlIKHandleNode* AlObject::asIKHandleNodePtr() Description

Returns a non-null pointer to an AlIKHandleNode if it is safe to downcast the AlObject to it.

AlImagePlane* AlObject::asImagePlanePtr() Description

Returns a non-null pointer to an AlImagePlane if it is safe to downcast the AlObject to it.

AlJoint* AlObject::asJointPtr() Description

Returns a non-null pointer to an AlJoint if it is safe to downcast the AlObject to it.

AlKeyframe* AlObject::asKeyframePtr() Description

Returns a non-null pointer to an AlKeyframe if it is safe to downcast the AlObject to it.

678 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlLayer* AlObject::asLayerPtr() Description

Returns a non-null pointer to an AlLayer if it is safe to downcast the AlObject to it.

AlLight* AlObject::asLightPtr() Description

Returns a non-null pointer to an AlLight if it is safe to downcast the AlObject to it.

AlLightNode* AlObject::asLightNodePtr() Description

Returns a non-null pointer to an AlLightNode if it is safe to downcast the AlObject to it.

AlLineAttributes* AlObject::asLineAttributesPtr() Description

Returns a non-null pointer to an AlLineAttributes if it is safe to downcast the AlObject to it.

AlLinearLight* AlObject::asLinearLightPtr() Description

Returns a non-null pointer to an AlLinearLight if it is safe to downcast the AlObject to it.

AlMotionAction* AlObject::asMotionActionPtr() Description

Returns a non-null pointer to an AlMotionAction if it is safe to downcast the AlObject to it.

AlObject | 679

AlNonAmbientLight* AlObject::asNonAmbientLightPtr() Description

Returns a non-null pointer to an AlNonAmbientLight if it is safe to downcast the AlObject to it.

AlOrientationConstraint* AlObject::asOrientationConstraintPtr() Description

Returns a non-null pointer to an AlOrientationConstraint if it is safe to downcast the AlObject to it.

AlOrthographicCamera* AlObject::asOrthographicCameraPtr() Description

Returns a non-null pointer to an AlOrthographicCamera if it is safe to downcast the AlObject to it.

AlParamAction* AlObject::asParamActionPtr() Description

Returns a non-null pointer to an AlParamAction if it is safe to downcast the AlObject to it.

AlPerspectiveCamera* AlObject::asPerspectiveCameraPtr() Description

Returns a non-null pointer to an AlPerspectiveCamera if it is safe to downcast the AlObject to it.

AlPickable* AlObject::asPickablePtr() Description

Returns a non-null pointer to an AlPickable if it is safe to downcast the AlObject to it.

680 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlPlaneAttributes* AlObject::asPlaneAttributesPtr() Description

Returns a non-null pointer to an AlPlaneAttributes if it is safe to downcast the AlObject to it.

AlPointConstraint* AlObject::asPointConstraintPtr() Description

Returns a non-null pointer to an AlPointConstraint if it is safe to downcast the AlObject to it.

AlPointLight* AlObject::asPointLightPtr() Description

Returns a non-null pointer to an AlPointLight if it is safe to downcast the AlObject to it.

AlRevSurfAttributes* AlObject::asRevSurfAttributesPtr() Description

Returns a non-null pointer to an AlRevSurfAttributes if it is safe to downcast the AlObject to it.

AlSettable* AlObject::asSettablePtr() Description

Returns a non-null pointer to an AlSettable if it is safe to downcast the AlObject to it.

AlSet* AlObject::asSetPtr() Description

Returns a non-null pointer to an AlSet if it is safe to downcast the AlObject to it.

AlObject | 681

AlSetMember* AlObject::asSetMemberPtr() Description

Returns a non-null pointer to an AlSetMember if it is safe to downcast the AlObject to it.

AlShader* AlObject::asShaderPtr() Description

Returns a non-null pointer to an AlShader if it is safe to downcast the AlObject to it.

AlShell* AlObject::asShellPtr() Description

Returns a non-null pointer to an AlShell if it is safe to downcast the AlObject to it.

AlShellNode* AlObject::asShellNodePtr() Description

Returns a non-null pointer to an AlShellNode if it is safe to downcast the AlObject to it.

AlSphereLight* AlObject::asSphereLightPtr() Description

Returns a non-null pointer to an AlSphereLight if it is safe to downcast the AlObject to it.

AlSpotLight* AlObject::asSpotLightPtr() Description

Returns a non-null pointer to an AlSpotLight if it is safe to downcast the AlObject to it.

682 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlSurface* AlObject::asSurfacePtr() Description

Returns a non-null pointer to an AlSurface if it is safe to downcast the AlObject to it.

AlSurfaceCV* AlObject::asSurfaceCVPtr() Description

Returns a non-null pointer to an AlSurfaceCV if it is safe to downcast the AlObject to it.

AlSurfaceNode* AlObject::asSurfaceNodePtr() Description

Returns a non-null pointer to an AlSurfaceNode if it is safe to downcast the AlObject to it.

AlTexture* AlObject::asTexturePtr() Description

Returns a non-null pointer to an AlTexture if it is safe to downcast the AlObject to it.

AlTextureNode* AlObject::asTextureNodePtr() Description

Returns a non-null pointer to an AlTextureNode if it is safe to downcast the AlObject to it.

AlTorusLight* AlObject::asTorusLightPtr() Description

Returns a non-null pointer to an AlTorusLight if it is safe to downcast the AlObject to it.

AlObject | 683

AlTrimBoundary* AlObject::asTrimBoundaryPtr() Description

Returns a non-null pointer to an AlTrimBoundary if it is safe to downcast the AlObject to it.

AlTrimCurve* AlObject::asTrimCurvePtr() Description

Returns a non-null pointer to an AlTrimCurve if it is safe to downcast the AlObject to it.

AlTrimRegion* AlObject::asTrimRegionPtr() Description

Returns a non-null pointer to an AlTrimRegion if it is safe to downcast the AlObject to it.

AlVolumeLight* AlObject::asVolumeLightPtr() Description

Returns a non-null pointer to an AlVolumeLight if it is safe to downcast the AlObject to it.

AlWindow* AlObject::asWindowPtr() Description

Returns a non-null pointer to an AlWindow if it is safe to downcast the AlObject to it.

AlLocator* AlObject::asLocatorPtr() Description

Returns a non-null pointer to an AlLocator if it is safe to downcast the AlObject to it.

684 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlPointLocator* AlObject::asPointPtr() Description

Returns a non-null pointer to an AlPoint if it is safe to downcast the AlObject to it.

AlSpaceLocator* AlObject::asSpacePointPtr() Description

Returns a non-null pointer to an AlSpacePoint if it is safe to downcast the AlObject to it.

AlCurveLocator* AlObject::asCurvePointPtr() Description

Returns a non-null pointer to an AlCurvePoint if it is safe to downcast the AlObject to it.

AlCurveOnSurfaceLocator* AlObject::asCurveOnSurfacePointPtr() Description

Returns a non-null pointer to an AlCurveOnSurfacePoint if it is safe to downcast the AlObject to it.

AlSurfaceLocator* AlObject::asSurfacePointPtr() Description

Returns a non-null pointer to an AlSurfacePoint if it is safe to downcast the AlObject to it.

AlConstructionEntity* AlObject::asConstructionEntityPtr() Description

This virtual function returns a non-null pointer to an AlConstructionEntity if it is safe to downcast the AlObject to it.

AlObject | 685

AlConstructionVector* AlObject::asConstructionVectorPtr() Description

This virtual function returns a non-null pointer to an AlConstructionVector if it is safe to downcast the AlObject to it.

AlConstructionPlane* AlObject::asConstructionPlanePtr() Description

This virtual function returns a non-null pointer to an AlConstructionPlane if it is safe to downcast the AlObject to it

AlAnnotationLocator * AlObject::asAnnotationLocatorPtr() Description

Returns a non-null pointer to an AlAnnotationLocator if it is safe to downcast the AlObject to it.

AlDistanceLocator* AlObject::asDistanceLocatorPtr() Description

Returns a non-null pointer to an AlDistanceLocator if it is safe to downcast the AlObject to it.

AlAngleLocator* AlObject::asAngleLocatorPtr() Description

Returns a non-null pointer to an AlAngleLocator if it is safe to downcast the AlObject to it.

AlRadialLocator* AlObject::asRadialLocatorPtr() Description

Returns a non-null pointer to an AlRadialLocator if it is safe to downcast the AlObject to it.

686 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlDeviationLocator* AlObject::asDeviationLocatorPtr() Description

Returns a non-null pointer to an AlDeviationLocator if it is safe to downcast the AlObject to it.

AlMinmaxLocator* AlObject::asMinmaxLocatorPtr() Description

Returns a non-null pointer to an AlMinmaxLocator if it is safe to downcast the AlObject to it.

AlCloud* AlObject::asCloudPtr() Description

Returns a non-null pointer to an AlCloud if it is safe to downcast the AlObject to it.

AlBlendCurve* AlObject::asBlendCurvePtr() Description

Returns a non-null pointer to an AlBlendCurve if it is safe to downcast the AlObject to it.

AlBlendPoint* AlObject::asBlendPointPtr() Description

Returns a non-null pointer to an AlBlendPoint if it is safe to downcast the AlObject to it.

AlCategory* AlObject::asCategoryPtr() Description

Returns a non-null pointer to an AlCategory if it is safe to downcast the AlObject to it.

AlObject | 687

AlObserver
An OpenAlias class that allows a plug-in to detect selected Alias events.

Synopsis
#include <AlObserver.h> class AlObserver enum ObserverMessage { kMaximizeWindow, kMinimizeWindow, kLowerWindow, kRaiseWindow, }; static statusCode create(); static statusCode deleteObject(); static statusCode installHandler( ObserverMessage, void (*)(void) ); static statusCode removeHandler( ObserverMessage, void (*)(void) );

Description
AlObserver is a static OpenAlias class. Currently, it allows a user to detect when the Alias window is minimized, maximized, lowered or raised. This class cannot trap events that are handled by the Window Manager. An example of an event that cannot be trapped is the raising of a window by clicking on its window bar. However, this situation can be detected by an X-event handler installed by the AlXevents class, so to test if a window is below the Alias window on ConfigureNotify events use the method AlXevents::belowAliasWindow().

statusCode AlObserver::create() Description

Initializes the API observer class. Note that this method should always be called by a plug-in that wants to observe events. If the observer class is already initialized, this routine will return successfully.

688 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Return Codes
sSuccess - the method succeeded sFailure - the method failed

statusCode AlObserver::deleteObject() Description

Terminates the observation of events if there are no handlers installed. This allows several plug-ins loaded into Alias to call deleteObject(). The observer is not removed until the last plug-in has removed its handlers and called this routine.

Return Codes
sSuccess - the method succeeded sFailure - the method failed. There may be handlers still installed. sInvalidObject - the observer has not been initialized; call AlObserver::create()

statusCode AlObserver::installHandler( ObserverMessage observerType, void (*function)(void) ) Description

Installs a callback handler for a specific observerType.

Arguments
< observerType - one of kMaximizeWindow, kMinimizeWindow, kLowerWindow, kRaiseWindow < function - pointer to a void function

Return Codes
sSuccess - the method succeeded sFailure - the method failed or the observer type was invalid sInvalidObject - the observer has not been initialized; call AlObserver::create() sInvalidArgument - function parameter was NULL

AlObserver | 689

statusCode AlObserver::removeHandler( ObserverMessage observerType, void (*function)(void) ) Description

Removes a callback handler for a specific observer type. Plug-ins must properly remove observer handlers to avoid Alias calling a routine that no longer exists in memory.

Arguments
< observerType - one of kMaximizeWindow, kMinimizeWindow, kLowerWindow, kRaiseWindow < function - pointer to a void function

Return Codes
sSuccess - the method succeeded sFailure - the method failed or the observer type was invalid sInvalidObject - the observer has not been initialized; call AlObserver::create()

AlOrientationConstraint
Interface to IK orientation constraint data.

Synopsis
#include <AlOrientationConstraint.h> class AlOrientationConstraint : public AlConstraint AlOrientationConstraint(); virtual ~AlOrientationConstraint(); virtual AlObject* copyWrapper() const; statusCode create(AlDagNode*, AlDagNode* ); statusCode create(AlDagNode*, AlDagNode*, double[2] ); virtual AlObjectType type() const; virtual AlOrientationConstraint*asOrientationConstraintPtr(); statusCode goalX( double[3] ) const; statusCode goalY( double[3] ) const; statusCode goalZ( double[3] ) const;

690 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Description
Allows access to the IK orientation constraint information on an AlJoint. This class is derived from the AlConstraint class. (See the discussion of skeletons, joints, contraints, IK, and so on, in the Menu Book and Tool Book for a full description.)

AlOrientationConstraint::AlOrientationConstraint() Description
Constructs an AlOrientationConstraint wrapper object.

AlOrientationConstraint::~AlOrientationConstraint() Description
Deletes an AlOrientationConstraint wrapper object.

AlObject *AlOrientationConstraint::copyWrapper() const Description

Wrapper object duplicator for AlOrientationConstraint.

statusCode AlOrientationConstraint::create(AlDagNode* srcNode, AlDagNode* dstNode ) Description

Does all the initialization necessary to attach the constraint node to a DAG joint node as an orientation constraint. A DAG node can not be constrained to itself.

Arguments
< srcNode - AlDagNode this constraint is to be added to < destNode - the AlDagNode that srcNode will be constrained to

AlOrientationConstraint | 691

Return Codes
sInvalidArgument - one of the arguments was wrong or tried to constrain a node to itself sInsufficientMemory - ran out of memory sFailure - failed to add the constraint sSuccess - successfully added the constraint

statusCode AlOrientationConstraint::create(AlDagNode* srcNode, AlDagNode* dstNode , double uv[2]) Description

This method does all the initialization necessary to attach the constraint node to dag joint node as a uv orientation constraint. A dag node can not be constrained to itself. The destNode must be a spline geometry node, for example, a spline curve or a spline surface.

Arguments
< srcNode - AlDagNode this constraint is to be added to. < destNode - The AlDagNode that srcNode will be constrained to. < uv[2] - The uv parameter on destNode that srcNode will be constrained to. If the destNode is a curve, only uv[0] is used.

Return Codes
sInvalidArgument - one of the arguments was wrong or tried to constrain a node to itself. sInsufficientMemory - ran out of memory. sFailure - failed to add the constraint. sSuccess - successfully added the constraint.

AlObjectType AlOrientationConstraint::type() const Description

Returns the class identifier kOrientationConstraintType.

692 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlOrientationConstraint* AlOrientationConstraint::asOrientationConstraintPtr() Description

A virtual function that returns a non-null pointer to itself, indicating that it is safe to cast to an object of this class.

statusCode AlOrientationConstraint::goalX( double ex[3] ) const Description

Returns the orientation goal in the X axis for this constraint.

statusCode AlOrientationConstraint::goalY( double ey[3] ) const Description

Returns the orientation goal in the Y axis for this constraint.

statusCode AlOrientationConstraint::goalZ( double ez[3] ) const Description

Returns the orientation goal in the Z axis for this constraint.

AlOrthographicCamera
Interface to orthographic modeling cameras.

Synopsis
#include <AlOrthographicCamera.h> class AlOrthographicCamera : public AlCamera AlOrthographicCamera(); virtual ~AlOrthographicCamera(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; statusCode create( AlWindow::AlViewType ); virtual AlObjectType type() const;

AlOrientationConstraint | 693

Description
This class provides an interface to orthographic cameras, primarily so that one can manipulate the image planes on those cameras. In general, little can be done to ortho cameras, as they are more of a modeling tool than geometry. In that regard, this class contains little functionality. It is possible to create a new orthographic camera through the create() call. The valid parameters to that call are defined in AlWindow.h. Note that creating an orthographic camera creates the associated modeling window.

AlOrthographicCamera::AlOrthographicCamera() Description
Constructs an AlOrthographicCamera wrapper object.

AlOrthographicCamera::~AlOrthographicCamera() Description
Deletes an AlOrthographicCamera wrapper object.

statusCode AlOrthographicCamera::deleteObject() Description

Deletes the orthographic camera node.

Return Codes
sSuccess - the camera data was successfully deleted sInvalidObject - the camera was not valid

AlObject* AlOrthographicCamera::copyWrapper() const Description

Makes a copy of the AlCamera. The returned AlCamera will reference the same data as the original.

694 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlObjectType AlOrthographicCamera::type() const Description

Returns the class identifier kOrthographicCameraType.

AlOrthographicCamera* AlOrthographicCamera::asOrthographicCameraPtr() Description

A virtual function that returns a non-null pointer to itself, indicating that it is safe to cast to an object of this class.

statusCode AlOrthographicCamera::create( AlWindow::AlViewType viewType ) Description

Creates an orthographic camera, with the associated window.

Arguments
viewType - type of window required

Return Codes
sSuccess - everything was created sInsufficientMemory - there was not enough memory sFailure - camera was not created sInvalidArgument - the viewType must be one of kFront, kRight, kTop

AlParamAction
Basic interface to derived class of actions for parameter curve actions.

AlParamAction | 695

Synopsis
#include <AlParamAction.h> class AlParamAction : public AlAction AlParamAction(); virtual ~AlParamAction(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; AlKeyframe* firstKeyframe() const; AlKeyframe* lastKeyframe() const; statusCode addKeyframe( double, double, AlKeyframe *&, boolean = TRUE, AlTangentType = kTangentFlat, AlTangentType = kTangentFlat ); statusCode addKeyframe( double, double, AlKeyframe &, boolean = TRUE, AlTangentType = kTangentFlat, AlTangentType = kTangentFlat ); statusCode addKeyframe( double, double, boolean = TRUE, AlTangent Type = kTangentFlat, AlTangentType = kTangentFlat ); int numberOfKeyframes() const; statusCode applyIteratorToKeyframes( AlIterator*, int& ); statusCode addKeyframeRange( int, double*, double*, boolean = TRUE, AlTangentType* = NULL, AlTangentType* = NULL ); statusCode deleteKeyframeRange( double, double );

Description
An AlParamAction is derived from an AlAction. This particular action has a list of AlKeyframes which are CVs on a Poon-Ross spline. This spline is basically a Hermite-linear spline. That is, it is a Hermite in y (the vertical axis) and a linear in x (the horizontal axis). In order to create an AlParamAction, you must have at least one valid, created AlKeyframe that will be the first keyframe of the action. After the AlParamAction is created, you can add other keyframes to the AlParamAction. Note that two AlKeyframes cannot have the same location. If you add a keyframe to the action that has the same location as an existing keyframe of the action, the existing keyframe will be deleted. Since an AlKeyframe is created at (0, 0), you cannot create a bunch of AlKeyframes, add them to the AlParamAction, and then modify their locations later, because the AlParamAction will only have one keyframe (the others will have been deleted as each successive keyframe with the same location is added to the AlParamAction). You must set the location of the AlKeyframe before adding it to the AlParamAction.

696 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

If you copy an AlParamAction, all the keyframes (and the keyframes streams) will also be copied. If you delete an AlParamAction, all its Keyframes will be deleted.

AlParamAction::AlParamAction() Description
Constructs an AlParamAction wrapper object. Use the create() method to initialize the AlParamAction.

AlParamAction::~AlParamAction() Description
Deletes an AlParamAction wrapper object.

AlObject* AlParamAction::copyWrapper() const Description

Returns a duplicate of this wrapper object, pointing to the same object.

AlObjectType AlParamAction::type() const Description

Returns the class identifier kParamActionType.

AlParamAction* AlParamAction::asParamActionPtr() Description

This virtual function returns a non-null pointer to itself, indicating that it is safe to cast to an object of this class.

AlKeyframe* AlParamAction::firstKeyframe() const Description

Returns the first keyframe of this parameter curve action.

AlParamAction | 697

AlKeyframe* AlParamAction::lastKeyframe() const Description

Returns the last keyframe of this parameter curve action.

statusCode AlParamAction::addKeyframe( double location, double value, AlKeyframe &kf, boolean recompute, AlTangentType intan, AlTangentType outtan ) Description
Similar to addKeyframe, but returns the newly created AlKeyframe in kf. This avoids the creation and deletion of wrappers when creating many keys. An example loop may look like
AlKeyframe key; for( int i =0; i < 100; i++ ) >addKeyframe( i, 1, key, ....) } { param-

Arguments
< location - the time value for the keyframe < value - the value of the keyframe > Alkeyframe &kf - the resulting keyframe < intan - the in tangent for the keyframe < outtan - the out tangent for the keyframe < recompute - recompute the tangents of neighboring keyframes

Return Codes
sSuccess - key frame added sInvalidArgument - kf was NULL sFailure - key frame not added

698 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlParamAction::addKeyframe( double location, double value, AlKeyframe *& kf, boolean recompute, AlTangentType intan, AlTangentType outtan ) Description
Similar to addKeyframe, but allocates a wrapper and returns the newly created AlKeyframe. It is up to you to delete these wrappers. Use this overloaded form if you wish to have the wrapper created for you. Below is an example code fragment
Alkeyframe *key1, *key2, *key3; param->addKeyframe( 0, 1, key1, .... param->addKeyframe( 1, 1, key2, .... param->ad dKeyframe( 2, 1, key3, .... ... delete key1; delete key2; delete key3;

Arguments
< location - the time value for the keyframe < value - the value of the keyframe > Alkeyframe* &kf - the resulting keyframe < intan - the in tangent for the keyframe < outtan - the out tangent for the keyframe < recompute - recompute the tangents of neighboring keyframes

Return Codes
sSuccess - key frame added sInvalidArgument - kf was NULL sFailure - key frame not added

statusCode AlParamAction::addKeyframe( double location, double value, boolean recompute, AlTangentType intan, AlTangentType outtan ) Description
Adds a keyframe to the parameter curves list of keyframes. If the parameter curve already has another keyframe at the same location as this keyframe, then the existing keyframe at this location will be deleted and replaced with

AlParamAction | 699

this keyframe. If this object does not yet reference an actual Parameter Curve, a new curve will be created.

Arguments
< location - the time value for the keyframe < value - the value of the keyframe < intan - the in tangent for the keyframe < outtan - the out tangent for the keyframe < recompute - recompute the tangents of neighboring keyframes

Return Codes
sSuccess - operation completed normally sFailure - operation failed to complete normally sInsufficientMemory - there wasnt enough memory to complete the operation

int AlParamAction::numberOfKeyframes() const Description

Returns the number of keyframes in this action, or -1 if the call fails.

statusCode AlParamAction::applyIteratorToKeyframes( AlIterator* iter, int &rc ) Description

Applies the given AlIterator to all keyframes in the action. The second argument will be set to the return value of the last application of the iterators function. See the AlIterator on page 544 class for more information.

Arguments
< iter - the iterator to be applied to each keyframe > rc - return value of the last application of the iterator

Return Codes
sSuccess - the application of the iterator terminated normally

700 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

sFailure - the application of the iterator terminated abnormally sInvalidArgument - the iterator was NULL sInvalidObject - the action was invalid

statusCode AlParamAction::deleteKeyframeRange( double minValue, double maxValue ) Description

Deletes all keyframes whose "time"s are greater or equal to the "minValue" given, and less than or equal to the "maxValue" given.

Arguments
< minValue - minimum time value to delete keyframes from < maxValue - maximum time value to delete keyframes up to

Return Codes
sSuccess - operation completed normally sFailure - operation failed to complete normally sInvalidObject - the action was invalid

statusCode AlParamAction::addKeyframeRange( int size, double location[], double value[], boolean recompute, AlTangentType intan[], AlTangentType outtan[]) Description
Adds a block of keyframes to the parameter curve's list keyframes. If the parameter curve already has a keyframe at the same location as one of the added keyframes, then the method will fail. If this object does not yet reference an actual Parameter Curve, a new curve will be created.If intan and outan are NULL, kTangentFlat is assumed.

Arguments
< size - size of input arrays < location - array of keyframe locations (time values) < value - array of keyframe values

AlParamAction | 701

< recompute - recompute tangents of neighboring keyframes < intan - array of the in-tangents for keyframes < outtan - array of the out-tangents for keyframes

Return Codes
sSuccess - operation completed normally sInvalidArgument - one of the arguments was NULL or invalid sInsufficientMemory - ran out of memory sFailure - could not create action sObjectAlreadyPresent - a keyframe already exists in given location

AlPerformance
Interface to Alias performance options.

702 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Synopsis
#include <AlPerformance.h> class AlPerformance enum AlPrecisionType { kActual, kScreenSize, kMedium, kLow, kConnectedPoints, kBound ary, kBoundingBox }; static AlPrecisionType redrawPrecision( void ); static void setRedrawPrecision( AlPrecisionType ); static Al PrecisionType motionPrecision( void ); static void setMotionPreci sion( AlPrecisionType ); static boolean drawTrimBoundaries( void ); static void setDrawTrimBoundaries( boolean ); static boolean trimBoundariesDuringPlayback( void ); static void setTrimBoundar iesDuringPlayback( boolean ); static boolean expressionsAfterModi fication( void ); static void setExpressionsAfterModification( boolean ); static boolean expressionsDuringXform( void ); static void setExpressionsDuringXform( boolean ); static boolean expres sionsDuringPlayback( void ); static void setExpressionsDuringPlay back( boolean ); static boolean constraintsAfterModification( void ); static void setConstraintsAfterModification( boolean ); static boolean constraintsDuringXform( void ); static void setConstraints DuringXform( boolean ); static boolean constraintsDuringPlayback( void ); static void setConstraintsDuringPlayback( boolean ); static boolean ikAfterModification( void ); static void setIkAfterModification( boolean ); static boolean ikDuringXform( void ); static void setIkDuringXform( boolean ); static boolean ikDuringPlayback( void ); static void setIkDuringPlayback( boolean ); static boolean constructionHistoryAfterModification( void ); static void setConstructionHistoryAfterModification( boolean ); static boolean constructionHistoryDuringXform( void ); static void setConstructionHistoryDuringXform( boolean ); static boolean constructionHistoryDuringPlayback( void ); static void setConstruc tionHistoryDuringPlayback( boolean ); static boolean blendDuring Playback( void ); static void setBlendDuringPlayback( boolean ); static boolean constructionHistoryRound( void ); static void set ConstructionHistoryRound( boolean ); static boolean action WindowAfterModification( void ); static void setActionWindowAfter Modification( boolean ); static boolean actionWindowDuringXform( void ); static void setActionWindowDuringXform( boolean ); static boolean displayablesAfterModification( void ); static void setDis playablesAfterModification( boolean ); static boolean displayables DuringXform( void ); static void setDisplayablesDuringXform( boolean ); static boolean displayablesDuringPlayback( void ); static void setDisplayablesDuringPlayback( boolean );

AlPerformance | 703

Description
This class encapsulates all access to the Alias performance options. Every value in the window can be retrieved and set.

AlPerformance::AlPrecisionType AlPerformance::redrawPrecision( void ) Description

Returns the redraw precision.

Return Codes
AlPerformance::kScreenSize AlPerformance::kActual

void AlPerformance::setRedrawPrecision( AlPrecisionType t ) Description

Sets the redraw precision to one of the following modes: AlPerformance::kScreenSize - precision of objects reduces as they become smaller AlPerformance::kActual - objects are drawn with the curve precision option

Arguments
t - the new redraw precision

AlPerformance::AlPrecisionType AlPerformance::motionPrecision( void ) Description

Returns the motion precision type.

Return Codes
AlPerformance::kScreenSize AlPerformance::kMedium AlPerformance::kLow

704 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlPerformance::kConnectedPoints AlPerformance::kBoundary AlPerformance::kBoundingBox AlPerformance::kActual

void AlPerformance::setMotionPrecision( AlPrecisionType t ) Description

Sets the redraw precision to one of the following modes: AlPerformance::kScreenSize - reduces the precision of the objects as they become smaller AlPerformance::kMedium - reduces the default precision AlPerformance::kLow - significantly reduces the default precision AlPerformance::kConnectedPoints - draws the objects by connecting edit points AlPerformance::kBoundary - draws the outer boundary of the object AlPerformance::kBoundingBox - draws the boundary box of the object AlPerformance::kActual - draws objects with the curve precision option

Arguments
t - the new redraw precision

int AlPerformance::evaluationsPerUpdate( void ) Description

Returns current value of evaluation density. The value should be in [1, 10].

void AlPerformance::setEvaluationsPerUpdate( int i ) Description

Sets the value of evaluation density. The value should be in [1, 10].

AlPerformance | 705

boolean AlPerformance::drawTrimBoundaries( void ) Description

Returns TRUE if trim boundaries are drawn during updates.

void AlPerformance::setDrawTrimBoundaries( boolean b ) Description

Selects if trim boundaries are drawn during updates.

Arguments
b - TRUE if trim boundaries are to be drawn

boolean AlPerformance::trimBoundariesDuringPlayback( void ) Description

Returns TRUE if trim boundaries are drawn during playback.

void AlPerformance::setTrimBoundariesDuringPlayback( boolean b ) Description

Selects if trim boundaries are drawn during playback.

Arguments
b - TRUE if trim boundaries are to be drawn

boolean AlPerformance::expressionsAfterModification( void ) Description

Returns TRUE if expressions are evaluated after modifications.

void AlPerformance::setExpressionsAfterModification( boolean b ) Description

Selects if expressions are evaluated after modifications.

706 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Arguments
b - TRUE if expressions are to be evaluated

boolean AlPerformance::expressionsDuringXform( void ) Description

Returns TRUE if expressions are evaluated during transformations.

void AlPerformance::setExpressionsDuringXform( boolean b ) Description

Selects if expressions are evaluated during transformations.

Arguments
b - TRUE if expressions are to be evaluated

boolean AlPerformance::expressionsDuringPlayback( void ) Description

Returns TRUE if expressions are evaluated during playback.

void AlPerformance::setExpressionsDuringPlayback( boolean b ) Description

Selects if expressions are evaluated during playback.

Arguments
b - TRUE if expressions are to be evaluated

boolean AlPerformance::constraintsAfterModification( void ) Description

Returns TRUE if constraints are updated after modifications.

AlPerformance | 707

void AlPerformance::setConstraintsAfterModification( boolean b ) Description

Selects if constraints are updated after modifications.

Arguments
b - TRUE if constraints are updated

boolean AlPerformance::constraintsDuringXform( void ) Description

Returns TRUE if constraints are updated during transformations.

void AlPerformance::setConstraintsDuringXform( boolean b ) Description

Selects if constraints are updated during transformations.

Arguments
b - TRUE if constraints are updated

boolean AlPerformance::constraintsDuringPlayback( void ) Description

Returns TRUE if constraints are updated during playback.

void AlPerformance::setConstraintsDuringPlayback( boolean b ) Description

Selects if constraints are updated during playback.

Arguments
b - TRUE if constraints are updated

708 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

boolean AlPerformance::ikAfterModification( void ) Description

Returns TRUE if IK are updated after modifications.

void AlPerformance::setIkAfterModification( boolean b ) Description

Selects if IK are updated after modifications.

Arguments
b - TRUE if IK are updated

boolean AlPerformance::ikDuringXform( void ) Description

Returns TRUE if IK are updated during transformations.

void AlPerformance::setIkDuringXform( boolean b ) Description

Selects if IK are updated during transformations.

Arguments
b - TRUE if IK are updated

boolean AlPerformance::ikDuringPlayback( void ) Description

Returns TRUE if IK are updated during playback.

void AlPerformance::setIkDuringPlayback( boolean b ) Description

Selects if IK are updated during playback.

AlPerformance | 709

Arguments
b - TRUE if IK are updated

boolean AlPerformance::constructionHistoryAfterModification( void ) Description

Returns TRUE if construction history updates occur after modifications.

void AlPerformance::setConstructionHistoryAfterModification( boolean b) Description

Selects if construction history updates occur after modifications.

Arguments
b - TRUE if construction history updates occur

boolean AlPerformance::constructionHistoryDuringXform( void ) Description

Returns TRUE if construction history updates occur during transformations.

void AlPerformance::setConstructionHistoryDuringXform( boolean b ) Description

Selects if construction history updates occur during transformations.

Arguments
b - TRUE if construction history updates occur

boolean AlPerformance::constructionHistoryDuringPlayback( void ) Description

Returns TRUE if construction history updates occur during playback.

710 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

void AlPerformance::setConstructionHistoryDuringPlayback( boolean b ) Description

Selects if construction history updates occur during playback.

Arguments
b - TRUE if construction history updates occur

boolean AlPerformance::blendDuringPlayback( void ) Description

Returns TRUE if blend updates occur during playback.

void AlPerformance::setBlendDuringPlayback( boolean b ) Description

Selects if blend updates occur during playback.

Arguments
b - TRUE if blend updates occur

boolean AlPerformance::constructionHistoryRound( void ) Description

Returns TRUE if construction history round updates occur.

void AlPerformance::setConstructionHistoryRound( boolean b ) Description

Selects if construction history round updates occur.

Arguments
b - TRUE if construction history round updates occur

AlPerformance | 711

boolean AlPerformance::actionWindowAfterModification( void ) Description

Returns TRUE if action window updates occur after modifications.

void AlPerformance::setActionWindowAfterModification( boolean b ) Description

Selects if action window updates occur after modifications.

Arguments
b - TRUE if action window updates occur

boolean AlPerformance::actionWindowDuringXform( void ) Description

Returns TRUE if action window updates occur during transformations.

void AlPerformance::setActionWindowDuringXform( boolean b ) Description

Selects if action window updates occur during transformations.

Arguments
b - TRUE if action window updates occur

boolean AlPerformance::displayablesAfterModification( void ) Description

Returns TRUE if displayables updates occur after modifications. Displayables are objects such as locators.

712 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

void AlPerformance::setDisplayablesAfterModification( boolean b ) Description

Selects if displayables updates occur after modifications. Displayables are objects such as locators.

Arguments
b - TRUE if displayables updates occur

boolean AlPerformance::displayablesDuringXform( void ) Description

Returns TRUE if displayables updates occur during transformations. Displayables are objects such as locators.

void AlPerformance::setDisplayablesDuringXform( boolean b ) Description

Selects if displayables updates occur during transformations. Displayables are objects such as locators.

Arguments
b - TRUE if displayables updates occur

boolean AlPerformance::displayablesDuringPlayback( void ) Description

Returns TRUE if displayables updates occur during animation playback. Displayables are objects such as locators.

void AlPerformance::setDisplayablesDuringPlayback( boolean b ) Description

Selects if displayables updates occur during animation playback. Displayables are objects such as locators.

AlPerformance | 713

Arguments
b - TRUE if displayables updates occur

AlPersistentID
A class for maintaining a persistent ID on an object.

Synopsis
#include <AlPersistentID.h> class AlPersistentID AlPersistentID(); AlPersistentID( AlPersistentID & ); AlPersistentID( int, int = 1, int = -1, int = -1 ); virtual ~AlPersistentID(); AlPersistentID &operator=( const AlPersistentID& ); void id( int &, int &, int &, int & ); friend int operator== (const AlPersistentID &, const AlPersistentID &); friend int operator!= (const AlPersistentID &, const AlPersistentID &);

Description
Sometimes it may be necessary to maintain a persistent ID on an object. The name of the object is inadequate for this since it may be changed by the user, changed when the file is loaded, and so on.The AlPersistentID remains with the object through storing and retrieving, without ever being changed. This ID is not unique, however. If the object is copied, or if a wire file is retrieved more than once (into one or several stages) the ID will be shared by all copies of the object. Note that querying an ID from an object will actually return a copy of the objects ID. This ensures that the ID for an object does not get changed. For efficiency, IDs are not created until the first time they are queried. As a result, copies of an object made before its ID is created will not have the same ID as the original object.

AlPersistentID::AlPersistentID() Description
Constructor that sets the internal values for the ID. In general it is unnecessary to use either of the constructors for this class.

714 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlPersistentID::AlPersistentID( int value0, int value1, int value2, int value3 ) Description
Copy constructor for the AlPersistentID class. This function creates a new AlPersistentID with the given values.

AlPersistentID::AlPersistentID(AlPersistentID &that) Description

Copy constructor for the AlPersistentID class. This function creates a new AlPersistentID with the same internal state as the given one.

AlPersistentID::~AlPersistentID() Description
Destructor for the AlPersistentID class. Any AlPersistentID returned to you by class must be deleted.

AlPersistentID &AlPersistentID::operator=( const AlPersistentID &that ) Description

Assignment operator. This function copies the contents of one ID onto another.

void AlPersistentID::id( int &value0, int &value1, int &value2, int &value3 ) Description
Returns the internal values of this class.

AlPerspectiveCamera
Encapsulates creation, deletion and manipulation of perspective cameras.

AlPerspectiveCamera | 715

Synopsis
#include <AlPerspectiveCamera.h> class AlPerspectiveCamera : public AlCamera , public AlSettable , public AlPickable , public AlAn imatable enum AlCameraWindowFitType { kFillFit, kHorizontalFit, kVerticalFit }; AlPerspectiveCamera(); virtual ~AlPerspectiveCam era(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; statusCode create(); virtual AlObjectType type() const; AlCameraNode* eye() const; AlCameraNode* view() const; AlCameraNode* up() const; statusCode worldEye( double&, double&, double& ) const; statusCode worldView( double&, double&, double& ) const; statusCode worldUp( double&, double&, double& ) const; statusCode worldEyeViewUp( double&, double&, double&, double&, double&, double&, double&, double&, double& ) const; statusCode setWorldEye( double, double, double); statusCode set WorldView( double, double, double ); statusCode setWorldUp( double, double, double ); statusCode setWorldEyeViewUp( double, double, double, double, double, double, double, double, double ); double twistAngle() const; statusCode setTwistAngle( double ); statusCode changeTwistAngleBy( double ); statusCode filmBack(double&, double&) const; statusCode filmOffset(double&, double&) const; statusCode setFilmBack(double, double); statusCode setFilmOff set(double, double); double focalLength() const; statusCode set FocalLength(double); double angleOfView() const; statusCode setAngleOfView( double ); statusCode depthOfField(boolean&, double&, double&) const; statusCode setDepthOfField(boolean, double, double); int placementFitCode() const; double placement Shift() const; statusCode setPlacementFitCode( AlCameraWindowFit Type ); statusCode setPlacementShift( double ); statusCode autoFo cus( boolean &enabled ) const; statusCode setAutoFocus( boolean enabled );

Description
This class encapsulates all the functionality for creating, deleting and manipulating a perspective camera. The user cannot create, delete or manipulate orthographic cameras. A camera is made of 4 parts - an AlPerspectiveCamera object and 3 attached AlCameraNodes that represent eye, view and up position of the camera. These camera nodes are members of the universes DAG structure. The view direction vector is the vector between the eye position and the view position. The up direction vector is the vector between the eye position and

716 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

the up position. There are methods to get these positions and to access the attached camera nodes. To create a perspective camera, the user must instantiate and call the create method on an AlPerspectiveCamera object. This creates the necessary eye, view and up AlCameraNodes, groups them under an AlGroupNode and inserts the group into the universes DAG structure. The user cannot instantiate an AlCameraNode directly. When a camera is created, if the coordinate system is specified as kZUp (when initializing the universe) the cameras default eye, view and up positions are respectively (0.0, -12.0, 0.0), (0.0, 0.0, 0.0), (0.0, -12.0, 1.0). If the coordinate system is specified as kYUp, then eye, view and up positions are (0.0, 0.0, 12.0), (0.0, 0.0, 0.0), (0.0, 1.0, 12.0). There are two ways to delete a camera object. When the deleteObject() method of an AlPerspectiveCamera object is called, its three camera nodes are deleted. Alternatively, when a camera node is deleted, its associated camera (and other camera nodes) are deleted. The group node that originally grouped the eye, view and up nodes is not deleted.

AlPerspectiveCamera::AlPerspectiveCamera() Description
Constructs an AlPerspectiveCamera wrapper object.

AlPerspectiveCamera::~AlPerspectiveCamera() Description
Deletes an AlPerspectiveCamera wrapper object.

AlObject *AlPerspectiveCamera::copyWrapper() const Description

Creates a copy of the AlPerspectiveCamera. The returned AlPerspectiveCamera will reference the same data as the original.

AlPerspectiveCamera | 717

statusCode AlPerspectiveCamera::deleteObject() Description

Removes all parts of the camera from the DAG and deletes them. This includes detaching and deleting the eye, view, and up DAG nodes.

Return Codes
sSuccess - the camera data was successfully deleted sInvalidObject - the camera was not valid (already deleted?)

statusCode AlPerspectiveCamera::create() Description

Creates a camera and all associated eye, view, and up camera nodes and attaches them to the camera. The camera is given default parameters for a perspective camera.

Return Codes
sSuccess - everything was created sInsufficientMemory - not enough memory sFailure - not created

AlObjectType AlPerspectiveCamera::type() const Description

Returns the class identifier kPerspectiveCameraType.

AlPerspectiveCamera* AlPerspectiveCamera::asPerspectiveCameraPtr() Description

This virtual function returns a non-null pointer to itself, indicating that it is safe to cast to an object of this class.

718 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlCameraNode* AlPerspectiveCamera::eye() const Description

Returns a pointer to this cameras eye node. If the eye node does not exist or is of the wrong type, then this method returns NULL.

AlCameraNode* AlPerspectiveCamera::view() const Description

Returns a pointer to this cameras view node. If the view node does not exist or is of the wrong type, then this method returns NULL.

AlCameraNode* AlPerspectiveCamera::up() const Description

Returns a pointer to this cameras up node. If the up node does not exist or is of the wrong type, then this method returns NULL.

statusCode AlPerspectiveCamera::worldEye( double &x, double &y, double &z ) const Description
Returns the cameras world eye position in x,y, & z in world space.

Arguments
> double &x - the position along the x axis > double &y - the position along the y axis > double &z - the position along the z axis

Return Codes
sSuccess - the position was successfully returned sInvalidObject - the camera is not valid

AlPerspectiveCamera | 719

statusCode AlPerspectiveCamera::worldView( double &x, double &y, double &z ) const Description
Returns the cameras view position in x,y, & z in world space. The view direction vector (the direction the camera is pointing in) is the vector between the eye position and the view position.

Arguments
> double &x - the position along the x axis > double &y - the position along the y axis > double &z - the position along the z axis

Return Codes
sSuccess - the position was successfully returned sInvalidObject - the camera is not valid

statusCode AlPerspectiveCamera::worldUp( double &x, double &y, double &z ) const Description
Returns the cameras up position in x,y, & z in world space. The up vector (the direction that indicates the cameras up direction) is the vector between the eye position and the up position.

Arguments
> double &x - the position along the x axis > double &y - the position along the y axis > double &z - the position along the z axis

Return Codes
sSuccess - the position was successfully returned sInvalidObject - the camera is not valid

720 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlPerspectiveCamera::worldEyeViewUp( double &ex, double &ey, double &ez,double &vx, double &vy, double &vz,double &ux, double &uy, double &uz) const Description
Returns the world eye, view and up positions in ex, ey, ez, vx, vy, vz, ux, uy & uz in world space. Note that the view direction vector is the vector between the eye and view positions and that the up direction vector is the vector between the eye and up positions.

Arguments
> double &ex - the eye position along the x axis > double &ey - the eye position along the y axis > double &ez - the eye position along the z axis > double &vx - the view position along the x axis > double &vy - the view position along the y axis > double &vz - the view position along the z axis > double &ux - the up position along the x axis > double &uy - the up position along the y axis > double &uz - the up position along the z axis

Return Codes
sSuccess - the position was successfully returned sInvalidObject - the camera is not valid

statusCode AlPerspectiveCamera::setWorldEye( double x, double y, double z) Description

Sets the cameras world eye position to be x,y, & z in world space. To do this, the cameras eye, view and up nodes may be changed.

Arguments
< double x - the new world eye position along the x axis

AlPerspectiveCamera | 721

< double y - the new world eye position along the y axis < double z - the new world eye position along the z axis

Return Codes
sSuccess - the position was successfully set sInvalidObject - the camera is not valid

statusCode AlPerspectiveCamera::setWorldView( double x, double y, double z) Description

Sets the cameras world view position to be x,y, & z in world space. To do this, the cameras eye, view and up nodes may be changed.

Arguments
< double x - the new world view position along the x axis < double y - the new world view position along the y axis < double z - the new world view position along the z axis

Return Codes
sSuccess - the position was successfully set sInvalidObject - the camera is not valid

statusCode AlPerspectiveCamera::setWorldUp( double x, double y, double z) Description

Sets the cameras world up position to be x,y, & z in world space. To do this, the cameras eye, view and up nodes may be changed.

Arguments
< double x - the new world up position along the x axis < double y - the new world up position along the y axis < double z - the new world up position along the z axis

722 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Return Codes
sSuccess - the position was successfully set sInvalidObject - the camera is not valid

statusCode AlPerspectiveCamera::setWorldEyeViewUp( double ex, double ey, double ez,double vx, double vy, double vz,double ux, double uy, double uz ) Description
Sets the cameras world eye,view and up positions to be ex, ey, ez, vx, vy, vz, ux, uy, uz in world space. To do this, the cameras eye, view and up nodes may be changed.

Arguments
< double ex - the eye position along the x axis < double ey - the eye position along the y axis < double ez - the eye position along the z axis < double vx - the view position along the x axis < double vy - the view position along the y axis < double vz - the view position along the z axis < double ux - the up position along the x axis < double uy - the up position along the y axis < double uz - the up position along the z axis

Return Codes
sSuccess - the position was successfully set sInvalidObject - the camera is not valid

double AlPerspectiveCamera::twistAngle() const Description

Returns the cameras twist angle in degrees. Angle can be either positive or negative. Zero will be returned if the camera is not valid.

AlPerspectiveCamera | 723

statusCode AlPerspectiveCamera::setTwistAngle( double twistAngle) Description

Sets the cameras twist angle to the given twistAngle. Angle is in degrees and can be either positive or negative.

Arguments
< double twistAngle - the new twist angle

Return Codes
sSuccess - the twist angle was successfully set sInvalidObject - the camera is not valid

statusCode AlPerspectiveCamera::changeTwistAngleBy( double deltaTwistAngle) Description

Changes the twist angle by the given deltaTwistAngle. Angle is in degrees and can be either positive or negative.

Arguments
< deltaTwistAngle - the change in twist angle to apply to the camera

Return Codes
sSuccess - the twist angle was successfully changed sInvalidObject - the camera is not valid

statusCode AlPerspectiveCamera::filmBack(double& filmXSize, double& filmYSize) const Description

Returns the film back size in the X and Y directions.

724 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Arguments
> double& filmXSize - the film back size (in inches) in the X direction > double& filmYSize - the film back size (in inches) in the Y direction

Return Codes
sSuccess - operation was successful sInvalidObject - the camera is not valid

statusCode AlPerspectiveCamera::filmOffset(double& filmXOffset, double& filmYOffset) const Description

Returns the film offset in the X and Y directions.

Arguments
> double& filmXOffset - the film offset (in inches) in the X direction > double& filmYOffset - the film offset (in inches) in the Y direction

Return Codes
sSuccess - the operation was successful sInvalidObject - the camera is not valid

statusCode AlPerspectiveCamera::setFilmBack(double filmXSize, double filmYSize) Description

Sets the film back size in the X and Y directions.

Arguments
< double filmXSize - the film back size (in inches) in the X direction < double filmYSize - the film back size (in inches) in the Y direction

AlPerspectiveCamera | 725

Return Codes
sSuccess - the operation successful sInvalidObject - the camera is not valid

statusCode AlPerspectiveCamera::setFilmOffset(double filmXOffset, double filmYOffset) Description

Sets the film offset in the X and Y directions.

Arguments
< double filmXOffset - the film offset (in inches) in the X direction < double filmYOffset - the film offset (in inches) in the Y direction

Return Codes
sSuccess - the operation was successful sInvalidObject - the camera is not valid

double AlPerspectiveCamera::focalLength() const Description

Returns the cameras focal length. -1 is returned if the camera is not valid.

statusCode AlPerspectiveCamera::setFocalLength( double focalLength) Description

Sets the cameras focal length.

Arguments
< double focalLength - the new focal length

Return Codes
sSuccess - the operation was successful

726 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

sInvalidObject - the camera is not valid sInvalidArgument - the focalLength is less than or equal to zero

double AlPerspectiveCamera::angleOfView() const Description

Returns the cameras angle of view. Valid range is from 2.0 to 179.0 degrees. -1 is returned if the camera is not valid.

statusCode AlPerspectiveCamera::setAngleOfView( double angleOfView) Description

Sets the cameras angle of view. Valid range is from 2.0 to 179.0 degrees.

Arguments
< double angleOfView - the new angle of view

Return Codes
sSuccess - the operation was successful sInvalidObject - the camera is not valid sInvalidArgument - if angleOfView is not in the valid range

statusCode AlPerspectiveCamera::depthOfField(boolean& dofEnabled, double& fStop, double& focalDistance) const Description

Returns the cameras depth of field information.

Arguments
> boolean& dofEnabled - TRUE if depth of field is enabled, FALSE if not > double& fStop - cameras f-Stop > double& focalDistance - distance from eye point to plane in focus

AlPerspectiveCamera | 727

Return Codes
sSuccess - the operation was successful sInvalidObject - the camera is not valid

statusCode AlPerspectiveCamera::setDepthOfField(boolean dofEnabled, double fStop, double focalDistance) Description

Sets the cameras depth of field information.

Arguments
< boolean dofEnabled - TRUE to enable depth of field, FALSE to disable it < double fStop - cameras f-Stop < double focalDistance - distance from eye point to plane in focus

Return Codes
sSuccess -the operation was successful sInvalidObject - the camera is not valid

statusCode AlPerspectiveCamera::autoFocus(boolean& enabled) const Description

Returns the cameras auto focus information.

Arguments
> boolean& enabled - TRUE if auto focus enabled, FALSE if not

Return Codes
sSuccess - the operation was successful sInvalidObject - the camera is not valid

728 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlPerspectiveCamera::setAutoFocus( boolean enabled ) Description

Sets the cameras auto focus information.

Arguments
< boolean enabled - TRUE to enable auto focus, FALSE to disable it

Return Codes
sSuccess - the operation was successful sInvalidObject - the camera is not valid

double AlPerspectiveCamera::placementShift() const Description

Returns the placement_shift of the camera. 0 is returned if the camera is not valid.

int AlPerspectiveCamera::placementFitCode() const Description

Returns the placement_fit_code of the camera.

Return values
-1 is returned if the camera is not valid. 0 - FILL_FIT 1 - HORIZONTAL_FIT 2 - VERTICAL_FIT

statusCode AlPerspectiveCamera::setPlacementShift( double placementShift ) Description

Sets the placement shift of the camera.

AlPerspectiveCamera | 729

Arguments
< placementShift - value to set the placement shift to.

Return Codes
sSuccess - if successful sInvalidObject - if the camera is not valid

statusCode AlPerspectiveCamera::setPlacementFitCode( AlCameraWindowFitType fitCode ) Description

Sets the placement fit type of the camera.

Arguments
< fitCode - value to set the placement fit code to.

Return Codes
sSuccess - if successful sInvalidObject - if the camera is not valid

AlPickable
Basic Interface to Alias objects which can be picked.

Synopsis
#include <AlPickable.h> class AlPickable virtual statusCode pick( void ); virtual statusCode unpick( void ); virtual boolean is Picked( void );

Description
This class encapsulates the functionality of Alias objects that have the capacity to be picked. As expected, pickable objects can either be picked or unpicked.

730 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlPickable::AlPickable() Description
Constructs an AlPickable wrapper object.

AlPickable::~AlPickable() Description
AlPickable destructor. Note that objects that are picked and then deleted from OpenModel (through deleteObject) will be unpicked.

statusCode AlPickable::pick( void ) Description

Picks the object.

Return Codes
sSuccess - the object was picked sFailure - the object could not be picked

statusCode AlPickable::unpick( void ) Description

Unpicks the object.

Return Codes
sSuccess - the object was unpicked sFailure - the object could not be unpicked

boolean AlPickable::isPicked( void ) Description

Returns TRUE if the object is picked.

AlPickable | 731

AlPickList
A static class which gives access to the Alias pick list.

Synopsis
#include <AlPickList.h> class AlPickList enum AlPickMaskType { kMaskUnchanged = 0x0, kMaskTemplate = 0x1, kMaskRoot = 0x2, kMaskInterior = 0x4, kMaskLeaf = 0x8, kMaskLight = 0x10, kMaskCurveOnSurface = 0x20, kMaskCamera = 0x40, kMaskLine = 0x80, kMaskPoint = 0x100, kMaskEditPoint = 0x200, kMaskParamCurve = 0x400, kMaskImagePlane = 0x800, kMaskJoint = 0x1000, kMaskCluster = 0x2000, kMaskSelectionHandle= 0x4000, kMaskIKHandle = 0x8000 }; static boolean isValid(); static AlOb ject* getObject(); static AlDagNode* getParentOfObject(); static statusCode firstPickItem(); static statusCode nextPickItem(); static statusCode prevPickItem(); static statusCode applyIterator ToItems( AlIterator*, int& ); static statusCode applyIterator ToItems( AlIteratorWithParent*, int& ); static statusCode clearPickList(); static statusCode pickByName( char* ); static statusCode pickFromScreen( Screencoord x, Screencoord y ); static statusCode pickAreaFromScreen( Screencoord x1, Screencoord y1, Screencoord x2, Screencoord y2 ); static statusCode pushPick List(boolean); static statusCode popPickList(); static statusCode setPickMask( int ); static statusCode getPickMask( int& ); static statusCode asynchronousPick( AlUserPickList& );

Description
This class gives access to the pick list, that is, those objects which are currently active. Note that this will include objects that are active in the MultiLister and not just those objects active in the modeling windows. Objects on the MultiLister include shaders, textures and lights. Once an object is selected in the MultiLister, there will always be a selected object returned by the API. Also, the method clearPickList() only clears the pick list of the modeling windows. Therefore, it is possible to clear the pick list and still have one item on it. This item would be on the MultiLister. The method pickByName() will not pick an item within the MultiLister. In addition, the pick mask and pushing and popping pick routines only work for modeling windows.

732 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

boolean AlPickList::isValid() Description

Returns TRUE if the pick list is currently pointing to something. Items will be either in the modeling windows or the MultiLister.

AlObject* AlPickList::getObject() Description

Returns the object that the pick list is currently referencing from either the modeling windows or the MultiLister.

AlDagNode* AlPickList::getParentOfObject() Description

Returns the parent AlDagNode of the object that the pick list is currently referencing. Note that this function will only return a valid AlDagNode* if the firstPickItem() function has been called. NULL will be returned if the picked object is in the MultiLister.

statusCode AlPickList::firstPickItem() Description

Sets the pick list to reference the first object on the list.

Return Codes
sSuccess - there was something on the pick list sFailure - there is nothing on the pick list

statusCode AlPickList::nextPickItem() Description

Causes the pick list to reference the next object on the list. The next object could be on the MultiLister or in the modeling windows. Use the iterator for traversing the picklist (it is faster and does not disturb the current context of the PickList).

AlPickList | 733

Return Codes
sSuccess - there was something on the pick list sFailure - went past the end of the list sInvalidObject - the picklist is invalid

statusCode AlPickList::prevPickItem() Description

Causes the pick list to reference the previous object on the list. If nextPickItem() just returned sFailure, this method can be used to reference the last item on the pick list.

Return Codes
sSuccess - there was something on the pick list sFailure - went past the end of the list sInvalidObject - the picklist is invalid

statusCode AlPickList::applyIteratorToItems( AlIterator* iter, int& rc ) Description

Applies the given AlIterator to all elements of the pick list. The second argument will be set to the return value of the last application of the iterators function. See the AlIterator on page 544 class for more information. Note that this method DOES NOT modify the pick list. It also allows you to safely traverse multiple pick lists (caused by pick list pushes, and so on). The firstItem,getObject,nextItem methods are unaffected by this routine. It is possible to push a new list, and call applyIterToItems from within another applyIterToItem (which is operating on another pick list in the stack).

Arguments
< iter - the iterator to be applied to each item on the pick list > rc - the return value of the last application of the iterator

734 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Return Codes
sSuccess - the application of the iterator terminated normally sFailure - the application of the iterator terminated abnormally sInvalidArgument - the iterator was NULL. sInvalidObject - you didnt initialize the universe

statusCode AlPickList::applyIteratorToItems( AlIteratorWithParent *iter, int& rc ) Description

Same as above. In addition, this routine uses an iterator with a func() that has a second parameter. This parameter is the AlDagNode* parent of the picked item. The AlDagNode pointer is null for any AlObject that is a shader.

Arguments
< iter - the iterator to be applied to each item on the pick list > rc - the return value of the last application of the iterator

Return Codes
sSuccess - the application of the iterator terminated normally sFailure - the application of the iterator terminated abnormally sInvalidArgument - the iterator was NULL sInvalidObject - the universe was not initialized

statusCode AlPickList::clearPickList( void ) Description

Removes all objects from the pick list. Please see the note W.R.T. the MultiLister in the AlPickList class description.

Return Codes
sSuccess - the pick list was successfully cleared

AlPickList | 735

statusCode AlPickList::pickByName( char* name ) Description

Adds all objects that match the given string pattern to the pick list. All objects in the DAG are searched and those that match the pattern are picked in a toggle manner (that is, if an object is picked already, then unpick it). If nothing in the DAG matched the pattern, then all set names are searched. If only one set name matches, then

if all set members are already picked, then unpick all members if at least one set member is not picked, then pick all members If more than one set name matches, then

if all members of all sets are already picked, then unpick all members if one member of any set is not picked, then pick all members of all sets

If no objects match and no set names match the pattern, then a message is displayed to the user. This method will not pick an item in the MultiLister.

Return Codes
sSuccess - something was successfully picked sFailure - nothing was found that matched the string sInvalidArgument - the given string pointer was NULL

statusCode AlPickList::pickFromScreen( Screencoord x, Screencoord y ) Description

Attempts to pick objects from the screen. Simply pass it the screen coordinates where you want picking to occur, and it will pick any appropriate objects in the window where these coordinates occur, including the SBD window. It will be necessary to do an AlUniverse::redrawScreen(kRedrawActive) to see the effects of the pick. This routine picks the objects in a 8x8 square about the point in question. Note that as would be expected, this routine fails under OpenModel.

736 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Arguments
< x,y - the coordinates to pick from

Return Codes
> sFailure - picking could not be accomplished < sSuccess - picking worked

statusCode AlPickList::pickAreaFromScreen( Screencoord x1, Screencoord y1, Screencoord x2, Screencoord y2 ) Description
Attempts to pick objects from the screen in the rectangle specified by (x1,y1)-(x2,y2). (x1,y1) is the lower left corner of the rectangle. Simply pass it the screen coordinates where you want picking to occur, and it will pick any appropriate objects in the window where those coordinates occur, including the SBD window. Note that as would be expected, this routine fails under OpenModel.

Arguments
< x1,y1,x2,y2 - the coordinates to pick from

Return Codes
> sFailure - picking could not be accomplished < sSuccess - picking worked sInvalidArgument - x2 < x1 or y2 < y1

statusCode AlPickList::pushPickList(boolean copy) Description

It is possible to keep up to 8 picklists in memory at one time with the pick stack. Pushing and popping the stack allows picklists to be maintained while new ones are created. The pick stack is limited to 8 levels deep. Exceeding this will cause errors to be reported to the errlog file.

AlPickList | 737

Arguments
< copy - if true the stack is copied when it is pushed

Return Codes
sSuccess - the stack was successfully pushed sFailure - the stack went too deep sInsufficientMemory - ran out of memory pushing the stack

statusCode AlPickList::popPickList() Description

Pops the pushed pick list. Make sure that you never pop more than you push.

Return Codes
sSuccess - the stack was successfully popped

statusCode AlPickList::setPickMask( int mask ) Description

Sets the mask used by picking routines to determine what can and cannot be picked at any given time. The mask passed in should be ORed together from all the object types that are valid to pick. The mask is a bitwise OR of the following flags:

AlPickList::kMaskUnchanged - no effect AlPickList::kMaskTemplate - objects in the template AlPickList::kMaskRoot - the root node of the DAG AlPickList::kMaskInterior - interior nodes in the DAG AlPickList::kMaskLeaf - leaf nodes in the DAG AlPickList::kMaskLight - lights AlPickList::kMaskUnused AlPickList::kMaskCamera - cameras

738 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlPickList::kMaskLine - lines AlPickList::kMaskPoint - points AlPickList::kMaskEditPoint - edit points AlPickList::kMaskParamCurve - curves in UV space AlPickList::kMaskImagePlane - image plane AlPickList::kMaskSkeleton - skeletons AlPickList::kMaskCluster - clusters AlPickList::kMaskHandle - handles

Arguments
mask - the bit mask to set to pick items

Return Codes
sSuccess - the operation was successful

statusCode AlPickList::getPickMask( int& mask ) Description

Gets the current pick mask and places the result in the mask parameter. This is a bitwise OR of the flags listed in the setPickMask "method."

Arguments
mask - the returned mask

Return Codes
sSuccess - the operation was successful

statusCode AlPickList::asynchronousPick( AlUserPickList& list ) Description

This method should almost NEVER be used. It is not a way to select a whole list of objects at one time. Instead it is to be used by plug-ins that launch

AlPickList | 739

co-operative routines such as those that would wait on the X events queue. Such routines may want to maintain a pick list separately from Alias and at times update Alias pick list. For example, consider a plug-in that implements the SBD window. If the user were doing a trim operation they may choose to select from this new SBD window. If they did so, having the plug-in call AlPickable::pick() would not properly notify the Alias application that the pick list has changed. In some operations the mismatch between what Alias thinks is picked and what is currently picked could cause a segmentation fault. Instead this method should be called with all objects selected in the SBD window. The selection code will then asynchronously update the pick list. It is therefore important that the AlUserPickList be kept consistent. In general this method allows updating of the pick list when the Alias user is in any other operation which may require them to select something. If this method is invoked when the user is not being prompted to select something, the Alias pick list will not be updated, and the AlUserPickList will not be examined until the next time Alias is in pick mode. The AlUserPickList should be a list of AlUserPickItems.

Return Codes
sSuccess - the method succeeded (always the case in OpenAlias) sFailure - the method failed (only occurs in OpenModel)

AlPixFile
Interface to Alias Pix files.

Synopsis
#include <AlPixFile.h> class AlPixFile enum Format { kAlias = 1, kSGI, kGIF, kTIFF, kTIFF16, kOMF, kTIM, kRLA, kFIDO, kHARRY }; AlPixFile(); virtual ~AlPixFile(); statusCode openForRead( char *path ); statusCode openForWrite( char *path, int width, int height, int numChannels, Format fileFormat = kAlias ); statusCode close(); int read( AlPixel *ldata ); int write( AlPixel *ldata ); int width(); int height(); int numChannels(); statusCode file Format( Format& );

740 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Description
This class allows you to read and write Alias Pix files. Please note that kGIF is unsupported since this class cannot open GIF files.

AlPixFile::AlPixFile( void ) Description

Constructs the Pix file object.

AlPixFile::~AlPixFile( void ) Description

Deletes the Pix file object.

statusCode AlPixFile::openForWrite( char *path, int imgWidth, int imgHeight, int numChannels, AlPixFile::Format fileFormat ) Description
Opens the Pix file for writing.

Arguments
< path - file to be opened < width - resolution in x direction < height - resolution in y direction < numChannels - 4 for RGBA, 3 for RGB, 1 for A

Return Codes
sSuccess - file successfully opened for writing sAlreadyCreated - file had already been opened sFailure - file could not be opened

AlPixFile | 741

statusCode AlPixFile::openForRead( char *path ) Description

Opens the Pix file for reading.

Arguments
< path - file to be opened

Return Codes
sSuccess - file successfully opened for reading sAlreadyCreated - file had already been opened sFailure - file could not be opened

statusCode AlPixFile::close( void ) Description

Closes the Pix file.

Return Codes
sSuccess - file successfully closed sInvalidArgument - file had not been opened sFailure - file could not be closed

int AlPixFile::read( AlPixel *ldata ) Description

Reads a scanline from the Pix file. ldata must be previously allocated to hold a scanline of AlPixels.

Arguments
> ldata - array of size width

742 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Return Codes
Returns the number of pixels read. -1 indicates a failure.

int AlPixFile::write( AlPixel *ldata ) Description

Writes a scanline to the Pix file. ldata must contain the scanline.

Arguments
< ldata - array of size width

Return Codes
Returns the number of pixels written. -1 indicates a failure.

int AlPixFile::width( void ) Description

Returns the x resolution of the Pix file. -1 indicates a failure.

int AlPixFile::height( void ) Description

Returns the y resolution of the Pix file. -1 indicates a failure.

int AlPixFile::numChannels( void ) Description

Returns the number of used channels in the Pix file. -1 indicates a failure.

statusCode AlPixFile::fileFormat( AlPixFile::Format &format ) Description

Returns the format of the pix file.

AlPixFile | 743

Arguments
> format - the file format

Return Codes
sSuccess - the file format was found sFailure - the method failed

AlPlaneAttributes
Interface to Alias plane surface attributes.

Synopsis
#include <AlPlaneAttributes.h> class AlPlaneAttributes : public AlAttributes virtual AlObjectType type() const; AlObject* copyWrap per() const; statusCode coefficients( double&, double&, double&, double& ) const; statusCode centerPoint( double&, double&, double& ) const;

Description
AlPlaneAttributes is a class derived from the AlAttributes class. This class allows access to the attributes for a plane. The attributes that define a plane are the coefficients of Ax + By + Cz + D = 0 and coordinates of the center of the plane. At this time it is only possible to query an AlPlaneAttribute. Further, it is currently not possible to create a plane with attributes either in OpenModel or Alias. This attribute is provided for compatibility with IGES, and as such, the only way to get a plane with attributes into an Alias wire file is to import an IGES file into Alias and then save a wire file.

AlObjectType AlPlaneAttributes::type() const Description

Returns the class identifier kPlaneAttributeType.

744 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlPlaneAttributes* AlPlaneAttributes::asPlaneAttributesPtr() Description

This virtual function returns a non-null pointer to itself, indicating that it is safe to cast to an object of this class.

AlObject* AlPlaneAttributes::copyWrapper() const Description

Creates a copy of the AlPlaneAttributes. The returned AlPlaneAttributes will reference the same data as the original.

statusCode AlPlaneAttributes::coefficients( double& c_a, double& c_b, double& c_c, double& c_d ) const Description
Determines the coefficients for the plane, where the plane is defined by the equation: Ax + By + Cz + D = 0.

Arguments
> c_a - coefficient A > c_b - coefficient B > c_c - coefficient C > c_d - coefficient D

Return Codes
sSuccess - the coefficients were successfully returned sInvalidObject - the plane attribute was invalid sFailure - an error occurred.

statusCode AlPlaneAttributes::centerPoint( double& x, double& y, double& z ) const Description

Determines the "center" of a plane.

AlPlaneAttributes | 745

Arguments
> double &x, &y, &z - the returned 3D position of the center

Return Codes
sSuccess - the coefficients were successfully returned sInvalidObject - the plane attribute was invalid sFailure - an error occurred

AlPlayBack
A static class for managing animation playback.

Synopsis
#include <AlPlayBack.h> class AlPlayBack static void playForward (); static void playReverse (); static void stop (); static boolean inPlayBack (); static void nextFrame (); static void previousFrame (); static void nextKeyframe (); static void previousKeyframe (); static void gotoStart (); static void gotoEnd (); static void gotoFrame (const double frame); static AlCallBack *setCallBack (AlCallBack *callBack); static void getStartEndBy (double &start, double &end, double &by);

Description
These set of static methods provide a plug-in developer with the ability to initiate and manage animation playback. A callback facility is also provided, which allows polling type plug-ins to do a limited set of operations after each frame has been displayed. Be VERY CAREFUL about what you do in this callback. As part of its optimization technique, a lot of animation information is cached outside of the normal messaging system. This means that if you delete some animation objects while playback is active, at some stage PowerAnimator will become very confused (as in core dump confused). Note that this class only functions in OpenAlias. In OpenModel the class exists but does not do anything.

746 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

void AlPlayBack::playForward () Description

Begins (or continues) playback forward.

void AlPlayBack::playReverse () Description

Begins (or continues) playback reverse.

void AlPlayBack::stop () Description

Stops playback.

boolean AlPlayBack::inPlayBack () Description

Returns TRUE if Alias is currently in playback.

void AlPlayBack::nextFrame () Description

Increments the current playing frame (or views the next frame if you are not in playback mode).

void AlPlayBack::previousFrame () Description

Decrements the current playing frame (or views the previous frame if you are not in playback mode).

AlPlayBack | 747

void AlPlayBack::nextKeyframe () Description

Advances the current playing frame to the next keyframe for currently selected objects (or views that frame if you are not in playback mode).

void AlPlayBack::previousKeyframe () Description

Backs up the current playing frame to the previous keyframe for currently selected objects (or views that frame if you are not in playback mode).

void AlPlayBack::gotoStart () Description

Sets the current playing frame to the start of the animation (or views that frame if you are not in playback mode).

void AlPlayBack::gotoEnd () Description

Sets the current playing frame to the end of the animation (or views that frame if you are not in playback mode).

void AlPlayBack::gotoFrame (const double frame) Description

Sets the current playing frame to the requested frame (or views that frame if you are not in playback mode).

void AlPlayBack::getStartEndBy (double &start, double &end, double &by) Description

Gets the current start/end/by values specified by the user.

748 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlCallBack *AlPlayBack::setCallBack (AlCallBack *callBack) Description

Sets the current playback callback function. During playback, this function will be called after each frame is displayed. This function is primarily intended to be used by device polling plug-ins that may wish to alter playback conditions. The current callback function is returned, and you should restore that function when you are done.

AlPlayFrame
An optimization of the view frame operation.

Synopsis
#include <AlPlayFrame.h> class AlPlayFrame AlPlayFrame (boolean bAllChannels = FALSE); ~AlPlayFrame (); statusCode viewFrame (const double frame, const boolean doRedraw = TRUE); void setShowSameFrame (const boolean showSameFrame = FALSE)

Description
Viewframes can be quite slow when done individually. The problem is that some information is being recomputed every time the viewFrame operation is called. This class encapsulates that dependency, doing the computation once, allowing for a series of viewframes to take place in rapid succession. Be VERY VERY CAREFUL about how you use this class. As part of its optimization technique, a lot of animation information is cached outside of the normal messaging system. This means that if you delete some animation objects while an AlPlayFrame object is active, then at some stage PowerAnimator will become very confused (as in core dump confused). In addition, the constructor for this class REQUIRES that modeling windows be opened. Core dumps or strange behaviour within the application can occur if this condition is not met. Ordinarily the AlPlayFrame class will not recompute a requested frame if it is already the current frame. However for certain uses (for example, if you are changing a keyframe position) it may be necessary to recompute the current frame. Passing TRUE to the setShowSameFrame method will allow you to override the default behavior.

AlPlayFrame | 749

To use AlPlayFrame, create an instance of AlPlayFrame at the point in your code where the viewFrames are to begin. Call the viewFrame member of that AlPlayframe object for as many frames as are necessary. When that AlPlayFrame object goes out of scope, the destructor undoes the optimization and it becomes safe to modify Alias structures. For example:
make list_of_frames; frm in list_of_frames do Frame( frm ); } { { } AlPlayFrame playframe; for playframe.view

AlPlayFrame::AlPlayFrame (boolean bAllChannels) Description

Constructs a new AlPlayFrame object, and setup the PowerAnimator view frame module for playback.

Arguments
bAllChannels - if TRUE all channels are played

AlPlayFrame::~AlPlayFrame () Description
Destructor for a AlPlayFrame object. Undoes the playframe optimizations and allows safe modifications of Alias objects.

statusCode AlPlayFrame::viewFrame(const double frame, const boolean doRedraw) Description

Views the universe at the frame time specified by "frame". All animated items in the universe will have their animation evaluated at the given frame time, and the animated parameters will now take on their new values. Note that if the model contains construction history, fillets and trims may be re-evaluated. This could cause any surface CV pointers to become invalid. Afterwards, any viewFrame pointers to anything should not be trusted. If this is a problem you should add a message handler for kMessageDagNodeReplaceGeometry.

Arguments
< frame - the time at which to evaluate the animation in the universe

750 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

< doRedraw - TRUE if this method should do the redraw, FALSE if the calling function well do it (perhaps by calling AlUniverse::redrawScreen)

Return Codes
sSuccess - the viewframe succeeded sFailure - an error occurred (that is, the universe may not have been initialized)

AlPointConstraint
Interface to IK point constraint data.

Synopsis
#include <AlPointConstraint.h> class AlPointConstraint : public AlConstraint AlPointConstraint(); virtual ~AlPointConstraint(); virtual AlObject* copyWrapper() const; statusCode create( AlDagNode*, AlDagNode* ); statusCode create( AlDagNode*, AlDagNode*, double[2] ); virtual AlObjectType type() const; statusCode point( double[3] ) const;

Description
The AlPointConstraint class allows access to the IK point constraint information on an AlJoint. This class is derived from the AlConstraint class. (See the discussion of skeletons, joints, constraints, ik, and so on, in the Alias manuals for a full description.)

AlPointConstraint::AlPointConstraint() Description
Constructs an AlPointConstraint wrapper object.

AlPointConstraint::~AlPointConstraint() Description
Deletes an AlPointConstraint wrapper object.

AlPointConstraint | 751

AlObject *AlPointConstraint::copyWrapper() const Description

Wrapper object duplicator for AlPointConstraint.

statusCode AlPointConstraint::create( AlDagNode* srcNode, AlDagNode* destNode ) Description

Does all the initialization necessary to attach the constraint node to the DAG node as a point constraint. A DAG node can not be constrained to itself.

Arguments
< srcNode - AlDagNode that this constraint is to be added to < destNode - the AlDagNode that srcNode will be constrained to

Return Codes
sInvalidArgument - one of the arguments was wrong or tried to constrain a node to itself sInsufficientMemory - ran out of memory sFailure - failed to add the constraint sSuccess - successfully added the constraint

statusCode AlPointConstraint::create( AlDagNode* srcNode, AlDagNode* destNode, double uv[2] ) Description

This method does all the initialization necessary to attach the constraint node to the dag node as an uv point constraint. A dag node can not be constrained to itself. The destNode must be a spline geometry node, for example, a spline curve or a spline surface.

Arguments
< srcNode - AlDagNode this constraint is to be added to. < destNode - The AlDagNode that srcNode will be constrained to.

752 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

< uv[2] - The uv parameter on destNode that srcNode will be constrained to. If the destNode is a curve, only uv[0] is used.

Return Codes
sInvalidArgument - one of the arguments was wrong or tried to constrain a node to itself. sInsufficientMemory - ran out of memory. sFailure - failed to add the constraint. sSuccess - successfully added the constraint.

AlObjectType AlPointConstraint::type() const Description

Returns the class identifier kPointConstraintType;

AlPointConstraint* AlPointConstraint::asPointConstraintPtr() Description

This virtual function returns a non-null pointer to itself, indicating that it is safe to cast to an object of this class.

statusCode AlPointConstraint::point( double pnt[3] ) const Description

Returns the coordinates of the point being constrained to.

AlPointLight
Encapsulates the creation, deletion and manipulation of a point light.

Synopsis
#include <AlPointLight.h> class AlPointLight: public AlNonAmbient Light AlPointLight(); virtual ~AlPointLight(); virtual AlObject* copyWrapper() const; statusCode create(); AlObjectType type() const;

AlPointLight | 753

Description
Point lights are like incandescent light bulbs. They emit light in all directions. To create a point light, the user must instantiate and call the create method on an AlPointLight object. (For more information on lights in general, see the Class Description of the AlNonAmbientLight on page 660 object.)

AlPointLight::AlPointLight() Description
Constructs an AlPointLight wrapper object.

AlPointLight::~AlPointLight() Description
Deletes an AlPointLight wrapper object.

statusCode AlPointLight::create() Description

Creates all the DAG nodes for this light and adds them to the universe. The DAG nodes are for position, look at and up, and another DAG node that groups these three together.

Return Codes
sSuccess - everything was successful sInsufficientMemory - not enough memory available sAlreadyCreated - light is already created

AlObjectType AlPointLight::type() const Description

Returns the class identifier, kPointLightType.

754 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlPoint
Contains functionality common to all Alias construction entity points.

Synposis
#include <AlPoint.h> class AlPoint : public AlConstructionEntity virtual ~AlPoint(); virtual AlObject * copyWrapper() const = 0; virtual AlObjectType type() const; virtual statusCode worldPosition(double &, double &, double &) const = 0;

Description
This virtual class is derived from AlConstructionEntity and encapsulates methods common to all the Alias point type such as space points, curve points, curve on surface points, and surface points.AlPoint::AlPoint(void)

AlPoint::AlPoint(void) Description
Constructs an AlPoint wrapper object.

AlPoint::~AlPoint() Description
Deletes an AlPoint wrapper object.

AlObjectType AlPoint::type() const Description

Returns the class identifier kPointType.

AlPrintf
Printf style utility functions for OpenAlias.

AlPoint | 755

Synopsis
#include <AlLiveData.h>

Description
These functions provide Printf and vPrintf style output for Alias.

void AlVprintf( AlOutputType ot, const char* fmt, va_list ap ) Description

A vprintf style output function. The output type will be one of: kStdout - the output will be sent to stdout kStderr - the output will be sent to stderr kPrompt - the output will be sent to the prompt line and it is added to the prompt line history kErrlog - the output will be sent to the error log file kPromptNoHistory - the output will be sent to the prompt line, but it will not be added to the history

Arguments
ot - the output type fmt - the string that is used to format the text ap - the variable argument list (see stdarg.h for details)

void AlPrintf( AlOutputType ot, const char* fmt, ... ) Description

A printf style output function. The output type will be one of kStdout, kStderr, kPrompt, kErrlog, or kPromptNoHistory.

Arguments
ot - the output type

756 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

fmt - the string that is used to format the text ... - variable arguments that depend on the output text

AlProduct
Class that provides information about the product and its version.

Synopsis
#include <AlProduct.h> class AlProduct static const char* productName( void ); static const char* versionNumber( void );

Description
This class provides methods for obtaining the product name and the current version number.

const char *AlProduct::productName( void ) Description

Returns the current product name.

const char *AlProduct::versionNumber( void ) Description

Returns the current product version number.

AlRadialLocator
Interface to Alias Radial locators.

AlProduct | 757

Synopsis
#include <AlRadialLocator.h> class AlRadialLocator : public AlLoc ator AlRadialLocator(); ~AlRadialLocator(); virtual AlObject * copyWrap per() const; virtual AlObjectType type() const; statusCode cre ate(const AlCurve *, double u = 0.0); statusCode create(const Al CurveOnSurface *, double u = 0.0); statusCode radius(double &) const; statusCode center(double &, double &, double &) const; statusCode setParameter(double); statusCode parameter(double &) const; statusCode setOffset(double); statusCode offset(double &) const; statusCode setLeftJustify(boolean); statusCode leftJustify(boolean &) const; AlObject * attachedTo();

Description
A Radial locator is used to create a radial measure of a curve or a curve on surface in its respective parametric space. This class encompasses methods to create the locator, query the radius and set the display attributes of the radial locator in the Alias windows. If the curve or curve on surface on which this locator is created is deleted, the locator is deleted.

AlRadialLocator::AlRadialLocator(void) Description
Constructs an AlRadialLocator wrapper object.

AlRadialLocator::~AlRadialLocator() Description
Deletes an AlRadialLocator wrapper object.

AlObject *AlRadialLocator::copyWrapper() const Description

Returns an exact copy of the AlRadialLocator wrapper.

758 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlObjectType AlRadialLocator::type() const Description

Returns the class identifier kRadialLocatorType.

statusCode AlRadialLocator::create(const AlCurve *curve, double u) Description

Creates a radial locator on the given curve.

Arguments
< curve - the curve on which the locator is created < u - curve parameter at which the locator is created

Return Codes
sSuccess - the locator was successfully created sAlreadyCreated - object has already been created sFailure - the radial locator could not be created sInvalidArgument - the curve is not a valid object

statusCode AlRadialLocator::create(const AlCurveOnSurface *curve, double u) Description

Creates a radial locator on the given curve on surface.

Arguments
< curve - the curve on surface on which the locator is created < u - curve parameter at which the locator is created

Return Codes
sSuccess - the locator was successfully created sAlreadyCreated - object has already been created

AlRadialLocator | 759

sFailure - the radial locator could not be created sInvalidArgument - the given curve on surface is not a valid object

statusCode AlRadialLocator::radius(double &radiusValue) const Description

Gets the radius of the curve where the radial locator is created.

Arguments
> radius - the radius of the curve

Return Codes
sSuccess - the radius was found sInvalidObject - the object is not valid

statusCode AlRadialLocator::center(double &x, double &y, double &z) const Description

Gets the center of curvature of the curve where the radial locator is created.

Arguments
> x, y, z - the world coordinates of the center

Return Codes
sSuccess - the center was found sInvalidObject - the object is not valid

statusCode AlRadialLocator::setParameter(double u) Description

Sets the curve parameter at which the radial locator is located.

Arguments
< u - curve parameter

760 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Return Codes
sSuccess - the parameter was set sInvalidObject - the object is not valid

statusCode AlRadialLocator::parameter(double &u) const Description

Gets the curve parameter where radial locator is located.

Arguments
> u - curve parameter

Return Codes
sSuccess - the parameter was found sInvalidObject - the object is not valid

statusCode AlRadialLocator::setOffset(double offset) Description

Sets the offset in Radial locator display.

Arguments
< offset - the value of the offset

Return Codes
sSuccess - the offset was set sInvalidObject - the object is not valid

statusCode AlRadialLocator::offset(double &offsetValue) const Description

Gets the offset of the Radial locator display.

AlRadialLocator | 761

Arguments
> offsetValue - the display offset

Return Codes
sSuccess - the offset was found sInvalidObject - the object is not valid

statusCode AlRadialLocator::setLeftJustify(boolean leftJustify) Description

Sets the justification of the text for the Radial locator. The text can be right justified or left justified.

Arguments
< leftJustify - a value of true makes the text left justified and a value false makes it right justified

Return Codes
sSuccess - setting was successful sInvalidObject - the object is not valid

statusCode AlRadialLocator::leftJustify(boolean &leftJustify) const Description

Finds whether the text of radial locator is left justified or right justified.

Arguments
> leftJustify - a value of true indicates that it is left justified and false indicates it is right justified.

Return Codes
sSuccess - the justification was found sInvalidObject - the object is not valid

762 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

AlObject *AlRadialLocator::attachedTo() Description

Returns the object this locator is attached to. This object can be attached to either a curve on surface or a curve node. NULL is returned if this method fails.

AlRender
Interface to Alias render options.

AlRender | 763

Synopsis

764 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

#include <AlRender.h> class AlResolutionItem : public AlLinkItem AlResolutionItem* nextItem() AlResolutionItem* prevItem() char* name; int x, y; double aspect; class AlRender // general settings static Source render(); static statusCode setRender( Source ); static boolean animation(); static statusCode setAnimation( boolean ); static AnimationRange animationRange(); static statusCode setAnimationRange( AnimationRange ); static statusCode animationRange(double&start, double&end, double&by ); static statusCode setAnimationRange(double start, double end, double by); static Scope hiddenLineParms(); static statusCode setHiddenLineParams( Scope ); static Scope qualityScope( Quality ); static statusCode setQualityScope( Quality, Scope ); static Quality qualityType( Quality ); static statusCode setQualityType( Quality, Scope ); // Global Quality Parameters: Subdivision & AntiAlias for low,med,high class Subdivision { static Type type( Quality ); static statusCode setType( Quality, Type ); static int uniformU( Quality ); static statusCode setUniformU( Quality, int ); // 1..256 static int uniformV( Quality ); static statusCode setUniformV( Quality, int ); // 1..256 static int adaptiveMin( Quality ); static statusCode setAdaptiveMin( Quality, int ); // 1..128 static int adaptiveMax( Quality ); static statusCode setAdaptiveMax( Quality, int ); // 1..128 static double adaptiveThreshold( Quality ); static statusCode setAdaptiveThreshold( Quality, double ); // 0..1 }; class AntiAlias { static int min( Quality ); static statusCode setMin( Quality, int ); // 0..6 static int max( Quality ); static statusCode setMax( Quality, int ); // 0..6 static double threshold( Quality ); static statusCode setThreshold( Quality, double ); }; class Limits { static boolean createPreview( Quality ); static statusCode setCreatePreview( Quality, boolean ); static int maxReflections( Quality ); static statusCode setMaxReflections( Quality,int ); // 0..10 static int maxRefractions( Quality ); static statusCode setMaxRefractions( Quality,int ); // 0..10 static int maxShad owLevels( Quality ); static statusCode setMaxShadowLevels( Qual ity,int ); // 0..10 static int subdivideRecurse( void ); static statusCode setSubdivideRecurse( int ); // 1..3 }; class Composite

AlRender | 765

{ static boolean enabled(); static statusCode setEnabled( boolean ); static double coverageThreshold(); static statusCode setCover ageThreshold( double ); // 0..1 }; class Blur { static boolean postFilter(); static statusCode setPostFilter( boolean ); static int postCenter(); static statusCode setPostCen ter( int ); // 0..20 static int postAdjacent(); static statusCode setPostAdjacent( int ); // 0..20 static int postDiagonal(); static statusCode setPostDiagonal( int ); // 0..20 static boolean motionBlur(); static statusCode setMotion Blur( boolean ); static double shutterAngle(); static statusCode setShutterAngle( double ); // 1..360 }; class Misc { static GeometrySource geometrySource(); static statusCode set GeometrySource( GeometrySource ); static boolean textures(); static statusCode setTextures( boolean ); static boolean skelet ons(); static statusCode setSkeletons( boolean ); static boolean noTransparencyInDepth(); static statusCode setNoTransparencyInDe pth( boolean ); static double transparency(); static statusCode setTransparency( double ); // 0..1 static boolean keepNon glowedImage(); static statusCode setKeepNonglowedImage( boolean ); static boolean spotLightDepthMaps(); static statusCode setSpot LightDepthMaps( boolean ); static boolean depthMapsInMemory(); static statusCode setDepthMapsInMemory( boolean ); static boolean attenuateTransparency(); static statusCode setAttenuateTranspar ency( boolean ); }; class Image { static Format format(); static statusCode setFormat( Format ); static DepthFormat depthFormat(); static statusCode setDepth Format( DepthFormat ); static Fields fields(); static statusCode setFields( Fields ); static boolean oddFirst(); static statusCode setOddFirst( boolean ); static boolean ignoreFilmGate(); static statusCode setIgnoreFilmGate( boolean ); static double gammaCorrec tion(); static statusCode source( const char *, boolean &, boolean &, boolean & ); static statusCode setSource( const char *, boolean, boolean, boolean ); static statusCode setGammaCorrection( double ); // 0..2 static boolean XYRatioLock(); static statusCode setXYRatioLock( boolean ); static int resolutionX(); static statusCode setResolutionX( int ); // 0..2048 static int resolutionY(); static statusCode setResolutionY( int ); // 0..2048 static double aspectRatio(); static statusCode setAspectRatio( double ); // 0..1 static statusCode readResol utions( AlList* &list ); };

766 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

class HiddenLine { static boolean useFillColor(); static statusCode setUseFillCol or( boolean ); static statusCode fillColor( double &, double &, double &); static statusCode setFillColor( double, double, double ); // 0..255 static statusCode lineColor( double &, double &, double &); static statusCode setLineColor( double, double, double ); // 0..255 static int patchLinesU(); static statusCode setPatchLinesU( int ); // 0..8 static int patchLinesV(); static statusCode setPatchLinesV( int ); // 0..8 }; class Particle { static boolean show(); static statusCode setShow( boolean ); static int simulationSubsteps(); static statusCode setSimulation Substeps( int ); // 1..8 static int framesPerSecond(); static statusCode setFramesPerSecond( int ); // 1..30 };

Description
This class encapsulates all access to the Alias render options. Every value in the window can be retrieved and set. Please see the Menu Book for additional information on these parameters and their functions.

AlRender::Source AlRender::render() Description

Returns the source that is currently being rendered.

statusCode AlRender::setRender( AlRender::Source source ) Description

Sets the source to kAll or kActive. Note: this setting is overridden by the store_active flag in the AlUniverse::writeSDL() method.

Arguments
< source - new value, kAll or kActive

Return Codes
sSuccess - value was set sInvalidArgument - value was not a valid enum member

AlRender | 767

boolean AlRender::animation() Description

Returns TRUE if animation is currently being rendered.

statusCode AlRender::setAnimation( boolean on ) Description

Sets if animation should be rendered.

Return Codes
sSuccess - value was set

AlRender::AnimationRange AlRender::animationRange() Description

Returns the animation type range that is being used.

statusCode AlRender::setAnimationRange( AlRender::AnimationRange range ) Description

Sets the type of animation range to kGlobalRange, kMinMax or kTimeSlider.

Return Codes
sSuccess - value was set sInvalidArgument - value was not a valid enum member

statusCode AlRender::animationRange( double& start, double& end, double& by) Description

Retrieves the animation range endpoints and step size. This is only valid for min/max and global.

768 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Arguments
start - start of the range end - end of the range by - step size

Return Codes
sSuccess - operation succeeded sFailure - operation failed sInvalidObject - the current animationRange is not MinMax or Global

statusCode AlRender::setAnimationRange( double start, double end, double by) Description

Sets the animation range. This is only valid for kGlobalRange.

Arguments
start - start of the range (must be >=0) end - end of the range (must be >= start) by - step size (must be >0 )

Return Codes
sSuccess - operation succeeded sFailure - operation failed sInvalidObject - the current animationRange is not Global sInvalidArgument - by was negative, start was negative or end < start

AlRender::Scope AlRender::hiddenLineParms() Description

Returns the current hidden line parameter setting.

AlRender | 769

statusCode AlRender::setHiddenLineParams( AlRender::Scope scope ) Description

Sets the hidden line parameter option in the rendering. Scope is either kPerObject or kGlobal.

Return Codes
sSuccess - value was set sInvalidArgument - value was not a valid enum member

AlRender::Scope AlRender::qualityScope( AlRender::Quality ) Description

Returns the current rendering quality scope.

statusCode AlRender::setQualityScope( AlRender::Quality, AlRender::Scope scope ) Description

Sets the rendering quality scope. Scope is either kPerObject or kGlobal.

Return Codes
sSuccess - value was set sInvalidArgument - value was not a valid enum member

AlRender::Quality AlRender::qualityType() Description

Returns the rendering quality type.

statusCode AlRender::setQualityType( AlRender::Quality q )SDescription

Sets the rendering quality type. Quality is one of kLow, kMedium or kHigh.

770 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Return Codes
sSuccess - value was set sInvalidArgument - value was not a valid enum member

AlRender::Subdivision::Type AlRender::Subdivision::type( AlRender::Quality q) Description

Returns the rendering subdivision type of the quality parameter.

statusCode AlRender::Subdivision::setType( AlRender::Quality q, AlRender::Subdivision::Type t ) Description

Sets the rendering subdivision type. The type is either kAdaptive or kUniform and is applied to the quality parameter selected.

Return Codes
sSuccess - value was set sInvalidArgument - value was not a valid enum member

int AlRender::Subdivision::uniformU( AlRender::Quality q ) Description

Returns the uniform U value for quality parameter.

statusCode AlRender::Subdivision::setUniformU( AlRender::Quality q, int num ) Description

Sets the uniform U value for the quality parameter. The uniform U value is used to subdivide patches into triangles without taking the curvature into account.

AlRender | 771

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 1..256

int AlRender::Subdivision::uniformV( AlRender::Quality q) Description

Returns the uniform V value for the quality parameter.

statusCode AlRender::Subdivision::setUniformV( AlRender::Quality q, int num) Description

Sets the uniform V value for the quality parameter. The uniform Vvalue is used to subdivide patches into triangles without taking the curvature into account.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 1..256

int AlRender::Subdivision::adaptiveMin( AlRender::Quality q) Description

Returns the adaptive minimum for the quality parameter.

statusCode AlRender::Subdivision::setAdaptiveMin( AlRender::Quality q, int num) Description

Sets the adaptive minimum of the subdivision for the quality parameter. This value determines the minimum number of subdivisions between CVs in both U and V.

772 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 1..128

int AlRender::Subdivision::adaptiveMax( AlRender::Quality q) Description

Returns the adaptive maximum of the quality parameter.

statusCode AlRender::Subdivision::setAdaptiveMax( AlRender::Quality q, int num) Description

Sets the adaptive maximum of the subdivision for the quality parameter. This value determines the maximum number of subdivisions between CVs in both U and V.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 1..128

double AlRender::Subdivision::adaptiveThreshold( AlRender::Quality q) Description

Returns the adaptive threshold of the quality parameter.

statusCode AlRender::Subdivision::setAdaptiveThreshold( AlRender::Quality q, double num ) Description Return Codes

sSuccess - the value was set sInvalidArgument - the value was not in the range 0..1

AlRender | 773

int AlRender::AntiAlias::min( AlRender::Quality q ) Description

Returns the anti-alias minimum for the quality parameter.

statusCode AlRender::AntiAlias::setMin( AlRender::Quality q, int num) Description

Sets the anti-alias minimum for the quality parameter. The anti-alias minimum determines the minimum number of subdivisions per pixel.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..6

int AlRender::AntiAlias::max( AlRender::Quality q ) Description

Returns the anti-alias maximum for the quality parameter.

statusCode AlRender::AntiAlias::setMax( AlRender::Quality q, int num) Description

Sets the adaptive maximum for the quality parameter. The adaptive maximum determines the maximum number of subdivisions per pixel.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..6

double AlRender::AntiAlias::threshold( AlRender::Quality q ) Description

Returns the anti-alias threshold for the quality parameter.

774 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlRender::AntiAlias::setThreshold( AlRender::Quality q, double num ) Description

Sets the anti-alias threshold for the quality parameter. If the samples of colors at each corner of a pixel is over threshold then subdivision is used to do a finer grain of anti-aliasing.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..1

boolean AlRender::Limits::createPreview( AlRender::Quality q ) Description

Returns if the preview option is selected for the quality parameter.

statusCode AlRender::Limits::setCreatePreview( AlRender::Quality q, boolean on ) Description

Sets the preview option for the quality parameter. If preview is turned on, a postage stamp sized raytraced image is calculated.

Return Codes
sSuccess - value was set

int AlRender::Limits::maxReflections( AlRender::Quality q ) Description

Returns the maximum number of reflections allowed for the quality parameter.

AlRender | 775

statusCode AlRender::Limits::setMaxReflections( AlRender::Quality q, int num) Description

Sets the maximum number of reflections for the quality parameter. This controls the number of levels that reflected rays will be raytraced.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..10

int AlRender::Limits::maxRefractions( AlRender::Quality q ) Description

Returns the maximum number of refractions allowed for the quality parameter.

statusCode AlRender::Limits::setMaxRefractions( AlRender::Quality q, int num) Description

Sets the maximum number of refractions allowed for the quality parameter. This controls the number of levels of refracted rays that will be raytraced.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..10

int AlRender::Limits::maxShadowLevels( AlRender::Quality q ) Description

Returns the maximum number of shadow levels allowed for the quality parameter.

776 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlRender::Limits::setMaxShadowLevels( AlRender::Quality q, int num ) Description

Sets the maximum number of shadow levels allowed for the quality parameter. This controls the number of levels of shadows rays that will be raytraced.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range -1..10

int AlRender::Limits::subdivideRecurse( void ) Description

Returns the current subdivide recurse setting.

statusCode AlRender::Limits::setSubdivideRecurse( int num ) Description

Sets the subdivide recurse setting to num. This setting provides a limit on the number of times that spatial subdivision is recursively applied to the scene.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 1..3

boolean AlRender::Composite::enabled() Description

Returns if composite rendering is enabled.

AlRender | 777

statusCode AlRender::Composite::setEnabled( boolean on ) Description

Sets composite rendering to on or off. If this option is on, then objects that are rendered are not anti-aliased against the background.

Return Codes
sSuccess - value was set

double AlRender::Composite::coverageThreshold() Description

Returns the composite rendering coverage threshold.

statusCode AlRender::Composite::setCoverageThreshold( double cover ) Description

Sets the composite rendering coverage threshold to cover. This setting determines the number of subsamples required for a pixel as a whole to be considered a part of an object and not a part of the background.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..1

boolean AlRender::Blur::postFilter() Description

Returns if motion blur post filter option is set.

statusCode AlRender::Blur::setPostFilter( boolean on ) Description

Sets the motion blur post filter option to on or off. Setting this option to on provides additional anti-aliasing after the regular rendering process.

778 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Return Codes
sSuccess - value was set

int AlRender::Blur::postCenter() Description

Returns the blur center pixel weight.

statusCode AlRender::Blur::setPostCenter( int center ) Description

Sets the blurring center pixel weight.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..20

int AlRender::Blur::postAdjacent() Description

Returns the blur edge pixel weights.

statusCode AlRender::Blur::setPostAdjacent( int adj ) Description

Sets the blur edge pixel weights.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..20

AlRender | 779

int AlRender::Blur::postDiagonal() Description

Returns the blur corner pixel weights.

statusCode AlRender::Blur::setPostDiagonal( int diag ) Description

Sets the blur corner pixel weights.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..20

boolean AlRender::Blur::motionBlur() Description

Returns TRUE if motion blur is on.

statusCode AlRender::Blur::setMotionBlur( boolean on ) Description

Sets the motion blur to be on or off. Turning this option on produces smoother animations.

Return Codes
sSuccess - value was set

double AlRender::Blur::shutterAngle() Description

Returns the current shutter angle.

780 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlRender::Blur::setShutterAngle( double shutter ) Description

Sets the current shutter angle if blur is on. The larger the shutter value the greater the blur.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 1..360

AlRender::Misc::GeometrySource AlRender::Misc::geometrySource() Description

Returns the current geometry source.

statusCode AlRender::Misc::setGeometrySource( AlRender::Misc::GeometrySource source ) Description

Sets the current geometry source to either kModeler or kSDLFile.

Return Codes
sSuccess - value was set sInvalidArgument - value was not a valid enum member

boolean AlRender::Misc::textures() Description

Returns TRUE if textures will be used in the rendering.

statusCode AlRender::Misc::setTextures( boolean on ) Description

Sets if textures will be used in the rendering.

AlRender | 781

Return Codes
sSuccess - value was set

boolean AlRender::Misc::skeletons() Description

Returns TRUE if skeletons are being displayed in the rendering.

statusCode AlRender::Misc::setSkeletons( boolean on ) Description

Sets if skeletons are being used in the rendering.

Return Codes
sSuccess - value was set

boolean AlRender::Misc::noTransparencyInDepth() Description

Returns TRUE if the "no transparency in depth" option is on.

statusCode AlRender::Misc::setNoTransparencyInDepth( boolean on ) Description

Sets the "no transparency in depth map" option. If this option is set, transparent objects appear in the depth map file.

Return Codes
sSuccess - value was set

double AlRender::Misc::transparency() Description

Returns the transparency percentage.

782 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlRender::Misc::setTransparency( double trans ) Description

Sets the transparency percentage. Objects with a transparency greater than or equal to the trans value will not appear in the depth file.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..1

boolean AlRender::Misc::keepNonglowedImage() Description

Returns TRUE if the renderer will not keep the post processed non glowed image.

statusCode AlRender::Misc::setKeepNonglowedImage( boolean on ) Description

Sets the renderer to keep the non glowed image in the rendering post process if parameter on is TRUE.

Return Codes
sSuccess - value was set

boolean AlRender::Misc::spotLightDepthMaps() Description

Returns TRUE if shadow depth maps are being written to disk.

statusCode AlRender::Misc::setSpotLightDepthMaps( boolean on ) Description

Sets if shadow depth maps should be written to disk based.

AlRender | 783

Return Codes
sSuccess - value was set

boolean AlRender::Misc::depthMapsInMemory() Description

Returns TRUE if depth maps are kept in memory.

statusCode AlRender::Misc::setDepthMapsInMemory( boolean on ) Description

Sets if depth maps are to be kept in memory. If set to TRUE, then the depth map is not recomputed for subsequent frames.

Return Codes
sSuccess - value was set

boolean AlRender::Misc::attenuateTransparency() Description

Returns FALSE if attenuate transparency is on.

statusCode AlRender::Misc::setAttenuateTransparency( boolean on ) Description

Sets attenuate transparency to off to make totally transparent objects appear opaque.

Return Codes
sSuccess - value was set

AlRender::Image::Format AlRender::Image::format() Description

Returns the image format.

784 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlRender::Image::setFormat( AlRender::Image::Format imageFormat ) Description

Sets the image format to one of kAlias, kSGI, kTIFF, kTIFF16, kRLA, kFIDO or kHARRY.

Return Codes
sSuccess - value was set sInvalidArgument - value was not a valid enum member

AlRender::Image::DepthFormat AlRender::Image::depthFormat() Description

Returns the depth format.

statusCode AlRender::Image::setDepthFormat( AlRender::Image::DepthFormat depth ) Description

Sets the image depth format to either kDepthAlias or kDepthComposer.

Return Codes
sSuccess - value was set sInvalidArgument - value was not a valid enum member

AlRender::Image::Fields AlRender::Image::fields() Description

Returns the images fields.

AlRender | 785

statusCode AlRender::Image::setFields( AlRender::Image::Fields setFields ) Description

Sets the image fields to one of kOff, kEven, kOdd or kBoth.

Return Codes
sSuccess - value was set sInvalidArgument - value was not a valid enum member

boolean AlRender::Image::oddFirst() Description

Returns TRUE if odd first ordering was chosen for field ordering.

statusCode AlRender::Image::setOddFirst( boolean oddFirst ) Description

Sets fields to be ordered by odd first if the parameter oddFirst is TRUE. If oddFirst if FALSE then field ordering will be even first.

Return Codes
sSuccess - value was set

boolean AlRender::Image::ignoreFilmGate() Description

Returns TRUE if the rendered image will ignore film gates.

statusCode AlRender::Image::setIgnoreFilmGate( boolean ignoreGate ) Description

Sets ignoreGate to TRUE if the region outside of the filmback should not be rendered.

786 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Return Codes
sSuccess - value was set

double AlRender::Image::gammaCorrection() Description

Returns the current gamma correction value.

statusCode AlRender::Image::setGammaCorrection( double gamma ) Description

Sets the gamma correction value. Gamma correction is used to alter images by specified factors in each channel to correct the rendered color.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..2

statusCode AlRender::Image::source( const char *camName, boolean &image, boolean &mask, boolean &depth ) Description
Returns the Image File Output toggles in the camera named camName.

Arguments
< camName - name of the camera > image - Image toggle > mask - Mask toggle > depth - Depth toggle

Return Codes
sSuccess - the values were retrieved sInvalidArgument - camName was NULL

AlRender | 787

sFailure - camera of the given name was not found

statusCode AlRender::Image::setSource( const char *camName, boolean image, boolean mask, boolean depth ) Description
Sets the Image File Output toggles in the camera named camName.

Arguments
< camName - name of the camera < image - Image toggle < mask - Mask toggle < depth - Depth toggle

Return Codes
sSuccess - the values were set sInvalidArgument - camName was NULL sFailure - camera of the given name was not found

boolean AlRender::Image::XYRatioLock() Description

Returns TRUE if XY ratio lock is on.

statusCode AlRender::Image::setXYRatioLock( boolean ratioLock ) Description

Sets the lock on the X/Y pixel ratio. If the lock is on, then doubling the X resolution will also double the Y resolution. If the lock is off, X and Y resolutions are independent.

Arguments
< ratioLock - new value of the lock

788 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

int AlRender::Image::resolutionX() Description

Returns the X resolution of the image.

statusCode AlRender::Image::setResolutionX( int xres ) Description

Sets the X resolution of the image.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..32767

int AlRender::Image::resolutionY() Description

Returns the Y resolution of the image.

statusCode AlRender::Image::setResolutionY( int yres ) Description

Sets the Y resolution of the image.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..32767

double AlRender::Image::aspectRatio() Description

Returns the aspect ratio of the image.

AlRender | 789

statusCode AlRender::Image::setAspectRatio( double aspect ) Description

Sets the aspect ratio of the image.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..1

boolean AlRender::HiddenLine::useFillColor() Description

Returns TRUE if all surfaces in the scene are to be filled with the fill color specified by the setFillColor() method.

statusCode AlRender::HiddenLine::setUseFillColor( boolean useFill ) Description

Sets the usage of fill colors for surfaces within a scene.

Return Codes
sSuccess - value was set

statusCode AlRender::HiddenLine::fillColor( double& r, double &g, double &b) Description

Returns the current fill colors.

Return Codes
sSuccess - the method succeeded

790 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlRender::HiddenLine::setFillColor( double r, double g, double b) Description

Sets the fill color to r,g,b.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..255

statusCode AlRender::HiddenLine::lineColor( double& r, double& g, double& b) Description

Returns the line color.

Return Codes
sSuccess - the line color was returned

statusCode AlRender::HiddenLine::setLineColor( double r, double g, double b) Description

Sets the color of lines for all surfaces within a scene to r,g,b.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..255

int AlRender::HiddenLine::patchLinesU() Description

Returns the U patch lines for a surface.

AlRender | 791

statusCode AlRender::HiddenLine::setPatchLinesU( int lines ) Description

Sets the number of U patch lines for a surface in a scene. This controls the number of lines that are shown in the U direction of each surface in a scene. Setting this to 0 will cause only edges of a surface to be displayed.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..8

int AlRender::HiddenLine::patchLinesV() Description

Returns the V patch lines for a surface.

statusCode AlRender::HiddenLine::setPatchLinesV( int lines ) Description

Sets the number of V patch lines for a surface in a scene. This controls the number of lines that are shown in the V direction of each surface in a scene. Setting this to 0 will cause only edges of a surface to be displayed.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 0..8

boolean AlRender::Particle::show() Description

Returns TRUE if particles will be shown in the scene.

792 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

statusCode AlRender::Particle::setShow( boolean on ) Description

Sets if particles should be rendered in the scene.

Return Codes
sSuccess - value was set

int AlRender::Particle::simulationSubsteps() Description

Returns the particle simulation substeps.

statusCode AlRender::Particle::setSimulationSubsteps( int substeps ) Description

Sets the particle simulation substeps. A higher number produces a more accurate animation but also increases rendering time.

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 1..8

int AlRender::Particle::framesPerSecond() Description

Returns the particle frames for second setting.

statusCode AlRender::Particle::setFramesPerSecond( int frames ) Description

Sets the particle frames per second value. This value is used to specify how fast images will be displayed from the final animation. This value is also used to calculate the correct amount of force and gravity to apply to particles during the simulation.

AlRender | 793

Return Codes
sSuccess - the value was set sInvalidArgument - the value was not in the range 1..30

statusCode AlRender::Image::readResolutions( AlList* &resolutions ) Description

Returns a list of resolutions as name,x,y,aspect. These are the entries that are found in the predefined area of the render globals area.

Arguments
> resolutions - list of resolutions

Return Codes
sSuccess - a list of resolutions was returned sFailure - the list could not be allocated

AlRenderInfo
A structure used to transfer render information.

Synopsis
#include <AlRenderInfo.h>

Description
An AlRenderInfo structure is used to store render information for an object. Before setting the AlRenderInfo for an object, it is necessary to retrieve the current values from the object. For example:
// No error checking is done here for brevity in the example. AlRenderInfo renderInfo; newSurface->renderInfo( renderInfo ); renderInfo.castsShadow = FALSE; newSurface->setRenderInfo( render Info );

See Render->globals in the Menu Book for a more detailed description of these fields.

794 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

doubleSided
Sets whether both sides of an object (inside and outside) or only the outside is to be rendered. For example, a closed object, such as a sphere doesnt have to be double sided; only one side of the object is going to be seen when it is rendered. The default is TRUE.

opposite
Determines which side of a surface will be used for the render; the side that the normals point out of, or the opposite side. The default is FALSE, meaning the side the normals point out of will be used.

castsShadow
Indicates whether or not the object will cast shadows in the RayCaster and RayTracer. The default is TRUE.

adaptive
Indicates whether adaptive or uniform subdivisions will be used. The default is TRUE, meaning adaptive subdivisions.

adaptive_min
Indicates the minimum level of adaptive subdivision on the object. The level must be a power of 2 between 0 and 7; any other values will cause the next higher power of 2 to be used. The default it 2.

adaptive_max
Indicates the maximum level of adaptive subdivision on the object. The level must be a power of 2 between 0 and 7; any other values will cause the next higher power of 2 to be used. The default it 4.

curvature_threshold
Controls the threshold for subdivision of the surface. Values must be between 0 and 1, with 0.96 being the default.

uniform_u
When "adaptive" is FALSE, this indicates the number of subdivisions in the U direction. Values must be between 1 and 256, with 4 being the default.

AlRender | 795

uniform_v
When "adaptive" is FALSE, this indicates the number of subdivisions in the V direction. Values must be between 1 and 256, with 4 being the default.

smooth_shading
Indicates whether smooth or flat shading should be used. The default is TRUE, meaning that smooth shading will be used.

motion_blur
Indicates whether the object should be motion blurred. The default is TRUE.

reflection_only
Indicates the object is a reflection only object.

motion_blur_texture_sample_level motion_blur_shading_samples
Parameters for motion blur.

AlRetrieve
A structure used to transfer options that control the AlUniverse::retrieve() method.

Synopsis
#include <AlRetrieveOptions.h>

Description
An AlRetrieveOptions structure is used to set or determine the options that the AlUniverse::retrieve() method uses to tailor the import of files. To avoid setting all of the fields of AlRetrieveOptions using AlUniverse::setRetrieveOptions(), it is recommended that the current values be acquired first using AlUniverse::retrieveOptions(). For example:

796 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

// No error checking is done here for brevity in the example. AlRetrieveOptions options; AlUniverse::retrieveOptions( options ); options.dxf.units = k_millimeters; options.dxf.in_create_shaders = True; AlUniverse::setRetrieveOptions( options );

See File->Retrieve in the Alias manuals for a more detailed description of these options.

General Options qk_wire

Determines whether or not all retrieved geometry is displayed in quick-wire mode. Only relevant for OpenAlias plug-ins.

new_stage
Determines if all retrieved geometry is put in the current stage, or put in a new stage named after the filename. If set to TRUE, then the retrieved geometry will be put in a new stage called <filename><ext> (for example, model.iges -> modeliges) and this stage will be made current.

Wire File Options:

All wire file options default to TRUE.

keep_windows
If set to TRUE, the modeling window layout contained in wire files will be retrieved, and if set to FALSE, the window layout will not be retrieved.

keep_cameras
If set to TRUE, the cameras contained in wire files will be retrieved, and if set to FALSE, the cameras will not be retrieved.

keep_animation
If set to TRUE, both the animation and the model contained in wire files will be retrieved, and if set to FALSE, only the model will be retrieved. Note: If a window contains an animated camera and keep_animation is TRUE, then this window will be retrieved also, even if keep_windows is FALSE.

AlRetrieve | 797

keep_backgrounds
If set to TRUE, the background contained in wire files will be retrieved, and if set to FALSE, the background will not be retrieved.

keep_unitsTolerances
If set to TRUE, linear units, angular units, and construction tolerances contained in the wire will be retrieved and set. If set to FALSE, the units and tolerances in the wire file are ignored. Only relevant for OpenAlias plug-ins.

keep_renderGlobals
If set to TRUE, the render global information stored in a wire file will be retrieved and set. If set to FALSE, this information will be ignored. Only relevant for OpenAlias plug-ins.

keep_layers
If set to TRUE, the layer information stored in a wire file will be retrieved and the layers re-created. If set to FALSE, layer information will be ignored and all objects will be placed into the default layer. Only relevant for OpenAlias plug-ins.

IGES/VDAIS/C4X/JAMA-IS and VDAFS File Options: group

If set to TRUE, all geometry retrieved from the file will be grouped under a node named after the translator. For example, IGES geometry will be grouped under a node called "IGES_FILE" and DXF geometry will be grouped under a node called "DXF_FILE". If set to FALSE, this group node will not be created. The default is FALSE.

coalesce
If set to TRUE, multiple knots will be removed based on continuity in IGES Parametric Curve and Surface geometry, and all VDAFS curve and surface geometry. The default is FALSE.

798 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

annotation
If set to TRUE, supported geometric entities that have been flagged for use as annotation will be retrieved. If set to FALSE, these entities will not be retrieved. This option does not apply to VDAFS.

trim_to_surf
If set to TRUE, retrieved Trimmed or Bounded surfaces whose boundaries are the same as, or iso-parametric to, the natural boundaries of the untrimmed surface, will be converted to untrimmed surfaces by shrinking the surface to the trim boundaries. If set to FALSE, trimmed surfaces will be represented as such even if the trim boundary information is unnecessary. The default is TRUE. This option does not apply to VDAFS.

scale
All retrieved geometry will be scaled by this factor. The default is 1.0.

layer_or_set
This controls the mapping of the IGES/VDAIS/JAMIAS Level. The options are kLayer, maps level to layer, this is the default kSet, maps level to set kLayerAndSet, maps level to layer and set kNoLayerOrSet, there is no mapping level is ignored. This option does not apply to VDAFS or C4

default_trim
This controls the type of curves that will be used in trimming a surface. The options are kParameter, use the parameter (2D) space curves, this is the default. kWorld, use the world (3D) space curves kUseFlag, use the preference in the IGES/VDAIS/JAMAIS/C4 file NOTE kUseFlag is invalid for VDAFS.

AlRetrieve | 799

create_scan_data
This control the conversion of "Scan Data" 106 Forms 1-3, 11-13 and 63. If on this entity is treated as Scan Data on import.

DXF File Options: group

See description above.

load_shaders
Determines whether or not shaders are to be loaded from the "shader" sub-directory of the current project. If set to TRUE, and if there is a shader on disk whose name matches a DXF layer name, then this shader will be loaded (if not already in memory) and assigned to all objects on that layer. If set to FALSE, this process is skipped, and at best, only simple color shaders will be created from the DXF colour information. The default is TRUE.

anonymous_blocks
Determines whether "anonymous" DXF BLOCK entities are processed (TRUE) or ignored (FALSE). The default is FALSE, since mostly, these BLOCK entities contain pattern hatching lines.

units
Sets the units of the DXF coordinate data, if known, so that the data is properly scaled. This option is necessary since the units of the DXF coordinate data is not stored in the file. The default is inches (kInches), but it can be set to any of the following values: kMiles, kFeet, kInches, kMils, kMicroInches, kKilometers, kMeters, kCentimeters, kMillimeters, or kMicrons.

scale
See above for a description of this field.

AlRevSurfAttributes
Interface to Alias arc curve attributes.

800 | Chapter 4 AlMappedFieldItem AlRevSurfAttributes

Synopsis
#include <AlRevSurfAttributes.h> class AlRevSurfAttributes : public AlAttributes virtual AlObjectType type() const; AlObject* copyWrapper() const; double startAngle() const; double endAngle() const;

Description
AlRevSurfAttributes is a class derived from the AlAttributes class. This class allows access to some of the attributes of a revolved surface; in this case, the start and end angles of revolution. When querying the attributes of a revolved surface (retrieved from IGES or created in Alias with exact ON) the first attribute will be an AlRevSurfAttributes, the second will be an AlLineAttributes representing the axis of revolution, and the remainder of the attributes describe the line that was revolved to generate the surface.

AlObjectType AlRevSurfAttributes::type() const Description

Returns the class identifier kRevSurfAttributeType.

AlObject* AlRevSurfAttributes::copyWrapper() const Description

Makes a copy of the AlRevSurfAttributes. The returned AlRevSurfAttributes will reference the same data as the original.

double AlRevSurfAttributes::startAngle() const Description

Returns the start angle in degrees for the revolved surface.

double AlRevSurfAttributes::endAngle() const Description

Returns the end angle in degrees for the revolved surface.

AlRevSurfAttributes | 801

802

AlSet AlXEvents

AlSet
Basic Interface to Alias set structures.

Synopsis
#include <AlSet.h> class AlSet : public AlObject AlSet(); virtual ~AlSet(); virtual statusCode deleteObject(); virtual AlObject *copyWrapper() const; statusCode create( const boolean ); virtual AlObjectType type() const; virtual const char* name() const; virtual statusCode setName( const char* ); AlSet* nextSet() const; AlSet* prevSet() const; statusCode nextSetD(); statusCode prev SetD(); boolean isEmpty() const; boolean isExclusive() const; statusCode setExclusive( const boolean on ); int numberOfMembers() const; *firstMember() const; statusCode applyIteratorToMembers( AlIterator* iter, int& );

Description
A set can be described as a storable list. A set can contain any combination of cameras, DAG nodes, curve CVs and surface CVs. A set can be exclusive or multi - exclusive means that a member of a set can be in no other set; multi means that a member of a set can be in any other non-exclusive set. You can access the members of a set by traversing a sets list of members. If you remove all members of a set, the empty AlSet object must be explicitly deleted. If you store an empty set, it will be lost when you retrieve your wire file into the interactive Alias package.

803

The following classes can be grouped into sets: AlDagNode, AlPerspectiveCamera, AlCurveCV, and AlSurfaceCV.

AlSet::AlSet() Description
Constructs an AlSet wrapper object. Use the create() method to initialize an AlSet.

AlSet::~AlSet() Description
Deletes an AlSet wrapper object.

statusCode AlSet::deleteObject() Description

Removes all the set members from the set, and then deletes the set itself.

Return Codes
sSuccess - the set was deleted sFailure - the set could not be deleted sInvalidObject - the set is invalid

AlObject* AlSet::copyWrapper() const Description

Returns an exact duplicate of the AlSet wrapper object.

statusCode AlSet::create( const boolean exclusive) Description

Does any initialization and allocation of data for an AlSet. If the exclusive flag is set to TRUE, then this set is made an exclusive set (that is, the members of this set are not allowed to be members of any other set). If it is set to FALSE,

804 | Chapter 5 AlSet AlXEvents

then the set is designated as "multiple" (that is, the members of this set can be in any other non-exclusive set).

Arguments
< exclusive - state to set the exclusive flag for this set (see above)

Return Codes
sSuccess - set was created sInsufficientMemory - no memory

AlObjectType AlSet::type() const Description

Returns the class identifier kSetType.

const char* AlSet::name() const Description

Returns the name of the object.

statusCode AlSet::setName( const char* newName ) Description

Changes the name of the set to a new name. If the given name is not a unique one, then a unique name is generated based on the given name and assigned to the set. In this case, a status code of sNameChangedToUniqueOne is returned. It is illegal for the new name to be NULL.

Arguments
< newName - new name of the object

Return Codes
sSuccess - name was changed successfully sFailure - name was not changed

AlSet | 805

sNameChangedToUniqueOne - name was changed to be a unique version of the given name sInvalidArgument - newName was NULL sInvalidObject - the set was invalid

AlSet* AlSet::nextSet() const Description

Returns a pointer to the next AlSet in the set list or NULL if there are no more sets.

AlSet* AlSet::prevSet() const Description

Returns a pointer to the previous AlSet in the set list or NULL if there are no previous sets.

statusCode AlSet::nextSetD() Description

Destructively sets the wrapper to point to the next set in the set list. If the next set cannot be found, the wrapper is unaffected.

Return Codes
sSuccess - the wrapper points to the next set sFailure - there is no next set sInvalidObject - the set is invalid

statusCode AlSet::prevSetD() Description

Destructively points the wrapper to the previous set in the set list. If the previous set cannot be found, the wrapper is unaffected.

806 | Chapter 5 AlSet AlXEvents

Return Codes
sSuccess - the wrapper points to the previous set sFailure - there is no previous set sInvalidObject - the set is invalid

boolean AlSet::isEmpty() const Description

Returns TRUE if the set is empty (ie. it has zero members). Otherwise, it returns FALSE.

boolean AlSet::isExclusive() const Description

Returns TRUE if the set is exclusive and FALSE if the set is "multiple".

statusCode AlSet::setExclusive( const boolean exclusive ) Description:

Makes the current set exclusive or multiple. If exclusive is TRUE then the set is made exclusive.

Arguments
< exclusive - TRUE or FALSE

Return Codes
sSuccess - the set has been made exclusive sFailure - the method failed sInvalidObject - the set is invalid sInvalidParameter - attempting to make a set exclusive that has members in another set

AlSet | 807

int AlSet::numberOfMembers() const Description

Returns the number of members belonging to this set. This method returns -1 if the set is invalid.

AlSetMember *AlSet::firstMember() const Description

Returns a pointer to the AlSetMember that is the first member in the list of members of this set. Returns NULL if this set has no members. Note that this operation is a O(lg n) operation and is provided for convenience. If you intend to do an operation on every element in the set, use an iterator.

statusCode AlSet::applyIteratorToMembers( AlIterator* iter, int& rc ) Description

Applies the given iterator to each member of this set. See the documentation for AlIterator on page 544.

Arguments
< iter - the iterator to apply to each set member > rc - the result of the last application of the iterator

Return Codes
sSuccess - applyIteratorToMembers exited normally sInvalidArgument - iter was NULL sFailure - applyIteratorToMembers exited abnormally sInvalidObject - the set is invalid

AlSetMember
Basic Interface to the members of Alias set structures.

808 | Chapter 5 AlSet AlXEvents

Synopsis
#include <AlSetMember.h> class AlSetMember : public AlObject virtual ~AlSetMember(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; AlSetMember* nextSetMember() const; AlSetMember* prevSetMember() const; statusCode nextSetMem berD(); statusCode prevSetMemberD(); AlObject* object() const; AlSet* set() const; statusCode removeFromSet( AlSet *set );

Description
This class provides utility functions for set operations. The first AlSetMember of a set can be retrieved from the AlSet. Then iteration through the sets can be done using the calls provided within this class. The following classes can be grouped into sets: AlDagNode, AlPerspectiveCamera, AlCurveCV and AlSurfaceCV. These classes use multiple inheritance, which includes the AlSettable class. Use the addToSet() method of class AlSettable to add the object to a set.

AlSetMember::~AlSetMember() Description
Deletes an AlSetMember wrapper object.

AlObject *AlSetMember::copyWrapper() const Description

Returns an exact duplicate of this AlSetMember wrapper.

AlObjectType AlSetMember::type() const Description

Returns the class identifier kSetMemberType.

AlSetMember* AlSetMember::nextSetMember() const Description

Returns a pointer to the next AlSetMember. Otherwise, returns NULL if there is no next set member.

AlSetMember | 809

AlSetMember* AlSetMember::prevSetMember() const Description

Returns a pointer to the previous AlSetMember. Otherwise, returns NULL if there is no previous set member.

statusCode AlSetMember::nextSetMemberD() Description

Destructively points this wrapper to next set member. If there is no such member, the object pointer is unaltered.

Return Codes
sSuccess - the wrapper points to the next set member sFailure - there is no next set member sInvalidObject - the set member is invalid

statusCode AlSetMember::prevSetMemberD() Description

Destructively points this wrapper to the previous set member. If there is no such member, the object pointer is unaltered.

Return Codes
sSuccess - the wrapper points to the previous set member sFailure - there is no previous set member sInvalidObject - the set member is invalid

AlObject *AlSetMember::object() const Description

Returns the object that this set member references.

810 | Chapter 5 AlSet AlXEvents

AlSet* AlSetMember::set() const Description

Returns the set that this set member belongs to.

statusCode AlSetMember::removeFromSet( AlSet *set ) Description

Removes this member from the set.

Arguments
< set - the set to remove this from

Return Codes
sSuccess - the object was removed successfully sInvalidArgument - the set was invalid sObjectNotAMember - the object was not found in this set sInvalidObject - the set is invalid

AlSettable
Encapsulates methods common to Alias objects that can belong to sets.

AlSettable | 811

Synopsis
#include <AlSettable.h> class AlSettable virtual AlSet* firstSet() const; virtual AlSet* nextSet( const AlSet* ) const; virtual AlSet* prevSet( const AlSet* ) const; virtual statusCode nextSetD( AlSet* ) const; virtual statusCode prevSetD( AlSet* ) const; virtual statusCode applyIteratorToSets( AlIterator*, int& ); statusCode removeFromAllSets(); statusCode removeFromSet( AlSet *set ); statusCode addToSet( AlSet *set ); AlSetMember* isSetMember( const AlSet *set ) const;

Description
This class is a base class for all objects which can be contained in a set. It provides the methods necessary to access the set methods of these objects.

AlSet* AlSettable::firstSet() const Description

Finds and returns the first set of which this object is a member. If no such set can be found, NULL is returned.

AlSet* AlSettable::nextSet( const AlSet* lastSet ) const Description

Finds and returns the set following the given one of which this object is a member. If no such set can be found, NULL is returned.

Argument
< lastSet - set to walk forward from

812 | Chapter 5 AlSet AlXEvents

AlSet* AlSettable::prevSet( const AlSet* lastSet ) const Description

Finds and returns the set preceding the given one of which this object is a member. If no such set can be found, NULL is returned.

Argument
< lastSet - set to walk forward from

statusCode AlSettable::nextSetD( AlSet* lastSet ) const Description

Destructively points lastSet to the next set for the given object.

Argument
< lastSet - set to walk forward from

Return Codes
sSuccess - the set wrapper points to the next set sInvalidArgument - lastSet is invalid or NULL sFailure - there is no next set

statusCode AlSettable::prevSetD( AlSet* lastSet ) const Description

Destructively points lastSet to the previous set for the given object. If this can not be accomplished, then lastSet is unaffected.

Argument
< lastSet - set to walk backward from

Return Codes
sSuccess - lastSet points to the previous set for the given object sInvalidArgument - lastSet is invalid or NULL

AlSettable | 813

sFailure - there is no previous set

statusCode AlSettable::applyIteratorToSets( AlIterator* iter, int &rc ) Description

Applies the given iterator to all the sets affected by this object. See the documentation for AlIterator on page 544. Warning: be careful when using this iterator. If you modify the actual set during an iteration, it is possible that this routine will end up pointing to invalid data and send you garbage. This should not happen when simply applying transformations to a set. But deleting a set using this method is considered unsafe. If you do it, return immediately.

Arguments
< iter - the iterator to apply to each set > rc - the value returned from the last application of the iterator

Return Codes
sSuccess - the applyIteratorToSets exited normally sFailure - applyIteratorToSets exited abnormally sInvalidArgument - iter is NULL

statusCode AlSettable::addToSet( AlSet *set ) Description

Adds this object to the set

Arguments
< set - set to add to

Return Codes
sSuccess - successfully added to the set sInsufficientMemory - not enough memory available sObjectInSet - this object already belongs to this set

814 | Chapter 5 AlSet AlXEvents

sObjectInAnotherSet - this set is exclusive and this object already belongs to another set sObjectInExclusiveSet - this object already belongs to an exclusive set sObjectAncestorInSet - an ancestor of this object already belongs to this set sObjectDescendentInSet - a descendent of this object already belongs to this set sInvalidArgument - set was NULL sInvalidObject - this object was invalid

statusCode AlSettable::removeFromSet( AlSet *set ) Description

Removes this object from the set. If the given DAG node was not found in the set, then nothing is removed.

Arguments
< set - the set to remove from

Return Codes
sSuccess - if this object was removed successfully sInvalidArgument - set was invalid sObjectNotAMember - if the object was not found in this set sInvalidObject - the set is invalid

AlSetMember *AlSettable::isSetMember( const AlSet *set ) const Description

Returns TRUE if this object is a member of the given set.

Arguments
< set - the object to test membership in

AlSettable | 815

statusCode AlSettable::removeFromAllSets() Description

Removes this object from all sets in the universe that it may be in.

Return Codes
sSuccess - object was removed from all sets

AlShader
Base object for representing shader data.

816 | Chapter 5 AlSet AlXEvents

Synopsis
#include <AlShader.h> class AlShader : public AlObject , public AlAnimatable AlShader(); virtual ~AlShader(); virtual statusCode deleteObject(); virtual AlObject *copyWrapper() const; statusCode create(); virtual AlObjectType type() const; virtual const char* name() const; virtual statusCode setName( const char * ); statusCode parameter( const AlShadingFields, double& ) const; statusCode setParameter( const AlShadingFields, const double ); statusCode blindData( int, long& , const char*& ); statusCode setBlindData( int, long, const char* ); statusCode removeBlindData( int user_type ); const char* shadingModel() const; statusCode setShadingModel( const char* ); AlTexture* firstTexture() const; AlTexture* nextTexture( const AlTexture* ) const; statusCode nextTextureD( AlTexture* ) const; AlList* fields() const; AlList* mappedFields() const; statusCode addTexture( const char*, const char*, AlTexture** re turnedTexture = NULL ); statusCode removeTexture( const char* ); statusCode applyIteratorToTextures( AlIterator*, int& ); AlShader* copyObject(); boolean isUsed(); AlShader* convertSolidToFileTexture( AlDagNode *, int ,boolean , const char * ); AlShader* convertEnvironmentToFileTexture( int , const char *, AlPixFile::Format, boolean );

Description
This class encapsulates the basic functionality for checking and setting the name of a shader as well as accessing the textures that a particular shader refers to, and the animation on the shader. Shader objects are accessible through both the AlUniverse class and the objects that reference them (AlSurface and AlFace classes).

AlShader | 817

A shader object may reference textures. The firstTexture() and nextTexture() methods are used to access these textures. firstTexture() returns the first texture that the shader object references. nextTexture() moves from a given referenced texture to the next texture in order, as related to the shader object. (See the similar methods for the AlTexture on page 933/AlEnvironment on page 458 classes.) The animation on a shader can be accessed through the firstChannel() and nextChannel() methods. All the channels on the shader can be deleted by calling deleteAnimation(). The shader parameters can be accessed through the parameter() and setParameter() methods. Each shader has a specific set of parameters that are valid for it that depend on its type. The full list of shader parameters can be seen in the file AlShadingFields.h. For example, all parameters specific to the Blinn shader have names of the form kFLD_SHADING_BLINN_*. Parameters common to all shaders have the form kFLD_SHADING_COMMON_*. All parameters are treated as doubles even though this may not necessarily be what they are. This is done to make the interface as simple and consistent as possible.

AlShader::AlShader() Description
Constructs an AlShader wrapper object. Use the create() method to initialize an AlShader.

AlShader::~AlShader() Description
Deletes an AlShader wrapper object.

statusCode AlShader::create() Description

Does any initialization and allocation of data for an AlShader. Allocates space for this AlShader and adds it to the global list of shaders in AlUniverse. The shader is initialized as the Alias default shader.

818 | Chapter 5 AlSet AlXEvents

Return Codes
sSuccess - creation succeeded sInsufficientMemory - not enough memory available

statusCode AlShader::deleteObject() Description

Deletes the AlShader and the AlTextures hanging off of the shader. All objects that were assigned this shader will be assigned the default shader. Note that after this operation, any pointers to AlTextures that had been part of this shader will no longer be valid.

Return Codes
sSuccess - shader was deleted sFailure - shader was not deleted sInvalidObject - the shader was invalid

AlObject *AlShader::copyWrapper() const Description

Returns an exact duplicate of this AlShader wrapper.

AlObjectType AlShader::type() const Description

Returns the class identifier kShaderType.

const char* AlShader::name() const Description

Returns the name of the shader.

AlShader | 819

statusCode AlShader::setName( const char *newName) Description

Changes the name of the shader to a new name. If the given name is not a unique one or contains illegal characters, then a new unique name is generated based on the given name and assigned to the shader. In this case, a status code of sNameChangedToUniqueOne is returned. It is illegal for the new name to be NULL. #, digits, upper case letters, lower case letters, and _ are valid characters

Arguments
< newName - new name of the object

Return Codes
sSuccess - name was changed sInvalidArgument - newName was NULL sInvalidObject - the shader is invalid sNameChangedToUniqueOne - name was changed to be a unique version of the given name sFailure - name was not changed

statusCode AlShader::parameter( const AlShadingFields field,double& result )const Description

Finds the value of a given shader field.

Arguments
< field - shader field type > result - returned result of the field

Return Codes
sSuccess - field was returned sInvalidArgument - field was not legal for this shader

820 | Chapter 5 AlSet AlXEvents

sFailure - field could not be returned sInvalidObject - the shader is invalid

statusCode AlShader::setParameter( const AlShadingFields field,const double value ) Description

Changes the value of the shader field. If the given field is not valid then a status code of sInvalidArgument is returned.

Arguments
< field - shader field type < value - new value that the shader field is to take

Return Codes
sSuccess - field was changed sInvalidArgument - field was not legal for this shader sFailure - field could not be changed sInvalidObject - the shader is invalid

const char* AlShader::shadingModel() const Description

Returns a string representing the shading model. The returned string will be one of BLINN, PHONG, LAMBERT, or LIGHTSOURCE.

statusCode AlShader::setShadingModel( const char* model ) Description

Tries to set the shading model of the shader. The model must be one of LIGHTSOURCE, LAMBERT, BLINN, or PHONG.

Return Codes
sSuccess - the shading model was successfully set

AlShader | 821

sInvalidArgument - the given string is not a shading model sInvalidObject - the shader is not valid

AlTexture* AlShader::firstTexture() const Description

Returns the first texture that this shader object references. If there are none then NULL is returned.

AlTexture* AlShader::nextTexture( const AlTexture* last_texture ) const Description

Returns the texture after the given one in the shaders texture list. Specifying NULL as parameter will return the first texture.

Arguments
< last_texture - texture from which to walk forward

statusCode AlShader::nextTextureD( AlTexture* last_texture ) const Description

Destructively points the last_texture wrapper to the next texture after the given one in the shaders texture list.

Arguments
<> last_texture - texture from which to walk forward

Return Codes
sSuccess - the wrapper points to the next texture sInvalidArgument - last_texture was invalid or NULL sFailure - there is no next texture sInvalidObject - the shader is invalid

822 | Chapter 5 AlSet AlXEvents

AlList* AlShader::fields() const Description

Returns an AlList of AlShadingFieldItems, each of which contains an AlShadingFields value valid for this shader.

AlList* AlShader::mappedFields() const Description

Returns an AlList of AlMappedFieldItems, each of which contains a character string identifier identifying a field on this shader which may be texture mapped. Note that these strings are identical to the SDL identifiers and the complete list can be found in the SDL manual.

statusCode AlShader::removeTexture( const char* fieldName ) Description

Removes a texture from a particular field of the AlShader. The first argument is the name of the field which will have the texture applied to it. Only those fields valid for this shader should be provided; any others will cause this method to fail. Valid fields are any returned by the fields() method.

Arguments
< fieldName - name of the field which will have the texture removed from it

Return Codes
sSuccess - the texture was added successfully sFailure - no texture was present sCannotDelete - a texture already existed on the field which could not be deleted sInvalidArgument - the argument was not valid for the shader sInvalidObject - the shader is invalid

AlShader | 823

statusCode AlShader::addTexture( const char* fieldName, const char* textureName, AlTexture** returnCreatedTexture ) Description
Adds a texture to a particular field of the AlShader. The first argument is the name of the field which will have the texture applied to it. Only those fields valid for this shader should be provided; any others will cause this method to fail. Valid fields are any returned by the fields() method. The second argument is the name of the texture type to apply to the field. The complete list of names is available in the SDL manual. Note: most of these names are also found on the widgets themselves (for example, sRock or Fractal) For example, to add shaders to the color fields, one would use commands such as
shader->addTexture( "color", "sRock" ) shader->addTexture( "color", "Fractal" )

Arguments
< fieldName - name of the field which will have the texture applied to it < textureName - name of the texture type to apply to the field > returnCreatedTexture - returns the created texture if not NULL

Return Codes
sSuccess - the texture was added successfully sFailure - the texture was not added sCannotDelete - a texture already existed on the field which could not be deleted sInvalidArgument - either argument was not valid for the shader sInvalidObject - the shader is invalid

824 | Chapter 5 AlSet AlXEvents

statusCode AlShader::applyIteratorToTextures( AlIterator *iter, int &rc ) Description

Applies the given AlIterator to all textures in the shader. The second argument will be set to the return value of the last application of the iterators function. See the AlIterator on page 544 class for more information.

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

Return Codes
sSuccess - the application of the iterator terminated normally sFailure - the application of the iterator terminated abnormally sInvalidObject - the shader is invalid sInvalidArgument - the iterator was NULL

AlShader *AlShader::copyObject() Description

Copies this AlShader returning a pointer to the new copy or NULL if the copy failed.

boolean AlShader::isUsed() Description

Returns TRUE if the shader is being used by another object. Return value is FALSE otherwise.

statusCode AlShader::blindData( int user_type, long& size, const char *& data ) Description
Obtains the size and address of a block of data associated with the object. If there is no data, then the size will be zero and the address of the data is NULL.

AlShader | 825

User_types between 0 and 13099 are reserved. If you would like to reserve a block of "user_types" please contact us.

Arguments
< user_type - user type of the data desired > size - number of characters in the block of data > data - address of the block of data

Return Codes
sSuccess - blind data retrieved sFailure - blind data not retrieved sInvalidObject - the polygon was invalid

statusCode AlShader::setBlindData( int user_type, long size, const char * data ) Description
Associates a block of data with the object. If a block of data is already associated with this object and this user_type, the old block is replaced by a reference to the new block. The old block of data is not deleted.

Arguments
< user_type - user type of the blind data desired < size - number of characters in the block < data - address of the block of data

Return Codes
sSuccess - everything is okay sInsufficientMemory - not enough memory to allocate a new block sFailure - create has not been called on this object yet sInvalidObject - the polygon is invalid

826 | Chapter 5 AlSet AlXEvents

statusCode AlShader::removeBlindData( int user_type ) Description

Removes the block of data of the given type from the object. Note that the user is still responsible for the memory associated with this block of data.

Arguments
< user_type - user type of the blind desired

Return Codes
sSuccess - everything is okay sFailure - no such blind data existed sInvalidObject - the given object was not valid

AlShader* AlShader::convertSolidToFileTexture( AlDagNode *dagNode, int resolution, boolean antiAlias, const char * pixFilename ) Description
If the current shader has a solid texture, this method copies this shader and converts the solid texture to a file texture for the specified dag node object. A pix file is created for the file texture using the resolution and anti-aliasing parameters specified. On failure, this method returns NULL. Notes: 1. Valid resolutions are 8 .. 1024 2. This method will fail if either dagNode or pixFilename are NULL 3. dagNode should be a valid API pointer

Arguments
< dagNode - dag node that the solid texture is applied to < resolution - size of output pix map < antiAlias - either TRUE or FALSE < pixFileName - where to place the converted file

AlShader | 827

AlShader* AlShader::convertEnvironmentToFileTexture(int resolution, const char * pixFilename, AlPixFile::Format pixFmt, boolean imageMap ) Description
If the current shader has an environment texture, this method copies this shader and converts the environment texture to a file texture. A pix file is created for the file texture using the resolution parameter specified. On failure, this method returns NULL.

Arguments
< resolution - x & y size of output pix map < pixFileName - where to place the converted file < map -

AlShadingFieldItem
Items for maintaining AlShader parameters.

Synopsis
#include <AlShadingFieldItem.h> class AlShadingFieldItem : public AlLinkItem AlShadingFields field() const; AlShadingFieldItem* nextField() const; AlShadingFieldItem* prevField() const;

Description
This class is derived from the AlLinkItem class, and is used to maintain one element of a list of parameters which are valid for a particular AlShader, AlTexture, or AlEnvironment.

AlShadingFields AlShadingFieldItem::field() const Description

Returns the AlShadingFields value for this field.

828 | Chapter 5 AlSet AlXEvents

AlShadingFieldItem* AlShadingFieldItem::nextField() const Description

Returns the next field in this list of fields. NULL may be returned if there is no next field.

AlShadingFieldItem* AlShadingFieldItem::prevField() const Description

Returns the prev field in this list of fields. NULL may be returned if there is no prev field.

AlShell
Interface to Alias NURBS surface geometry.

AlShell | 829

Synopsis
#include <AlShell.h> class AlShell : public AlObject AlShell(); virtual ~AlShell(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; AlShellNode* shellNode() const; statusCode create( AlTrimRegion*, boolean ); statusCode addToShell( AlTrimRegion*, boolean ); boolean isInShell( AlTrimRegion* ); AlTrimRegion* firstTrimRegion() const; AlGroupNode* unstitchShell( void ); AlShader* firstShader() const; AlShader* nextShader( const AlShader* ) const; statusCode nextShaderD( AlShader* ) const; statusCode assignShader( AlShader* ); statusCode layerShader( AlShader* ); statusCode renderInfo( AlRenderInfo& ) const; statusCode setRenderInfo( const AlRenderInfo& ) const; boolean isDisplayModeSet( AlDisplayModeType ) const; statusCode setDisplayMode( AlDisplayModeType, boolean ); statusCode area( double &, boolean = TRUE, double tolerance=0.001 ); statusCode circumference( double &, boolean = TRUE, double toler ance=0.001 );

Description
A shell is a collection of surfaces that behaves as a single object. Each surface can have its own set of trim curves. A cube with six square sides is a shell. The cube can be assigned a single shader and rendering formation. The cube is made of a collection of 6 spline surfaces. The AlTrimRegions are inaccurately named. They actually represent the surfaces in the shell.

AlShell::AlShell() Description
Constructs an AlShell wrapper object.

830 | Chapter 5 AlSet AlXEvents

AlShell::~AlShell() Description
Deletes an AlShell wrapper object.

AlObject *AlShell::copyWrapper() const Description

Returns an exact duplicate of this AlShell wrapper.

AlObjectType AlShell::type() const Description

Returns the class identifier kShellType.

AlShell* AlShell::asShellPtr() Description

This virtual function returns a non-null pointer to itself, indicating that it is safe to cast to an object of this class.

AlShellNode* AlShell::shellNode() const Description

Returns a pointer to the AlShellNode for this surface.

statusCode AlShell::create( AlTrimRegion * region, boolean shrink_surface ) Description

Creates a shell by transforming the given trim region. A new shell is created in Alias, which matches the trim region. A DagNode is also constructed above the shell.

Arguments
region - an AlTrimRegion which serves as a base for the shell

AlShell | 831

shrink_surface - if this flag is set, the surface underlying the given trim region will be reparameterized if the amount thrown away is great enough

Return Codes
sSuccess - a shell was constructed sInvalidArgument - the given region was not valid sFailure - the shell could not be constructed

statusCode AlShell::addToShell( AlTrimRegion * region, boolean shrink_surface ) Description

Adds trim region to the shell. Note that only adjacent surfaces can be added to a shell. This may require that the user try this method for all of the remaining shells to see if it fails for each one.

Arguments
region - an AlTrimRegion which is added to the shell shrink_surface - if this flag is set, the surface underlying the given trim region will be reparameterized if the amount thrown away is great enough

Return Codes
sSuccess - the trim region was added sInvalidArgument - the given region was not valid sFailure - the trim region could not be added

boolean AlShell::isInShell( AlTrimRegion * region ) Description

Returns TRUE if the trim region is in the shell.

Arguments
region - an AlTrimRegion to check

832 | Chapter 5 AlSet AlXEvents

AlTrimRegion* AlShell::firstTrimRegion() const Description

Returns the first trim region of a list if the surface has been trimmed. Returns NULL if there is no such trim region. Use the methods in the AlNewTrimRegion class to get trim region information.

AlGroupNode *AlShell::unstitchShell( void ) Description

Unstitches the shell into a collection of objects.

AlShader* AlShell::firstShader() const Description

Returns the first shader that this surface object references. Returns NULL if there are no shaders.

AlShader* AlShell::nextShader( const AlShader* last_shader ) const Description

Returns the shader after the given shader in the objects shader list. Returns NULL if there isnt a next shader. Specifying NULL as parameter will return the first shader.

Arguments
< last_shader - shader from which to walk forward

statusCode AlShell::nextShaderD( AlShader* last_shader ) const Description

Destructively points last_shader to the shader after the given shader in the objects shader list.

Arguments
< last_shader - shader from which to walk forward

AlShell | 833

Return Codes
sSuccess - last_shader now points to the next shader sFailure - there isnt a next shader sInvalidArgument - last_shader is invalid sInvalidObject - the surface is invalid

statusCode AlShell::assignShader( AlShader* shader ) Description

Assigns the given shader to the surface. If the surface already has shaders, they will be removed from the surface. The surface must have a surface node for this method to succeed.

Arguments
< shader - the shader which will be assigned to the surface

Return Codes
sSuccess - the shader was successfully assigned to the surface sInvalidArgument - shader was invalid sFailure - the shader was not created sInvalidObject - the surface is invalid

statusCode AlShell::layerShader( AlShader* shader ) Description

Layers the given shader on the surface. The surface must have a surface node for this method to succeed.

Arguments
< shader - the shader that will be layered on the surface

Return Codes
sSuccess - the shader was successfully layered on the surface

834 | Chapter 5 AlSet AlXEvents

sInvalidArgument - shader was invalid sFailure - the shader was not created sInvalidObject - the surface is invalid

statusCode AlShell::renderInfo( AlRenderInfo &renderInfo ) const Description

Fills in the renderInfo structure with the render info for this surface.

Arguments
> renderInfo - the structure to fill in

Return Codes
sSuccess - getting the render information was successful sInvalidArgument - renderInfo is NULL sFailure - there wasnt any render information (renderInfo is unchanged) sInvalidObject - the surface is invalid

statusCode AlShell::setRenderInfo( const AlRenderInfo &renderInfo ) const Description

Sets the render info for this surface to the contents of the renderInfo structure.

Arguments
< renderInfo - the structure to take the render information from

Return Codes
sSuccess - setting the render information was successful sInvalidArgument - renderInfo was NULL or a parameter in renderInfo was out of range sFailure - setting the render information failed sInvalidObject - the surface is invalid

AlShell | 835

boolean AlShell::isDisplayModeSet( AlDisplayModeType mode ) const Description

Returns TRUE if the specified display mode is toggled on for the surface. Returns FALSE otherwise. The only valid AlDisplayModeTypes for an AlSurface are
kDisplayGeomHull kDisplayGeomEditPoints kDisplayGeomKeyPoints kDisplayGeomCVs

Arguments
< mode - display mode of interest

statusCode AlShell::setDisplayMode( AlDisplayModeType mode, boolean on_or_off ) Description

For the given display mode, if the flag is TRUE then the display mode for the surface is set, otherwise it is unset. The only valid AlDisplayModeTypes for an AlSurface are
kDisplayGeomHull kDisplayGeomEditPoints kDisplayGeomKeyPoints kDisplayGeomCVs

Arguments
< mode - display mode of interest < on_or_off - TRUE means that this surface will have the display mode set. FALSE means it will be unset.

Return values
sSuccess - operation was successful sFailure - unable to complete this operation sInvalidArgument - invalid display type

836 | Chapter 5 AlSet AlXEvents

sInvalidObject - the surface is invalid

statusCode AlShell::area( double& area, boolean worldCoordinates, double tolerance ) Description

Determines the area of the shell. This is the area of all of the members of the shell summed.

Arguments
< worldCoordinates - TRUE to get the world space area > area - the returned value > tolerance - the error tolerance

Return Codes
sSuccess - the coordinate was successfully determined sFailure - the evaluation failed sInvalidObject - the shell is invalid

statusCode AlShell::circumference( double& circ, boolean worldCoordinates, double tolerance ) Description

Determines the area of the shell. This will be the area of all of the members of the shell summed.

Arguments
< worldCoordinates - TRUE to get the world space area > area - the returned value > tolerance - the error tolerance

Return Codes
sSuccess - the coordinate was successfully determined sFailure - the evaluation failed

AlShell | 837

sInvalidObject - the shell is invalid

AlShellNode
Dag node class for shells.

Synopsis
#include <AlShellNode.h> class AlShellNode : public AlDagNode virtual ~AlShellNode(); virtual AlObject *copyWrapper() const; virtual AlObjectType type() const; AlShell* shell() const; AlShell* shell(AlTM&) const;

Description
This method provides DagNode level access to Shells. Use the shell method to get the actual AlShell underneath this DagNode.

AlShellNode::~AlShellNode() Description
Deletes an AlShellNode wrapper object.

AlObject *AlShellNode::copyWrapper() const Description

Makes an exact copy of the AlShellNode wrapper.

AlObjectType AlShellNode::type() const Description

Returns the class identifier kShellNodeType.

838 | Chapter 5 AlSet AlXEvents

AlShell* AlShellNode::shell() const Description

Returns a pointer to the shell data structure that can be used to access the geometry of the shell.

AlShell* AlShellNode::shell(AlTM& tm) const Description

Returns a pointer to the shell data structure that can be used to access the geometry of the shell. The AlTM will be updated with the shells TM.

Arguments
> tm - the AlTM to be updated with the shells TM

AlSnap
Basic Interface to Alias snapping functions

Synopsis
#include <AlSnap.h> class AlSnap static statusCode toGrid( Screencoord x, Screencoord y, double worldPos[3], AlWindow* window = NULL ); static statusCode toCV( Screencoord x, Screencoord y, AlObject* &obj, AlWindow *window = NULL ); static statusCode toCurve( Screencoord x, Screencoord y, AlObject* &obj, double &curveParam, AlWindow *window = NULL ); static int snappingTo( void );

Description
This class contains various utility functions for doing snapping. You can snap to grids, CVs and curves. When using the toGrid function, the world position returned would be used to translate the object to the correct location. For the CV and curve functions, the world position of the AlObject returned would be used to translate the object to the correct location. The function snappingTo

AlSnap | 839

returns either kSnapGrid, kSnapCurve or kSnapCV based on what buttons have been set in the application.

statusCode AlSnap::toGrid( Screencoord x, Screencoord y, double worldPos[3], AlWindow* window ) Description

Snaps a point on the screen to the closest grid intersection. Returns world space coordinates for the closest grid intersection to the specified cursor position. The grid size is set using the meshSize method in AlWindow.

Arguments
< x, y - the screen position to test > worldPos - the returned snapped world position < window - the window to snap it to. Specify NULL to snap to the current window.

Return Codes
sSuccess - everything okay sObjectNotFound - there was no point in range to snap to sFailure - snapping failed sInvalidArgument - the window was invalid (if given)

statusCode AlSnap::toCV( Screencoord x, Screencoord y, AlObject* &obj, AlWindow *window ) Description

Snaps a point on the screen to the closest curve, surface, or CurveOnSurface CV.

Arguments
< x, y - the screen position to test > *obj - the returned snapped object

840 | Chapter 5 AlSet AlXEvents

< window - the window to snap it to. Specify NULL to snap to the current window.

Return Codes
sSuccess - everything okay sObjectNotFound - there was no point in range to snap to sInsufficientMemory - not enough memory available sFailure - could not complete request.

statusCode AlSnap::toCurve( Screencoord x, Screencoord y, AlObject* &obj, double &curveParam, AlWindow *window ) Description
Snaps a point on the screen to the closest curve intersection.

Arguments
< x, y - the screen position to test > *obj - the returned snapped object > curveParam - the parameter position on the curve < window - the window to snap it to. Specify NULL to snap to the current window.

Return Codes
sSuccess - everything okay sObjectNotFound - there was no point in range to snap to sInsufficientMemory - not enough memory available sFailure - could not complete request

int AlSnap::snappingTo( void ) Description

Returns the snap setting currently selected within the application.

AlSnap | 841

Return Codes
kSnapGrid - Alias has grid snapping on kSnapCV - Alias has CV snapping on kSnapCurve- Alias has curve snapping on NOTE: return values will be ORed together if more than one of the snapping functions is on.

AlSpacePoint
Interface to Alias space points.

Synposis
#include <AlSpacePoint.h> class AlSpacePoint : public AlPoint AlSpacePoint(); ~AlSpacePoint(); virtual AlObject * copyWrapper() const; virtual AlObjectType type() const; statusCode create(double x = 0.0, double y = 0.0, double z = 0.0); statusCode setWorldPosition(double x = 0.0, double y = 0.0, \ double z = 0.0); virtual statusCode worldPosition(double &, double &, double &) const;

Description
AlSpacePoint is the interface to Alias Space points. A space point can be created at any point in the world coordinate system. There are methods to query and modify the position of the point in this class.

AlSpacePoint::AlSpacePoint(void) Description
Constructs an AlSpacePoint wrapper object.

842 | Chapter 5 AlSet AlXEvents

AlSpacePoint::~AlSpacePoint() Description
Deletes an AlSpacePoint wrapper object.

AlObject *AlSpacePoint::copyWrapper() const Description

Returns an exact copy of the AlSpacePoint wrapper.

AlObjectType AlSpacePoint::type() const Description

Returns the class identifier kSpacePointType.

statusCode AlSpacePoint::create(double x, double y, double z) Description

Create a space point.

Arguments
< x, y, z - the world coordinates of the point at which the space point is created

Return Codes
sSuccess - The space point was successfully created. sFailure - failed to create the space point sAlreadyCreated - object has already been created

statusCode AlSpacePoint::setWorldPosition(double x, double y, double z) Description

Move a space point to a new location in world coordinates.

AlSpacePoint | 843

Arguments
< x, y, z - the new coordinates of the space point

Return Codes
sSuccess - the point was moved sInvalidObject - the point is not valid

statusCode AlSpacePoint::worldPosition(double &x, double &y, double &z) const Description

Find the world coordinates of a space point

Arguments
> x, y, z - the X, Y, Z world coordinates of the space point

Return Codes
sSuccess - the world coordinates were found sInvalidObject - the point is not valid

AlSphereLight
Add parameters for sphere-shaped volume light.

Synopsis
#include <AlSphereLight.h> class AlSphereLight: public AlVolumeLight AlSphereLight(); virtual ~AlSphereLight(); virtual AlObject* copyWrapper() const; statusCode create(); AlObjectType type() const; double arc() const; statusCode setArc(double);

844 | Chapter 5 AlSet AlXEvents

Description
A sphere light is a volume light where light exists within a sphere. There are no additional parameters other than those already on the volume light.

AlSphereLight::AlSphereLight() Description
Constructs an AlSphereLight wrapper object.

AlSphereLight::~AlSphereLight() Description
Deletes an AlSphereLight wrapper object.

statusCode AlSphereLight::create() Description

Creates all the DAG nodes for this light and adds them to the universe. The DAG nodes are for position, look at and up, and another DAG node that groups these three together.

Return Codes
sSuccess - everything was successful sInsufficientMemory - not enough memory available

AlObjectType AlSphereLight::type() const Description

Returns the class identifier kSphereLightType.

double AlSphereLight::arc() const Description

Returns the sphere lights arc (that is, how much of the sphere we actually have). This method returns -1 if the light is invalid.

AlSphereLight | 845

statusCode AlSphereLight::setArc( double arc ) Description

Sets the sector of the sphere that the arc will sweep out. The given arc must be in the range 0 - 360.

Arguments
< double arc - portion of the sphere to use

Return Codes
sSuccess - setting arc succeeded sInvalidObject - not a valid volume light sInvalidArgument - arc out of the range 0..360 sFailure - an error occurred

AlSpotLight
Encapsulates the creation, deletion and manipulation of a spot light.

846 | Chapter 5 AlSet AlXEvents

Synopsis
#include <AlSpotLight.h> class AlSpotLight: public AlDirectionLight AlSpotLight(); virtual ~AlSpotLight(); virtual AlObject* copyWrapper() const; statusCode create(); AlObjectType type() const; double dropOff() const; double minBias() const; double maxBias() const; double spreadAngle() const; int offset() const; int multFactor() const; int shadowSize() const; double penumbra() const; virtual statusCode direction( double&, double&, double& ) const; virtual statusCode setDirection( double, double, double ); statusCode setDropOff( double ); statusCode setMinBias( double ); statusCode setMaxBias( double ); statusCode setSpreadAngle( double ); statusCode setOffset( int ); statusCode setMultFactor( int ); statusCode setShadowSize( int ); statusCode setPenumbra( double);

Description
To create a spot light, the user must instantiate and call the create method on an AlSpotLight object. (For more information on lights in general, see the Class Description of the AlDirectionLight on page 434 object.) The spot light is the only light that uses the look at and up nodes of a light. The direction vector of a spot light is the vector between the spot lights position point and look at point. The up direction vector is the vector between the spot lights position point and the up point. Other spot light parameters that can be manipulated are spread angle, dropoff, shadows, exclusivity, multiplication factor, offset, size, bias, and penumbra.

AlSpotLight | 847

AlSpotLight::AlSpotLight() Description
Constructs an AlSpotLight wrapper object.

AlSpotLight::~AlSpotLight() Description
Deletes an AlSpotLight wrapper object.

statusCode AlSpotLight::create() Description

Creates all the DAG nodes for this light and adds them to the universe. The DAG nodes are for position, look at and up, and another DAG node that groups these three together.

Return Codes
sSuccess - everything was successful sInsufficientMemory - not enough memory available

AlObjectType AlSpotLight::type() const Description

Returns the class identifier, kSpotLightType.

double AlSpotLight::dropOff() const Description

Returns the spot lights dropoff value. Dropoff is the rate at which light intensity decreases from the center to the edge of the spotlight beam. There are no numerical limits. Values of 1.0 and below give practically identical results; that is, no intensity dropoff along the radius of the spotlight beam: all intensity variation is due to basic distance effects and is controlled by decay. Default dropoff value is 0.0.

848 | Chapter 5 AlSet AlXEvents

double AlSpotLight::minBias() const Description

Returns the spot lights minimum bias value. Minimum and maximum bias define the range for which each surface point is randomly moved towards the eye before it is determined whether or not it is in a shadow. The minimum must be smaller than the maximum.

double AlSpotLight::maxBias() const Description

Returns the spot lights maximum bias value. Minimum and maximum bias define the range for which each surface point is randomly moved towards the eye before it is determined whether or not it is in a shadow. The maximum must be larger than the minimum.

double AlSpotLight::spreadAngle() const Description

Returns the spot lights spread angle. This is also referred to as the cut off value. Valid range is from 0.0 to infinity. Spread angle is the measure in degrees of the angle from the edge to edge of the spotlights beam. Resolution problems may occur when the spread is set to a number greater than 170 degrees: some objects are small enough to not produce a shadow with that large a light spread. -1 is returned if the light is not valid.

int AlSpotLight::offset() const Description

Returns the spot lights offset value. (This is similar to blur offset for textures.) Offset modifies the sampling region of the depth map. Offset adds a specified amount to the pixel area of the sampling region. The default sampling region is 4 by 4 pixels in the depth map. The formula used to calculate the sample region is:
numPixels = (4 * multFactor) + offset

The value of numPixels must always be greater than 0. Offset is ignored for spotlights if the shadows flag is FALSE.

AlSpotLight | 849

int AlSpotLight::multFactor() const Description

Returns the spot lights multiplication factor. (This is similar to blur factor for textures.) The multiplication factor is a scaling factor for the size of the sample region for the depth map. Values lower than 0.5 (without using offset) are prone to aliasing and banding. The default sampling region is 4 by 4 pixels in the depth map. The formula used to calculate the sample region is:
numPixels = (4 * multFactor) + offset

The value of numPixels must always be greater than 0.

int AlSpotLight::shadowSize() const Description

Returns the spot lights shadow size. Shadow size defines the resolution of depth maps used to cast shadows when ray casting. Increasing the size will provide more detailed shadows and will also increase the rendering time and amount of memory used. A size of 512 uses 1 Mbyte of memory, 1024 uses 4 Mbytes of memory.

double AlSpotLight::penumbra() const Description

Returns the spot lights penumbra angle. Penumbra is used to define how sharp or soft the spot lights edges are. As penumbra angle moves closer to zero (either from the positive or negative side), the spot light edge becomes sharper. As penumbra angle moves away from zero in a positive direction, the edge becomes softer outside of the area defined by the spread angle. If penumbra angle moves in a negative direction, then the edge becomes softer towards the centre of the spot light beam. The penumbra angle should not be less than: -1 * (spreadAngle/2) and should not be more than: (90 degrees spreadAngle/2).

statusCode AlSpotLight::setDropOff( double newDropoff ) Description

Sets the spot lights dropoff value. Dropoff is the rate at which light intensity decreases from the center to the edge of the spotlight beam. There are no

850 | Chapter 5 AlSet AlXEvents

numerical limits. Values of 1.0 and below give practically identical results; that is, no intensity dropoff along the radius of the spotlight beam: all intensity variation is due to basic distance effects and is controlled by decay. Default dropoff value is 0.0.

Arguments
< double newDropoff - is the new dropoff value

Return Codes
sSuccess - setting dropoff succeeded sInvalidObject - not a valid spot light sFailure - an error occurred

statusCode AlSpotLight::setMinBias( double newMinBias ) Description

Sets the spot lights minimum bias value. To be valid, newMinBias must be smaller than the current max Bias. Minimum and maximum bias define the range for which each surface point is randomly moved towards the eye before it is determined whether or not it is in a shadow. The minimum must be smaller than the maximum.

Arguments
< double newMinBias - is the new minimum bias value

Return Codes
sSuccess - setting min bias succeeded sInvalidObject - not a valid spot light sInvalidArgument - new min bias was greater than current max bias sFailure - an error occurred

AlSpotLight | 851

statusCode AlSpotLight::setMaxBias( double newMaxBias ) Description

Sets the spot lights maximum bias value. To be valid, newMaxBias must be larger than the current min Bias. Minimum and maximum bias define the range for which each surface point is randomly moved towards the eye before it is determined whether or not it is in a shadow. The minimum must be smaller than the maximum.

Arguments
< double newMaxBias - is the new maximum bias value

Return Codes
sSuccess - setting max bias succeeded sInvalidObject - not a valid spot light sInvalidArgument - new max bias was less than current min bias sFailure - an error occurred

statusCode AlSpotLight::setSpreadAngle( double newSpreadAngle ) Description

Sets the spot lights spread angle. This is also referred to as cut off. Valid range is from 0.0 to infinity. Spread angle is the measure in degrees of the angle from the edge to edge of the spotlights beam. Resolution problems may occur when the spread is set to a number greater than 170 degrees: some objects will not produce shadows with that large of a spread angle.

Arguments
< double newSpreadAngle - is the new spread angle

Return Codes
sSuccess - setting spread angle succeeded sInvalidObject - not a valid spot light sInvalidArgument - spread angle was less than 0

852 | Chapter 5 AlSet AlXEvents

sFailure - an error occurred

statusCode AlSpotLight::setOffset( int newOffset ) Description

Sets the spot lights offset value. (This is similar to blur offset for textures.) Offset modifies the sampling region of the depth map. Offset adds a specified amount to the pixel area of the sampling region. The default sampling region is 4 by 4 pixels in the depth map. The formula used to calculate the sample region is:
numPixels = (4 * multFactor) + offset

The value of numPixels must always be greater than 0. Offset is ignored for spotlights if the shadows flag is FALSE.

Arguments
< double newOffset - is the new offset value

Return Codes
sSuccess - setting the offset succeeded sInvalidObject - not a valid spot light sFailure - an error occurred

statusCode AlSpotLight::setMultFactor( int newMultFactor ) Description

Sets the spot lights multiplication factor. (This is similar to blur factor for textures.) The multiplication factor is a scaling factor for the size of the sample region for the depth map. Values lower than 0.5 (without using offset) are prone to aliasing and banding. The default sampling region is 4 by 4 pixels in the depth map. The formula used to calculate the sample region is:
numPixels = (4 * multFactor) + offset

The value of numPixels must always be greater than 0.

Arguments
< int newMultFactor - is the new multiplication factor

AlSpotLight | 853

Return Codes
sSuccess - setting the multiplication factor succeeded sInvalidObject - not a valid spot light sFailure - an error occurred

statusCode AlSpotLight::setShadowSize( int newShadowSize ) Description

Sets the spot lights shadow size. Shadow size defines the resolution of depth maps used to cast shadows when ray casting. Increasing the size will provide more detailed shadows and will also increase the rendering time and amount of memory used. A size of 512 uses 1 Mbyte of memory, 1024 uses 4 Mbytes of memory.

Arguments
< int newShadowSize - is the new shadow size

Return Codes
sSuccess - setting the shadow size succeeded sInvalidObject - not a valid spot light sFailure - an error occurred

statusCode AlSpotLight::setPenumbra( double newPenumbraAngle ) Description

Sets the spot lights penumbra angle. Penumbra is used to define how sharp or soft the spot light edges are. As penumbra angle moves closer to zero (either from the positive or negative side), the spot light edge becomes sharper. As penumbra angle moves away from zero in a positive direction, the edge becomes softer outside of the area defined by the spread angle. If penumbra angle moves in a negative direction, then the edge becomes softer towards the centre of the spot light beam. The penumbra angle should not be less than: -1 * (spreadAngle/2) and should not be more than: 90 degrees spreadAngle/2).

854 | Chapter 5 AlSet AlXEvents

Arguments
< double newPenumbraAngle - is the new penumbra angle

Return Codes
sSuccess - setting the prenumbra succeeded sInvalidObject - not a valid spot light sFailure - an error occurred

statusCode AlSpotLight::direction( double &x, double &y, double &z ) const Description
Returns the direction of the spotlight as a vector in x, y, z. The vector returned is really just the vector between the world position of this light and its lookat node.

Arguments
> double &x - is the direction of the light in x > double &y - is the direction of the light in y > double &z - is the direction of the light in z

Return Codes
sSuccess - getting the direction succeeded sInvalidObject - not a valid spot light sFailure - an error occurred

statusCode AlSpotLight::setDirection( double x, double y, double z ) Description

Sets the direction of the spotlight as a vector in x, y, z by altering the position of the lookat node.

Arguments
> double x - is the direction of the light in x

AlSpotLight | 855

> double y - is the direction of the light in y > double z - is the direction of the light in z

Return Codes
sSuccess - setting the direction succeeded sInvalidObject - not a valid spot light sFailure - an error occurred

AlStatusHandler
Augments the status codes of the Alias API.

Synopsis
#include <AlStatusHandler.h> class AlStatusHandler static const char* statusErrorString(); static int statusErrorNumber(); static void clear(); static statusCode installHandler( \ void (*)(int, const char *) ); static statusCode removeHandler( void (*)(int, const char *) );

Description
There are methods in the Alias API where a standard error code is used in more than one method return statement. The return value is essentially overloaded and it becomes difficult for the API developer to figure out which error condition was actually hit. This class will assist the API developer by providing a text string message whenever the overloaded return value condition is hit. This class supports retrieving the current status error string and number. Clearing the state of the status handler and installing and removing callbacks which listen to changes of state in the status handler. Notes: 1. The AlStatusHandler::clear() method is not called by the API. It is up to the programmer to ensure that the status handler has been cleared.

856 | Chapter 5 AlSet AlXEvents

2. The text messages will only be set in cases where the return value is overloaded. Therefore it is possible for an API method to fail without any change to the state of the status handler. 3. The Alias API contains many internal checks that could cause a method to return with a failure condition. In this case, an "internal error" will be returned by the status handler. This condition should be rare. 4. The AlStatusHandler::clear() method does not generate a call to a status handler callback. Therefore it can be used in a status handler callback without running into recursion problems. 5. The overloaded errors handled by this class are sFailure, sInvalidArgument and sInvalidObject.

void AlStatusHandler::clear() Description

Clears the current state of the status handler. It is possible to call this method from within an AlStatusHandler callback since the ::clear() method does not generate another call to the status handler callback.

const char* AlStatusHandler::statusErrorString() Description

Returns the error string associated with the current state of the status handler.

int AlStatusHandler::statusErrorNumber() Description

Returns the error number associated with the current state of the status handler.

statusCode AlStatusHandler::installHandler( void (*function)(int, const char *) ) Description

This method installs a callback handler that will be invoked when the status handler is set.

AlStatusHandler | 857

Arguments
< function - pointer to a void(int, const char* ) function

Return Codes
sSuccess - the method succeeded sInvalidObject - the method failed to install the handler sInvalidArgument - function parameter was NULL

statusCode AlStatusHandler::removeHandler( void (*function)(int, const char *) ) Description

This method removes a callback handler that was listening to status handler messages.

Arguments
< function - pointer to a void( int, const char * ) function

Return Codes
sSuccess - the method succeeded sFailure - the handler failed to be removed sInvalidArgument - function parameter was NULL

AlSurface
Interface to Alias NURBS surface geometry.

858 | Chapter 5 AlSet AlXEvents

Synopsis

AlSurface | 859

#include <AlSurface.h> class AlSurface : public AlObject AlSurface(); virtual ~AlSurface(); virtual statusCode deleteObject(); virtual AlObject* copyWrapper() const; statusCode create( int, int, curveFormType, curveFormType, int, int, const double[], const double[], int, int, const double[], const int[], const int[] ); statusCode create( int, int, curveFormType, curveFormType, const double[], const double[], int, int, const double[] ); statusCode createRevolvedSurface(const double[3], const double[3], double, double, const AlCurve* ); statusCode createRevolvedSurface( double [3], double [3], AlCurve* ); statusCode createLinearExtrusionSurface( double [3], double, Al Curve* ); statusCode createTorus(const double[3], const double[3], double, double, const double[3], double, double, double, double); statusCode createSphere( double [3], double ); statusCode createCylinder( double [3], double [3], double); statusCode createCone( double[3], double, double[3], double); virtual AlObjectType type() const; AlSurfaceNode* surfaceNode() const; curveFormType uForm() const; curveFormType vForm() const; int uDegree() const; int vDegree() const; int uNumberOfSpans() const; int vNumberOfSpans() const; int uNumberOfCVs() const; int vNumberOfCVs() const; AlSurfaceCV* firstCV() const; AlSurfaceCV* getCV( int, int ) const; AlAttributes* firstAttribute() const; boolean isAffectedByViewFrame() const; // Obselete boolean isConstructionHistoryResultingSurface() const; // Specific to AlSurface statusCode setCVsUnaffectedPosition( const double[]); statusCode setuKnotVector( const double[] ); statusCode setvKnotVector( const double[] ); statusCode setCVsUnaffectedPositionInclMultiples( const double[] );

860 | Chapter 5 AlSet AlXEvents

statusCode setRealuKnotVector( const double[] ); statusCode setRealvKnotVector( const double[] ); statusCode unpileEndKnots( int, const double[] ); boolean isPointActive( double u, double v ) const; // Common to AlSurface, AlTrimRegion statusCode CVsWorldPosition( double[], int[], int[])const; statusCode CVsAffectedPosition( const AlTM&, double[], int[], int[]) const; statusCode CVsUnaffectedPosition( double[], int[], int[])const; int uNumberOfKnots() const; int vNumberOfKnots() const; statusCode uKnotVector( double[] ) const; statusCode vKnotVector( double[] ) const; int uNumberOfCVsInclMultiples() const; int vNumberOfCVsInclMultiples() const; statusCode CVsWorldPositionInclMultiples( double[] ) const; statusCode CVsAffectedPositionInclMultiples( const AlTM&, double[] ) const; statusCode CVsUnaffectedPositionInclMultiples( double[] )const; int realuNumberOfKnots() const; int realvNumberOfKnots() const; statusCode realuKnotVector( double[] ) const; statusCode realvKnotVector( double[] ) const; statusCode area( double& area, boolean worldCoords = TRUE, double tolerance=0.001 ); statusCode circumference( double& circ, boolean worldCoords = TRUE, double tolerance=0.001 ); statusCode eval(double,double,boolean,double P[3], double Pu[3]=NULL, double Pv[3]=NULL, double n[3]=NULL,boolean=FALSE,boolean=FALSE ) const; // Specific to AlSurface AlShader* firstShader() const; AlShader* nextShader( const AlShader* ) const; statusCode nextShaderD( AlShader* ) const; statusCode assignShader( AlShader* ); statusCode layerShader( AlShader* ); statusCode renderInfo( AlRenderInfo& ) const; statusCode setRenderInfo( const AlRenderInfo& ) const; boolean trimmed() const; boolean isTargetSurface() const; statusCode project( AlCurveNode*, double[3], boolean ); statusCode projectNormal( AlCurveNode* curveNode, boolean keep_history );

AlSurface | 861

statusCode trim( int, const double[], const double[], boolean ); statusCode trim( int, const double[], const double[] ); statusCode trim( int, const AlCurveOnSurface*[] ); statusCode uniformRebuild( AlSurfaceNode* &newSurfaceNode, int nu, int nv, boolean inU, boolean inV, boolean=TRUE ); statusCode periodicToNonPeriodic( int, int ); statusCode periodicToNonPeriodic() const; AlSurface* untrimmedToTrimmedSurface() const; AlTrimRegion* trimSurfaceToRegion() const; AlTrimRegion* firstTrimRegion() const; AlCurve* localBoundary( int ) const; AlCurve* getModelSpaceSurfaceBoundary() const; AlCurve* parameterBoundary( int ) const; AlCurve* getParamSpaceSurfaceBoundary() const; AlCurveOnSurface* firstCurveOnSurface() const; statusCode addCurveOnSurface( AlCurveOnSurface* ); statusCode removeCurveOnSurface( AlCurveOnSurface* ); boolean isDisplayModeSet( AlDisplayModeType ) const; statusCode setDisplayMode( AlDisplayModeType, boolean ); statusCode doUpdates( boolean newState = TRUE ); statusCode insert( double, Direction ); statusCode reverseDirection( boolean inU, boolean inV );

Description
AlSurface is the interface to the geometric data of Alias NURBS surface objects. To create a surface, first instantiate and create an AlSurface and then instantiate and create an AlSurfaceNode. There is only a limited amount that you can do with an AlSurface that does not have an AlSurfaceNode. For more information on how to create the surface geometry, see the description for the create() method. Note: method isAffectedByViewFrame() is now obsolete. The new method to call is isConstructionHistoryResultingSurface() to find out if a surface may be modified based on changes to its constructor objects. A NURBS surface is described as having two dimensions, u and v. Many of the surface properties (form, multiplicity, and so on) are the same as a NURBS curve but are expressed in both the u and v direction. The form of a surface in the u or v direction can be one of three types: periodic, closed or open. If a surface is "kPeriodic" in u, then it is tangent continuous in u at all points in that direction. If a surface is "kClosed" in u, it is not periodic but its edges in the u direction are coincident. If the surface is neither closed

862 | Chapter 5 AlSet AlXEvents

nor periodic in u, it is considered to be "kOpen". The same applies in the v direction. There are two ways to delete an AlSurface. If the AlSurface deleteObject() is called, the attached AlSurfaceNode is deleted. If the AlSurfaceNode deleteObject() is called, the attached AlSurface is deleted. You should always create a surface node for a surface. If you create a surface with no surface node, then the surface is not added to the universe. If you should lose the pointer to the surface, it will become lost memory. There is one limitation to this class: you cannot add or remove individual CVs (except by changing multiplicity). If an AlSurface has curves-on-surface, then you can get a pointer to the first curve-on-surface and then traverse the curves using methods in the class AlCurveOnSurface. If an AlSurface is trimmed, the trim regions on the surface can be accessed using the firstTrimRegion() method and then traversed using methods in the class AlTrimRegion. All AlSurface objects will have at least one shader attached to them. These can be accessed through the firstShader() and nextShader() methods. All AlSurface objects have render information attached to them. The AlRenderInfo structure can be used to query the surfaces render parameters. Surfaces are made of surface control points (or CVs) which you traverse as a list by using the firstCV() in conjunction with the AlSurfaceCV methods. You can also pack the surface information into an array using methods in this class.

What is multiplicity?
An AlSurfaceCV object can actually represent multiple CVs, depending on the AlSurfaceCVs multiplicity and periodicity. Notice that in this class there are two sets of methods - some "InclMultiples" and some not (namely "numberOfCVs", "CVsWorldPosition", "CVsUnaffectedPosition", etc). The set of methods without multiplicity lets you get all surface CVs where a surface CV can have multiplicity of 1, 2 or 3. The set of methods "InclMultiples" lets you get ALL surface CVs including multiples due to a multiplicity > 1 and due to periodicity.

AlSurface | 863

Example 1
Create a surface in the interactive Alias package with 16 CVs, and pick the CV which is second in the u direction and second in the v direction. Set the multiplicity of this CV to 3 in the u direction and 2 in the v direction (using the "multiplicity" tool). Then: 1 uNumberOfCVs() will return 4. uNumberOfCVs() will return 4. 2 CVsWorldPosition must be passed a 4x4x4 CVs matrix, and the u and v multiplicity vectors must each be of length 4. 3 CVsUnaffectedPosition() must be passed the same as item 2. 4 setCVsUnaffectedPosition() must be passed the same as item 2. 5 uNumberOfCVsInclMultiples() will return 6. vNumberOfCvsInclMultiples() will return 5. 6 CVsWorldPositionInclMultiples() must be passed a 6x5x4 CVs matrix. You will notice that in this matrix there are duplicate CVs to indicate multiples due to multiplicity > 1 and periodicity. 7 CVsUnaffectedPositionInclMultiples() must be passed the same as item 6. You will notice that in this matrix there are duplicate CVs to indicate multiples due to multiplicity > 1 and periodicity. 8 setCVsUnaffectedPositionInclMultiples() must be passed the same as item 6. Similar to items 6 and 7, you should put duplicate CVs to account for multiples although this is not mandatory. You may want to refer to the examples in the AlCurve class description. The way CVs are ignored also applies to this method.

Example 2
If you create a surface in the interactive Alias package with 16 CVs and "close" the surface in the u direction (using the "close" tool in the Object Tools palette), you create a periodic surface. Then: 1 uNumberOfCVs() will return 4. uNumberOfCVs() will return 4. 2 CVsWorldPosition must be passed a 4x4x4 CVs matrix, and the u and v multiplicity vectors must each be of length 4. 3 CVsUnaffectedPosition() must be passed the same as item 2. 4 setCVsUnaffectedPosition() must be passed the same as item 2.

864 | Chapter 5 AlSet AlXEvents

5 uNumberOfCVsInclMultiples() will return 7. uNumberOfCVsInclMultiples() will return 4. 6 CVsWorldPositionInclMultiples() must be passed a 7x4x4 CVs matrix. 7 CVsUnaffectedPositionInclMultiples() must be passed the same as item 6. 8 setCVsUnaffectedPositionInclMultiples() must be passed the same as item 6. Similar to items 6 and 7, you should put duplicate CVs to account for multiples although this is not mandatory. You may want to refer to the examples in the AlCurve class description. The way CVs are ignored also applies to this method.

How do I process a matrix of CVs?

Methods in this class store CVs in the V direction first, then in the U direction. Heres an example of how to get the world positions of the CVs of a surface and print them out in V direction then U direction. (Notice that the outer "for" loop uses the number of CVs in the U direction).
int numUCvs = surface->uNumberOfCVs(); int numVCvs = surface->vNumberOfCVs(); double *cvs = new double [numUCvs * numVCvs * 4]; int *uMult = new int [numUCvs]; int *vMult = new int [numVCvs]; int u, v, index; surface->CVsWorldPosition( cvs, uMult, vMult ); for( index = 0, u = 0; u < numUCvs; u++ ) { for( v = 0; v < numVCvs; v++, index+=4 ) { printf(" %g, %g, %g, %g\n", cvs[index], cvs[index+1], cvs[index+2], cvs[index+3] ); } }

AlSurface::AlSurface() Description
Constructs an AlSurface wrapper object.

AlSurface | 865

AlSurface::~AlSurface() Description
Deletes an AlSurface wrapper object.

AlObject *AlSurface::copyWrapper() const Description

Returns an exact duplicate of this AlSurface wrapper.

statusCode AlSurface::deleteObject() Description

Deletes the AlSurface, its AlSurfaceCVs, and any AlCurveOnSurface attached to the surface. If this surface has an attached AlSurfaceNode, this node is also deleted.

Return Codes
sSuccess - the surface was deleted sFailure - the surface couldnt be deleted sInvalidObject - the surface is invalid

AlObjectType AlSurface::type() const Description

Returns the class identifier kSurfaceType.

AlSurfaceNode* AlSurface::surfaceNode() const Description

Returns a pointer to the AlSurfaceNode for this surface. Returns NULL if there is not attached surface node.

statusCode AlSurface::create(int uDeg,int vDeg,curveFormType uForm,curveFormType vForm,int uNumKnots,int vNumKnots,const double uKnotVector[],const double vKnotVector[],int uNumControlPts,int

866 | Chapter 5 AlSet AlXEvents

vNumControlPts,const double controlPoints[],const int uMultiplicity[],const int vMultiplicity[] ) Description

Used to create the data used to represent a surface. See the AlCurve::create() method in AlCurve on page 301 for a general description of how NURBS curves are represented with this interface. Surfaces are a natural extension of curves. Surfaces contain two one-dimensional arrays of knot values called knot vectors for each of the u and v parametric directions of the surface. The form and degree of the surface can be different in both the u and v direction. The control points are stored in a two-dimensional array of points so there are a total of uNumControlPts * vNumControlPts control points. The controlPoints parameter must have the dimensions [uNumControlPts][vNumControlPts][4]. This method may be used in the same way as the AlCurve::create() method, and the conditions that must be met by the input data are the same except that the conditions apply to both the u and v directions independently. For more information on multiplicity, see the Class Description.

Arguments
< uDeg - the degree of the curve in u < vDeg - the degree of the curve in v < uForm - open, closed or periodic in u < vForm - open, closed or periodic in v < uNumKnots - the number of knots in the uKnotVector < vNumKnots - the number of knots in the vKnotVector < uKnotVector - the sequence of knot values in u < vKnotVector - the sequence of knot values in v < uNumControlPts - the number of points in controlPoint in u < vNumControlPts - the number of points in controlPoint in v < controlPoints - the array of control points with dimensions controlPoints[uNumControlPts][vNumControlPts][4] < uMultiplicity - The multiplicity vector in u. This must be of length uNumControlPts

AlSurface | 867

< vMultiplicity - The multiplicity vector in v. This must be of length vNumControlPts

Return code
sSuccess - surface was created sInsufficientMemory - ran out of memory sAlreadyCreated - the AlSurface has already been created sInvalidArgument - this return code can be generated in many ways

number of spans <= 0 either in U or V { if periodic, number of spans = number of control points, if open or closed, number of spans = number of control points - degree. Substitute parameters for either the U or V direction. } number of knots != number of spans + 1 in either U or V the U or V knot vectors are not a non-decreasing sequence of values knots that delimit the first and last spans are non -zero, ie. ( knotVector[1] - knotVector[0] ) and ( knotVector[numKnots-1] - knotVector[numKnots-2] ) are not both zero for either U or V if U is closed, the first and last CVs in U are not identical for all Vs if V is closed, the first and last CVs in V are not identical for all Us if U is periodic, the number of spans in U is less than 3 or the U degree is greater than the number of spans in U if V is periodic, the number of spans in V is less than 3 or the V degree is greater than the number of spans in V

statusCode AlSurface::create(int uDeg,int vDeg,curveFormType uForm,curveFormType vForm,const double uKnotVector[],const double vKnotVector[],int uNumControlPts,int vNumControlPts,const double controlPoints[] ) Description
Used to create the data used to represent a surface. See the AlCurve::create() method for a general description of how NURBS curves are represented with this interface. Surfaces are a natural extension of curves.

868 | Chapter 5 AlSet AlXEvents

Surfaces contain two one-dimensional arrays of knot values called knot vectors for each of the u and v parametric directions of the surface. The form and degree of the surface can be different in both the u and v direction. The control points are stored in a two-dimensional array of points so there are a total of uNumControlPts * vNumControlPts control points. The controlPoints parameter must have the dimensions [uNumControlPts][vNumControlPts][4]. This method may be used in the same way as the AlCurve::create() method, and the conditions that must be met by the input data are the same except that the conditions apply to both the u and v directions independently. Note: this method requires that redundant knots be specified.

Arguments
< uDeg - the degree of the curve in u < vDeg - the degree of the curve in v < uForm - open, closed or periodic in u < vForm - open, closed or periodic in v < uKnotVector - the sequence of knot values in u. Size of this array is uNumControlPts + uDeg + 1 < vKnotVector - the sequence of knot values in v. Size of this array is vNumControlPts + vDeg + 1 < uNumControlPts - the number of points in controlPoint in u < vNumControlPts - the number of points in controlPoint in v < controlPoints - the array of control points with dimensions controlPoints[uNumControlPts][vNumControlPts][4]

Return code
sSuccess - surface was created sInsufficientMemory - ran out of memory sAlreadyCreated - the AlSurface has already been created sInvalidArgument - this return code can be generated in many ways

the number of spans is <= 0 in either U or V { number of spans = number of control points - degree in either U or V. Substitute parameters for either the U or V direction. }

AlSurface | 869

the U or V knot vectors are not a non-decreasing sequence of values the difference between the first degree { U or V } and difference between the last degree { U or V } number of knots is not 0
for (i = 0; i < deg; i++) ( knotVector[i+1] - knotVector[i] != 0) || ( knotVector[numKnots-i-1] - knotVector[numKnots-i-2] != 0 )

for a periodic surface in U or V, the knot deltas for a periodic dimension are not correct. If the knot deltas are correct, the following is true:
For i = 0 to 2*deg-1 (n = numberSpans) T[i+1] - T[i] = T[i+n+1] - T[i+n]

if U is closed, the first and last CVs in U are not identical for all points in V if V is closed, the first and last CVs in V are not identical for all points in U if U is periodic, the number of spans in U is less than 3 or the U degree is greater than the number of spans in U if V is periodic, the number of spans in V is less than 3 or the V degree is greater than the number of spans in V for a periodic surface in U, the first uDegree number of CVs must match the last uDegree number of CVs for all V dimensions. for a periodic surface in V, the first vDegree number of CVs must match the last vDegree number of CVs for all U dimensions

statusCode AlSurface::createRevolvedSurface( const double startPoint[3], const double endPoint[3], double startAngle, double endAngle, const AlCurve* generatrix ) Description
Used to create a surface of revolution instead of the more complex AlSurface::create() method. Angles are measured in degrees with the generatrix being at zero degrees. As well the angles of rotation are measured counter clockwise while looking in the direction of startPoint from endPoint.

870 | Chapter 5 AlSet AlXEvents

Arguments
< startPoint - one end of axis of revolution < endPoint - other end of axis of revolution < startAngle - the starting angle in degrees < endAngle - the ending angle in degrees < generatrix - the curve to be spun about the axis

Return code
sSuccess - the surface was created sInvalidArgument - a NULL argument was supplied sInsufficientMemory - ran out of memory sAlreadyCreated - the AlSurface has already been created sFailure - generatrix was invalid

statusCode AlSurface::createRevolvedSurface( double pointOnAxis[3], double direction[3], AlCurve *curve ) Description

Create a surface of revolution from a point, a direction vector and a curve

Arguments
< pointOnAxis - point on axis of the revolved surface < direction - direction of the revolved surface axis < curve - boundary curve that defines the revolved surface

Return code
sSuccess - the surface was created sInvalidArgument - a NULL argument was supplied or curve is invalid sInsufficientMemory - ran out of memory sAlreadyCreated - the AlSurface has already been created sFailure - the method failed

AlSurface | 871

statusCode AlSurface::createLinearExtrusionSurface( double direction[3], double len, AlCurve *curve ) Description

Create a surface of linear extrusion from a direction vector, a length of extrusion and a curve.

Arguments
< direction - direction to extrude along < len - length to extrude by < curve - edge boundary to extrude from

Return code
sSuccess - the surface was created sInvalidArgument - a NULL argument was supplied sInsufficientMemory - Ran out of memory. sAlreadyCreated - the AlSurface has already been created sFailure - curve was invalid

statusCode AlSurface::createTorus(const double origin[3], const double direction[3], double majorRadius, double minorRadius, const double zero[3], double rot_start, double rot_end, double arc_start, double arc_end) Description
Create a partial torus surface.

Arguments
> origin - center of torus > direction - axis direction > majorRadius - major radius > minorRadius - minor radius > zero - vector toward zero angle > rot_start - start angle for rotation

872 | Chapter 5 AlSet AlXEvents

> rot_end - end angle for rotation > arc_start - start angle for arc > arc_end - end angle for arc

Returns
sSuccess - the surface was successfully created sInvalidArgument - an invalid argument was supplied sFailure - an error occurred

statusCode AlSurface::createSphere( double origin[3], double radius ) Description

Create a spherical surface from an origin point and a radius.

Arguments
< origin - center of sphere < radius - radius of the sphere

Returns
sSuccess - the surface was successfully created sInvalidArgument - an invalid argument was supplied or radius <= 0 sFailure - an error occurred

statusCode AlSurface::createCylinder( double bottomAxisPoint[3], double topAxisPoint[3], double radius ) Description

Create a Cylindrical surface from a bottom and top point and a radius.

Arguments
< bottomAxisPoint - center point of the cylinders bottom < topAxisPoint - center point of the cylinders top < radius - radius of the cylinder

AlSurface | 873

Returns
sSuccess - the surface was successfully created sInvalidArgument - an invalid argument was supplied or radius <= 0 or the top and bottom points are the same sFailure - an error occurred

statusCode AlSurface::createCone( double bottomAxisPoint[3], double bottomRadius, double topAxisPoint[3], double topRadius ) Description
Create a conical surface from a bottom axis point and its radius and a top axis point and its radius.

Arguments
< bottomAxisPoint - bottom center point of the cone < topAxisPoint - top center point of the cone < bottomRadius - radius at the bottom of the cone < topRadius - radius at the top of the cone

Returns
sSuccess - the surface was successfully created sInvalidArgument - an invalid argument was supplied or bottomRadius <= 0 o topRadius <= 0 or the top and bottom points are the same sFailure - an error occurred

curveFormType AlSurface::uForm() const Description

Returns the form of the surface in the u direction, that is, kOpen, kClosed or kPeriodic. For more information on form, see the AlSurface on page 858class description. kInvalidCurve is returned if the surface is invalid.

874 | Chapter 5 AlSet AlXEvents

curveFormType AlSurface::vForm() const Description

Returns the form of the surface in the v direction, that is, kOpen, kClosed or kPeriodic. For more information on form, see the AlSurface on page 858 class description. kInvalidCurve is returned if the surface is invalid.

int AlSurface::uDegree() const Description

Returns the degree of the surface in the u direction. -1 is returned if the surface is not valid.

int AlSurface::vDegree() const Description

Returns the degree of the surface in the v direction. -1 is returned if the surface is not valid.

int AlSurface::uNumberOfSpans() const Description

Returns the number of spans in the u direction of the surface. If the surface is not valid -1 will be returned.

int AlSurface::vNumberOfSpans() const Description

Returns the number of spans in the v direction of the surface. If the surface is not valid -1 will be returned.

int AlSurface::uNumberOfCVs() const Description

Returns the number of CVs in the u direction of the surface. If the surface is not valid -1 will be returned.

AlSurface | 875

int AlSurface::vNumberOfCVs() const Description

Returns the number of CVs in the v direction of the surface. If the surface is not valid -1 will be returned.

AlSurfaceCV* AlSurface::firstCV() const Description

Returns a pointer to the first CV in this surface. To traverse the CVs of this surface, use the methods in the AlSurfaceCV class. With the 6.1 release of OpenModel it is no longer necessary to specify whether a permanent pointer is necessary as was done in earlier releases.

AlSurfaceCV* AlSurface::getCV( int indexU, int indexV ) const Description

Returns a pointer to the CV identified by the given indices. Returns NULL if the CV could not be found or one of the indices was negative. The indices of the first CV are (0,0).

AlAttributes* AlSurface::firstAttribute() const Description

Returns the first attribute on this surface if any, otherwise NULL is returned. Note that if CV positions are modified through any of the AlSurface, AlSurfaceCV, AlCluster, AlSet, and so on, methods then the attributes are removed from the surface.

statusCode AlSurface::CVsWorldPosition(double CVList[], int uMultiplicity[], int vMultiplicity[] ) const Description

Returns the world position of this surfaces CVs in the given array and the multiplicity of each CV in the multiplicity vector. The CV array must have the size [uNumberOfCVs * vNumberOfCVs * 4]. The multiplicity vector uMultiplicity must be of length uNumberOfCVs and the vector vMultiplicity must be of length vNumberOfCVs.

876 | Chapter 5 AlSet AlXEvents

Note that the positions returned are [ x y z w ] and not [ w*x w*y w*z w ]. The multiplicity vectors returned by this function are the same as the ones returned by CVsUnaffectedPosition().

Arguments
> CVList - contains all the CVs world positions upon return > uMultiplicity - contains each CVs multiplicity in u > vMultiplicity - contains each CVs multiplicity in v

Return Codes
sSuccess - the CVs world positions were retrieved sInvalidArgument - one of the parameters was NULL sFailure - the world positions were not retrieved sInvalidObject - the surface is invalid

statusCode AlSurface::CVsAffectedPosition( const AlTM& tm, double CVList[],int uMultiplicity[],int vMultiplicity[] ) const Description
Returns the affected position of this surfaces CVs in the given array and the multiplicity of each CV in the multiplicity vector. The CV array must have the size [uNumberOfCVs * vNumberOfCVs * 4]. The multiplicity vector uMultiplicity must be of length uNumberOfCVs and the vector vMultiplicity must be of length vNumberOfCVs. The multiplicity vectors returned by this function are the same as the ones returned by CVsUnaffectedPosition().

Arguments
< tm - the transformation matrix generated while walking the DAG > CVList - contains all the CVs world positions upon return > uMultiplicity - contains each CVs multiplicity in u > vMultiplicity - contains each CVs multiplicity in v

Return Codes
sSuccess - the CVs affected positions were retrieved

AlSurface | 877

sInvalidArgument - one of the parameters was NULL sFailure - the affected positions were not retrieved sInvalidObject - the surface is invalid

statusCode AlSurface::CVsUnaffectedPosition( double CVList[],int uMultiplicity[],int vMultiplicity[] ) const Description

Returns the unaffected positions of this surfaces CVs in the given array and the multiplicity of each CV in the multiplicity vector. The CV array must have the size [uNumberOfCVs * vNumberOfCVs * 4]. The multiplicity vector uMultiplicity must be of length uNumberOfCVs and the vector vMultiplicity must be of length vNumberOfCVs. The multiplicity vectors returned by this function are the same as the ones returned by CVsWorldPosition().

Arguments
> CVList - contains all the CVs unaffected positions upon return > uMultiplicity - contains each CVs multiplicity in u > vMultiplicity - contains each CVs multiplicity in v

Return Codes
sSuccess - the CVs unaffected positions were retrieved sInvalidArgument - one of the parameters was NULL sFailure - the unaffected positions were not retrieved sInvalidObject - the surface is invalid

statusCode AlSurface::doUpdates( boolean newState ) Description

See AlDagNode on page 381.

statusCode AlSurface::insert( double param, Direction dir ) Description

Inserts an isoparm into the surface.

878 | Chapter 5 AlSet AlXEvents

Arguments
< param - parametric value of the new isoparm on the surface < dir - direction of the new isoparm (either kU or kV)

Return Codes
sSuccess - normal completion sInvalidArgument - one of the parameters is out of range sFailure - an error occurred sInvalidObject - the surface is invalid

statusCode AlSurface::setCVsUnaffectedPosition( const double CVList[] ) Description

Sets the unaffected positions of this surfaces CVs to the given array. The passed-in CV array must have the size [uNumberOfCVs * vNumberOfCVs * 4].

Arguments
< CVList - contains all the CVs unaffected positions upon return

Return Codes
sSuccess - the unaffected positions were set sInvalidArgument - one of the parameters was NULL sFailure - the unaffected positions were not set sInvalidObject - the surface is invalid

boolean AlSurface::isAffectedByViewFrame() const Description

This function is now OBSELETE. Call method is ConstructionHistoryResultingSurface() instead.

AlSurface | 879

boolean AlSurface::isConstructionHistoryResultingSurface() const Description

Returns TRUE if this surface is the resulting surface of a construction history operation.

Return Codes
TRUE - the surface is created by construction history FALSE - the surface is not created by construction history or the surface has no AlSurfaceNode

boolean AlSurface::isPointActive( double u, double v ) const Description

Determines the U,V coordinates of a point on a surface in a trim region.

Arguments
< u - the parametric u coordinate of the point on the surface < v - the parametric v coordinate of the point on the surface

Return Codes
TRUE - the point is in a trimmed region FALSE - the point is outside of a trimmed region

statusCode AlSurface::area( double& area, boolean worldCoordinates, double tolerance ) Description

Determines the area of the surface. sSuccess will be returned if the evaluation succeeded. sFailure will be returned if the evaluation failed.

Arguments
< worldCoordinates - the evaluation is to be in world coordinates

880 | Chapter 5 AlSet AlXEvents

> area - the returned value > tolerance - the error tolerance

Return Codes
sSuccess - the coordinate was successfully determined sFailure - the evaluation failed sInvalidObject - the surface is invalid sInvalidArgument - tolerance was not a positive number

statusCode AlSurface::circumference( double& circumference, boolean worldCoordinates, double tolerance ) Description

Determines the circumference of the surface. This is a meaningless value for a closed surface but it will be attempted anyway. For example, a sphere has four edges that join at the poles, although it does not have a true circumference. sSuccess will be returned if the evaluation succeeded. sFailure will be returned if the evaluation failed.

Arguments
< worldCoordinates - the evaluation is to be in world coordinates > circumference - the returned value > tolerance - the error tolerance

Return Codes
sSuccess - the coordinate was successfully determined sFailure - the evaluation failed sInvalidObject - the surface is invalid sInvalidArgument - tolerance was not a positive number

AlSurface | 881

statusCode AlSurface::eval(double u, double v, boolean worldCoordinates, double P[3], double Pu[3], double Pv[3], double n[3], boolean uLimitFromBelow, boolean vLimitFromBelow ) const Description
Determines the 3D coordinate and partial derivatives of the parameter values on the surface. sSuccess will be returned if the evaluation succeeded. sFailure will be returned if the evaluation failed. Use isPointActive to determine if the point is in a trim region uLimitsFromBelow and vLimitsFromBelow are used when determining the normal. These tell which direction limits are used to determine the normal if the gradient is not numerically stable.

Arguments
< u - the parametric u coordinate of the point on the surface < v - the parametric v coordinate of the point on the surface < worldCoordinates - the evaluation is to be in world coordinates > P - the point on the surface (if not NULL) > Pu - the partial wrt u of the point on the surface (if not NULL) > Pv - the partial wrt v of the point on the surface (if not NULL) > n - the normal to the surface (if not NULL) < uLimitFromBelow - use u limit from below < vLimitFromBelow - use v limit from below

Return Codes
sSuccess - the coordinate was successfully determined sFailure - the evaluation failed sInvalidObject - the surface is invalid

882 | Chapter 5 AlSet AlXEvents

int AlSurface::uNumberOfKnots() const Description

Returns the number of knots in the u direction of the surface. This method will not function properly on surfaces with unpiled end knots. Use realuNumberOfKnots() instead. This method will return -1 if the surface is invalid.

int AlSurface::vNumberOfKnots() const Description

Returns the number of knots in the v direction of the surface. This method will not function properly on surfaces with unpiled end knots. Use realvNumberOfKnots() instead. This method will return -1 if the surface is invalid.

statusCode AlSurface::uKnotVector( double knotVector[] ) const Description

Returns this curves knot vector in the given knotVector. The parameter knotVector must be of length uNumberOfKnots(). This method will only function properly with surfaces with knots piled up on the ends. For surfaces with unpiled end knots use realuKnotVector() instead.

Arguments
> knotVector - vector of length uNumberOfKnots() that contains this curves knot vector upon return

Return Codes
sSuccess - the curves knot vector was returned sInvalidArgument - knotVector was NULL sInvalidObject - the surface was invalid

AlSurface | 883

statusCode AlSurface::vKnotVector( double knotVector[] ) const Description

Returns this curves knot vector in the given knotVector. The parameter knotVector must be of length vNumberOfKnots(). This method will only function properly with surfaces with knots piled up on the ends. For surfaces with unpiled end knots use realvKnotVector() instead.

Arguments
> knotVector - vector of length vNumberOfKnots() that contains this curves knot vector upon return

Return Codes
sSuccess - the v knot vector was returned sInvalidArgument - knotVector was NULL sFailure - the v knot vector was not returned sInvalidObject - the surface is invalid

statusCode AlSurface::setuKnotVector( const double uKnotVector[] ) Description

Sets this curves knot vector to the given uKnotVector. The parameter knotVector must be of length uNumberOfKnots(). If the surface is trimmed this method does nothing. This method will only function properly with surfaces with knots piled up on the ends. For surfaces with unpiled end knots use setRealuKnotVector() instead.

Arguments
< uKnotVector - vector of length uNumberOfKnots() to set this curve with

Return Codes
sSuccess - the u knot vector was set sInvalidArgument - knotVector was NULL sFailure - the u knot vector was not set or the surface is trimmed

884 | Chapter 5 AlSet AlXEvents

sInvalidObject - the surface is invalid

statusCode AlSurface::setvKnotVector( const double vKnotVector[] ) Description

Sets this curves knot vector to the given vKnotVector. The parameter knotVector must be of length vNumberOfKnots(). If the surface is trimmed this method does nothing. This method will only function properly with surfaces with knots piled up on the ends. For surfaces with unpiled end knots use setRealvKnotVector() instead.

Arguments
< vKnotVector - vector of length vNumberOfKnots() to set this curve with

Return Codes
sSuccess - the v knot vector was set sInvalidArgument - knotVector was NULL sFailure - the v knot vector was not set or the surface is trimmed sInvalidObject - the surface is invalid

int AlSurface::uNumberOfCVsInclMultiples() const Description

Returns the number of control points in the u direction (uDegree + uNumberOfSpans). For more information on multiplicity, see the AlSurface on page 858 class description. This method returns -1 if the surface is invalid.

int AlSurface::vNumberOfCVsInclMultiples() const Description

Returns the number of control points in the v direction (vDegree + vNumberOfSpans). For more information on multiplicity, see the AlSurface on page 858 class description. This method returns -1 if the surface is invalid.

AlSurface | 885

statusCode AlSurface::CVsWorldPositionInclMultiples( double CVList[] ) const Description

Same as CVsWorldPosition() except that this method includes multiples. The parameter CVList must have dimensions [uNumberOfCVsInclMultiples * vNumberOfCVsInclMultiples * 4]. The surfaceNode must be set or sFailure will be returned For more information on multiplicity, see the AlSurface on page 858class description. NOTE: The data is arranged in the array as cv[u][v][4]. Note that the positions returned are [ x y z w ] and not [ w*x w*y w*z w ].

Arguments
> CVList - contains the world positions of all CVs upon return

Return Codes
sSuccess - the world positions of all CVs was returned sInvalidArgument - CVList was NULL sFailure - the world positions of all CVs could not be returned sInvalidObject - the surface is invalid

statusCode AlSurface::CVsAffectedPositionInclMultiples( const AlTM& tm, double CVList[] ) const Description

Same as CVsAffectedPosition() except that this method includes multiples. The parameter CVList must have dimensions [uNumberOfCVsInclMultiples * vNumberOfCVsInclMultiples * 4]. For more information on multiplicity, see the AlSurface on page 858 class description. NOTE: The data is arranged in the array as cv[u][v][4]. Note that the positions returned are [ x y z w ] and not [ w*x w*y w*z w ].

Arguments
< tm - the transformation matrix generated while walking the DAG

886 | Chapter 5 AlSet AlXEvents

> CVList - contains the world positions of all CVs upon return

Return Codes
sSuccess - the affected positions of all CVs were returned sInvalidArgument - CVList was NULL sFailure - the affected positions of all CVs could not be returned sInvalidObject - the surface is invalid

statusCode AlSurface::CVsUnaffectedPositionInclMultiples( double CVList[] ) const Description

Same as CVsUnaffectedPosition() except that this method includes multiples. The parameter CVList must have dimensions [uNumberOfCVsInclMultiples * vNumberOfCVsInclMultiples * 4]. For more information on multiplicity, see the AlSurface on page 858 class description. For more information on unaffected position, see the description in the AlSurfaceCV on page 904 class, method unaffectedPosition(). NOTE: The data is arranged in the array as cv[u][v][4].

Arguments
> CVList - contains the unaffected positions of all CVs upon return

Return Codes
sSuccess - the unaffected positions of all CVs were returned sInvalidArgument - CVList was NULL sFailure - the unaffected positions of all CVs could not be returned sInvalidObject - the surface is invalid

statusCode AlSurface::setCVsUnaffectedPositionInclMultiples( const double CVList[] ) Description

Same as setCVsUnaffectedPosition() except that this method includes multiples. The parameter CVList must have dimensions [uNumberOfCVsInclMultiples

AlSurface | 887

* vNumberOfCVsInclMultiples * 4]. For more information on multiplicity, see the AlSurface on page 858 class description. For more information on unaffected position, see the description in the AlSurfaceCV on page 904 class, method unaffectedPosition(). You cannot give multiples different values. This is best explained in the examples in the AlCurve class description. Some of the values in the given CVList may be ignored, because they specify a redundant point due to multiplicity > 1 or due to periodicity. NOTE: The data is arranged in the array as cv[u][v][4].

Arguments
< CVList - the new positions to set this surfaces CVs to

Return Codes
sSuccess - the unaffected positions of all CVs were set sInvalidArgument - CVList was NULL sFailure - the unaffected positions of all CVs could not be set sInvalidObject - the surface is invalid

boolean AlSurface::isTargetSurface() const Description

Returns TRUE if the surface is a target surface. If this node does not have a parent Dag node, then it is considered not to be a target surface.

boolean AlSurface::trimmed() const Description

Returns TRUE if the surface has been trimmed. A target surface (a surface with a curve-on-surface that has never been trimmed) is not considered to be a trimmed surface.

888 | Chapter 5 AlSet AlXEvents

statusCode AlSurface::project( AlCurveNode* curveNode, double vector[3], boolean keep_history ) Description

This method projects a 3D curve along the given vector onto the surface, creating 2D curves on the surface. Several curves can be projected onto the surface which can then be trimmed.

Arguments
< curveNode - the curve to be projected onto the surface < vector - the vector to project the curve along < keep_history - Should the construction history be kept.

Return Codes
sSuccess - successfully projected the curve sInvalidObject - this surface is not valid sInvalidArgument - the curve node is not valid, the vector is of zero length, or the surface has no parent surface node sInsufficientMemory - inadequate memory to run the command sFailure - failed to project the curve

statusCode AlSurface::unpileEndKnots( int whichEnds, const double interval[] ) Description

NOTE: This operation generates prototype geometry that may not be compatible with all OpenModel or Alias operations. Operations on unpiled surfaces may result in unexpected results including fatal errors. Use unpiled surfaces at your own risk. Surfaces in Alias have knots that are piled up at the ends so that the surface interpolates the ends. This operation will unpile these knots so that the curve no longer interpolates the ends. The interval used to space the knots of the unpiled knots will either be taken from the given argument, or if this is NULL the last non-zero knot interval

AlSurface | 889

on the given end will be used. All knot intervals must be greater than zero or sInvalidArgument will be returned. The AlSurface requires an AlSurfaceNode above it for this operation to succeed.

Arguments
< whichEnds - one or more of AL_UNPILE_START_U, ..., AL_UNPILE_END_V ored together < interval - an array (possibly NULL) of degree - 1 knot intervals

Return Codes
sSuccess - the specified ends were unpiled sFailure - the surface is invalid in some way (ex. no CVs) sInvalidObject - the surface is invalid sInvalidArgument - an attempt was made to unpile a periodic surface in the direction of its periodicity

int AlSurface::realuNumberOfKnots() const Description

Returns the actual number of u knots on the surface. That is uNumberOfSpans() + 2*uDegree() - 1. (Note that two additional knots are required to define a NURBS curve, but they have no effect on the curve so are not included in this count.) This method returns -1 if the surface is not valid.

int AlSurface::realvNumberOfKnots() const Description

Returns the actual number of v knots on the surface. That is vNumberOfSpans() + 2*vDegree() - 1. (Note that two additional knots are required to define a NURBS curve, but they have no effect on the curve so are not included in this count.) This method returns -1 if the surface is not valid.

890 | Chapter 5 AlSet AlXEvents

statusCode AlSurface::realuKnotVector( double knotVector[] ) const Description

Returns realuNumberOfKnots() in knotVector for the u direction of the surface.

Arguments
> knotVector - array to place the knot vector into

Return Codes
sSuccess - successfully copied the surfaces knot vector into knotVector sInvalidArgument - knotVector was NULL sInvalidObject - the surface was invalid

statusCode AlSurface::realvKnotVector( double knotVector[] ) const Description

Returns realvNumberOfKnots() in knotVector for the v direction of the surface.

Arguments
> knotVector - array to place the knot vector into

Return Codes
sSuccess - successfully copied the surfaces knot vector into knotVector sInvalidArgument - knotVector was NULL sInvalidObject - the surface was invalid

statusCode AlSurface::setRealuKnotVector( const double knotVector[] ) Description

Sets the knots in the u direction for this surface. The parameter knotVector must be of realuNumberofKnots().

AlSurface | 891

Arguments
< knotVector - array of knots

Return Codes
sSuccess - the u knots were successfully set sInvalidArgument - knotVector was NULL sFailure - the surface was trimmed sInvalidObject - the surface is invalid

statusCode AlSurface::setRealvKnotVector( const double knotVector[] ) Description

Sets the knots in the v direction for this surface. The parameter knotVector must be of realvNumberofKnots().

Arguments
< knotVector - array of knots

Return Codes
sSuccess - the v knots were successfully set sInvalidArgument - knotVector was NULL sFailure - the surface was trimmed sInvalidObject - the surface is invalid

AlShader* AlSurface::firstShader() const Description

Returns the first shader that this surface object references. Returns NULL if there are no shaders.

892 | Chapter 5 AlSet AlXEvents

AlShader* AlSurface::nextShader( const AlShader* last_shader ) const Description

Returns the shader after the given shader in the objects shader list. Returns NULL if there isnt a next shader. Specifying NULL as parameter will return the first shader.

Arguments
< last_shader - shader from which to walk forward

statusCode AlSurface::nextShaderD( AlShader* last_shader ) const Description

Destructively points last_shader to the shader after the given shader in the objects shader list.

Arguments
< last_shader - shader from which to walk forward

Return Codes
sSuccess - last_shader now points to the next shader sFailure - there isnt a next shader sInvalidArgument - last_shader is invalid sInvalidObject - the surface is invalid

statusCode AlSurface::assignShader( AlShader* shader ) Description

Assigns the given shader to the surface. If the surface already has shaders they will be removed from the surface. The surface must have a surface node for this method to succeed.

Arguments
< shader - the shader which will be assigned to the surface

AlSurface | 893

Return Codes
sSuccess - the shader was successfully assigned to the surface sInvalidArgument - shader was invalid sFailure - the shader was not created sInvalidObject - the surface is invalid

statusCode AlSurface::layerShader( AlShader* shader ) Description

Layers the given shader on the surface. The surface must have a surface node for this method to succeed.

Arguments
< shader - the shader which will be layered on the surface

Return Codes
sSuccess - the shader was successfully layered on the surface sInvalidArgument - shader was invalid sFailure - the shader was not created sInvalidObject - the surface is invalid

statusCode AlSurface::renderInfo( AlRenderInfo &renderInfo ) const Description

Fills in the renderInfo structure with the render info for this surface.

Arguments
> renderInfo - the structure to fill in

Return Codes
sSuccess - getting the render information was successful sInvalidArgument - renderInfo is NULL

894 | Chapter 5 AlSet AlXEvents

sFailure - there wasnt any render information (renderInfo is unchanged) sInvalidObject - the surface is invalid

statusCode AlSurface::setRenderInfo( const AlRenderInfo &renderInfo ) const Description

Sets the render info for this surface to the contents of the renderInfo structure.

Arguments
< renderInfo - the structure to take the render information from

Return Codes
sSuccess - setting the render information was successful sInvalidArgument - renderInfo was NULL or a parameter in renderInfo was out of range sFailure - setting the render information failed sInvalidObject - the surface is invalid

AlCurveOnSurface* AlSurface::firstCurveOnSurface() const Description

Returns the first curve on surface from the list of curves on this surface. Access the remainder of the curves on surfaces in the list with AlCurveOnSurface methods. This method returns NULL if there arent any curves on this surface.

statusCode AlSurface::addCurveOnSurface( AlCurveOnSurface* AlCos ) Description

Add a curve on surface to the list of curves on this surface. It is illegal to add a curve on surface that is already attached to another surface. The surface must be attached to a surfaceNode or this routine will fail.

Arguments
< AlCos - the curve-on-surface to add to the surface

AlSurface | 895

Return Codes
sSuccess - the curve was added sInvalidArgument - AlCos was invalid sFailure - the surface is trimmed sInvalidObject - the surface is invalid

statusCode AlSurface::removeCurveOnSurface( AlCurveOnSurface* AlCos ) Description

Remove a curve on surface from the list of curves on this surface. It is illegal to attempt to remove a curve on surface from this surface if it is not attached to this surface. It is legal to remove a curve on surface from a surface that is trimmed as long as the curve on surface has not been used for the trimming of the surface.

Arguments
< AlCos - the curve on surface to remove

Return Codes
sSuccess - the CoS was removed sInvalidArgument - AlCos was invalid sFailure - the Curve on surface could not be removed sInvalidObject - the surface is invalid

boolean AlSurface::isDisplayModeSet( AlDisplayModeType mode ) const Description

Returns TRUE if the specified display mode is toggled on for the surface. Returns FALSE otherwise. The only valid AlDisplayModeTypes for an AlSurface are: kDisplayGeomHull kDisplayGeomEditPoints

896 | Chapter 5 AlSet AlXEvents

kDisplayGeomKeyPoints kDisplayGeomCVs

Arguments
< mode - display mode of interest

statusCode AlSurface::setDisplayMode( AlDisplayModeType mode, boolean on_or_off ) Description

For the given display mode, if the flag is TRUE then the display mode for the surface is set, otherwise it is unset. The only valid AlDisplayModeTypes for an AlSurface are: kDisplayGeomHull kDisplayGeomEditPoints kDisplayGeomKeyPoints kDisplayGeomCVs

Arguments
< mode - display mode of interest < on_or_off - TRUE means that this surface will have the display mode set. FALSE means it will be unset.

Return values
sSuccess - operation was successful sFailure - unable to complete this operation sInvalidArgument - invalid display type. sInvalidObject - the surface is invalid

AlSurface | 897

AlTrimRegion* AlSurface::firstTrimRegion() const Description

Returns the first trim region of a list if the surface has been trimmed. Returns NULL if there is no such trim region. Use the methods in the AlNewTrimRegion class to get trim region information.

AlSurface* AlSurface::untrimmedToTrimmedSurface() const Description

Converts an untrimmed surface to a trimmed surface. NULL is returned if the function fails. The surface is attached to face and therefore may not be separately deleted. A deletion of the face will also force the deletion of the surface. Use the methods in the AlNewTrimRegion class to get trim region information.

AlTrimRegion* AlSurface::trimSurfaceToRegion() const Description

Converts a trim surface to a trim region. NULL is returned on failure. The surface is attached to face and therefore may not be separately deleted. A deletion of the face will also force a deletion of the surface. Use the methods in the AlNewTrimRegion class to get trim region information.

statusCode AlSurface::periodicToNonPeriodic( int u, int v ) Description

If a surface is periodic, converts it to a non-periodic surface (closed surface) by making it have multiple end knots in the selected direction (u/v). Note: This method modifies the surface.

Arguments
> u - change in u direction if u has the following value:

1 make left (u0) end multiple 0 make both (u) ends multiple 1 make right(un) end multiple

898 | Chapter 5 AlSet AlXEvents

> v - change in v direction if v has the following value:

-1 make left (v0) end multiple 0 make both (v) ends multiple 1 make right(vn) end multiple

Return Codes
sInvalidObject - the surface was invalid sFailure - the method didn't succeed sSuccess - the surface was converted to non-periodic one in the u/v direction

statusCode AlSurface::periodicToNonPeriodic( ) const Description

If a surface is periodic, converts it to a non-periodic surface (closed surface) by making it have multiple end knots at both endpoints in u/v. Note: This method modifies the surface.

Return Codes
sInvalidObject - the surface was invalid sFailure - the method didn't succeed sSuccess - the surface was converted to non-periodic one in both u and v directions

AlCurve* AlSurface::getModelSpaceSurfaceBoundary() const Description:

This method builds and returns the true 3D boundary curve. This methods builds an edge bspline for each edge of the surface, and appends each of them to the resulting curve. For example, a cylinder would return a singular curve of 4 bsplines: a line, a circle, a line and a circle. Restrictions:

AlSurface | 899

Edges are numbered counter-clockwise from ne = 0 to 3 where:

ne=0 at v=v0, ne=1 at u=un, ne=2 at v=vn, ne=3 at u=u0

Edges are numbered as follows:

0 = edge bspline is u0,v0 to u1,v0 1 = edge bspline is u1,v0 to u1,v1 2 = edge bspline is u1,v1 to u0,v1 3 = edge bspline is u0,v to u0,v0

The surface has multiple end knots in u and v. This method misses a bspline segment when an edge has no length (that is, at a pole).

AlCurve* AlSurface::getParamSpaceSurfaceBoundary() const Description

This methods builds a parameter space (2D) bspline for each edge of the surface, and appends each of them to the resulting 2D curve. Edges are numbered counter-clockwise from ne = 0 to 3 where
ne=0 ne=1 ne=2 ne=3 at at at at v=v0, u=un, v=vn, u=u0.

The surface has multiple end knots in u and v. This method builds and returns a singular 2D boundary curve.

AlCurve* AlSurface::localBoundary( int ne ) const Description

Returns the bspline resulting from an edge of a surface. The function extracts the surface 3D boundary bspline corresponding to the edge number ne (0-3). NULL is returned if the edge boundary cannot be found. Edges are numbered counter-clockwise 0 to 3 where:

900 | Chapter 5 AlSet AlXEvents

0 = bottom edge (v = 1 = right edge (u = 2 = top edge (v = 3 = left edge (u = edge 0 is at v0, edge 1 is at un, edge 2 is at un and edge 3 is at u0. ne=0 at v=v0, ne=1 at u=un, ne=2 at v=vn, ne=3 at u=u0.

*srf->node0->v) *srf->noden->u) *srf->noden->v) *srf->node0->u)

The surface has multiple end knots in u and v. This method handles a bspline segment when an edge has no length (that is, at a pole).

AlCurve* AlSurface::parameterBoundary( int ne ) const Description

Returns the parameter space bspline of an edge of a surface. NULL is returned if the edge boundary cannot be found. The function extracts the surface 2D boundary bspline corresponding to the edge number ne (0-3). Edges are numbered counter-clockwise 0 to 3 where: Edge 0 is at v0, edge 1 is at un, edge 2 is at vn and edge 3 is at u0. ne=0 at v=v0, ne=1 at u=un, ne=2 at v=vn, ne=3 at u=u0. The surface has multiple end knots in u and v.

statusCode AlSurface::trim( int count, const double u[], const double v[], boolean keepArea ) Description
This method applies the current curves on the surface to this surface. The surface can be trimmed already. See the descriptions for AlTrimRegion, AlTrimBoundary, and AlTrimCurve for a description of trim geometry. The surface must have a surface node for this method to succeed. A trim selector is a point in the region which is to be kept in the trim. The 'count' value must be greater than 1.

AlSurface | 901

Arguments
< count - number of (u,v) trim selectors < u,v - an array of u,v coordinates marking regions inside the trim to keep u an v are within the space of the surface < keepArea - if true, marked region is kept. Otherwise marked region isremoved.

statusCode AlSurface::trim( int count, const AlCurveOnSurface* uvTrimCurves[] ) Description

Applies the passed curves on the surface to this (untrimmed) surface. Each curve on surface must be a closed curve. The first curve in the array must by the outer boundary of a trim region. All other curves in the array are disjoint closed inner boundaries that do not intersect the outer boundary. See the descriptions for AlTrimRegion on page 976, AlTrimBoundary on page 964, and AlTrimCurve on page 968 for a description of trim geometry. The surface must have a surface node for this method to succeed.

Arguments
< count - number of AlCurveOnSurface curves (must be > 0) < uvTrimCurves - an array of closed AlCurveOnSurfaces that defines one trimmed region

Return code
sSuccess - a trim region was successfully created sInvalidArgument - one of the parameters is NULL or out of range sFailure - the trim operation failed sInvalidObject - the surface is invalid

AlSurface::reverseDirection( boolean inU, boolean inV ) Description

Reverse the direction of the surface

902 | Chapter 5 AlSet AlXEvents

Arguments
< inU - set to TRUE to reverse in the U direction < inV - set to TRUE to reverse in the V direction

Returns
sSuccess - the surface was reversed sInvalidObject - the surface is invalid sFailure - an error occurred

statusCode AlSurface::projectNormal( AlCurveNode* curveNode, boolean keep_history ) Description

This method projects a curve onto a surface.

Arguments
< curveNode - The curve to be projected onto the surface. < keep_history - Should the construction history be kept.

Return Codes
sSuccess - Successfully projected the curve. sInvalidObject - This surface is not valid. sInvalidArgument - The curve node is not valid, the vector is of zero length, or the surface has no parent surface node. sInsufficientMemory - Inadequate memory to run the command. sFailure - Failed to project the curve. {

AlSurface | 903

statusCode AlSurface::uniformRebuild( AlSurfaceNode* &newSurfaceNode, int requested_nu, int requested_nv, boolean inU, boolean inV, boolean matchParameterization ) Description
Approximate this rational surface with a uniform non-rational with a given number of spans. This is a "sample and fit" version of the reduction routine. Trim curves and curves on surface are copied and adjusted to the new surface. The parameters requested_nu/v specify the number of spans that are requested. If the matchParameterization flag is TRUE, then the reduced surface will be reparameterized to match the same parameter space as the original curve. Otherwise, the curve will be parameterized from 0 to the number of requested spans (in integer increments).

Arguments
> newSurfaceNode - the rebuilt copy of the surface < requested_nu - number of requested spans in the u direction < requested_nv - number of requested spans in the v direction < inU - rebuild in the U direction < inV - rebuild in the V direction < matchParameterization - preserve the parameterization space

Return code
sSuccess - the surface was successfully rebuilt sFailure - the rebuild operation failed sInvalidObject - the surface is invalid sInvalidArgument - both inU and inV were FALSE;

AlSurfaceCV
Encapsulates methods common to surface CVs.

904 | Chapter 5 AlSet AlXEvents

Synopsis
#include <AlSurfaceCV.h> class AlSurfaceCV : public AlObject , public AlClusterable , public AlAnimatable , public AlSettable , public AlPickable virtual ~AlSurfaceCV(); virtual AlObject* copyWrapper() const; AlObjectType type() const; int uIndex() const; int vIndex() const; AlSurfaceCV* nextInU() const; AlSurfaceCV* nextInV() const; AlSurfaceCV* prevInU() const; AlSurfaceCV* prevInV() const; statusCode nextInUD(); statusCode nextInVD(); statusCode prevInUD(); statusCode prevInVD(); int multiplicityInU() const; int multiplicityInV() const; statusCode worldPosition( double&, double&, double&, double& ) const; statusCode affectedPosition( const AlTM&, double&, double&, double&, double& ) const; statusCode unaffectedPosition( double&, double&, double&, double& ) const; statusCode setMultiplicity( int, int ); statusCode setWorldPosition( double, double, double, boolean ); statusCode setWorldPosition( double, double, double, AlTM ); statusCode setUnaffectedPosition( double, double, double, double ); AlSurface* surface() const; statusCode blindData( int, long&, const char *& ); statusCode setBlindData( int, long, const char * ); statusCode removeBlindData( int ); statusCode applyIteratorToCVsInU( AlIterator* iter, int &rc ); statusCode applyIteratorToCVsInV( AlIterator* iter, int &rc ); statusCode doUpdates( boolean newState = TRUE );

Description
AlSurfaceCV is the class used to access and manipulate surface CVs (also referred to as Control Points). There is one AlSurfaceCV object for each CV of

AlSurfaceCV | 905

an AlSurface as you see it in the interactive Alias package. You cannot create or delete an AlSurfaceCV. AlSurfaceCVs are only created through AlSurfaces. There are methods to query and set the multiplicity of a CV, and method to query the world position and the "unaffected" position of a CV. The "unaffected" position of a CV is its position BEFORE any transformations (from its parent DAG node or from affecting clusters) have been applied to it. There is also a method to access the clusters that affect a CV. Methods setWorldPosition are used for setting either the unaffected or affected(clusters) position of a CV. For more information on CVs please see AlCurveCV on page 337.

AlSurfaceCV::~AlSurfaceCV() Description
Deletes an AlSurfaceCV wrapper object.

AlObject* AlSurfaceCV::copyWrapper() const Description

Returns an exact duplicate of this AlSurfaceCV wrapper.

AlObjectType AlSurfaceCV::type() const Description

Returns the class identifier kSurfaceCVType.

int AlSurfaceCV::uIndex() const Description

Returns the index of this CV in the 'u' direction. Returns -1 if the CV is not valid. The indices of the first CV are (0,0).

int AlSurfaceCV::vIndex() const Description

Returns the index of this CV in the 'v' direction. Returns -1 if the CV is not valid. The indices of the first CV are (0,0).

906 | Chapter 5 AlSet AlXEvents

AlSurfaceCV* AlSurfaceCV::nextInU() const Description

Returns a pointer to the next AlSurfaceCV in the u direction. Otherwise, returns NULL if there is no next surface CV or the CV is inactive.

statusCode AlSurfaceCV::nextInUD() Description

Destructively points this wrapper to the next AlSurfaceCV in the u direction.

Return Codes
sSuccess - the wrapper points to the next CV sFailure - there is no next CV sInvalidObject - the CV is invalid/inaction

AlSurfaceCV* AlSurfaceCV::nextInV() const Description

Returns a pointer to the next AlSurfaceCV in the v direction. Otherwise, returns NULL if there is no next surface CV or the CV is inactive.

statusCode AlSurfaceCV::nextInVD() Description

Destructively points the wrapper to the next AlSurfaceCV in the v direction.

Return Codes
sSuccess - the wrapper points to the next CV sFailure - there is no next CV sInvalidObject - the CV is inactive/invalid

AlSurfaceCV | 907

AlSurfaceCV* AlSurfaceCV::prevInU() const Description

Returns a pointer to the previous AlSurfaceCV in the u direction. Otherwise, returns NULL if there is no previous surface CV or the CV is inactive.

statusCode AlSurfaceCV::prevInUD() Description

Destructively points the wrapper to the previous AlSurfaceCV in the u direction.

Return Codes
sSuccess - the wrapper points to the previous CV sFailure - there is no previous CV sInvalidObject - the CV is inactive / invalid

AlSurfaceCV* AlSurfaceCV::prevInV() const Description

Returns a pointer to the previous AlSurfaceCV in the v direction. Otherwise, returns NULL if there is no previous surface CV or the CV is inactive.

statusCode AlSurfaceCV::prevInVD() Description

Destructively points the wrapper to the previous AlSurfaceCV in the v direction.

Return Codes
sSuccess - the wrapper points to the previous CV sFailure - there is no previous CV sInvalidObject - the CV is inactive / invalid

908 | Chapter 5 AlSet AlXEvents

int AlSurfaceCV::multiplicityInU() const Description

Returns the multiplicity of this surface CV in the u direction. The returned value is always 1, 2 or 3. -1 is returned if the surfaceCV is invalid.

int AlSurfaceCV::multiplicityInV() const Description

Returns the multiplicity of this surface CV in the v direction. The returned value is always 1, 2 or 3. -1 is returned if the surfaceCV is invalid.

statusCode AlSurfaceCV::worldPosition( double &x, double &y,double &z, double &w) const Description
Returns the position of this surface CV in world space. This position includes the transformations of all DAG nodes above this surface and the effects of all clusters. Note that the position returned is [ x y z w ] and not [ w*x w*y w*z w ]. If the surface CV is no longer active no position is returned.

Arguments
> double &x - the world position in the x direction > double &y - the world position in the y direction > double &z - the world position in the z direction > double &w - homogeneous coordinate

Return Codes
sSuccess - the world position was retrieved sInvalidObject - the object was invalid sFailure - the surface CV is no longer active

AlSurfaceCV | 909

statusCode AlSurfaceCV::affectedPosition( const AlTM& tm, double &x, double &y,double &z, double &w) const Description
Returns the position of this surface CV modified by the AlTM. Note that the position returned is [ x y z w ] and not [ w*x w*y w*z w ]. If the surface CV is no longer active no position is returned.

Arguments
< AlTM& tm - the transformation matrix generated while walking the DAG > double &x - the world position in the x direction > double &y - the world position in the y direction > double &z - the world position in the z direction > double &w - homogeneous coordinate

Return Codes
sSuccess - the affected position was retrieved sInvalidObject - the object was invalid

statusCode AlSurfaceCV::unaffectedPosition( double &x, double &y,double &z, double &w ) const Description
Returns the position of this surface CV PRIOR TO ANY TRANSFORMATIONS (hence "unaffected"). How are the unaffected position and world position related? The world position is the unaffected position with the inclusive transformation of all DAG nodes above this surface applied to it AND the transformations of all affecting clusters applied to it (in proportion). If the surface CV is no longer active no position is returned.

Arguments
> double &x - the unaffected position in the x direction

910 | Chapter 5 AlSet AlXEvents

> double &y - the unaffected position in the y direction > double &z - the unaffected position in the z direction > double &w - homogeneous coordinate

Return Codes
sSuccess - the unaffected position was retrieved sInvalidObject - the object was invalid

statusCode AlSurfaceCV::setMultiplicity( int u, int v ) Description

Sets the multiplicity of this surface CV to the given multiplicity. The new multiplicity must be 1, 2, or 3. You cannot change the multiplicity of a corner CV of a surface that is open in either the u or v direction.

Arguments
< int u - the new multiplicity in the u direction < int v - the new multiplicity in the v direction

Return Codes
sSuccess - the multiplicity has been properly set sInvalidObject - the surface CV is no longer active / valid sInsufficientMemory - not enough memory sInvalidArgument - the multiplicities must be 1, 2 or 3 sFailure - the surface CV is no longer active

statusCode AlSurfaceCV::doUpdates( boolean newState ) Description

See AlDagNode on page 381.

AlSurfaceCV | 911

statusCode AlSurfaceCV::setWorldPosition( double x, double y, double z, boolean includeWorld ) Description

Sets the world position of the CV. The CV may be in a cluster.

Arguments
< double x - the new unaffected position in the x direction < double y - the new unaffected position in the y direction < double z - the new unaffected position in the z direction < boolean includeWorld - include world transformation in move

Return Codes
sSuccess - the position was properly set sFailure - the move could not be done sInvalidObject - the CV is invalid / inactive

statusCode AlSurfaceCV::setWorldPosition( double x, double y, double z, AlTM tm ) Description

Sets the world position of the CV. The CV may be in a cluster. Note that this method uses the inverse of the transformation matrix that is passed in so that the calling routine does not need to generate it.

Arguments
< double x - the new unaffected position in the x direction < double y - the new unaffected position in the y direction < double z - the new unaffected position in the z direction < AlTM tm - users transformation matrix

Return Codes
sSuccess - the position was properly set

912 | Chapter 5 AlSet AlXEvents

sFailure - the move could not be done sInvalidObject - the CV is invalid / inactive

statusCode AlSurfaceCV::setUnaffectedPosition( double x, double y,double z, double w ) Description

Sets the unaffected position of the CV.

Arguments
< double x - the new unaffected position in the x direction < double y - the new unaffected position in the y direction < double z - the new unaffected position in the z direction < double w - homogeneous coordinate

Return Codes
sSuccess - the position was properly set sFailure - the surface CV is no longer active sInvalidObject - the CV is invalid / inactive

AlSurface* AlSurfaceCV::surface() const Description

Returns a pointer to the AlSurface that this surface CV belongs to or NULL if the surface CV is no longer valid.

statusCode AlSurfaceCV::blindData( int user_type, long& size, const char *& data ) Description
Obtains the size and address of a block of data associated with the object. If there is no data, then the size will be zero and the address of the data is NULL. User_types between 0 and 13099 are reserved. If you would like to reserve a block of "user_types" please contact us.

AlSurfaceCV | 913

Arguments
< user_type - user type of the data desired > size - number of characters in the block of data > data - address of the block of data

Return Codes
sSuccess - the blind data was retrieved sInvalidObject - the object was invalid

statusCode AlSurfaceCV::setBlindData( int user_type, long size, const char * data ) Description
Associates a block of data with the object. If a block of data is already associated with this object and this user_type, the old block is replaced by a reference to the new block. The old block of data is not deleted.

Arguments
< user_type - user type of the blind data desired < size - number of characters in the block < data - address of the block of data

Return Codes
sSuccess - operation was successful sInsufficientMemory - not enough memory to allocate a new block sInvalidObject - the CV is invalid

statusCode AlSurfaceCV::removeBlindData( int user_type ) Description

Removes the block of data of the given type from the object. Note that the user is still responsible for the memory associated with this block of data.

914 | Chapter 5 AlSet AlXEvents

Arguments
< user_type - user type of the blind desired

Return Codes
sSuccess - operation was successful sFailure - no such blind data existed sInvalidObject - the given object is not valid

statusCode AlSurfaceCV::applyIteratorToCVsInU( AlIterator* iter, int &rc ) Description

Starting at this CV, apply the iterator to all CVs in the surface in the U direction. This iterator can be combined with the applyIteratorToCVsInV iterator to create a superiterator that iterates over all CVs in the surface.

AlSurfaceCV | 915

class iterV : public AlIterator { public: iterV( AlIterator* inIter ) : iter( inIter ) {}; virutal int func( AlObject* obj ) { int rc; if( sSuccess == obj->asSurfaceCVPtr()->applyIteratorToCVsInU( iter, rc ) ) return rc; else return -1; } private: AlIterator* iter; } .... statusCode applyIteratorToSurfaceCVs( AlSurface *surf, AlIterator* iter, int &rc ) { if( !iter || !surf ) return sInvalidArgument; iterV doV( iter ); AlSurfaceCV* cv = surface->firstCV(); statusCode stat = cv->applyIteratorToCVsInV( &doV, rc ); delete cv; return stat; }

See the documentation for AlIterator on page 544.

Arguments
< iter - the iterator to apply to each CV > rc - the result of the last application of the iterator

Return Codes
sSuccess - the iterator exited normally sFailure - the iterator exited abnormally sInvalidArgument - the iterator iter was NULL sInvalidObject - the curve was not valid

916 | Chapter 5 AlSet AlXEvents

statusCode AlSurfaceCV::applyIteratorToCVsInV( AlIterator* iter, int &rc ) Description

Starting at this CV, apply the iterator to all CVs in the surface in the V direction. See the documentation for AlIterator on page 544.

Arguments
< iter - the iterator to apply to each CV > rc - the result of the last application of the iterator

Return Codes
sSuccess - the iterator exited normally sFailure - the iterator exited abnormally sInvalidArgument - the iterator iter was NULL sInvalidObject - the iterator was not valid

AlSurfacePoint
Interface to Alias Surface points.

AlSurfacePoint | 917

Synposis
#include <AlSurfacePoint.h> class AlSurfacePoint : public AlPoint AlSurfacePoint(); ~AlSurfacePoint(); virtual AlObject * copyWrapper() const; virtual AlObjectType type() const; statusCode create(const AlSurface *, double, double); statusCode setParameter(double, double); statusCode parameter(double &, double &) const; virtual statusCode worldPosition(double &, double &, double &) const; statusCode uTangent(double &, double &, double &) const; statusCode vTangent(double &, double &, double &) const; statusCode normal(double &, double &, double &) const; statusCode meanRadius(double &) const; statusCode gaussianRadius(double &) const; statusCode principalMinimumRadius(double &) const; statusCode principalMaximumRadius(double &) const; statusCode uArcLength(double &) const; statusCode vArcLength(double &) const; AlSurfaceNode * attachedTo();

Description
A point can be created in the parametric space of any AlSurface. This point can be queried for the surface normal, tangents, position in world coordinate system, arc lengths, and curvatures. This class contains methods for creating, and moving the surface point. If the AlSurface is deleted, the surface point created on it is deleted.

AlSurfacePoint::AlSurfacePoint(void) Description
Constructs an AlSurfacePoint wrapper object.

AlSurfacePoint::~AlSurfacePoint() Description
Deletes an AlSurfacePoint wrapper object.

918 | Chapter 5 AlSet AlXEvents

AlObject *AlSurfacePoint::copyWrapper() const Description

Returns an exact copy of the AlSurfacePoint wrapper.

AlObjectType AlSurfacePoint::type() const Description

Returns the class identifier kSurfacePointType.

statusCode AlSurfacePoint::create(const AlSurface *surface, double u, double v) Description

Creates a point on the given surface

Arguments
< surface - the surface on which the point is created. < u - surface parameter at which point is created < v - surface parameter at which point is created

Return Codes
sSuccess - the point was successfully created sAlreadyCreated - object has already been created sFailure - failed to create a point sInvalidArgument - the surface was not valid

statusCode AlSurfacePoint::setParameter(double u, double v) Description

Move the point created on a surface.

Arguments:
< u, v - the parameters of the surface where the point has to be moved

AlSurfacePoint | 919

Return Codes
sSuccess - the point was moved sInvalidObject - the point is not valid

statusCode AlSurfacePoint::parameter(double &u, double &v) const Description

Find the surface parameters at where the surface point is located

Arguments
> u, v - the U and V parameters of the surface.

Return Codes
sSuccess - the parameters were found sInvalidObject - the point is not valid

statusCode AlSurfacePoint::worldPosition(double &x, double &y, double &z) const Description

Find the world coordinates of the surface point

Arguments
> x, y, z - the world coordinates of the surface point

Return Codes
sSuccess - the coordinates were found. sInvalidObject - the point is not valid

statusCode AlSurfacePoint::uTangent(double &x, double &y, double &z) const Description

Find the tangent to the surface at the point in the U direction.

920 | Chapter 5 AlSet AlXEvents

Arguments
> x, y, z - the X, Y, Z components of the normalized tangent

Return Codes
sSuccess - the tangent was found. sInvalidObject - the point is not valid

statusCode AlSurfacePoint::vTangent(double &x, double &y, double &z) const Description

Find the tangent to the surface at the point in the V direction.

Arguments
> x, y, z - the X, Y, Z components of the normalized tangent

Return Codes
sSuccess - the tangent was found. sInvalidObject - the point is not valid

statusCode AlSurfacePoint::normal(double &x, double &y, double &z) const Description

Find the normal to the surface at the point.

Arguments
> x, y, z - the X, Y, Z components of the normalized normal

Return Codes
sSuccess - the normal was found. sInvalidObject - the point is not valid

AlSurfacePoint | 921

statusCode AlSurfacePoint::meanRadius(double &meanRad) const Description

Find the mean of the principal radii of the surface at the point.

Arguments
> meanRad - The mean radius of the surface

Return Codes
sSuccess - the mean radius was found. sInvalidObject - the point is not valid

statusCode AlSurfacePoint::gaussianRadius(double &gausRad) const Description

Find the product of the principal radii of the surface at the point.

Arguments
> gausRad - The gaussian radius of the surface at the point

Return Codes
sSuccess - the gaussian radius was found. sInvalidObject - the point is not valid

statusCode AlSurfacePoint::principalMinimumRadius(double &pminRad) const Description

Find the minimum radius of the curves on the surface, which pass through the point.

Arguments
> pminRad - The principal minimum radius of the surface

922 | Chapter 5 AlSet AlXEvents

Return Codes
sSuccess - the radius was found. sInvalidObject - the point is not valid

statusCode AlSurfacePoint::principalMaximumRadius(double &pmaxRad) const Description

Find the maximum radius of the curves on the surface, which pass through the point.

Arguments
> pmaxRad - The principal maximum radius of the surface

Return Codes
sSuccess - the radius was found. sInvalidObject - the point is not valid

statusCode AlSurfacePoint::uArcLength(double &uarcLen) const Description

Find the arc length along U tangent at the point on the surface.

Arguments
> uarcLen - The arc length along U tangent

Return Codes
sSuccess - the arc length was found. sInvalidObject - the point is not valid

statusCode AlSurfacePoint::vArcLength(double &varcLen) const Description

Find the arc length along V tangent at the point on the surface.

AlSurfacePoint | 923

Arguments
> varcLen - The arc length along V tangent

Return Codes
sSuccess - the arc length was found. sInvalidObject - the point is not valid

AlSurfaceNode * AlSurfacePoint::attachedTo() Description

Returns the surface node that this point is associated with. NULL is returned if this method fails.

AlSurfaceNode
Dag node class for NURBS surfaces.

Synopsis
#include <AlSurfaceNode.h> class AlSurfaceNode : public AlDagNode AlSurfaceNode(); virtual ~AlSurfaceNode(); virtual AlObject* copyWrapper() const; statusCode create( AlSurface * ); virtual AlObjectType type() const; AlSurface* surface() const; AlSurface* surface(AlTM&) const; int curvePrecision() const; statusCode setCurvePrecision( int precision ); int patchPrecision() const; statusCode setPatchPrecision( int precision );

Description
AlSurfaceNode is the class used to access and manipulate surfaces within the DAG. This class behaves like other DAG nodes (see AlDagNode on page 381 for a description of the usage and purpose of DAG nodes) and in addition

924 | Chapter 5 AlSet AlXEvents

allows users to add curves on surfaces and access the geometry of the surface via the surface() method. The surface() method returns a pointer to an AlSurface object, which provides the user with the methods used to modify the geometry of the surface. Surfaces can be created from scratch by calling the AlSurfaceNode::create() method, or read in from a wire file (see AlUniverse on page 993 documentation).

AlSurfaceNode::AlSurfaceNode() Description
Constructs an AlSurfaceNode wrapper object.

AlSurfaceNode::~AlSurfaceNode() Description
Deletes an AlSurfaceNode wrapper object.

AlObject* AlSurfaceNode::copyWrapper() const Description

Returns an exact duplicate of this AlSurfaceNode wrapper.

statusCode AlSurfaceNode::create( AlSurface *newSurface ) Description

Allocates the DAG node and geometry required for this object. This method must be called once and only once before any other method and only if the surface has been allocated by the user (that is, not read in from a wire file). It is an error to call this method twice or if the object has been read in from a wire file.

Arguments
< newSurface - the surface to create this surface node for

Return Codes
sSuccess - the surface node was created sInvalidArgument - newSurface was NULL or invalid

AlSurfaceNode | 925

sFailure - the surface node was not created

AlObjectType AlSurfaceNode::type() const Description

Returns the class identifier kSurfaceNodeType.

AlSurface* AlSurfaceNode::surface() const Description

Returns a pointer to the surface data structure which can be used to access the geometry of the surface.

AlSurface* AlSurfaceNode::surface(AlTM& tm) const Description

Returns a pointer to the surface data structure that can be used to access the geometry of the surface. The AlTM will be updated with the groupNodes TM if a childNode exists.

Arguments
< tm - the AlTM to update with the group nodes TM

int AlSurfaceNode::curvePrecision() const Description

Obtains the curve precision for the surface. -1 is returned if the surface is invalid.

statusCode AlSurfaceNode::setCurvePrecision( int precision ) Description

Sets the curve precision for the surface.

Arguments
< precision - the new curve precision (range is 1-129)

926 | Chapter 5 AlSet AlXEvents

Return code
sSuccess - the curve precision was set sInvalidArgument - value for curve precision was invalid sInvalidObject - the surface node was invalid

int AlSurfaceNode::patchPrecision() const Description

Obtains the patch precision for the surface. -1 is returned if the surface is invalid.

statusCode AlSurfaceNode::setPatchPrecision( int precision ) Description

Sets the patch precision for the surface.

Arguments
< precision - the new patch precision (range is 2-64)

Return code
sSuccess - the patch precision was set sInvalidArgument - value for patch precision was invalid sInvalidObject - the surface node was invalid

AlTesselate
Methods to tesselate geometry.

AlTesselate | 927

Synopsis
#include <AlTesselate.h> class AlTesselate static statusCode uniform( AlDagNode* &, const AlDagNode*, AlTesselateTypes = kTESSELATE_TRIANGLE, int = 2, int = 2); static statusCode adaptive(AlDagNode* &, const AlDagNode*, AlTesselateTypes = kTESSELATE_TRIANGLE, int = 2, int = 4, double = 0.6, int = 2); static statusCode number(AlDagNode* &, const AlDagNode*, AlTes selateTypes = kTESSELATE_TRIANGLE, int = 512, int = 32, double = 0.001); static statusCode rendererSettings( AlDagNode* &, const AlDagNode*, AlTesselateTypes = kTESSELATE_TRIANGLE ); static statusCode chordHeightDeviation( AlDagNode * &, const AlDagNode*, double tolerance = .01 ); static statusCode chordHeightDeviationFast( AlDagNode * &, const AlDagNode*, double tolerance = .01 ); static statusCode chordHeightDeviationAccurate( AlDagNode * &, const AlDagNode*, double tolerance = .01 );

Description
This is a static class in that all of its member functions are static. It provides the functionality to tesselate geometry. The methods in this library will generate polysets or meshes from the geometry directly below the AlDagNode. Meshes are composed entirely out of triangles. Polysets can be composed of either triangles or quadrilaterals based on the type argument to the method (either kTESSELATE_TRIANGLE or kTESSELATE_QUADRILATERAL). Note that when tesselating a trimmed surface, some triangles may be created along the trim edge even though quadrilateral tesselation was selected. NOTE The first five methods generate polysets and are now deprecated. We recommend using only the last two methods which produce mesh objects, the only polygonal object type now recognized by Alias.

statusCode AlTesselate::uniform( AlDagNode* &outdag, const AlDagNode* dagNode, AlTesselateTypes type, int alongU, int alongV ) Description
This method causes the geometry below the AlDagNode to be subdivided into polygons in a uniform manner. That is, each spline patch will be converted

928 | Chapter 5 AlSet AlXEvents

into a fixed number of polygons. This method should not be used on trimmed geometry as it will fail; instead, you should use the adaptive method below.

Arguments
>> outdag - The resulting dagnode for a polyset. < dagNode - The AlDagNode above the geometry to tesselate. < type - kTESSELATE_TRIANGLE or kTESSELATE_QUADRILATERAL. < alongU - The number of subdivisions in the U direction (minimum of 1). < alongV - The number of subdivisions in the V direction (minimum of 1).

Return Codes
sSuccess - Tesselation succeeded. sInvalidArgument - An argument was NULL or alongU or alongV was less than 1. sFailure - Tesselation failed.

statusCode AlTesselate::adaptive( AlDagNode* &outdag, const AlDagNode* dagNode, AlTesselateTypes type, int min, int max, double threshold, int uniformUV ) Description
This method causes geometry below the AlDagNode to be subdivided into polygons depending on the curvature of the surface. Each spline patch will be converted into the minimum allowable number of polygons that satisfy the threshold parameter. If the threshold can not be satisfied by subdividing within the maximum number of subdivisions then the maximum subdivisions value will be used. When converting face nodes, adaptive subdivision cannot be used. Uniform subdivision is used with a spacing of 'uniformUV'.

Arguments
>> outdag - The resulting dagnode for a polyset. < dagNode - The AlDagNode above the geometry to tesselate. < type - kTESSELATE_TRIANGLE or kTESSELATE_QUADRILATERAL. < min - The minimum number of times the surface will be subdivided meet the threshold (minimum of 1 ).

AlTesselate | 929

< max - The maximum number of times the surface will be subdivided meet the threshold (minimum of 1 ). < threshold - The accuracy of the approximation (between 0 and 1). Higer values give a better approximations. < uniformUV - Uniform value used when handing FaceNodes.

Return Codes
sSuccess - Tesselation succeeded. sInvalidArgument - An argument was NULL or min or max was less than 1 or threshold was not in 0..1. sFailure - Tesselation failed.

statusCode AlTesselate::number( AlDagNode* &outdag, const AlDagNode* dagNode, AlTesselateTypes type, int total, int count_tol, double curve_tol) Description
This method repeatedly tesselates the surfaces with different adaptive subdivision parameters until settings are found that produce a total polygon count close to the requested number. If the requested polygon count cannot be satisfied within the given search tolerance, this function will return either the closest tesselation found that is below the requested total or the minimum number of polygons that it can possibly create. Unlike the interactive method there is no way to abandon this process prematurely. Since the number of polygons that a spline surface may be tesselated into is not a continuous function it may not be possible to achieve the desired number of polygons exactly. To prevent the search from continuing infinitely, there are tolerances that limit the tesselation. When a test tesselation finds parameter settings that give a polygon count that is between total - count_tol and total + count_tol the search is stopped. Further since it may not be possible to find a tesselation that satisfies the requested total within the given count tolerance this parameter allows the search to be ended when the changes the function makes to the adaptive subdivision curvature threshold parameter falls below curve_tol.

Arguments
>> outdag - The resulting dagnode for a polyset. < dagNode - The AlDagNode above the geometry to tesselate.

930 | Chapter 5 AlSet AlXEvents

< type - kTESSELATE_TRIANGLE or kTESSELATE_QUADRILATERAL. < total - The number of polygons desired (minimum of 1 ). < count_tol - How close to the total is acceptable (minimum of 0). < curve_tol - The adaptive subdivision tolerance (between 0 and 1). Lower values give a better approximation.

Return Codes
sSuccess - Tesselation succeeded. sInvalidArgument - NULL argument or total < 1, count_tol < 0, or curve_tol was not in 0..1. sFailure - Tesselation failed.

statusCode AlTesselate::rendererSettings( AlDagNode* &outdag, const AlDagNode* dagNode, AlTesselateTypes type ) Description
This method causes the geometry below the AlDagNode to be subdivided into polygons in according to the current AlRender parameters.

Arguments
>> outdag - The resulting dagnode for a polyset. < dagNode - The AlDagNode above the geometry to tesselate. < type - kTESSELATE_TRIANGLE or kTESSELATE_QUADRILATERAL.

Return Codes
sSuccess - Tesselation succeeded. sInvalidArgument - An argument was NULL. sFailure - Tesselation failed.

AlTesselate | 931

statusCode AlTesselate::chordHeightDeviation( AlDagNode* &outdag, const AlDagNode* dagNode, double tolerance ) Description
This method tessellates a dag using a chord height deviation tolerance. The chord height deviation specifies the maximum distance that a triangle will be away from the surface boundary that it will be representing.

Arguments
>> outdag - The resulting dagnode for a polyset. < dagNode - The dag node to triangulate. < tolerance - Chord height deviation.

Return Codes
sSuccess - Tesselation succeeded. sInvalidArgument - An argument was NULL or 'dagNode' is an invalid wrapper. sFailure - Tesselation failed.

statusCode AlTesselate::chordHeightDeviationFast( AlDagNode* &outdag, const AlDagNode* dagNode, double tolerance ) Description
This method tessellates a dag node using a chord height deviation tolerance and the fast tessellator. The chord height deviation specifies the maximum distance that a triangle will be away from the surface boundary that it will be representing.

Arguments
>> outdag - The resulting dagnode for a mesh. < dagNode - The dag node to triangulate. < tolerance - Chord height deviation.

Return Codes
sSuccess - Tesselation succeeded.

932 | Chapter 5 AlSet AlXEvents

sInvalidArgument - An argument was NULL or 'dagNode' is an invalid wrapper. sFailure - Tesselation failed.

statusCode AlTesselate::chordHeightDeviationAccurate( AlDagNode* &outdag, const AlDagNode* dagNode, double tolerance ) Description
This method tessellates a dag node using a chord height deviation tolerance and the accurate tesselator. The chord height deviation specifies the maximum distance that a triangle will be away from the surface boundary that it will be representing.

Arguments
>> outdag - The resulting dagnode for a mesh. < dagNode - The dag node to triangulate. < tolerance - Chord height deviation.

Return Codes
sSuccess - Tesselation succeeded. sInvalidArgument - An argument was NULL or 'dagNode' is an invalid wrapper. sFailure - Tesselation failed.

AlTexture
Base object for representing texture data.

AlTexture | 933

Synopsis
#include <AlTexture.h> class AlTexture : public AlObject, virtual ~AlTexture(); virtual statusCode deleteObject(); virtual AlObject *copyWrapper() const; virtual AlObjectType type() const; virtual const char* name() const; virtual statusCode setName(const char *); AlTexture* firstTexture() const; AlTexture* nextTexture( const AlTexture* ) const; statusCode nextTextureD( AlTexture* ); const char* textureType() const; const char* fieldType() const; statusCode parameter( const AlShadingFields, double& ) const; statusCode setParameter( const AlShadingFields, const double ); /* this section is only for file textures */ const char* filename() const; statusCode setFilename( const char* ); const char* firstPerObjectPixEntry(); const char* nextPerObjectPixEntry( const char *); const char* getPerObjectPixFilename( const char*) const; statusCode setPerObjectPixFilename( const char*, const char*); statusCode addPerObjectPixEntry( const char*, const char*); statusCode removePerObjectPixEntry( const char* ); boolean isParametric( void ) const; statusCode eval( double, double, double, double, double, double, double, double, double, double, double*, double*, double*, double*, boolean = TRUE, double = 1.0, double = 0.0, char *objectname = NULL ) const; AlList* fields() const; AlList* mappedFields() const; statusCode addTexture( const char*, const char*, AlTexture** re turnedTexture = NULL ); statusCode removeTexture( const char* ); AlTextureNode* textureNode() const; statusCode applyIteratorToTextures( AlIterator*, int& ); /* for environment textures only */ statusCode environmentPixMap( AlPixel *, int, boolean );

934 | Chapter 5 AlSet AlXEvents

Description
Encapsulates the basic functionality for checking and setting the name of a texture as well as accessing the textures that this texture refers to, and the animation on this texture. These texture objects can be obtained from the AlShader class and the AlEnvironment class. A texture object itself may also reference other textures. For this reason the firstTexture() and nextTexture() methods are used. firstTexture() returns the first texture that the texture object references. nextTexture() moves from a given referenced texture to the next texture in order, as related to the texture object. (See the similar methods for the AlShader on page 816/AlEnvironment on page 458 classes.) The animation on a texture can be accessed through the firstChannel() and nextChannel() methods. All the channels on the texture can be deleted by calling deleteAnimation(). The texture parameters can be accessed through the parameter() and setParameter() methods. Each texture has a specific set of parameters that are valid for it that depend on its type. The full list of texture parameters can be seen in the file AlShadingFields.h. For example, all parameters specific to the water texture have names of the form kFLD_SHADING_WATER_*. Parameters common to all textures have the form kFLD_SHADING_COMMON_TEXTURE_*. All parameters are treated as doubles even though this may not necessarily be what they are. This was done to make the interface as simple and consistent as possible. New AlTextures cannot be created by allocating a new AlTexture object because an AlTexture must be associated with a shader. Use the AlShader::addTexture() method to create the new AlTexture.

AlTexture::~AlTexture() Description
Deletes an AlTexture wrapper object.

statusCode AlTexture::deleteObject() Description

Deletes the AlTexture and the AlTextures hanging off of the texture. If an AlTextureNode is attached to this texture, it will be deleted as well. Note that

AlTexture | 935

after this operation any pointers to AlTextures that had been part of this texture will no longer be valid.

Return Codes
sSuccess - the object was deleted sInvalidObject - the object is invalid sFailure - the object could not be deleted

AlObject *AlTexture::copyWrapper() const Description

Returns an exact duplicate of this AlTexture wrapper.

AlObjectType AlTexture::type() const Description

Returns the class identifier kTextureType.

const char* AlTexture::name() const Description

Returns the name of the texture.

statusCode AlTexture::setName( const char *newName ) Description

Changes the name of the texture to a new name. If the given name is not a unique one or contains illegal characters, then a unique name is generated based on the given name and assigned to the texture. In this case, a status code of sNameChangedToUniqueOne is returned. It is illegal for the new name to be NULL. #, digits, upper case letters, lower case letters, and _ are valid characters

Arguments
< newName - new name of the object

936 | Chapter 5 AlSet AlXEvents

Return Codes
sSuccess - name was changed sFailure - the name was not set sInvalidArgument - the name was NULL sInvalidObject - the texture is invalid sNameChangedToUniqueOne - name was changed to be a unique version of the given name

AlTexture* AlTexture::firstTexture() const Description

Returns the first texture that this texture object references. If there are none then NULL is returned.

AlTexture* AlTexture::nextTexture( const AlTexture* last_texture ) const Description

Returns the texture after the given one in the textures list of subtextures. Specifying NULL as a parameter will return the first texture.

Arguments
< last_texture - Texture from which to walk forward

statusCode AlTexture::nextTextureD( AlTexture* last_texture ) Description

Destructively points the given texture wrapper to the next texture.

Arguments
< last_texture - texture from which to walk forward

Return Codes
sSuccess - the wrapper now points to the next object in the list sFailure - there is no next texture

AlTexture | 937

sInvalidObject - the texture is invalid sInvalidArgument - the given texture is invalid

const char* AlTexture::textureType() const Description

Returns a string which indicates the "name" of the texture type. Note that these strings are identical to those output to SDL.

const char* AlTexture::fieldType() const Description

Returns a string which indicates which field of the parent object (AlShader, AlTexture, AlEnvironment) that this texture is mapped to. Note that the returned strings are identical to the field names written out to SDL. The SDL manual gives a complete list of possible return values for this function.

statusCode AlTexture::parameter( const AlShadingFields field,double& result)const Description

Finds the value of a given texture field.

Arguments
< field - texture field type > result - returned result of the field

Return Codes
sSuccess - field was returned sInvalidArgument - field was not legal for this texture sFailure - field could not be returned sInvalidObject - the texture is invalid

938 | Chapter 5 AlSet AlXEvents

statusCode AlTexture::setParameter( const AlShadingFields field,const double value) Description

Changes the value of the texture field.

Arguments
< field - texture field type < value - new value that the texture field is to take

Return Codes
sSuccess - field was changed sInvalidArgument - field was not legal for this texture sFailure - field could not be changed sInvalidObject - the texture is invalid

const char* AlTexture::filename() const Description

If the texture is a file texture, this method returns the path and name to the image file used for the texture. If the texture is any other type, NULL is returned.

statusCode AlTexture::setFilename(const char* filename) Description

If the texture is a file texture, this method sets the path and name to the image file used for the texture. If the texture is any other type, sFailure is returned. Note that the string provided is duplicated, so you are responsible for the space allocated for the original copy.

Arguments
< filename - the filename to set in the texture

AlTexture | 939

Return Codes
sSuccess - the path name was set sFailure - the name was not set sInvalidObject - the texture is invalid

const char* AlTexture::firstPerObjectPixEntry() Description

If the texture is a file texture, this method returns the name of the first object in the Per Object Pix list of the file texture. If the list is empty, or if the texture is not a file texture, then NULL is returned.

const char* AlTexture::nextPerObjectPixEntry( const char* prev_objname ) Description

If the texture is a file texture and the objname is in the per object pix file list of the texture, this method returns the name of the next object after prev_objname. If no such object exists, or if the texture is not a file texture, then NULL is returned.

const char* AlTexture::getPerObjectPixFilename( const char* objname ) const Description

If the texture is a file texture and the objname is in the "per object pix file" list of the texture, this method returns the image file used for the objname object (object meaning an Alias geometry). If the object is not in the list, then the image file used will be AlTexture::filename() which contains the texture that is applied to all objects that are not specifically mentioned in the "per object pix file" list. If the return value of getPerObjectPixFilename() is NULL, then the object is not textured.

Arguments
< objname - the name of the object to query for a filename

940 | Chapter 5 AlSet AlXEvents

statusCode AlTexture::setPerObjectPixFilename( const char* objname,const char* filename ) Description

If the texture is a file texture and the objname exists in the per obj pix list, this method sets the name of the image file use for that object (object in the sense of an Alias geometry). Otherwise, sFailure is returned (not file texture or object doesnt exist). The filename string is duplicated, so you are responsible for the space allocated for the original copy

Arguments
< objname - name of the object whose filename is to be set < filename - the name of the image to fill objnames filename field

Return Codes
sSuccess - the path name was set sFailure - the name was not set sInvalidObject - the texture is invalid

statusCode AlTexture::addPerObjectPixEntry( const char* objname,const char* filename ) Description

If the texture is a file texture, this method adds a per object pix entry to the texture. If the texture is any other type, sFailure is returned. If the objname object is not already in the per object pix entry list, it is added. If the objname object does exist in the list, its filename field is modified to contain the given filename.

Arguments
< objname - name of the object whose filename is to be set < filename - the name of the image to fill objnames filename field

Return Codes
sSuccess - the path name was set

AlTexture | 941

sFailure - the name was not set sInvalidObject - the texture is invalid

statusCode AlTexture::removePerObjectPixEntry( const char* objname ) Description

If the texture is a file texture and the objname object is found in the per object pix list, this method will delete that item from the per object pick list. If the texture is not a file texture, sFailure is returned.

Arguments
< objname - specifies the name of the object in the per object pix list to delete

Return Codes
sSuccess - the path name was set sFailure - the name was not set sInvalidObject - the texture is invalid

boolean AlTexture::isParametric() const Description

Indicates whether the texture is a parametric texture or a solid/environment texture. TRUE is returned if the texture is parametric.

AlList* AlTexture::fields() const Description

Returns an AlList of AlShadingFieldItems, each of which contains an AlShadingFields value valid for this texture.

AlList* AlTexture::mappedFields() const Description

Returns an AlList of AlMappedFieldItems, each of which contains a character string identifier identifying a field on this texture that may be texture mapped.

942 | Chapter 5 AlSet AlXEvents

Note that these strings are identical to the SDL identifiers and the complete list can be found in the SDL manual.

statusCode AlTexture::removeTexture( const char* fieldName ) Description

Removes a texture to a particular field of the AlTexture. The first argument is the name of the field that will have the texture applied to it. Only those fields valid for this texture should be provided; any others will cause this method to fail. Valid fields are any returned by the fields() method.

Arguments
< fieldName - name of the field which will have the texture removed from it

Return Codes
sSuccess - the texture was removed successfully sFailure - there was no texture on the field sInvalidObject - the texture is invalid sCannotDelete - a texture already existed on the field which could not be deleted sInvalidArgument - the argument was not valid for the texture

statusCode AlTexture::addTexture( const char* fieldName, const char* textureName, AlTexture** returnCreatedTexture ) Description
Adds a texture to a particular field of the AlTexture. The first argument is the name of the field which will have the texture applied to it. Only those fields valid for this texture should be provided, any others will cause this method to fail. Valid fields are any returned by the fields() method. The second argument is the name of the texture type to apply to the field. The complete list of names is available in the SDL manual.

Arguments
< fieldName - name of the field which will have the texture applied to it < textureName - name of the texture type to apply to the field

AlTexture | 943

> returnCreatedTexture - if not NULL, then the created texture is returned

Return Codes
sSuccess - the texture was added successfully sFailure - the texture was not added sInvalidObject - the texture is invalid sCannotDelete - a texture already existed on the field which could not be deleted sInvalidArgument - either argument was not valid for the texture

AlTextureNode* AlTexture::textureNode() const Description

Returns a pointer to the transformation AlTextureNode on solid textures. If the texture is not a solid texture or there is no AlTextureNode, this method returns NULL.

statusCode AlTexture::eval( double u, double v, double x, double y, double z, double nx, double ny, double nz, double usize, double vsize, double *r, double *g, double *b, double *a, boolean initialize, double blurmult, double bluroffset, char *objectname ) const Description
Evaluates a texture at the passed location. The initialize flag specifies whether the texture transforms should be initialized. Note that this is a costly operation, so initialize only when necessary, generally on the first call. This routine allows you to find out for a given location what color the texture would return if that location was shaded by the renderer. The location of the color is specified by either u, v coordinates in parametric space for a 2D texture, or x, y, z coordinates in world space for a 3D texture As some textures also require the normal at that point to be provided the user supplies the normal in the nx, ny, and nz fields. The usize and vsize are used to express the extent of the point in parametric space. This has the effect of blurring the texture with larger usize,vsize. The value is returned in *r, *g, *b, *a. This is a color value. The *r, *g, *b, *a values should be set before calling Eval to the color you wish returned if the texture is not to be applied (for instance if the texture alpha value is 0).

944 | Chapter 5 AlSet AlXEvents

The blurmult and bluroffset fields specify the amount of blurring to apply to the texture as per the controls in the interactive package. The object name field is used to determine which texture should be used in file type textures that have more than one specific object/texture file pair. These textures may typically be created using Alias paint features.

Arguments
< u, v - specify the parametric location at the evaluated point < x, y, z - specify the world space location at the evaluated point < nx, ny, nz - specify the normal at the evaluated point < usize, vsize - specify the parametric extent of the point < > *r, *g, *b, *a - will contain the resultant color < initialize - initialize this texture. Must be initialized before first use. < blurmult - how much to blur the sample by < bluroffset - how much to offset the blur by < objectname - optionally, the name of the object being textured. Used to texture objects using file textures with per object texture maps.

Return Codes
sSuccess - the texture was evaluated successfully sFailure - the texture was not evaluated sInvalidObject - the texture is invalid sInvalidArgument - one of the pointer arguments was NULL

statusCode AlTexture::applyIteratorToTextures( AlIterator *iter, int &rc ) Description

Applies the given AlIterator to all textures in the texture. The second argument will be set to the return value of the last application of the iterators function. See the AlIterator on page 544 class for more information.

Arguments
< iter - a pointer to the iterator

AlTexture | 945

> rc - the result of the last application of the iterator

Return Codes
sSuccess - the application of the iterator terminated normally sFailure - the application of the iterator terminated abnormally sInvalidArgument - the iterator was NULL sInvalidObject - the texture is invalid

statusCode AlTexture::environmentPixMap( AlPixel *pixArray, int resolution, boolean imageMap ) Description:

Converts an environment texture to a square pix map. The AlPixel structure can be used in conjunction with the AlPixFile class to output the pix file. Note: if this texture is not an environment map, this method will fail.

Arguments:
< pixArray - AlPixel array of size resolution * resolution < resolution - row/column size of the pix array < imageMap -

Return Codes:
sSuccess - the pix array was set sFailure - internal failure sInvalidArgument - pixArray is NULL or resolution < 0 sInvalidObject - the texture is invalid

AlTextureNode
Dag node class for solid textures.

946 | Chapter 5 AlSet AlXEvents

Synopsis
#include <AlTextureNode.h> class AlTextureNode : public AlDagNode virtual AlObjectType type() const; virtual AlObject* copyWrapper() const; virtual ~AlTextureNode(); virtual boolean isInstanceable(); AlTexture* texture() const; AlTexture* texture(AlTM&) const;

Description
AlTextureNode is the class used to access and manipulate the transformations on solid textures within the DAG. This class behaves like other DAG nodes (see AlDagNode on page 381 for a description of the usage and purpose of DAG nodes) except that you are not able to instantiate or create one.

AlTextureNode::~AlTextureNode() Description
Deletes an AlTextureNode wrapper object.

AlObject* AlTextureNode::copyWrapper() const Description

Returns an exact duplicate of this AlTextureNode.

AlObjectType AlTextureNode::type() const Description

Returns the class identifier kTextureNodeType.

boolean AlTextureNode::isInstanceable() Description

Returns FALSE. An AlTextureNode is not an instanceable DAG node.

AlTextureNode | 947

AlTexture* AlTextureNode::texture() const Description

Returns a pointer to the texture data structure which can be used to access the geometry of the texture. Returns NULL if this object is invalid or if there is no texture attached to this node.

AlTexture* AlTextureNode::texture(AlTM& tm) const Description

Returns a pointer to the texture data structure that can be used to access the fields of the texture. The AlTM will be updated with the textureNodes TM.

Arguments
> tm - the transformation matrix to be updated

AlTM
Basic Interface to Alias transformation matrix.

948 | Chapter 5 AlSet AlXEvents

Synopsis

AlTM | 949

#include <AlTM.h> class AlTM inline AlTM() ; inline ~AlTM() ; AlTM( const AlTM& ); AlTM( const double[4][4] ); AlTM( const double d0,const double d1,const double d2,const double d3 ); inline double* operator []( int row ) inline const double* operator []( int row ) const statusCode getTM( double[4][4] ) const; statusCode setTM( const double[4][4] ); AlTM& operator =( const AlTM& ); AlTM& operator =( const double d ); int operator ==( const AlTM& ) const; int operator !=( const AlTM& ) const; AlTM operator +( const AlTM& ) const; AlTM operator -( const AlTM& ) const; AlTM operator *( const AlTM& ) const; AlTM operator *( const double ) const; friend AlTM operator *( const double d, const AlTM& tm ); AlTM& operator +=( const AlTM& ); AlTM& operator -=( const AlTM& ); AlTM& operator *=( const AlTM& ); AlTM& operator *=( const double ); statusCode transPoint( double d[4] ) const; statusCode transPoint( const double pt[4], double transPt[4] ) const; statusCode transPoint( double& x, double &y, double &z, double &w ) const; statusCode transPoint( double& x, double &y, double &z ) const; // assumes w = 1.0 statusCode transVector( double& x, double& y, double& z ) const; statusCode transNormal( double& x, double& y, double& z ) const; statusCode decompose ( double [3], double [3], double [3], double [3] ) const; AlTM inverse( void ) const; AlTM transpose( void ) const; static AlTM identity( void ); static AlTM zero( void ); static AlTM diagonal( const double d0, const double d1, const double d2, const double d3 ); // standard transformations

950 | Chapter 5 AlSet AlXEvents

static static ); static ); static static static static

AlTM scale( const double ); AlTM scale_nonp( const double, const double, const double AlTM translate( const double, const double, const double AlTM AlTM AlTM AlTM rotateX( const rotateY( const rotateZ( const rotate( double double ); double ); double ); x, double y, double z, double angle );

Description
This class encapsulates the functionality for creating, manipulating and deleting Alias 4x4 transformation matrices. Transformation matrices are used to do linear transformations of a vector. Composite transformations are done by multiplying the individual transformations together. The matrix is ordered as AlTM[y][x]:
0,0 1,0 2,0 3,0 0,1 1,1 2,1 3,1 0,2 1,2 2,2 3,2 0,3 1,3 2,3 3,3

The transformation matrix usually takes the form:

TM | | | = | r00 r01 r02 0 | r10 r11 r12 0 | r20 r21 r22 0 | tx0 ty0 tz0 1 |

where tx0, ty0, tz0 are the aggregate translations and r(xy) is the aggregate product of rotations, scales and shears. A point is transformed by considering the point to be a row vector of 4 elements and then post multiplying by the transformation matrix.
[x y z w] = [x y z w] | 10 11 12 13 | | 20 21 22 23 | | 30 31 32 33 | | 00 01 02 03 |

If the w component is not specified, it is assumed to have a value of 1.

AlTM | 951

The static functions at the end of the class are used to create typical transformation matrices. Note: the [] operator has been defined for the AlTM class. This means that the individual matrix elements can be addressed as if the AlTM were a standard 4x4 array of doubles. This eliminates the need to create a temporary 4x4 array to retrieve the values.
for example, AlTM matrix; matrix[3][2] = 10.0;

AlTM::AlTM( const double d0, const double d1, const double d2, const double d3 ) Description
Constructor for the AlTM. This initializes the matrix by setting the diagonal to (d0,d1,d2,d3) Warning: for efficiency reasons, the matrix is NOT initialized by the default constructor. Use the AlTM(1,1,1,1) constructor to initialize the identity matrix (that is, this sets the diagonal to 1s, and the rest of the matrix to 0) Similarly, to initialize the matrix with all 0, use the constructor AlTM(0) or AlTM(0,0,0,0)

AlTM::AlTM( const AlTM& tm ) Description

Constructor for the AlTM. This initializes the matrix by making a copy of the given AlTM matrix tm.

AlTM::AlTM( const double tm[4][4] ) Description

Constructor for the AlTM. This initializes the matrix by making a copy of the given 4x4 array tm.

952 | Chapter 5 AlSet AlXEvents

statusCode AlTM::getTM( double tm[4][4] ) const Description

Copies the contents of the AlTM into a 4x4 array tm.

Arguments
< tm - where to copy the transformation matrix to

Return Codes
sSuccess - the matrix was successfully copied sInvalidArgument - the pointer is NULL

statusCode AlTM::setTM( const double tm[4][4] ) Description

Copies the given matrix into the AlTM.

Return Codes
sSuccess - the matrix was successfully copied sInvalidArgument - the pointer is NULL

AlTM& AlTM::operator =( const AlTM& tm ) Description

A=B This copies matrix B to matrix A.

AlTM& AlTM::operator =( const double d ) Description

A=d Every entry in matrix A is set to the scalar value in d.

AlTM | 953

int AlTM::operator ==( const AlTM& tm ) const Description

A == B Returns 1 if matrix A and B are equal, 0 otherwise.

int AlTM::operator !=( const AlTM& tm ) const Description

A != B Returns 1 if matrix A and B are not equal, 0 otherwise.

AlTM AlTM::operator +( const AlTM& tm ) const Description

result = A + B Returns the result of matrix B added to matrix A.

AlTM AlTM::operator -( const AlTM& tm ) const Description

result = A - B Returns the result of matrix B subtracted from matrix A.

AlTM AlTM::operator *( const AlTM& tm ) const Description

result = A * B Returns the result of matrix A post multiplied by matrix B.

AlTM operator *( const double d, const AlTM& tm )const Description

result = d * A

954 | Chapter 5 AlSet AlXEvents

Returns the result of matrix A multiplied by the scalar value in d.

AlTM AlTM::operator *( const double d ) const Description

result = A * d Returns the result of matrix A multiplied by the scalar value in d.

AlTM& AlTM::operator +=( const AlTM& tm ) Description

A=A+B Adds matrix B to matrix A.

AlTM& AlTM::operator -=( const AlTM& tm ) Description

A=A-B Subtracts matrix B from matrix A.

AlTM& AlTM::operator *=( const AlTM& tm ) Description

A=A*B Post multiplies matrix A by matrix B.

AlTM& AlTM::operator *=( const double d ) Description

A=A*d Multiplies every entry in matrix A by the scalar value in d.

AlTM | 955

statusCode AlTM::decompose( double translate[3], double scale[3], double rotate[3], double shear[3] ) const Description
Decomposes the transform into translate, rotate, scale, and shear components. The shears are saved as XY, XZ, and YZ in the return vector "shear". They may be ignored, but only at your peril! Alias transformation nodes can contain a shear despite the fact that there is no explicit shear operation (a two level DAG with rotate and scale will do it).

Arguments
> translate - vector to store translation in > scale - vector to store scale in > rotate - vector to store rotation in > shear - vector to store shear in

Return Codes
sSuccess - the matrix decomposition worked sFailure - the matrix decomposition failed

AlTM AlTM::inverse( void ) const Description

result = A.inverse() Returns the inverse of matrix A. If A is not invertible, then a zero matrix is returned (the result can be compared to the zero matrix ).

AlTM AlTM::transpose( void ) const Description

result = A.transpose() Returns the transpose of matrix A.

956 | Chapter 5 AlSet AlXEvents

AlTM AlTM::identity( void ) Description

AlTM::identity() returns the identity matrix.

AlTM AlTM::zero( void ) Description

AlTM::zero() returns a zero matrix.

AlTM AlTM::diagonal( const double d0, const double d1, const double d2, const double d3 ) Description
Returns a zero matrix with diagonal values of d. The following matrix is returned:
[ [ [ [ d0 0 0 0 ] 0 d1 0 0 ] 0 0 d2 0 ] 0 0 0 d3 ]

Arguments
< d - value to set the diagonal to

AlTM AlTM::scale( const double d ) Description

Returns a transformation matrix to scale a point [ x y z ] by a constant with value of d. The following matrix is returned:
[ [ [ [ d 0 0 0 0 d 0 0 0 0 d 0 0 0 0 1 ] ] ] ]

AlTM | 957

Arguments
< d - value to scale a point by

AlTM AlTM::scale_nonp( const double sx, const double sy, const double sz ) Description
Returns a transformation matrix to nonproportionally scale a point [ x y z ] by sx in the x axis, sy in the y axis and sz in the z axis. The following matrix is returned:
[ [ [ [ sx 0 0 0 0 sy 0 0 0 0 sz 0 0 0 0 1 ] ] ] ]

Arguments
< sx - scale of the x axis < sy - scale of the y axis < sz - scale of the z axis

AlTM AlTM::translate( const double tx, const double ty, const double tz ) Description
Returns a transformation matrix to translate a point (x,y,z) by (tx, ty, tz).

Arguments
< tx, ty, tz - the vector (tx, ty, tz) to translate the point by

AlTM AlTM::rotateX( const double rx ) Description

Returns a transformation matrix to rotate about the X axis.

958 | Chapter 5 AlSet AlXEvents

Arguments
< rx - angle in radians to rotate about the x axis

AlTM AlTM::rotateY( const double ry ) Description

Returns a transformation matrix to rotate about the Y axis.

Arguments
< ry - angle in radians to rotate about the y axis

AlTM AlTM::rotateZ( const double rz ) Description

Returns a transformation matrix to rotate about the Z axis.

Arguments
< rz - angle in radians to rotate about the z axis

AlTM AlTM::rotate( double x, double y, double z, double angle ) Description

Returns a transformation matrix to rotate counterclockwise about the axis (x,y,z).

Arguments
< angle - angle in radians to rotate counterclockwise by < x,y,z - the axis to rotate about

statusCode AlTM::transNormal( double& x, double& y, double& z ) const Description

Transforms a normal. sFailure is returned if the upper 3x3 matrix is not invertible n = n * trans(inv(M)).

AlTM | 959

NOTE: this function inverts the given matrix to do the operation. This operation may not be numerically accurate. It is suggested that, for DAG traversals, you use AlDagNode::inverseGlobalTransform to get the inverse of the transformation. Then take the transformation, then use transVector. for example,
double normX, normY, normZ; AlTM invTM; dagNode->inverseGlobalTransformMatrix( invTM ); invTM.transpose().transVector( normX, normY, normZ );

statusCode AlTM::transVector( double& x, double& y, double& z ) const Description

Transforms a vector (assumes w=0).

statusCode AlTM::transPoint( const double pt[4], double transPt[4] ) const Description

Using the matrix, transforms the point in pt[] to transPt[]. It does the operation
transPt[ x y z w ] = pt[ x y z w ] * matrix

Arguments
< pt - the point to transform > transPt - where to place the result

Return Codes
sSuccess - the matrix was successfully copied sInvalidArgument - one of the pointers was NULL

statusCode AlTM::transPoint( double pt[4] ) const Description

Using the matrix, transforms the point in pt[] to pt[]. It does the operation

960 | Chapter 5 AlSet AlXEvents

pt[ x y z w ] = pt[ x y z w ] * matrix

Arguments
<> pt - the point to transform

Return Codes
sSuccess - the vector was successfully transformed sInvalidArgument - the pointer was NULL

statusCode AlTM::transPoint( double &x, double &y, double &z, double &w ) const Description
Using the transformation matrix, transforms the point (x,y,z,w). It does the operation
[ x y z w ] = [ x y z w ] * matrix

Arguments
<> &x, &y, &z, &w - the row vector to transform

Return Codes
sSuccess - the vector was successfully transformed

statusCode AlTM::transPoint( double &x, double &y, double &z ) const Description
Using the matrix, transforms the point (x, y, z, 1). It does the operation
[ x y z 1 ] = [ x y z 1 ] * matrix

Arguments
<> &x, &y, &z - the row vector to transform

AlTM | 961

Return Codes
sSuccess - the vector was successfully transformed

AlTorusLight
Add parameters for torus light.

Synopsis
#include <AlTorusLight.h> class AlTorusLight: public AlVolumeLight AlTorusLight(); virtual ~AlTorusLight(); virtual AlObject* copyWrapper() const; statusCode create(); AlObjectType type() const; double arc() const; double torusRadius() const; statusCode setArc(double); statusCode setTorusRadius(double);

Description
A torus light creates light within a donut. The relative thickness of the donut is set determined by the TorusRadius. The arc determines whether you get the whole torus or just a wedge cut out of a torus. Torus lights are good for halo-shaped particle system effects.

AlTorusLight::AlTorusLight() Description
Constructs an AlTorusLight wrapper object.

AlTorusLight::~AlTorusLight() Description
Deletes an AlTorusLight wrapper object.

962 | Chapter 5 AlSet AlXEvents

statusCode AlTorusLight::create() Description

Creates all the DAG nodes for this light and adds them to the universe. The DAG nodes are for position, look at and up, and another DAG node that groups these three together.

Return Codes
sSuccess - everything was successful sInsufficientMemory - not enough memory available sAlreadyCreated - light is already created

AlObjectType AlTorusLight::type() const Description

Returns the class identifier kTorusLightType.

double AlTorusLight::arc() const Description

Returns the sphere lights arc (that is, how much of the sphere we actually have). -1 is returned if the light is invalid.

double AlTorusLight::torusRadius() const Description

Returns the sphere lights radius. -1 is returned if the light is invalid.

statusCode AlTorusLight::setArc( double arc ) Description

Sets the arc of the light.

Arguments
< double arc - portion of the sphere to use from 0 to 360 degrees

AlTorusLight | 963

Return Codes
sSuccess - setting arc succeeded sInvalidObject - not a valid volume light sInvalidArgument - arc out of range sFailure - an error occurred

statusCode AlTorusLight::setTorusRadius( double torus_radius ) Description

Sets the radius of the light.

Arguments
< double arc - the radius of the sphere to use (must be greater than 0)

Return Codes
sSuccess - setting the radius succeeded sInvalidObject - not a valid volume light sInvalidArgument - the radius is less than 0 sFailure - an error occurred

AlTrimBoundary
A list of trim curves defining a trim boundary.

964 | Chapter 5 AlSet AlXEvents

Synopsis
#include <AlTrimBoundary.h> class AlTrimBoundary : public AlObject virtual ~AlTrimBoundary(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; AlTrimRegion* parentRegion() const; AlDagNode* parentDagNode() const; AlTrimCurve* firstCurve() const; statusCode applyIteratorToCurves( AlIterator*, int& ); AlTrimBoundary* nextBoundary() const; statusCode nextBoundaryD(); AlTrimBoundary* prevBoundary() const; statusCode prevBoundaryD(); statusCode convertToUVPolyline( int &np, double *&CVList );

Description
This class holds a list of AlTrimCurve objects. The trim curves form a closed boundary which partition a surface. The trim curves are defined in a surfaces parametric space. Note that trim boundaries have the surface to the right of the defining curves. Also, in the list of trim curves, the end point of a trim curve is coincident with the first point of its following trim curve. The end point of the last trim curve is coincident with the first point of the first trim curve.

AlTrimBoundary::~AlTrimBoundary() Description
Deletes an AlTrimBoundary wrapper object.

AlObject *AlTrimBoundary::copyWrapper() const Description

Return an exact duplicate of this AlTrimBoundary wrapper.

AlTrimBoundary | 965

AlObjectType AlTrimBoundary::type() const Description

Returns the class identifier kTrimBoundary type.

AlTrimCurve* AlTrimBoundary::firstCurve() const Description

Returns the first trim curve of a list of trim boundaries or NULL if this boundary has no curves.

AlTrimBoundary* AlTrimBoundary::nextBoundary() const Description

Returns the next trim boundary. Returns NULL if there is no such trim boundary.

statusCode AlTrimBoundary::nextBoundaryD() Description

Destructively points this wrapper to the next boundary. If there is no such boundary, then the object is left unchanged.

Return Codes
sSuccess - the wrapper now points to the next boundary sFailure - there is no next boundary sInvalidObject - the trim boundary is invalid

AlTrimBoundary* AlTrimBoundary::prevBoundary() const Description

Returns the previous trim boundary. Returns NULL if there is no such trim boundary.

966 | Chapter 5 AlSet AlXEvents

statusCode AlTrimBoundary::prevBoundaryD() Description

Destructively points this wrapper to the previous boundary. If there is no such boundary, then the object is left unchanged.

Return Codes
sSuccess - the wrapper now points to the previous boundary sFailure - there is no prev boundary sInvalidObject - the trim boundary is invalid

statusCode AlTrimBoundary::convertToUVPolyline( int &n, double *& CVList ) Description

Converts the trim boundary to a uv polyline. The number of points in the polyline is returned in "n", and the points are returned in "CVList", which is essentially an array: CVList[n][2], but must be accessed as a single dimensional array; for example, CVList[i * 2 + 0] for u and CVList[i * 2 + 1] for v.

Return Codes
sSuccess - the array has been allocated, loaded and returned sFailure - parent does not exist, n will be 0, and CVList will be NULL sInvalidObject - the trim boundary is invalid

AlTrimRegion* AlTrimBoundary::parentRegion() const Description

Returns the parent trim region of the trim boundary.

AlDagNode* AlTrimBoundary::parentDagNode() const Description

Returns the parent DAG node of the trim boundary.

AlTrimBoundary | 967

statusCode AlTrimBoundary::applyIteratorToCurves( AlIterator* iter, int& rc ) Description

Applies an iterator to each trim boundary curve.

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

Return Codes
sSuccess - the iterator was successfully applied to each trim boundary curve sInvalidArgument - 'iter' was NULL

AlTrimCurve
A curve in parametric surface space, part of a trim boundary.

968 | Chapter 5 AlSet AlXEvents

Synopsis
#include <AlTrimCurve.h> class AlTrimCurve : public AlObject virtual ~AlTrimCurve(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; AlTrimBoundary* parentBoundary() const; AlTrimRegion* parentRegion() const; AlDagNode* parentDagNode() const; AlCurve* worldSpace3DCopy( double = 1.0e-5 ) const; AlCurve* unaffected3DCopy( double = 1.0e-5 ) const; AlCurve* affected3DCopy( AlTM&, double = 1.0e-5 ) const; AlTrimCurve* getTwinCurve() const; boolean isReversed() const; curveFormType form() const; int degree() const; int numberOfSpans() const; int numberOfKnots() const; int numberOfCVs() const; statusCode CVsUVPosition( double[], double[][3] ) const; int realNumberOfKnots() const; statusCode realKnotVector( double[] ) const; statusCode periodicToNonPeriodic( ) const; AlTrimCurve* nextCurve() const; statusCode nextCurveD(); AlTrimCurve* prevCurve() const; statusCode prevCurveD(); statusCode eval(double t, double *p, double *p1, double *p2) const;

Description
This class holds the trim curve data and provides access methods for the data. A trim curve is defined over a surfaces parametric space.

statusCode AlTrimCurve::eval(double t, double *p, double *p1, double *p2)const Description

Evaluate the curve at parameter t to get its point and derivatives.

AlTrimCurve | 969

Return Codes
sSuccess - the wrapper now points to the prev curve sFailure - there is no prev curve sInvalidObject - the curve is invalid

AlTrimCurve::~AlTrimCurve() Description
Deletes an AlTrimCurve wrapper object.

AlObject *AlTrimCurve::copyWrapper() const Description

Returns an exact duplicate of this AlTrimCurve wrapper.

AlObjectType AlTrimCurve::type() const Description

Returns the class identifier kTrimCurve type.

AlTrimCurve* AlTrimCurve::getTwinCurve() const Description

Trim curves on shells are twinned - the edges where faces meet in a shell are tightly coupled. This function, given an AlTrimCurve, will return the AlTrimCurve which corresponds to the trim curves twin. In the case of trimmed surfaces, edges are not twinned, so NULL is returned. If the trim curve in question is a true edge of the shell, NULL is returned.

boolean AlTrimCurve::isReversed() const Description

Returns TRUE if the trim curve has been reversed.

970 | Chapter 5 AlSet AlXEvents

int AlTrimCurve::degree() const Description

Returns the degree of the trim curve.

curveFormType AlTrimCurve::form() const Description

Returns the form of the curve, which is kOpen, kClosed or kPeriodic. If a trim curve is periodic, it is tangent continuous at the point where it is closed. (If you use the "close" tool in the interactive Alias package, you actually make a curve periodic.) If a curve is periodic, it implies that it is closed. If a curve is kClosed, then it just means that its endpoints are coincident. Otherwise, the curve is kOpen.

int AlTrimCurve::numberOfSpans() const Description

Returns the number of spans in the curve. -1 is returned if the curve is invalid.

int AlTrimCurve::numberOfKnots() const Description

Returns the number of knot values (just numberOfSpans() + 1). -1 is returned if the curve is invalid.

int AlTrimCurve::numberOfCVs() const Description

Returns the number of CVs (degree + numberOfSpans). -1 is returned if the curve is invalid.

AlTrimCurve | 971

statusCode AlTrimCurve::CVsUVPosition( double knotVector[], double CVs[][3] ) const Description

Assumes that the knotVector is of length numberOfKnots() and the CVs array is of length numberOfCVs() and returns the values of the knots and CVs points in these arrays. Notice that each CV has three coordinates - the three coordinates describe 2D parameter space, with a homogeneous coordinate. Each control point is u, v and w, where u and v are parameter space and w is the homogeneous coordinate.

Arguments
> knotVector - contains the knots for this curve upon return > CVs - contains the control points upon return

Return Codes
sSuccess - the CVs positions were retrieved sInvalidObject - the curve was invalid

int AlTrimCurve::realNumberOfKnots() const Description

Returns the actual number of knots on the curve. That is uNumberOfSpans() + 2*degree() - 1. (Note that two additional knots are required to define a NURBS curve, but they have no effect on the curve so are not included in this count.) This method returns -1 if the curve is not valid.

statusCode AlTrimCurve::realKnotVector( double knotVector[] ) const Description

Returns realNumberOfKnots() in knotVector for the curve.

Arguments
> knotVector - array to place the knot vector into

972 | Chapter 5 AlSet AlXEvents

Return Codes
sSuccess - successfully copied the curves knot vector into knotVector sInvalidArgument - knotVector was NULL sInvalidObject - the curve was invalid

AlTrimCurve* AlTrimCurve::nextCurve() const Description

Returns the next trim curve. Returns NULL if there is no such trim curve.

statusCode AlTrimCurve::nextCurveD() Description

Destructively points this wrapper to the next curve. If there is no next curve, then the object is left unchanged.

Return Codes
sSuccess - the wrapper now points to the next curve sFailure - there is no next curve sInvalidObject - the curve is invalid

AlTrimCurve* AlTrimCurve::prevCurve() const Description

Returns the previous trim curve. Returns NULL if there is no such trim curve.

statusCode AlTrimCurve::prevCurveD() Description

Destructively points this wrapper to the previous curve. If there is no previous trim curve, then the object is left unchanged.

Return Codes
sSuccess - the wrapper now points to the previous curve

AlTrimCurve | 973

sFailure - there is no previous curve sInvalidObject - the curve is invalid

AlCurve* AlTrimCurve::worldSpace3DCopy( double tolerance ) const Description

Returns a pointer to a temporary curve that represents a world space copy of the surface trim curve. This returns the world space (xyz) copy of the parameter space (uv) trim curve with all DAG transformations that affect the surface applied to the returned curve. That is, if you were to draw this curve, it would show up right on the surface. The default value for tolerance is 1.0E-5.

AlCurve* AlTrimCurve::unaffected3DCopy( double tolerance ) const Description

Returns a pointer to a temporary curve that represents a world space copy of the surface trim curve. This returns the world space (xyz) copy of the parameter space (uv) trim curve but with no DAG transformations applied. If you were to draw this curve, it would show up near the xyz origin. The default value for tolerance is 1.0E-5.

AlCurve* AlTrimCurve::unaffected3DCopyNoReverse( double tolerance ) const Description

In a loop of AlTrimCurves, all the parameter space versions are connected nose to tail to form a closed boundary. The world space copies are not guaranteed to be all in the same direction like this. worldSpace3DCopy, unaffected3DCopy, and affected3D copy will reverse the direction of the curve if necessary so that if you get a copy of the whole loop, the curves are all in the same direction. unaffected3DCopyNoReverse will not reverse a curve's direction to guarantee this. The default value for tolerance is 1.0E-5.

974 | Chapter 5 AlSet AlXEvents

AlCurve* AlTrimCurve::affected3DCopy( AlTM& tm, double tolerance ) const Description

Returns a pointer to a temporary curve that represents a world spacecopy of the surface trim curve. This is like worldSpace3DCopy, except that instead of the transformations affecting the surface being applied to the curve, you specify your own transformation matrix. tm is the transformation matrix generated while walking the DAG. The default value for tolerance is 1.0E-5.

AlTrimBoundary* AlTrimCurve::parentBoundary() const Description

Returns the parent trim boundary of the trim region.

AlTrimRegion* AlTrimCurve::parentRegion() const Description

Returns the parent trim region of the trim curve.

AlDagNode* AlTrimCurve::parentDagNode() const Description

Returns the parent DAG node of the trim curve.

statusCode AlTrimCurve::periodicToNonPeriodic() const Description

Converts a periodic curve to a non-periodic curve (closed curve) by making it have multiple end knots. Note: this method modifies the trim curve.

AlTrimCurve | 975

Return Codes
sInvalidObject - the trim curve was invalid sFailure - the method did not succeed sSuccess - the trim curve was converted to a non-periodic curve

AlTrimRegion
A list of trim boundaries defining a trim region.

976 | Chapter 5 AlSet AlXEvents

Synopsis

AlTrimRegion | 977

#include <AlTrimRegion.h> class AlTrimRegion : public AlObject virtual ~AlTrimRegion(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; AlDagNode* parentDagNode() const; AlTrimBoundary* firstBoundary() const; statusCode applyIteratorToBoundaries( AlIterator*, int& ) const; AlTrimRegion* nextRegion() const; statusCode nextRegionD(); AlTrimRegion* prevRegion() const; statusCode prevRegionD(); // Stuff to get surface information curveFormType uForm() const; curveFormType vForm() const; int uDegree() const; int vDegree() const; int uNumberOfSpans() const; int vNumberOfSpans() const; int uNumberOfCVs() const; int vNumberOfCVs() const; statusCode periodicToNonPeriodic( int, int ); statusCode periodicToNonPeriodic() const; statusCode CVsWorldPosition( double[], int[], int[])const; statusCode CVsAffectedPosition( const AlTM&, double[], int[], int[]) const; statusCode CVsUnaffectedPosition( double[], int[], int[])const; int uNumberOfKnots() const; int vNumberOfKnots() const; statusCode uKnotVector( double[] ) const; statusCode vKnotVector( double[] ) const; int uNumberOfCVsInclMultiples() const; int vNumberOfCVsInclMultiples() const; statusCode CVsWorldPositionInclMultiples( double[] ) const; statusCode CVsAffectedPositionInclMultiples( const AlTM&, double[] ) const; statusCode CVsUnaffectedPositionInclMultiples( double[] )const; int realuNumberOfKnots() const; int realvNumberOfKnots() const; statusCode realuKnotVector( double[] ) const; statusCode realvKnotVector( double[] ) const;

978 | Chapter 5 AlSet AlXEvents

statusCode eval(double,double,boolean,double P[3]=NULL, double Pu[3]=NULL, double Pv[3]=NULL, double n[3]=NULL,boolean=FALSE,boolean=FALSE ) const; statusCode persistentID( AlPersistentID *&id, int ut = 1 ); statusCode hasPersistentID( int ut = 1 ); statusCode setPersistentID( AlPersistentID &id, int ut );

Description
This class defines a region of a surfaces parametric space that identifies an area of interest on a surface. It holds at least one AlTrimBoundary object. The first boundary on the list represents the outermost boundary of a trim region, and the rest represent the inner boundaries (holes) if there are any. For each trim boundary, the surface is to the left of the boundary when viewed from above (hence a hole is to the right of the boundary). For example, in this diagram we have a surface represented by As. Each additional letter is an island trimmed out of A and each would be a separate AlTrimRegion. The AlTrimRegion for A would have two AlTrimBoundaries, B would have three, and C, D, and E would have one each.
AAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAA AA AA AA BBBBBBBBBBB CCCCCCCCCC AA AA BBBBBBBBBBB CCCCCCCCCC AA AA BB BBBB AA AA BB EEE BBBBBBBBBBBBBBB AA AA BB EEE BBBB BB AA AA BB BBBB DDDDDDD BB AA AA BBBBBBBBBBB DDDDDDD BB AA AA BBBBBBBBBBB BB AA AA BBBBBBBBBBBBBBBBBBBBBB AA AA AA AAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAA

AlTrimRegion::~AlTrimRegion() Description
Deletes an AlTrimRegion wrapper object.

AlTrimRegion | 979

AlObject *AlTrimRegion::copyWrapper() const Description

Returns an exact duplicate of this AlTrimRegion wrapper.

AlObjectType AlTrimRegion::type() const Description

Returns the class identifier kTrimRegionType.

AlDagNode * AlTrimRegion::parentDagNode() const Description

Gets the parent DagNode above this trim region. NULL is returned if there is no parent.

AlTrimBoundary* AlTrimRegion::firstBoundary() const Description

Returns the first trim boundary of a list of trim boundaries or NULL if this region has no boundaries.

AlTrimRegion* AlTrimRegion::nextRegion() const Description

Returns the next trim region. Returns NULL if there is no such trim region.

statusCode AlTrimRegion::nextRegionD() Description

Destructively points this wrapper object to the next trim region. If there is no next trim region, then the object is left unchanged.

Return Codes
sSuccess - the wrapper now points to the next trim region sFailure - there is no next trim region

980 | Chapter 5 AlSet AlXEvents

sInvalidObject - the region is invalid

AlTrimRegion* AlTrimRegion::prevRegion() const Description

Returns the previous trim region. Returns NULL if there is no such trim region.

statusCode AlTrimRegion::prevRegionD() Description

Destructively points this wrapper object to the previous trim region. If there is no previous trim region, then the object is left unchanged.

Return Codes
sSuccess - the wrapper now points to the previous trim region sFailure - there is no previous trim region sInvalidObject - the region is invalid

curveFormType AlTrimRegion::uForm() const Description

See the documentation for this function in AlSurface on page 858.

curveFormType AlTrimRegion::vForm() const Description

See the documentation for this function in AlSurface on page 858.

int AlTrimRegion::uDegree() const Description

See the documentation for this function in AlSurface on page 858.

AlTrimRegion | 981

int AlTrimRegion::vDegree() const Description

See the documentation for this function in AlSurface on page 858.

int AlTrimRegion::uNumberOfSpans() const Description

See the documentation for this function in AlSurface on page 858.

int AlTrimRegion::vNumberOfSpans() const Description

See the documentation for this function in AlSurface on page 858.

int AlTrimRegion::uNumberOfCVs() const Description

See the documentation for this function in AlSurface on page 858.

int AlTrimRegion::vNumberOfCVs() const Description

See the documentation for this function in AlSurface on page 858.

statusCode AlTrimRegion::CVsWorldPosition(double CVList[], int uMultiplicity[], int vMultiplicity[] ) const Description

See the documentation for this function in AlSurface on page 858.

statusCode AlTrimRegion::CVsAffectedPosition( const AlTM& tm, double CVList[],int uMultiplicity[],int vMultiplicity[] ) const Description
See the documentation for this function in AlSurface on page 858.

982 | Chapter 5 AlSet AlXEvents

statusCode AlTrimRegion::CVsUnaffectedPosition( double CVList[],int uMultiplicity[],int vMultiplicity[] ) const Description

See the documentation for this function in AlSurface on page 858.

int AlTrimRegion::uNumberOfKnots() const Description

See the documentation for this function in AlSurface on page 858.

int AlTrimRegion::vNumberOfKnots() const Description

See the documentation for this function in AlSurface on page 858.

statusCode AlTrimRegion::uKnotVector( double knotVector[] ) const Description

See the documentation for this function in AlSurface on page 858.

statusCode AlTrimRegion::vKnotVector( double knotVector[] ) const Description

See the documentation for this function in AlSurface on page 858.

int AlTrimRegion::uNumberOfCVsInclMultiples() const Description

See the documentation for this function in AlSurface on page 858.

int AlTrimRegion::vNumberOfCVsInclMultiples() const Description

See the documentation for this function in AlSurface on page 858.

AlTrimRegion | 983

statusCode AlTrimRegion::CVsWorldPositionInclMultiples( double CVList[] ) const Description

See the documentation for this function in AlSurface on page 858.

statusCode AlTrimRegion::CVsAffectedPositionInclMultiples( const AlTM& tm, double CVList[] ) const Description

See the documentation for this function in AlSurface on page 858.

statusCode AlTrimRegion::CVsUnaffectedPositionInclMultiples( double CVList[] ) const Description

See the documentation for this function in AlSurface on page 858.

int AlTrimRegion::realuNumberOfKnots() const Description

See the documentation for this function in AlSurface on page 858.

int AlTrimRegion::realvNumberOfKnots() const Description

See the documentation for this function in AlSurface on page 858.

statusCode AlTrimRegion::realuKnotVector( double knotVector[] ) const Description

See the documentation for this function in AlSurface on page 858.

984 | Chapter 5 AlSet AlXEvents

statusCode AlTrimRegion::realvKnotVector( double knotVector[] ) const Description

See the documentation for this function in AlSurface on page 858.

statusCode AlTrimRegion::eval(double u, double v, boolean worldCoordinates, double P[3], double Pu[3], double Pv[3], double n[3], boolean uLimitFromBelow, boolean vLimitFromBelow ) const Description
See the documentation for this function in AlSurface on page 858.

statusCode AlTrimRegion::applyIteratorToBoundaries(AlIterator* iter, int& rc ) const Description

Applies an iterator to each trim region boundary.

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

Return Codes
sSuccess - the iterator was successfully applied to each trim region boundary sInvalidArgument - 'iter' was NULL

statusCode AlTrimRegion::periodicToNonPeriodic( int u, int v ) Description

If an underlaying surface of the trim region is periodic, converts it to a non-periodic surface (closed surface) by making it have multiple end knots in the selected direction (u/v). Note: this method modifies the underlaying surface of the trim region.

AlTrimRegion | 985

Arguments
> u - change in u direction if u has the following value: -1 make left (u0) end multiple 0 make both (u) ends multiple 1 make right(un) end multiple > v - change in v direction if v has the following value: -1 make left (v0) end multiple 0 make both (v) ends multiple 1 make right(vn) end multiple

Return Codes
sInvalidObject - the underlaying surface was invalid. sFailure - the method did not succeed sSuccess - the underlaying surface was converted to a non-periodic one in the u/v direction

statusCode AlTrimRegion::periodicToNonPeriodic( ) const Description

If an underlying surface of the trim region is periodic, converts it to a non-periodic surface (closed surface) by making it have multiple end knots at both endpoints in u/v directions. Note: this method modifies the underlying surface of the trim region.

Return Codes
sInvalidObject - the underlaying surface was invalid sFailure - the method did not succeed sSuccess - the underlaying surface was converted to a non-periodic one in both u and v directions

986 | Chapter 5 AlSet AlXEvents

statusCode AlTrimRegion::persistentID( AlPersistentID *&id, int userType ) Description

Returns a copy of the AlPersistentID associated with this face. For user type 1, persistent IDs are created if they do not exist already. For all other user types, persistent IDs are not created if they do not exist already, and the method fails. User types between 0 and 9999 are reserved. If you would like to reserve a block of user types please contact us.

Arguments
< type - user type of the persistent ID desired > id - a copy of the AlPersistentID

Return Codes
sSuccess - normal completion sInvalidObject - the given object is not valid

statusCode AlTrimRegion::setPersistentID( AlPersistentID &id, int userType ) Description

Sets the values of the AlPersistentID associated with this node. This method only allows you to create persistent IDs with user types other than 1. If the persistent ID does not exist, it will be created. User types between 0 and 9999 are reserved. If you would like to reserve a block of user types please contact us.

Arguments
< type - user type of the persistent ID desired > id - a copy of the AlPersistentID

Return Codes
sSuccess - normal completion sInvalidObject - the given object is not valid

AlTrimRegion | 987

sInvalidArgument - the given userType is not valid sFailure - the id did not exist or could not be created

statusCode AlTrimRegion::hasPersistentID( int user_type ) Description

Checks that the AlTrimRegion has a persistent ID associated with it.

Arguments
< type - user type of the persistent ID desired

Return Codes
sSuccess - node has a persistent ID sFailure - node does not have a persistent ID sInvalidObject - the given object is not valid

AlUnits
Interface to units.

988 | Chapter 5 AlSet AlXEvents

Synopsis
#include <AlUnits.h> class AlUnits enum Type { kUnit, kSubunit, kPosition }; enum LinearUnit { kMiles, kYards, kFeet, kInches, kCentimeters, kMeters, kKilometers, kMillimeters }; enum AngularUnit { kRadians, kDegrees, kMinutes, kSeconds }; static AngularUnit angularUnits( Type type ); static double angularScale( Type type ); static LinearUnit linearUnits( Type type ); static double linearScale( Type type ); static double linearInCM( LinearUnit unit ); static double angularInDegrees( AngularUnit unit ); static statusCode parseStringAngular( const char* string, char* &ret, const char* format=0 ); static statusCode parseStringLinear( const char* string, char* &ret, const char* format=0 ); static statusCode parseStringNoUnits( const char* string, char* &ret, const char* format=0 );

Description
This class provides access to linear and angular units in the Alias API. Note that all of the internal geometry routines work in centimeters and degrees. If you wish to use other units for distance tolerances and lengths, they must be converted to centimeters. Similarly, all angles must be converted to degrees.

AlUnits::AngularUnit AlUnits::angularUnits( AlUnits::Type type ) Description

Returns the current angular units.

AlUnits | 989

AlUnits::LinearUnit AlUnits::linearUnits( AlUnits::Type type ) Description

Returns the current linear units.

double AlUnits::angularScale( AlUnits::Type type ) Description

Returns the current scaling of the angular units.

double AlUnits::linearScale( AlUnits::Type type ) Description

Returns the current scaling of the linear units.

double AlUnits::linearInCM( AlUnits::LinearUnit unit ) Description

Returns the size of a unit in centimeters. To convert a measurement to centimeters, use the equation:
double scale = AlUnits::linearScale( type ); double unitsInCM = AlUnits::linearInCM( type ); sizeCM = sizeInUnits * unitsInCM * scale;

Arguments
unit - the linear unit in question

double AlUnits::angularInDegrees( AlUnits::AngularUnit unit ) Description

Returns the size of a unit in degrees.

Arguments
unit - the angular unit in question

990 | Chapter 5 AlSet AlXEvents

statusCode AlUnits::parseStringAngular( const char* string, char* &ret, const char* format ) Description
Parses a string and converts the resulting angle into degrees. An input string is a collection of angles separated by spaces or comma. An angle is composed of digits, units and : separators used to denote subunits. An angle does not contain any spaces. For example, the string 10deg:5.4min is converted to degrees (10.09 degrees) and the resulting value is placed into the return string as 10.090000000 . Strings such as 10 deg:5.4min or 10 deg, 5.4min and so on, are not considered to be valid for a single angle value. If the format string is not specified, then the default format string %f is used (this reads a single angle). The format string uses a simplified version of the typical printf style arguments. To read three angles, specify format string of %f %f %f. In the input string, spaces and commas ("," or " ") are used to separate the input items. For example, if the format string is "%f %f", then the input string should be formatted as two angles separated by a space (for example, "10deg:5.4min 99sec"). The angles will be converted to degrees (10.09 degrees and 0.0275 degrees) and formatted into the return string separated by a space (for example, "10.09000000 0.027500000"). Note that the returned string contains the angle without any units in its string. This function is available only under OpenAlias.

Arguments
string - input string ret - returned parsed string format - if this is not NULL, then it specifies the input format. %f is the default.

Return Codes
sSuccess - operation was successful sFailure - format error

AlUnits | 991

statusCode AlUnits::parseStringLinear( const char* string, char* &ret, const char* format ) Description
Parses a string and combines all of the units into a single unit. The result is converted to centimeters for linear units. See parseStringAngular for details. This function is available only under OpenAlias.

Arguments
string - input string ret - returned parsed string format - the input format

Return Codes
sSuccess - operation was successful sFailure - format error

statusCode AlUnits::parseStringNoUnits( const char* string, char* &ret, const char* format ) Description
Parses a string and sprintfs the value into the resulting string. This method parses the string to ensure that it does not contain any units. This function is available only under OpenAlias.

Arguments
string - input string ret - returned parsed string format - the input format

Return Codes
sSuccess - operation was successful sFailure - format error

992 | Chapter 5 AlSet AlXEvents

AlUniverse
Encapsulates the retrieval, data access and storage of Alias Wire Files.

AlUniverse | 993

Synopsis

994 | Chapter 5 AlSet AlXEvents

#include <AlUniverse.h> class AlUniverse : public AlMessage enum AlFileType { kUnknown, // File type is unknown and will be ignored by ::re trieve(). kWire, // Autodesk Wire File kIges, // Initial Graphics Exchange Standard kVdais, // Verband Der Automobilindustrie IGES Subset kC4x, // EDS/GM format. kJamais, // Japan Automobile Manufacturers Association IGES Sub set. kVdafs, // Verband Der Automobilindustrie Freeform Surface Inter face. kDxf, // Drawing Exchange Format // The file types below are available only in OpenAlias. kDes, // EDS/GM Data Exchange Standard kTri, // Autodesk Object Separated Triangle Format kQuad, // Autodesk Object Separated Quad Format kProRender, // Pro/Engineer Render File Format. kInventor, // OpenInventor Metafile Subset V1.0 kStl, // 3D Systems SLA Format kObj, // Autodesk TAV format. kEpsf, // Adobe Encapsulated Postscript v2.x kIllustrator, // Illustrator Format. kSlc // 3D Systems Slice Format. }; // Project subdirectory types. // These indicate the subdirectories where different types of files are // located. enum AlDirectoryType { kAnimData, // Animation data (Save Anim / Retrieve Anim) kCanvasData, // Paint canvas files kDepthData, // Depth files kEnvironmentData, // Environment files (saved/retrieved via // multi-lister) kLightData, // Light files (saved/retrieved via multi-lister) kMaskData, // Mask files kMiscData, // Miscellaneous data files: color, window and so on. kOptionData, // UI option files kPixData, // Image files for file textures, image planes and so on. kPlotData, // Plot files

AlUniverse | 995

kRibData, // Pixar RIB files kSlaData, // Stereo Lithography files (.stl, .slc, .tri) kSdlData, // Scene Description Files kShaderData, // Shader files (saved/retrieved via multi-lister) kStageData, // Wire files representing stages. kTextureData, // Texture files (saved/retrieved via multi-lister) kWireData // Wire files an CAD files (for example, IGES, DXF, and so on.) }; enum AlApplicationMode { kOpenModel, kOpenAlias }; enum AlLayerSortMode{ kLayerNumber, kLayerName }; static statusCode initialize( AlCoordinateSystem = kZUp, boolean initProjectEnv = FALSE ); static boolean isInitialized(); static AlCoordinateSystem coordinateSystem (); static statusCode expandFileName( char[], const char *, AlDirectoryType directoryType ); static boolean isWireFile( const char *, char * ); static boolean AlUniverse::isOldWireFile( const char *fileName ); static statusCode wireFileWindowSize( int &sizeX, int &sizeY ); static statusCode setWireFileWindowSize( int sizeX, int sizeY ); static AlFileType fileType( const char * ); static statusCode retrieveOptions( AlRetrieveOptions& ); static statusCode setRetrieveOptions( const AlRetrieveOptions& ); static statusCode retrieve( const char * ); static statusCode retrieve( const char *, void(*)(int) ); static const char* lastWireFileRetrieved(); static const char* lastFileSaved(); static statusCode store( const char *, AlDagNode* = NULL ); static statusCode storeActive( const char * ); static AlDagNode* firstDagNode(); static AlSet* firstSet(); static AlCluster* firstCluster(); static const char* currentStage( void ); static statusCode setCurrentStage( const char* ); static statusCode mergeStage( const char* );

996 | Chapter 5 AlSet AlXEvents

static static static static static static static static static static static static static static static * ); static static static static static static static static static static static static static static static static static static static static static static static static static static static

statusCode mergeAllStages( void ); statusCode deleteStage( const char* ); statusCode deleteAllStages( void ); statusCode stageVisibility( const char *, boolean& ); statusCode setStageVisibility( const char *, boolean ); const char* stageWindowSource( void ); statusCode setStageWindowSource( const char * ); const char* stageBackgroundSource( void ); statusCode setStageBackgroundSource( const char * ); statusCode renameStage( const char *, const char * ); AlList* stageNames( void ); statusCode createNewStage( const char *, char*& ); statusCode retrieveStageSet( const char *,boolean ); statusCode saveStageSet( const char *); statusCode setStageWireFileName( const char *, const char const char* stageWireFileName( const char * ); AlWindow* firstWindow(); AlWindow* currentWindow(); AlWindow* sbdWindow(); AlImagePlane* firstImagePlane(); statusCode blindData( int, long&, const char*& ); statusCode blindData( int, int, long&, const char*& ); statusCode setBlindData( int, long, const char* ); statusCode removeBlindData( int ); statusCode removeBlindData( int, int ); AlChannel* firstChannel(); AlChannel* nextChannel(AlChannel *); statusCode nextChannelD( AlChannel *); AlAction* firstAction(); AlAction* nextAction(AlAction *); AlShader* firstShader(); AlShader* nextShader( AlShader* ); statusCode nextShaderD( AlShader* ); AlEnvironment* firstEnvironment(); AlLayer* firstLayer(); AlLayer* nextLayer( AlLayer* ); statusCode nextLayerD( AlLayer* ); AlLayer* layerByNumber(int); AlLayer* creationLayer(); statusCode setCreationLayer(AlLayer *); boolean layersEnabled(); statusCode setLayersEnabled( boolean );

AlUniverse | 997

static statusCode sortLayersInLayersBar(AlLayerSortMode); static AlPerspectiveCamera* firstCamera(); static AlPerspectiveCamera* nextCamera( AlPerspectiveCamera* ); static statusCode nextCameraD( AlPerspectiveCamera* ); static AlLocator* firstLocator(); static AlLocator* nextLocator(AlLocator *); static statusCode deleteAll(); static statusCode deleteAllLocators(); static AlConstructionEntity* firstConstructionEntity(); static AlConstructionEntity* nextConstructionEntity(AlConstruction Entity *); static statusCode nextConstructionEntityD(AlConstructionEntity *); static statusCode deleteAllConstructionEntities(); static statusCode importCloudFile( const char *, int ); static AlCloud *firstCloud(); static int numberOfClouds(); static AlBlendCurve* firstBlendCurve(); static int numberOfBlendCurves(); static statusCode redrawScreen( unsigned int flags = kRedrawInact ive | kRedrawActive ); static statusCode applyIteratorToImagePlanes( AlIterator*, int& ); static statusCode applyIteratorToWindows( AlIterator *, int& ); static statusCode applyIteratorToDagNodes( AlIterator *, int& ); static statusCode applyIteratorToActions( AlIterator *, int& ); static statusCode applyIteratorToChannels( AlIterator *, int& ); static statusCode applyIteratorToSets( AlIterator *, int& ); static statusCode applyIteratorToClusters( AlIterator *, int& ); static statusCode applyIteratorToShaders( AlIterator *, int& ); static statusCode applyIteratorToLocators(AlIterator *, int &); static statusCode applyIteratorToLayers(AlIterator *, int &); static statusCode applyIteratorToClouds(AlIterator *, int &); static statusCode applyIteratorToBlendCurves(AlIterator *, int &); static statusCode writeSDLNoAnimation( const char *, boolean ); static statusCode writeSDL( const char *, boolean, double, double, double ); static statusCode frameRange(AlFrameRangeType, double&, double&, double&); static double currentTime(); static statusCode doUpdates( boolean = TRUE ); static boolean updatesOn() static AlApplicationMode applicationMode(); static statusCode userPrefColor( int, int&, int&, int& );

998 | Chapter 5 AlSet AlXEvents

static static static static static

statusCode setUserPrefColor( int, int, int, int ); boolean constructionPlaneInEffect(); statusCode constructionPlaneTransform( AlTM& ); AlCategory *firstCategory(); AlCategory *nextCategory(AlCategory *);

Description
This is a static class in that all of its member functions are static. It provides the foundation on which to interface with Alias Wire Files (OpenModel) or with Alias directly (via OpenAlias). In Alias, there is the concept of a stage, an independent entity that encapsulates all the top-level information about a modeling environment. The stage effectively represents the running version of an individual Wire file. In the interactive package, stages can be controlled through the Stage Editor. The identical control also exists in the AlUniverse class, via the Stage functions. These let you switch between stages, create and destroy stages, merge stages, and alter their features. OpenAlias and OpenModel use object data that defines, among other things, transformations, curve and surface geometry, cameras, and lights. Transformations are kept in objects called "DAG nodes". DAG nodes can be connected to other DAG nodes to form a list of DAG nodes. There are particular types of DAG nodes which refer specifically to geometry, cameras, lights, or refer to another list of DAG nodes to form a hierarchical structure. Together, these different types of DAG nodes can be used to build a list of hierarchical structures which is collectively called a directed acyclic graph or "DAG". The AlUniverse class gives access to the first DAG node in the DAG, and from that DAG node, the list of all DAG nodes in the universe can be traversed. The object data may also contain animation information on various animatable items, such as a DAG node or a piece of geometry. The animation information can be accessed through the item that is animated. The AlUniverse class also gives access to animation data through global lists. Geometry also contains shading information. Each surface or face (a particular kind of curve) contains a list of shaders. The AlUniverse class also gives access to a global list of all shaders in the universe, as well as the single environment class. The AlUniverse class also gives access to the list of sets in the universe via the firstSet() method. Similarly, the firstCluster() method gives access to all the clusters in the universe. However, clusters are also accessible through methods in the classes that can belong to clusters (that is, AlDagNode, AlCurveCV and

AlUniverse | 999

AlSurfaceCV). A cluster is an object in the DAG that has a collection of DAG nodes and/or CVs. The transformations in the DAG nodes above the cluster are applied to the CVs in the cluster after the latters own transformations have been applied. AlUniverse provides base access to the ImagePlane list and the Window list through firstImagePlane(), firstWindow() and related functions. Whenever a new Alias object of any kind is created, it is added to the appropriate place in the universe. For example, if a DAG node is created, it is traversable through the AlUniverse::firstDagNode() method. If a new animation action is created, it is accessible by walking the list of actions via AlUniverse::firstAction()/nextAction(). However, there are a few exceptions. The AlCurve, AlFace, AlSurface and AlKeyframe classes can all be created and will not be part of the universe initially. They will become part of the universe when they are added to other objects. For example, an AlCurve becomes part of the universe when its AlCurveNode is created. An AlKeyframe becomes part of the universe when its AlParamAction is created. If a class is not part of the universe, this means that if AlUniverse::store() is called, that class will not be stored. If an OpenAlias plug-in exits without making an object part of the universe, then the data will be lost and wasted memory will result. The initialize method must be called before any other AlUniverse method is called. A Alias AlObject cannot be created until the initialize method is called.

statusCode AlUniverse::doUpdates( boolean newState ) Description

Notifies the system that you are finished performing. If this flag is TRUE, then it is equivalent to sending out a geometry modified message to the rest of the system. When the system receives the update message, then operations such as construction history, and so on are done. If the previous state of the flag was FALSE and the new state is TRUE, then an update will be done now and on each subsequent DAG modification.

boolean AlUniverse::isInitialized() Description

Returns TRUE if the initialize method has been called.

1000 | Chapter 5 AlSet AlXEvents

statusCode AlUniverse::initialize( AlCoordinateSystem up, boolean initProjectEnv ) Description

Initializes the OpenAlias/OpenModel environment so that Alias object data can be retrieved, created, and/or stored. The world space coordinate system of the Universe can be oriented so that either the positive Y-axis or positive Z-axis is considered the "up" direction. This method will do nothing if called more than once. By default OpenModel applications are not aware of the Alias project environment (for example, user_data/demo/wire etc). By passing TRUE as the second argument, the OpenModel application will become aware of the Alias project environment, expect such an environment to exist, and will use it for locating files. The .Alias* setup files will be read and processed. However, unlike Alias, when the OpenModel application starts, if the project environment does not exist, it will not be created, and the application will proceed in the default manner. Note that the arguments have no effect when initialization occurs under OpenAlias. That is, the world space coordinate system and the project environment are determined by the running Alias application.

Arguments
< up - indicates whether the y-axis (kYUp) or z-axis (kZUp) should be the up direction. If no argument is specified, the default is kZUp. This parameter has no effect when using OpenAlias. < initProjectEnv - indicates whether the OpenModel application is to be aware of the Alias project environment or not. The default if FALSE.

Return Codes
sSuccess - universe initialized sAlreadyCreated - the universe is already initialized sInsufficientMemory - not enough memory to initialize sFailure - could not initialize sNoProjectEnvironment - this will be the case if initProjEnv is TRUE and Alias project environment does not exist.

AlUniverse | 1001

boolean AlUniverse::isOldWireFile( const char *fileName ) Description

Determine if a file is an old Alias wire file.

Return values
TRUE - the indicated file is a valid Wire file FALSE - one of the arguments was invalid or the file was not a Wire file.

AlCoordinateSystem AlUniverse::coordinateSystem() Description

Returns the current world space coordinate system of the Universe. Note that once AlUniverse::initialize has been called, or while running under OpenAlias, the coordinate system will never change during "this" session.

Return values
kYUp - positive Y-axis is "up" kZUp - positive Z-axis is "up"

statusCode AlUniverse::expandFileName( char expandedName[], const char *fileName, AlDirectoryType directoryType ) Description
Given a filename, expands to an absolute pathname based on the files type and Alias project environment.

Arguments
> expandedName - location to return expanded filename. < fileName - name of the file to locate within the project environment. Must not contain leading slashes or dots. < directoryType - the type of project subdirectory where the file is located. (See AlUniverse.h for possible values.

1002 | Chapter 5 AlSet AlXEvents

Return Codes
sSuccess - the fully expanded name was successfully constructed and the file exists sInvalidArguments - the passed filename is already absolute (contains leading /), or is relative (contains leading ..), or the directory type is invalid sNoProjectEnvironment - the returned path does not exist. This may be because the Alias project environment does not exist in whole or in part. SFailure - either or both passed names were NULL

statusCode AlUniverse::wireFileWindowSize( int &sizeX, int &sizeY ) Description

Gets the window size that was retrieved on the previous call to AlUniverse::retrieve. This method is available only under OpenModel and fails under OpenAlias.

Return Codes
sSuccess - the store size was set sFailure - OpenAlias is in use sInvalidArgument - sizeX <=0 or sizeY <=0

statusCode AlUniverse::setWireFileWindowSize( int sizeX, int sizeY ) Description

Sets the window size that is written to the next call of AlUniverse::store. Note that these values are changed whenever a call to AlUniverse::retrieve is called. This method is available only under OpenModel and fails under OpenAlias.

Return Codes
sSuccess - the store size was set sFailure - OpenAlias is in use

AlUniverse | 1003

sInvalidArgument - sizeX <=0 or sizeY <=0

boolean AlUniverse::isWireFile( const char *fileName, char * vbuf ) Description

Determines if a file is an Alias wire file and finds the version number. Note: vbuf must be allocated and at least 8 characters.

Arguments
< filename - the name of the file to check > vbuf - if the file is an Alias wire file then this buffer will contain the version string

Return values
TRUE - the indicated file is a valid Wire file FALSE - one of the arguments was invalid or the file was not a Wire file

AlUniverse::AlFileType AlUniverse::fileType( const char *fileName ) Description

Determine a files type.

Arguments
< fileName - the name of the file to type check

Return values
kUnknown - file type is unknown and will be ignored by ::retrieve(). The file types listed below are available for import in both OpenModel and OpenAlias.
kWire Autodesk Wire File

kIges

Initial Graphics Exchange Standard

1004 | Chapter 5 AlSet AlXEvents

kVdais

Verband Der Automobilindustrie IGES Subset EDS/GM format

kC4x

kJamais

Japan Automobile Manufacturers Association IGES Subset Verband Der Automobilindustrie Freeform Surface Interface Drawing Exchange Format

kVdafs

kDxf

kStl

3D Systems SLA Format

The file types listed below are available for import only in OpenAlias.
kDes EDS/GM Data Exchange Standard

kTri

Autodesk Object Separated Triangle Format

kQuad

Autodesk Object Separated Quad Format

kProRender

Pro/Engineer Render File Format

kInventor

OpenInventor Metafile Subset V1.0

kObj

Autodesk TAV format

kEpsf

Adobe Encapsulated Postscript

kIllustrator :

Illustrator Format

kSlc

3D Systems Slice Format

AlUniverse | 1005

statusCode AlUniverse::retrieveOptions( AlRetrieveOptions &options ) Description

Gets the options used by AlUniverse::retrieve().

Arguments
> options - options that ::retrieve() will use when retrieving files

Return Codes
sSuccess - the options were returned successfully sInvalidArgument - options was NULL sFailure - AlUniverse was not initialized

statusCode AlUniverse::setRetrieveOptions( const AlRetrieveOptions &options ) Description

Sets the options used by AlUniverse::retrieve().

Arguments
< options - options that AlUniverse::retrieve() will use when retrieving files

Return Codes
sSuccess - the options were set correctly sInvalidArgument - options was NULL, or a parameter in options was out of range sFailure - AlUniverse was not initialized

statusCode AlUniverse::retrieve( const char *fileName ) Description

Retrieves an Alias Wire file and adds the objects stored in the file to the list of Alias AlDagNode objects. If fileName is NULL the file is read from stdin.

1006 | Chapter 5 AlSet AlXEvents

Note that if sInvalidWireFile is returned you are likely trying to retrieve a newer wire file than your application recognizes. In this case you should link your application with the OpenModel library distributed with the newer Alias.

Arguments
< fileName - the name of the file to be retrieved

Return Codes
sSuccess - the file was retrieved successfully sInsufficientMemory - not enough memory sFailure - the wire file could not be retrieved properly sInvalidWireFile - the file was not a compatible Alias wire file

statusCode AlUniverse::retrieve( const char *fileName,void(*progressCallback)(int) ) Description

This method is a variation of the AlUniverse::retrieve(const char *) method with the addition that it allows a retrieve progress callbackto be set. NOTES: 1. The function progressCallback() should be in the C name space within an extern "C" block. 2. The int number passed to the progress callback is expressed as a percentage value between 0 and 100. This number is a close approximation of the retrieval progress and will not be exact due to compression usedin the Alias wire file format.

Arguments:
< fileName - the name of the file to be retrieved

Return Codes:
sSuccess - the file was retrieved successfully sInsufficientMemory - not enough memory sFailure - the wire file could not be retrieved properly

AlUniverse | 1007

sInvalidWireFile - the file was not a compatible Alias wire file. sInvalidArgument - NULL parameter passed to method

const char* AlUniverse::lastWireFileRetrieved() Description

Returns the last wire file retrieved either by the API or by Alias. Note that the file name will not change to NULL if a delete all is done. NULL is returned if no files have been retrieved or if the function fails.

const char* AlUniverse::lastFileSaved() Description

Returns the name of the last file saved within Alias. If no file has been saved or the function failed, NULL will be returned. Also note that if the DT options are changed, this function will return NULL until after the next save. Note: this method will fail and always return NULL in OpenModel.

statusCode AlUniverse::store( const char * fileName, AlDagNode* dagNode ) Description

If the AlDagNode argument is absent or NULL then this method stores all the AlObjects in the universe to a file as an Alias Wire file. If the AlDagNode argument is not NULL then only the model below the AlDagNode is stored. If the AlDagNode is in the middle of a hierarchy, the AlDagNodes above the argument will also be stored so as to preserve transformations on the model.

Arguments
fileName - the name of the file to be stored dagNode - see description

Return Codes
sSuccess - the file was stored successfully sFailure - the wire file could not be stored properly

1008 | Chapter 5 AlSet AlXEvents

statusCode AlUniverse::storeActive( const char * fileName ) Description

Allows the user to store only those objects which are on the pick list.

Arguments
fileName - the name of the file to be stored

Return Codes
sSuccess - the file was stored successfully sFailure - the wire file could not be stored properly

AlDagNode* AlUniverse::firstDagNode() Description

Returns the first AlDagNode in the list of Alias AlDagNode objects (the DAG). NULL is returned if the list is empty.

AlSet* AlUniverse::firstSet() Description

Returns a pointer to the first set in this universe. Returns NULL if there are no sets in this universe.

AlCluster* AlUniverse::firstCluster() Description

Returns a pointer to the first cluster in this universe. Returns NULL if there are no clusters in this universe.

AlChannel* AlUniverse::firstChannel() Description

Returns the first channel in the list of all channels in the universe. This list is not in any particular order, although channels animating the same item will

AlUniverse | 1009

appear consecutively in the list. This method returns NULL if nothing in the universe is animated.

const char* AlUniverse::currentStage( void ) Description

Returns the name of the current stage.

statusCode AlUniverse::setCurrentStage( const char* name ) Description

Switches the current stage to the stage with the indicated name.

Arguments
name - the name of the stage to switch to

Return Codes
sSuccess - the stage was set to the indicated stage sFailure - the stage with the given name could not be found

statusCode AlUniverse::mergeStage( const char *name ) Description

Merges the current stage with another stage.

Arguments
name - the name of the stage to merge with

Return Codes
sSuccess - the stage was successfully merged sFailure - a stage with the given name could not be found or the merge operation failed

1010 | Chapter 5 AlSet AlXEvents

statusCode AlUniverse::mergeAllStages( void ) Description

Merges all of the stages into a single stage. The current stage is switched to the merged stage.

Return Codes
sSuccess - all of the stages were successfully merged sFailure - the merge operation failed or there were no stages to merge

statusCode AlUniverse::deleteStage( const char *name ) Description

Deletes the stage with the given name. Under OpenAlias, this operation will not delete the last stage if there is only one stage remaining.

Arguments
name - the name of the stage to delete

Return Codes
sSuccess - the stage was successfully deleted sFailure - there was no stage with the given name or the delete operation failed

statusCode AlUniverse::deleteAllStages( void ) Description

Deletes all stages. This operation will fail if there is only one stage remaining.

Return Codes
sSuccess - all of the stages were successfully deleted sFailure - the delete operation failed

AlUniverse | 1011

statusCode AlUniverse::stageVisibility( const char *name, boolean& on_or_off ) Description

Returns the visibility status of the indicated stage.

Arguments
< name - the name of the stage to examine > on_or_off - the variable to return the status in

Return Codes
sSuccess - the stage was found and its visibility status was returned sFailure - there was no stage with the given name

statusCode AlUniverse::setStageVisibility( const char *name, boolean on_or_off ) Description

Sets the visibility status of the indicated stage.

Arguments
name - the name of the stage to alter on_or_off - TRUE if the stage is visible

Return Codes
sSuccess - the stage was found and its visibility status was set sFailure - there was no stage with the given name

const char *AlUniverse::stageWindowSource( void ) Description

Returns the name of the currently active application window universe.

1012 | Chapter 5 AlSet AlXEvents

statusCode AlUniverse::setStageWindowSource( const char *name ) Description

Sets the window universe to the indicated stage. The window universe contains the windows you are looking through to see the objects in the current universe.

Arguments
name - the name of the stage to set the window universe to

Return Codes
sSuccess - the stage was found and the window universe was set sFailure - there was no stage with the given name

const char *AlUniverse::stageBackgroundSource( void ) Description

Returns the name of the current background source.

statusCode AlUniverse::setStageBackgroundSource( const char *name ) Description

Chooses which stage to take the background source from (the environment shader) that is used for rendering.

Arguments
name - the name of the stage to use

Return Codes
sSuccess - the stage was found sFailure - there was no stage with the given name

AlUniverse | 1013

statusCode AlUniverse::renameStage( const char* oldName, const char *newName ) Description

Renames the stage with the name oldName to newName. If NULL is specified for oldName, then the current stage is renamed.

Arguments
oldName - the name of the stage to rename newName - the new name for the stage

Return Codes
sSuccess - the stage was renamed sNameChangedToUniqueOne - the stage was renamed, but the newName was altered to be unique sInvalidArgument - the newName was NULL sFailure - the indicated stage could not be found

AlList* AlUniverse::stageNames( void ) Description

Returns an AlList (of AlNameItems) containing the names of all of the stages that are present.

statusCode AlUniverse::createNewStage( const char* name, char*& stagename ) Description

Creates a new stage and sets the current stage to the new stage. The name assigned to the stage is returned in stagename. Access to stagename is important when stage names are reused and a new unique name is selected. Note that stagename will be assigned to something that can change through calls in the API. So caution must be taken when using stagename in future calls. In addition, what stagename points to must not be modified since it is internal Alias data.

1014 | Chapter 5 AlSet AlXEvents

Arguments
< name - the name of the stage to create > stagename - pointer to created name

Return Codes
sSuccess - a new stage with the name name was created sNameChangedToUniqueOne - a new stage was created, although the newName was altered to be unique sFailure - a new stage could not be created

statusCode AlUniverse::retrieveStageSet( const char *stageSet, boolean deleteStages ) Description

Retrieves a stage set file.

Arguments
> stageSet - the name of the stage set file to be retrieved > deleteStages - if true, any existing stages will be deleted

Return Codes
sSuccess - the method succeeded in retrieving the stage set sFailure - the method failed sInvalidArgument - stageSet is NULL

statusCode AlUniverse::saveStageSet( const char *stageSet ) Description

Saves a stage set file. This method saves out all of the stages and their associated wire file names. If a stage has an associated wire file name that is NULL, this routines fails.

AlUniverse | 1015

Arguments
> stageSet - the name (with path) of the stage set file to be created

Return Codes
sSuccess - the method succeeded in saving the stage set sFailure - the method failed sInvalidArgument - stageSet is NULL

statusCode AlUniverse::setStageWireFileName( const char *stageName, const char *wireFileName ) Description

Sets the wire file name that is to be used for the stage when the stage set is written out using the saveStageSet() call. Note that this function will change the default name of the wire file in the store and retrieve dialog boxes in Alias.

Arguments
> stageName - the name of the stage > wireFileName - the name of the wire file

Return Codes
sSuccess - the method succeeded in setting the wire file for the stage sFailure - not a valid stage name or the setting of the wire file name failed sInvalidArgument - stageSet or wireFileName are NULL

const char* AlUniverse::stageWireFileName( const char *stageName ) Description

Returns the wire file name of stage 'stageName'. NULL is returned if the wire file is not set or if an error occurred.

1016 | Chapter 5 AlSet AlXEvents

Arguments
> stageName - the name of the stage

AlWindow *AlUniverse::firstWindow( void ) Description

Returns the first window layer.

statusCode AlUniverse::applyIteratorToWindows( AlIterator *iter, int& rc ) Description

Applies an iterator to each window.

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

Return Codes
sSuccess - the iterator was successfully applied to each window sInvalidArgument - iter was NULL

AlImagePlane* AlUniverse::firstImagePlane( void ) Description

Returns the first image plane.

statusCode AlUniverse::applyIteratorToImagePlanes( AlIterator* iter, int& rc ) Description

Applies an iterator to each image plane.

AlUniverse | 1017

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

Return Codes
sSuccess - the iterator was successfully applied to each image plane sInvalidArgument - iter was NULL

AlWindow* AlUniverse::currentWindow( void ) Description

Returns the currently active window.

AlWindow* AlUniverse::sbdWindow( void ) Description

Returns the current SBD window.

statusCode AlUniverse::blindData( int type, long& size, const char*& ptr ) Description
Retrieves the blind data for the universe. If there is no data, the size will be 0 and the pointer will be NULL.

Arguments
< type - the blind data type to find > size - the size of the blind data if found > ptr - a pointer to the blind data if found

Return Codes
sSuccess - the blind data type was found sFailure - the blind data type was not found

1018 | Chapter 5 AlSet AlXEvents

statusCode AlUniverse::blindData( int type, int index, long& size, const char*& ptr ) Description
Retrieves the blind data for the universe. If there is no data, the size will be 0 and the pointer will be NULL NOTE: If universes are merged then the resulting universe will have blind data for both universes. If there are two or more blind data packets with the same "type", the parameter 'index' can be used to access them.

Arguments
< type - the blind data type to find < index - the index of the blind data packet > size - the size of the blind data if found > ptr - a pointer to the blind data if found

Return Codes
sSuccess - the blind data type was found sFailure - the blind data type was not found sInvalidArgument - index was negative

statusCode AlUniverse::setBlindData( int type, long size, const char* ptr ) Description
Associates a block of data with the object. If a block of data is already associated with this object and this user_type, the old block is replaced by a reference to the new block. The old block of data is not deleted.

Arguments
type - the type of the blind data to set size - the size of the blind data ptr - a pointer to the blind data

AlUniverse | 1019

Return Codes
sSuccess - the blind data was set

statusCode AlUniverse::removeBlindData( int type ) Description

Removes the blind data from the universe with the indicated type. Note that the user is still responsible for the memory associated with this block of data.

Arguments
type - the blind data type to remove

Return Codes
sSuccess - the type was found and removed sFailure - the indicated type could not be found

statusCode AlUniverse::removeBlindData( int type, int index ) Description

Removes the blind data from the universe with the indicated type and index.

Arguments
< type - the blind data type to remove < index - the index of the blind data packet

Return Codes
sSuccess - the type was found and removed sFailure - the indicated type could not be found sInvalidArgument - index was negative

1020 | Chapter 5 AlSet AlXEvents

AlChannel* AlUniverse::nextChannel(AlChannel *curChannel ) Description

Returns the next channel in the global list of all channels that appears after the given channel curChannel.

Arguments
< curChannel - the channel in the list to obtain the next channel from

statusCode AlUniverse::nextChannelD(AlChannel *curChannel ) Description

Destructively points curChannel to the next channel in the global list of all channels that appear after the given channel. sFailure is returned if there is no next channel.

Arguments
< curChannel - the channel in the list to obtain the next channel from

Return Codes
sSuccess - curChannel now points to the next channel sFailure - the universe is not initialized or there is no next channel sInvalidArgument - curChannel is invalid or NULL

AlAction* AlUniverse::firstAction() Description

Returns the first action in the list of all actions in the universe. This list is not in any particular order, and in particular, if an action is added to or deleted from the universe, this list may be reordered. Returns NULL if there are no actions in this universe.

AlUniverse | 1021

AlAction* AlUniverse::nextAction( AlAction *curAction ) Description

Returns the next action in the global list of all actions that appears after the given action curAction. This list is not in any particular order, and in particular, if an action is added to or deleted from the universe, this list may be reordered.

Arguments
< curAction - the action in the list to obtain the next action from

AlLayer* AlUniverse::firstLayer() Description

Returns the first layer which refers to the default layer. This layer is always valid in the universe. NULL is returned if the universe is not initialized.

AlLayer* AlUniverse::nextLayer(AlLayer *curLayer) Description

Returns the layer following curLayer in the list of Alias AlLayer objects. NULL is returned if curLayer has no next layer.

Arguments
< curLayer - layer from which to walk forward

statusCode AlUniverse::nextLayerD(AlLayer *curLayer) Description

Destructively points 'curLayer' to the AlLayer following curLayer in the list of Alias layer objects.

Arguments
< curLayer - layer from which to walk forward

1022 | Chapter 5 AlSet AlXEvents

Return Codes
sSuccess - curLayer now points to the next layer sFailure - there is no next layer sInvalidArgument - curLayer was invalid

AlLayer *AlUniverse::layerByNumber(int layerID) Description

Returns a layer object for a given layer number. NULL is returned if the layerID does not exist.

Arguments
< layerID - the number of the layer

boolean AlUniverse::layersEnabled() Description

Checks if the layer functionality is enabled. True is returned if the functionality is enabled and false otherwise.

statusCode AlUniverse::setLayersEnabled(boolean enable) Description

Enables or disables the layer functionality temporarily. In the disabled state, the layers are only temporarily disabled. Their attributes and assignment of AlDagNodes restored with enabling layers. While disabling the layers, no information about layers is permanently lost.

Arguments
< enable - a value of true enables the layers and false disables it

Return Codes
sSuccess - the layer was enabled or disabled sFailure - the layer could not be disabled or enabled

AlUniverse | 1023

AlShader* AlUniverse::firstShader() Description

Returns the first AlShader in the list of Alias AlShader objects. NULL is returned if the list is empty.

AlShader* AlUniverse::nextShader( AlShader* curShader ) Description

Returns the AlShader following curShader in the list of Alias AlShader objects. NULL is returned if curShader has no next shader.

Arguments
< curShader - shader from which to walk forward

statusCode AlUniverse::nextShaderD( AlShader* curShader ) Description

Destructively points curShader to the AlShader following curShader in the list of Alias AlShader objects.

Arguments
< curShader - shader from which to walk forward

Return Codes
sSuccess - curShader now points to the next shader sFailure - there is no next shader sInvalidArgument - curShader was invalid

AlPerspectiveCamera* AlUniverse::firstCamera( void ) Description

Returns the first perspective camera.

1024 | Chapter 5 AlSet AlXEvents

AlPerspectiveCamera* AlUniverse::nextCamera( AlPerspectiveCamera* curCamera ) Description

Returns the next perspective camera following curCamera in the list of all cameras. NULL is returned if curCamera has no next perspective camera.

Arguments
< curCamera - the camera in the list to obtain the next camera from

statusCode AlUniverse::nextCameraD( AlPerspectiveCamera* curCamera ) Description

Destructively points 'curCamera' to the AlPerspectiveCamera following curCamera in the list of perspective cameras.

Arguments
< curCamera - the camera in the list to obtain the next camera from

Return Codes
sSuccess - curCamera now points to the next camera sFailure - there is no next camera sInvalidArgument - curCamera was invalid

AlLocator* AlUniverse::firstLocator() Description

Returns the first AlLocator in the list of Alias AlLocator objects. NULL is returned if the list is empty.

AlUniverse | 1025

AlLocator* AlUniverse::nextLocator(AlLocator *curLocator) Description

Returns the AlLocator following curLocator in the list of Alias AlLocator objects. NULL is returned if curLocator has no next locator.

Arguments
< curLocator - locator from which to walk forward

AlEnvironment* AlUniverse::firstEnvironment() Description

Returns the first AlEnvironment in the list of Alias AlEnvironment objects. NULL is returned if the list is empty.

statusCode AlUniverse::deleteAll() Description

Deletes all objects in the universe. After this operation ALL references to ALL objects will be invalid.

Return Codes
sSuccess - everything was successfully deleted sFailure - the universe was not initialized or the deletion failed

statusCode AlUniverse::deleteAllLocators() Description

Deletes all locators. After this operation ALL references to ALL AlLocators will be invalid.

Return Codes
sSuccess - everything was successfully deleted sFailure - the universe was not initialized or the deletion failed

1026 | Chapter 5 AlSet AlXEvents

AlConstructionEntity* AlUniverse::firstConstructionEntity() Description

Returns the first AlConstructionEntity in the list of Alias AlConstructionEntity objects. NULL is returned if the list is empty.

AlConstructionEntity* AlUniverse::nextConstructionEntity(AlConstructionEntity *curConstructionEntity) Description

Returns the AlConstructionEntity following curConstructionEntity in the list of Alias AlConstructionEntity objects. NULL is returned if curConstructionEntity has no next locator. Arguments: < curConstructionEntity - Construction Entity from which to walk forward

statusCode AlUniverse::nextConstructionEntityD(AlConstructionEntity *ce) Description:

Destructively points ce to the AlConstructionEntity following ce in the list of Alias AlConstructionEntity objects.

Arguments
< ce - construction entity from which to walk forward

Return Codes
sSuccess - ce now points to the next AlConstructionEntity sFailure - there is no next AlConstructionEntity sInvalidArgument - ce was invalid

AlUniverse | 1027

statusCode AlUniverse::deleteAllConstructionEntities() Description

Deletes all construction entities. After this operation ALL references to ALL AlConstructionEntities will be invalid.

Return Codes
sSuccess - everything was successfully deleted. sFailure - the universe was not initialized or the deletion failed.

AlLayer* AlUniverse::firstLayer() Description

Returns the first layer which refers to the default layer. This layer is always valid in the universe. NULL is returned if the universe is not initialized.

AlLayer* AlUniverse::nextLayer(AlLayer *curLayer) Description

Returns the layer following curLayer in the list of Alias AlLayer objects. NULL is returned if curLayer has no next layer.

Arguments
< curLayer - layer from which to walk forward

statusCode AlUniverse::nextLayerD(AlLayer *curLayer) Description

Destructively points 'curLayer' to the AlLayer following curLayer in the list of Alias layer objects.

Arguments
< curLayer - layer from which to walk forward

1028 | Chapter 5 AlSet AlXEvents

Return Codes
sSuccess - curLayer now points to the next layer sFailure - there is no next layer sInvalidArgument - curLayer was invalid

AlLayer *AlUniverse::layerByNumber(int layerID) Description

Returns a layer object for a given layer number. NULL is returned if the layerID does not exist.

Arguments
< layerID - the number of the layer

AlLayer * AlUniverse::creationLayer() Description

Returns the layer object of the creation layer. NULL is returned if the universe if not initialized.

statusCode AlUniverse::setCreationLayer(AlLayer *layer) Description

Makes the layer a creation layer. When a layer is made a creation layer, all its attributes temporarily become similar to the default layer. For example, an invisible layer becomes visible till it is a creation layer.

Return Codes
sSuccess - the layer was set as a creation layer sFailure - the layer was not set because either the layer functionality is disabled or the universe is not initialized. sInvalidArgument - the layer object is not valid.

AlUniverse | 1029

boolean AlUniverse::layersEnabled() Description

Checks if the layer functionality is enabled. True is returned if the functionality is enabled and false otherwise.

statusCode AlUniverse::setLayersEnabled(boolean enable) Description

Enables or disables the layer functionality temporarily. In the disabled state, the layers are only temporarily disabled. Their attributes and assignment of AlDagNode is restored with enabling layers. While disabling the layers, no information about layers is permanently lost.

Arguments
< enable - a value of true enables the layers and false disables it

Return Codes
sSuccess - the layer was enabled or disabled sFailure - the layer could not be disabled or enabled

statusCode AlUniverse::sortLayersInLayersBar(AlLayerSortMode sortMode) Description

Sorts the position of layer buttons in the layer bar in the increasing order.

Arguments
< sortMode

kLayerNumber - sort the buttons by their layer number kLayerName - sort the buttons by their layer name in the lexicographically increasing order

Return Codes
sSuccess - the layer buttons were sorted

1030 | Chapter 5 AlSet AlXEvents

sInvalidArgument - the value of sortMode is not valid sFailure - the universe is not initialized

statusCode AlUniverse::importCloudFile( const char *fileName, int samplingFactor) Description

Imports a cloud file.

Arguments
< fileName - the name of the cloud file to process < samplingFactor - controls the sample rate of cloud (a value from 1 to 100)

Return Codes
sInvalidArgument - sampling factor is not from 1 to 100, or fileName is NULL sSuccess - the cloud file was successfully imported sFailure - the operation failed or the universe has not been initialized

AlCloud *AlUniverse::firstCloud() Description

Returns the first cloud in the universe. NULL is returned if the method failed. This method would always fail if the universe has not been initialized.

int AlUniverse::numberOfClouds() Description

Returns the number of clouds in the universe. The universe must be initialized first for this method to work.

AlBlendCurve* AlUniverse::firstBlendCurve() Description

Returns the first blend curve in the universe. The universe must be initialized before this method will work.

AlUniverse | 1031

int AlUniverse::numberOfBlendCurves() Description

Returns the number of blend curves in the universe. The universe must be initialized first for this method to work

statusCode AlUniverse::redrawScreen( unsigned int flags ) Description

Redraws the modeling windows. Use it after you have completed an operation to see the results. Different parts of the display can be selectively updated by performing a bitwise OR of the following flags:

kRedrawInactive - redraw the inactive objects kRedrawActive - redraw the active objects kRedrawTemplate - redraw templated objects kRedrawWindows - OBSELETE kRedrawListers - redraw any open editors kRedrawNone - method will exit without performing any operations

To redraw everything use the following flag:

kRedrawAll = (kRedrawInactive | kRedrawActive | kRedrawTemplate | kRedrawWindows | kRedrawListers )

This routine succeeds in OpenAlias and fails in OpenModel.

Return Codes
sSuccess - able to redraw sInvalidArgument - flags are out of range sFailure - unable to redraw (this always occurs in OpenModel)

1032 | Chapter 5 AlSet AlXEvents

statusCode AlUniverse::applyIteratorToDagNodes( AlIterator* iter, int& rc ) Description

Applies an iterator to all DAG nodes. This does not recursively go down the DAG.

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

Return Codes
sSuccess - the iterator was successfully applied to each dagNode sInvalidArgument - iter was NULL sFailure - AlUniverse was not initialized

statusCode AlUniverse::applyIteratorToActions( AlIterator* iter, int& rc ) Description

Applies an iterator to each action.

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

Return Codes
sSuccess - the iterator was successfully applied to each action sInvalidArgument - iter was NULL sFailure - AlUniverse was not initialized

AlUniverse | 1033

statusCode AlUniverse::applyIteratorToChannels( AlIterator* iter, int& rc ) Description

Applies an iterator to each channel.

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

Return Codes
sSuccess - the iterator was successfully applied to each channel sInvalidArgument - iter was NULL sFailure - AlUniverse was not initialized

statusCode AlUniverse::applyIteratorToSets( AlIterator* iter, int& rc ) Description

Applies an iterator to each set.

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

Return Codes
sSuccess - the iterator was successfully applied to each set sInvalidArgument - iter was NULL sFailure - AlUniverse was not initialized

1034 | Chapter 5 AlSet AlXEvents

statusCode AlUniverse::applyIteratorToClusters( AlIterator* iter, int& rc ) Description

Applies an iterator to each cluster.

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

Return Codes
sSuccess - the iterator was successfully applied to each cluster sInvalidArgument - iter was NULL sFailure - AlUniverse was not initialized

statusCode AlUniverse::applyIteratorToShaders( AlIterator* iter, int& rc ) Description

Applies an iterator to each shader.

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

Return Codes
sSuccess - the iterator was successfully applied to each shader sInvalidArgument - iter was NULL sFailure - AlUniverse was not initialized

statusCode AlUniverse::applyIteratorToLocators(AlIterator *iter, int &rc) Description

Applies an iterator to each AlLocator defined in Alias.

AlUniverse | 1035

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

Return Codes
sSuccess - the iterator was successfully applied to each locator sInvalidArgument - 'iter' was NULL

statusCode AlUniverse::applyIteratorToLayers( AlIterator* iter, int& rc ) Description

Applies an iterator to all layers.

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

Return Codes
sSuccess - the iterator was successfully applied to each layer sInvalidArgument - 'iter' was NULL sFailure - AlUniverse was not initialized

statusCode AlUniverse::applyIteratorToClouds( AlIterator* iter, int& rc ) Description

Applies an iterator to all clouds.

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

1036 | Chapter 5 AlSet AlXEvents

Return Codes
sSuccess - the iterator was successfully applied to each cloud sInvalidArgument - 'iter' was NULL sFailure - AlUniverse was not initialized

statusCode AlUniverse::applyIteratorToBlendCurves( AlIterator* iter, int& rc ) Description

Applies an iterator to all blend curves.

Arguments
< iter - the iterator to apply > rc - the return value of the last application of the iterator

Return Codes:
sSuccess - the iterator was successfully applied to each blend curve sInvalidArgument - iter was NULL sFailure - AlUniverse was not initialized

statusCode AlUniverse::writeSDLNoAnimation( const char *filename, boolean store_active ) Description

This method outputs an SDL file for the entire universe if store_active is FALSE. If it is TRUE, then only the active objects in the current universe will be output to a file. In either case no animation will be output; the scene is evaluated at the current view frame which can be set using the AlViewFrame class methods.

Arguments
< filename - the base name of the SDL file to write to (including path if appropriate) < store_active - as described above

AlUniverse | 1037

Return Codes
sSuccess - the file(s) was/were successfully written sFailure - it was not possible to write the SDL file sInvalidArgument - the filename was NULL

statusCode AlUniverse::writeSDL( const char *filename, boolean store_active, double start, double end, double by ) Description
This method outputs an SDL file for the entire universe if store_active is FALSE. If it is TRUE, then only the active objects in the current universe will be output to a file. Animation will be written to the SDL file for the frame range given. If 'by' is zero then only a single frame will be output.

Arguments
< filename - the base name of the SDL file to write to (including path if appropriate) < store_active - as described above < start - the frame to start the animation at < end - the frame to end the animation at < by - the increment to get from start to end

Return Codes
sSuccess - the file(s) was/were successfully written sFailure - it was not possible to write the SDL file sInvalidArgument - the filename was NULL

double AlUniverse::currentTime() Description

Used during playback to return the value of the current frame.

1038 | Chapter 5 AlSet AlXEvents

statusCode AlUniverse::frameRange(AlFrameRangeType rangeType, double &start, double &end, double &by) Description
Determines the frame range for the current universe. The range type can be one of kFromPreviewWindow (gets the value from the Preview window, either kMinMax or kGlobal; based on the choice in the preview window - this is undefined for OpenModel), kMinMax (gets the actual start and end as defined by the animaiton on the objects), and kGlobal (gets the values entered by the user - again, undefined for OpenModel).

Arguments
rangeType - as described above start - frame at which the animation starts end - frame at which the animation ends by - the amount by which frames are incremented

Return Codes
sSuccess - the frame range was successfully determined sInvalidArgument - rangeType was not one of the legal values AlUniverse::AlApplicationMode AlUniverse::applicationMode()

AlUniverse::AlApplicationMode AlUniverse::applicationMode() Description

Returns the current mode that the Alias API is running in (kOpenModel or kOpenAlias). This is useful when writing code that is shared between OpenModel and OpenAlias.

statusCode AlUniverse::userPrefColor( int colorField, int &r, int &g, int &b) Description
Returns RGB values for the given color field. Color field constants are defined in AlUserColors.h. This method always fails in OpenModel.

AlUniverse | 1039

Arguments
< colorField - color field > r - red RGB value > g - green RGB value > b - blue RGB value

Return Codes
sSuccess - normal completion sFailure - an error occurred

statusCode AlUniverse::setUserPrefColor( int colorField, int r, int g, int b) Description

Sets RGB values for the given color field. Color field constants are defined in AlUserColors.h. This method always fails in OpenModel.

Arguments
< colorField - color field < r - red RGB value < g - green RGB value < b - blue RGB value

Return Codes
sSuccess - normal completion sFailure - an error occurred

boolean AlUniverse::constructionPlaneInEffect() Description

Returns TRUE if there is a construction plane in effect.

1040 | Chapter 5 AlSet AlXEvents

statusCode AlUniverse::constructionPlaneTransform( AlTM &tm ) Description

Returns the transformation matrix of the construction plane. This matrix will map a point in the construction plane to a point in world space.

Arguments
> tm - matrix where construction plane is returned

Return Codes
sFailure - method failed, or there is no construction plane in effect sSuccess - the method succeeded

AlCategory* AlUniverse::firstCategory() Description

Returns the head of the Category structure which is attached to the universe. This function will return NULL if, a) The universe is not initialized b) Layers are not initialized c) There are no categories

AlCategory* AlUniverse::nextCategory(AlCategory *curCategory) Description

This method returns the next category in the global list of all categories that appears after the given category curCategory.

Arguments
< curCategory - Category in the list to obtain the next category from

AlUniverse | 1041

AlUserCommand
Encapsulates the user defined interface to command history.

1042 | Chapter 5 AlSet AlXEvents

Synopsis

AlUserCommand | 1043

#include <AlUserCommand.h> class AlOutput virtual statusCode output( const void *data, int size ); virtual statusCode declareObject( AlObject *obj ); class AlInput virtual statusCode input( void *data, int size ); virtual int inputRemaining() const; virtual AlObject* resolveObject( AlObject *obj ); class AlUserCommand // overloaded user functions // do not call these directly or the command history may not be correctly // maintained // virtual ~AlUserCommand(); virtual int isValid(); virtual int execute(); virtual int declareReferences(); virtual int instanceDag( AlDagNode *oldDag, AlDagNode *newDag ); virtual int undo(); virtual int dagModified( AlDagNode *dag ); virtual int geometryModified( AlDagNode *dag ); virtual int curveOnSurfaceModified( AlCurveOnSurface *surf ); virtual int listModifiedDagNodes( const AlNotifyDagNode *dagMod, AlObject *obj ); virtual int debug( const char *prefix ); virtual void * asDerivedPtr(); virtual statusCode storeWire( AlOutput *output ); virtual statusCode storeSDL( ofstream &outputSDL ); virtual statusCode retrieveWire( AlInput *input ); virtual statusCode resolveWire( AlInput *input ); // for your own use virtual int type(); // general utility functions const char * name() const; AlCommand * command() const; // declare utility functions AlCommandRef* firstConstructorRef(); statusCode addConstructorRef( AlDagNode * ); statusCode addConstructorRef( AlCurveOnSurface *); statusCode addConstructorContact( AlDagNode *, AlContact * ); AlCommandRef* firstTargetRef(); statusCode addTargetRef( AlDagNode * );

1044 | Chapter 5 AlSet AlXEvents

statusCode addTargetRef( AlCurveOnSurface * ); statusCode addTargetContact( AlDagNode *, AlContact * ); statusCode deleteAllReferences(); boolean isDagNodeAConstructor( AlDagNode * ) const; boolean isDagNodeATarget( AlDagNode *, boolean includeCOS = FALSE ) const; boolean isCurveOnSurfaceAConstructor( AlCurveOnSurface *) const; boolean isCurveOnSurfaceATarget( AlCurveOnSurface *) const;

Description
This class contains the definitions required to define a user command history command. The developer will be implementing many of these functions and must follow the return value conventions of this class.

statusCode AlOutput::declareObject( AlObject *objectPtr ) Description

Used by the calling routine to declare that it references an AlObject pointer in its private data so that it can use the AlInput::relocateObject to relocate an object on the retrieve.

Arguments
< objectPtr - the pointer that is referenced

Return Codes
sSuccess - the method worked sFailure - the method failed.

AlData* resolveData( int type, int typeId ) AlObject *resolveObject() Description

This method is used by the AlUserCommand class to resolve pointers to AlObjects. Object resolution must be performed in the same order as object declaration. This preserves the object types that will be saved in the command.

AlUserCommand | 1045

AlCommand *AlUserCommand::command() const Description

Returns the parent command object. This may not be possible when the command is being initialized.

AlUserCommand::AlUserCommand() Description
Default constructor for the user data for a command.

AlUserCommand::~AlUserCommand() Description
A default destructor for the user command. This method is called whenever the command is about to be freed. It is the responsibility of this function to free all of the data contained in the command, including lists and geometry used locally. Care should be taken not to free data that is referenced elsewhere; for instance, in the DAG. This routine should only free data that is not referenced elsewhere.

int AlUserCommand::isValid() Description

Used to determine if a command is valid by returning a value. Examples of a command being invalid are: essential DAG pointers becoming NULL, input out of range or the geometry that this command depends on being modified in such a way that this command is no longer valid (for example, curve CVs are deleted until there are fewer than one span). The function returns 0 if the command is valid; otherwise, a non zero value indicates what is wrong with it. These values are defined by the specific command. An invalid command is freed when it is executed during an update of the construction history list. It can be freed when executing it explicitly if the execute function is told to do so.

1046 | Chapter 5 AlSet AlXEvents

int AlUserCommand::execute() Description

Called when the command should be executed. Before this function is executed, the isValid() method is called to ensure that the command is valid. Invalid commands are not executed. Most commands may behave differently if they are being called for the first time. For example, the fillet command saves a reference to a DAG node on the first call. If the command is re-executed, the previous DAG node pointer is used instead of the new one. This method returns 0 on success and non-zero on failure.

int AlUserCommand::undo() Description

Undoes what is done by the execution of the command. This may require the original execution of the command to record the state of the model before execution. It is valid not to define this method. This method returns 0 on success and non-zero on failure.

int AlUserCommand::declareReferences() Description

Appends constructor and target references to the command for each reference that it makes to the geometry in the model. Use the command() method to find the parent command. From the parent command, use the addTargetRef() and addConstructorRef() methods to create references to the geometry. The command system may dynamically free all references and ask the declareReferences() method to rebuild the list. It is very important that every reference be declared. Failing to do so may result in unpredictable behaviour in the user interface. This method returns 0 on success and non-zero on failure.

int AlUserCommand::instanceDag( AlDagNode *oldDag, AlDagNode *newDag ) Description

Changes all references to oldDag to newDag. This may involve walking the reference list for this command and changing the DAG node pointers to point to the new DAG node. This method returns 0 on success and non-zero on failure.

AlUserCommand | 1047

Arguments
< oldDag - the old DAG node to look for < newDag - the new DAG node to replace it with

int AlUserCommand::dagModified( AlDagNode *dag ) Description

Called whenever the DAG node passed in is modified. This usually means a transformation in the DAG node has changed. This function will only be called if the DAG node is present in the reference list for the command. Some commands do not need to implement this function, since they may only be required to execute after the DAG is modified. Only implement this command if the command block needs to be updated when the DAG is modified. It is valid not to define this method. This method returns 0 on success and non-zero on failure.

Arguments
< dag - the DAG node to update

int AlUserCommand::geometryModified( AlDagNode *dag ) Description

Called when the geometry beneath the DAG node is modified. An example is moving a CVs position or deleting a CV. Only implement this function if there is something that must be updated in the command block when the geometry on a DAG node is transformed. An example of this is a command that creates a local copy of the constructor geometry. If the local copy is not updated when the original is, then when the command is re-executed, the correct result will not appear. This method returns 0 on success and non-zero on failure. Note: This command, as well as dagModified(), should not rely on the geometry of the constructor being in a stable state. It is valid not to define this method.

1048 | Chapter 5 AlSet AlXEvents

int AlUserCommand::curveOnSurfaceModified( AlCurveOnSurface *surf ) Description

Called whenever the system modifies a curve on surface. If this command references the curve on surface parameter "surf", then it should return 1.

Arguments
< surf - the curve on surface to check

int AlUserCommand::listModifiedDagNodes( const AlNotifyDagNode *dagMod, AlObject *obj ) Description

Notifies Alias of any DAG nodes that will be modified if the given object is changed. The code fragment for the function will resemble the following:
int myCmd::listModifiedDagNodes( dagMod, AlObject *obj ) { for each dag node adag which will be affected when obj is modified { dagMod->notify( adag ); } }

It is valid not to define this method. This method returns 0 on success and non-zero on failure.

int AlUserCommand::debug( const char *prefix ) Description

Used for debugging purposes. This method should print out any relevant debugging information for this command and would be called from the implemented methods of AlUserCommand of the construction history plug-in. For each output line, print out the string in prefix first. It will contain spacing information, and so on. It is valid not to define this method. For example,

AlUserCommand | 1049

int myCmd::debug( const char *prefix ) { cerr << prefix << "The command contains" << this->myValue << cend; cerr << prefix << "and the value " << this->myOtherValue << cend; return 0; }

This method returns 0 on success and non-zero on failure.

statusCode AlUserCommand::storeWire( AlOutput *output ) Description

Outputs the contents of the command to be stored in the output Wire file. This function returns sSuccess if it was successful. The function is passed a memory stream to write the contents of the command to. OpenAlias will use the name() method to denote the command identifier to label this data chunk with. It is valid to call the AlOutput->output() multiple times. This method must be defined for objects to save correctly. Do not write the AlUserCommand structure out directly to disk. This will also write out virtual table pointers, and so on. First create a private data class which contains the data which will be written out to the wire file. Make your derived object inherit this private data class, then write out its portion instead. For example,

1050 | Chapter 5 AlSet AlXEvents

class myCmdData { this will enable us to get a pointer to the myCmdData section of our derived structure myCmdData *cmdDataPtr() { return this; } public: . AlDagNode *dag1; double value; }; class myCmd : public AlUserCommand, public myCmdData { ... public: . double MiscData; } myCmd:storeWire( AlOutput *wireOut ) { wireOut->output( cmdDataPtr(), sizeof( myCmdData ) ); wireOut->declareObject( myCmdData->dag1 ); wireOut->output( &MiscData, sizeof( MiscData ); final data is written to disk when we return }

Arguments
< output - the output method

Return Codes
sFailure - the method did not work sSuccess - the method worked

statusCode AlUserCommand::retrieveWire( AlInput *input ) Description

Unpacks the current command from the wire file. Returns sSuccess if the method worked. Note that the command() method may return NULL at this point in time. (It will be valid after the entire file has been loaded.) The retrieveWire routine is almost identical to the retrieve routine. For example,

AlUserCommand | 1051

myCmd:retrieveWire( AlInput *wireIn ) { wireIn->input( cmdDataPtr(), sizeof( myCmdData ) ); wireIn->input( &MiscData, sizeof( MiscData ); Note that we do not worry about AlObject pointers until later }

Arguments
< data - the block of data for you to unpack < size - the size of the data block

Return Codes
sFailure - the method did not work sSuccess - the method worked

statusCode AlUserCommand::storeSDL( ofstream &outputSDL ) Description

Outputs the command to an SDL file. This function is currently unused (it will never be called) and is present for future uses.

Arguments
< outputSDL - the output file stream for the SDL file

Return Codes
sFailure - the method did not work sSuccess - the method worked

int AlUserCommand::type() Description

User definable type field to be used with asDerivedPtr()

1052 | Chapter 5 AlSet AlXEvents

void *AlUserCommand::asDerivedPtr() Description

Provided for safe downcasting to your derived type, so no assumptions of the location of the derived data need to be made. Use this method in conjunction with the commandType(). For example,
switch( commandType() ) { case myCommandType: . myCommand *cmd = (myCommand *)asDerivedPtr(); .... } The pointer is declared as follows void * myDerivedCmd::asDerivedPtr() { return this; }

const char *AlUserCommand::name() const Description

Returns the name of the command, as specified when it was created.

AlCommandRef* AlUserCommand::firstConstructorRef() Description

Returns a wrapper to the first constructor reference.

AlCommandRef* AlUserCommand::firstTargetRef() Description

Returns a wrapper to the first target reference.

AlUserCommand | 1053

statusCode AlUserCommand::addConstructorRef( AlDagNode *dagNode ) Description

Adds a reference to a DAG node to the constructor list. To be used by the declare method.

Arguments
< dagNode - DAG node that is referenced

Return Codes
sSuccess - the reference was added sInvalidArgument - dagNode was invalid sFailure - the reference was not added sInvalidObject - the command was not valid

statusCode AlUserCommand::addConstructorRef( AlCurveOnSurface *curveOnSurface ) Description

Adds a reference to a curve on surface to the constructor list. To be used by the declare method.

Arguments
< curveOnSurface - curve on surface that is referenced

Return Codes
sSuccess - the reference was added sInvalidArgument - curveOnSurface was invalid sFailure - the reference was not added sInvalidObject - the command was not valid

1054 | Chapter 5 AlSet AlXEvents

statusCode AlUserCommand::addConstructorContact( AlDagNode *dagNode, AlContact *contact ) Description

Add a contact constructor to the constructor list. To be used by the declare method.

Arguments
< dagNode - DAG node that is referenced < contact - the contact

Return Codes
sSuccess - the reference was added sInvalidArgument - dagNode or contact was invalid sFailure - the reference was not added sInvalidObject - the command was not valid

statusCode AlUserCommand::addTargetRef( AlDagNode *dagNode ) Description

Adds a reference to a DAG node to the target list. To be used by the declare method.

Arguments
< dagNode - DAG node that is referenced

Return Codes
sSuccess - the reference was added sInvalidArgument - dagNode was invalid sFailure - the reference was not added sInvalidObject - the command was not valid

AlUserCommand | 1055

statusCode AlUserCommand::addTargetRef( AlCurveOnSurface *curveOnSurface ) Description

Adds a reference to a curve on surface to the target list. To be used by the declare method.

Arguments
< curveOnSurface - curve on surface that is referenced

Return Codes
sSuccess - the reference was added sInvalidArgument - curveOnSurface was invalid sFailure - the reference was not added sInvalidObject - the command was not valid

statusCode AlUserCommand::addTargetContact( AlDagNode *dagNode, AlContact *contact ) Description

Adds a contact target to the target list. To be used by the declare method.

Arguments
< dagNode - DAG node that is referenced < contact - the contact

Return Codes
sSuccess - the reference was added sInvalidArgument - dagNode or contact was invalid sFailure - the reference was not added sInvalidObject - the command was not valid

1056 | Chapter 5 AlSet AlXEvents

statusCode AlUserCommand::deleteAllReferences() Description

Deletes all reference from this command.

Return Codes
sSuccess - the command worked sInvalidObject - the current command is not valid

boolean AlUserCommand::isDagNodeAConstructor( AlDagNode* dagNode ) const Description

Returns TRUE if the given DAG node is a constructor of this command.

Arguments
< dagNode - the DAG node in question

boolean AlUserCommand::isDagNodeATarget( AlDagNode* dagNode, boolean includeCoS ) const Description

Returns TRUE if the given DAG node is a target of this command.

Arguments
< dagNode - the DAG node in question < includeCoS - if TRUE, also consider curves on surface which are children of the DAG node to be part of the DAG node

boolean AlUserCommand::isCurveOnSurfaceAConstructor( AlCurveOnSurface* curveOnSurface ) const Description

Returns TRUE if the given curve on surface is a constructor of this command.

AlUserCommand | 1057

Arguments
< curveOnSurface - the curve on surface in question

boolean AlUserCommand::isCurveOnSurfaceATarget( AlCurveOnSurface* curveOnSurface ) const Description

Returns TRUE if the given curve on surface is a target of this command.

Arguments
< curveOnSurface - the curve on surface in question

AlUserPickItem
An item of a list maintaining AlPickable objects.

Synopsis
#include <AlUserPickItem.h> class AlUserPickItem : public AlLinkItem AlUserPickItem( AlPickable& ); virtual ~AlUserPickItem(); AlUserPickItem* nextItem() AlUserPickItem* prevItem()

Description
This class is used in a list of objects maintained for the AlPickList::asynchronousPick() method. It is derived from AlLinkItem.

AlUserPickItem::AlUserPickItem( AlPickable& pickable ) Description

Instantiates and initializes an AlUserPickItem with a AlPickable object. The AlPickable wrapper is not kept by the AlUserPickItem, so it must be freed.

1058 | Chapter 5 AlSet AlXEvents

AlUserPickItem::~AlUserPickItem() Description
Deletes the AlUserPickItem. This method does not delete the AlPickable that it was initialized with.

AlUserPickList
An AlList for maintaining AlUserPickItems.

Synopsis
#include <AlUserPickList.h> class AlUserPickList : public AlList AlUserPickList( int keyState = 0 ) : fState(keyState) virtual ~AlUserPickList() int state() void setState( int keyState )

Description
This class is simply an AlList that maintains a list of AlUserPickItems, but with one addition; it is possible to set a key state for the list, where the key state is one of the kModifier #defines found in AlFunction.h (that is, kModifierControl, kModifierShift, kModifierAlt, and so on.). This allows for indicating to the selection code what modifier keys were pressed during the selection.

AlViewFrame
All the methods to do a viewframe operation.

AlUserPickList | 1059

Synopsis
#include <AlViewFrame.h> class AlViewFrame enum Options { kObject, kObjectAndAbove, kObjectAndBelow, kObjectAndAboveBelow }; static statusCode viewFrame(const double); static statusCode viewFrame(AlAnimatable*, const double,Options=kOb ject); static statusCode viewFrame(AlSurface*, const double, Options=kOb ject); static statusCode viewFrame(AlCurve*, const double, Options=kOb ject);

Description
This is a static class in that all of its member functions are static. It provides the functionality to do a viewframe on the entire universe or a single file. When doing a viewframe, it is important to remember that if the model contains construction history, fillet surfaces may be recreated. As a result, any existing AlSurfaceCVs from these surfaces will no longer be valid after the viewframe. They will not be deleted, but will instead be made inactive; all their methods will fail. Any object can be tested to see whether it is no longer active with the isValid() method. An inactive object may be deleted, or all inactive objects may be deleted with the AlUniverse::cleanUpUniverse() method. Please see the documentation on AlUniverse on page 993::cleanUpUniverse() for its possible side affects.

statusCode AlViewFrame::viewFrame(const double frame) Description

Views the universe at the frame time specified by "frame". All animated items in the universe will have their animation evaluated at the given frame time, and the animated parameters will now take on their new values. Note that if the model contains construction history, fillets and trims may be re-evaluated. This could cause any surface CV pointers to become invalid. After any

1060 | Chapter 5 AlSet AlXEvents

viewFrame, pointers to anything should not be trusted. If this is a problem, you should add a message handler for kMessageDagNodeReplaceGeometry.

Arguments
< frame - the time at which to evaluate the animation in the universe

Return Codes
sSuccess - the viewframe succeeded sFailure - an error occurred (that is, the universe may not have been initialized)

statusCode AlViewFrame::viewFrame( AlAnimatable* obj, const double frame, AlViewFrame::Options opts ) Description
Views the animatable object at the frame time specified by "frame". The object will have its animation evaluated at the given frame time, and the animated parameters will now take on their new values.

Arguments
< frame - the time at which to evaluate the animation < obj - object to view < opts - what to view ( kObject, kObjectAndAbove, kObjectAndBelow )

Return Codes
sSuccess - the viewframe succeeded sFailure - an error occurred (that is, the universe may not have been initialized)

statusCode AlViewFrame::viewFrame( AlCurve* curve, const double frame, AlViewFrame::Options opts ) Description
Views the CVs of the curve at the frame time specified by "frame". The curve CVs will have their animation evaluated at the given frame time, and the animated parameters will now take on their new values. A viewFrame is NOT done on the shaders and textures on the geometry below the curve.

AlViewFrame | 1061

Arguments
< frame - the time at which to evaluate the animation < curve - the curve to view

Return Codes
sSuccess - the viewframe succeeded sFailure - an error occurred (that is, the universe may not have been initialized)

statusCode AlViewFrame::viewFrame( AlSurface* surface, const double frame, AlViewFrame::Options opts ) Description
Views the CVs of the surface at the frame time specified by "frame". The surface CVs will have their animation evaluated at the given frame time, and the animated parameters will now take on their new values. A viewFrame will NOT be done on the shaders and textures on the geometry below the surface.

Arguments
< frame - the time at which to evaluate the animation < surface - the surface to view

Return Codes
sSuccess - the viewframe succeeded sFailure - an error occurred (that is, the universe may not have been initialized)

AlVolumeLight
Encapsulates the functionality common to all volume lights.

1062 | Chapter 5 AlSet AlXEvents

Synopsis

AlVolumeLight | 1063

#include <AlVolumeLight.h> class AlVolumeLight: public AlLight virtual ~AlVolumeLight(); virtual AlObject* copyWrapper() const; virtual AlObjectType type() const; boolean shadows() const; boolean specular() const; boolean turbulenceAnimated() const; boolean turbulenceDirectional() const; int turbulenceSpaceRes() const; int turbulenceTimeRes() const; double intensity() const; double decay() const; double decayStart() const; double directionality() const; double concentric() const; double directional() const; double radial() const; double dropoff() const; double dropoffStart() const; double turbulenceIntensity() const; double turbulenceSpread() const; double turbulencePersistance() const; double turbulenceGranularity() const; double turbulenceRoughness() const; double turbulenceVariability() const; statusCode setShadows(boolean); statusCode setSpecular(boolean); statusCode setTurbulenceAnimated(boolean); statusCode setTurbulenceDirectional(boolean); statusCode setTurbulenceSpaceRes(int); statusCode setTurbulenceTimeRes(int); statusCode setIntensity( double ); statusCode setDecay(double); statusCode setDecayStart(double); statusCode setDirectionality(double); statusCode setConcentric(double); statusCode setDirectional(double); statusCode setRadial(double); statusCode setDropoff(double); statusCode setDropoffStart(double); statusCode setTurbulenceIntensity(double); statusCode setTurbulenceSpread(double);

1064 | Chapter 5 AlSet AlXEvents

statusCode statusCode statusCode statusCode

setTurbulencePersistance(double); setTurbulenceGranularity(double); setTurbulenceRoughness(double); setTurbulenceVariability(double);

Description
There are two ways that this class is used. If the user instantiates and calls the create method on an AlVolumeLight, the resulting object is a box volume light. This light has all the special effects parameters in a cubic volume. Alternatively, the user could instantiate and create an AlSphereLight, AlCylinderLight, AlTorusLight, AlConeLight or AlBoxLight (which are all considered "volume" and which are all derived from this light class). Note that volume lights differ in their shape, the way that their direction components are interpreted with respect to that shape, and the way that dropoff and decay are applied.

AlVolumeLight::~AlVolumeLight() Description
Deletes an AlVolumeLight wrapper object.

AlObjectType AlVolumeLight::type() const Description

Returns the class identifier, kVolumeLightType.

boolean AlVolumeLight::shadows() const Description

Returns the volume lights shadow flag (that is, does the light cast shadows). This method returns FALSE if the light is not valid.

boolean AlVolumeLight::specular() const Description

Returns the volume lights specular flag (that is, will this light contribute to specular component). This method returns FALSE if the light is not valid.

AlVolumeLight | 1065

boolean AlVolumeLight::turbulenceAnimated() const Description

Returns the turbulence Animated flag. If the flag is TRUE, then a 4D turbulence table is built. Otherwise a 3D table is built. This method returns FALSE if the light is not valid.

boolean AlVolumeLight::turbulenceDirectional() const Description

Returns the turbulence Directional flag. If the flag is TRUE, then turbulence will be relative to the local light direction. This method returns FALSE if the light is not valid.

int AlVolumeLight::turbulenceSpaceRes() const Description

Returns the turbulence space Resolution (the size of the turbulence table in each dimension). -1 is returned if the light is not valid.

int AlVolumeLight::turbulenceTimeRes() const Description

Returns the turbulence time Resolution (the size of the turbulence table in time dimension). -1 is returned if the light is not valid.

double AlVolumeLight::intensity() const Description

Returns the volume lights intensity. -1 is returned if the light is not valid.

double AlVolumeLight::decay() const Description

Returns the volume lights decay. -1 is returned if the light is not valid.

1066 | Chapter 5 AlSet AlXEvents

double AlVolumeLight::decayStart() const Description

Returns the proportion of the distance from the center where the decay starts. -1 is returned if the light is not valid.

double AlVolumeLight::directionality() const Description

Returns the volume lights directionality. -1 is returned if the light is not valid.

double AlVolumeLight::concentric() const Description

Returns the relative strength of the concentric component of the light. -1 is returned if the light is not valid.

double AlVolumeLight::directional() const Description

Returns the relative strength of the directional component of the light. -1 is returned if the light is not valid.

double AlVolumeLight::radial() const Description

Returns the relative strength of the radial component of the light. -1 is returned if the light is not valid.

double AlVolumeLight::dropoff() const Description

Returns the volume lights dropoff. -1 is returned if the light is not valid.

AlVolumeLight | 1067

double AlVolumeLight::dropoffStart() const Description

Returns the portion of the distance from the center to where the dropoff starts. -1 is returned if the light is not valid.

double AlVolumeLight::turbulenceIntensity() const Description

Returns the lights turbulence intensity. -1 is returned if the light is not valid.

double AlVolumeLight::turbulenceSpread() const Description

Returns the lights turbulence spread (space scale). -1 is returned if the light is not valid.

double AlVolumeLight::turbulencePersistance() const Description

Returns the lights turbulence Persistence (time scale). -1 is returned if the light is not valid.

double AlVolumeLight::turbulenceGranularity() const Description

Returns the lights turbulence granularity (high-pass cutoff). -1 is returned if the light is not valid.

double AlVolumeLight::turbulenceRoughness() const Description

Returns the lights turbulence Roughness (low-pass space cutoff). -1 is returned if the light is not valid.

1068 | Chapter 5 AlSet AlXEvents

double AlVolumeLight::turbulenceVariability() const Description

Returns the lights turbulence Variability (low-pass time cutoff). -1 is returned if the light is not valid.

statusCode AlVolumeLight::setShadows(boolean shadows) Description

Sets the shadows flag.

Arguments
< shadows - TRUE if shadows are to be cast

Return Codes
sSuccess - setting shadows succeeded sInvalidObject - not a valid volume light

statusCode AlVolumeLight::setSpecular(boolean specular) Description

Sets the volume lights specular flag (that is, will this light contribute to specular component).

Arguments
< specular - TRUE if the light contributes to the specular component

Return Codes
sSuccess - setting specular succeeded sInvalidObject - not a valid volume light sFailure - setting failed

AlVolumeLight | 1069

statusCode AlVolumeLight::setTurbulenceAnimated(boolean animated) Description

Sets the turbulence Animated flag.

Arguments
< animated - TRUE if a 4D turbulence table is to be built - FALSE if a 3D table is to be built

Return Codes
sSuccess - setting the animated succeeded sInvalidObject - not a valid volume light sFailure - setting failed

statusCode AlVolumeLight::setTurbulenceDirectional(boolean directional) Description

Sets the turbulence Directional flag.

Arguments
< directional - TRUE if turbulence is relative to the local light direction

Return Codes
sSuccess - setting the turbulence flag succeeded sInvalidObject - not a valid volume light sFailure - setting failed

statusCode AlVolumeLight::setTurbulenceSpaceRes(int space_res) Description

Sets the turbulence space Resolution. Note that the product time_res*space_res should be <= 256 or you risk running out of swap space and patience.

1070 | Chapter 5 AlSet AlXEvents

Arguments
< space_res - the size of the turbulence table in each direction

Return Codes
sSuccess - setting space resolution succeeded sInvalidObject - not a valid volume light sInvalidArgument - space_res out of range 1..32 sFailure - setting failed

statusCode AlVolumeLight::setTurbulenceTimeRes(int time_res) Description

Sets the turbulence time Resolution. Note that the product time_res*space_res should be <= 256 or you risk running out of swap space and patience.

Arguments
< time_res - the size of the turbulence table in the time dimension

Return Codes
sSuccess - setting time resolution succeeded sInvalidObject - not a valid volume light sInvalidArgument - time_res out of range 1..32 sFailure - setting failed

statusCode AlVolumeLight::setIntensity(double intensity) Description

Sets the volume lights intensity.

Arguments
< intensity - the intensity of the light

AlVolumeLight | 1071

Return Codes
sSuccess - setting the intensity succeeded sInvalidObject - the light is not valid sFailure - setting failed

statusCode AlVolumeLight::setDecay(double decay) Description

Sets the volume lights decay (please see the volume light documentation in the Menu Book; this decay is significantly different from the standard light decay).

Arguments
< decay - the decay of the light (from 0 to 1)

Return Codes
sSuccess - setting decay succeeded sInvalidObject - not a valid volume light sInvalidArgument - decay out of range 0..1 sFailure - setting failed

statusCode AlVolumeLight::setDecayStart(double decay_start) Description

Sets the proportion of the distance from the center to where the decay starts.

Arguments
< decay_start - proportion of the distance from the center to the start

Return Codes
sSuccess - setting decay succeeded sInvalidObject - not a valid volume light sInvalidArgument - decay out of range 0..1

1072 | Chapter 5 AlSet AlXEvents

sFailure - setting failed

statusCode AlVolumeLight::setDirectionality(double directionality) Description

Sets the volume lights directionality.

Arguments
< directionality - this is from 0 to 1

Return Codes
sSuccess - setting directionality succeeded sInvalidObject - not a valid volume light sInvalidArgument - the directionality was out of the range 0..1 sFailure - setting failed

statusCode AlVolumeLight::setConcentric(double concentric) Description

Sets the relative strength of the concentric component of the light.

Arguments
< concentric - relative strength from 0 to 1

Return Codes
sSuccess - setting specular succeeded sInvalidObject - not a valid volume light sInvalidArgument - concentric out of range 0..1 sFailure - setting failed

AlVolumeLight | 1073

statusCode AlVolumeLight::setDirectional(double directional) Description

Sets the relative strength of the directional component of the light.

Arguments
< directional - the strength from 0 to 1

Return Codes
sSuccess - setting directional succeeded sInvalidObject - not a valid volume light sInvalidArgument - directional out of range 0..1 sFailure - setting failed

statusCode AlVolumeLight::setRadial(double radial) Description

Sets the relative strength of the radial component of the light.

Arguments
< radial - the strength from 0 to 1

Return Codes
sSuccess - setting radial succeeded sInvalidObject - not a valid volume light sInvalidArgument - radial out of range 0..1 sFailure - setting failed

statusCode AlVolumeLight::setDropoff(double dropoff) Description

Sets the volume lights dropoff.

1074 | Chapter 5 AlSet AlXEvents

Arguments
< dropoff - the dropoff from 0 to 50

Return Codes
sSuccess - setting volume succeeded sInvalidObject - not a valid volume light sInvalidArgument - volume out of range 0..50 sFailure - setting failed

statusCode AlVolumeLight::setDropoffStart(double dropoff_start) Description

Sets the portion of the distance from the center to where the dropoff starts.

Arguments
< dropoff_start - the distance from 0 to 1

Return Codes
sSuccess - setting dropoff succeeded sInvalidObject - not a valid volume light sInvalidArgument - dropoff out of range 0..1 sFailure - setting failed

statusCode AlVolumeLight::setTurbulenceIntensity(double intensity) Description

Sets the turbulence intensity.

Arguments
< intensity - the intensity to set

AlVolumeLight | 1075

Return Codes
sSuccess - setting intensity succeeded sInvalidObject - not a valid volume light sFailure - setting failed

statusCode AlVolumeLight::setTurbulenceSpread(double spread) Description

Sets the turbulence spread (on the space scale).

Arguments
< spread - the spread to set

Return Codes
sSuccess - setting spread succeeded sInvalidObject - not a valid volume light sFailure - setting failed

statusCode AlVolumeLight::setTurbulencePersistance(double persistance) Description

Sets the turbulence Persistence (on the time scale).

Arguments
< persistence - persistence to set

Return Codes
sSuccess - setting the Persistence succeeded sInvalidObject - not a valid volume light sFailure - setting failed

1076 | Chapter 5 AlSet AlXEvents

statusCode AlVolumeLight::setTurbulenceGranularity(double granularity) Description

Sets the turbulence granularity (high-pass cutoff).

Arguments
< granularity - granularity to set

Return Codes
sSuccess - setting granularity succeeded sInvalidObject - not a valid volume light sFailure - setting failed

statusCode AlVolumeLight::setTurbulenceRoughness(double roughness) Description

Sets the turbulence Roughness (low-pass space cutoff).

Arguments
< roughness - the roughness to set

Return Codes
sSuccess - setting roughness succeeded sInvalidObject - not a valid volume light sFailure - setting failed

statusCode AlVolumeLight::setTurbulenceVariability(double variability) Description

Sets the turbulence Variability (low-pass time cutoff).

Arguments
< variability - the variability to set

AlVolumeLight | 1077

Return Codes
sSuccess - setting Variability succeeded sInvalidObject - not a valid volume light sFailure - setting failed

AlWindow
Interface to the Alias modeling windows.

1078 | Chapter 5 AlSet AlXEvents

Synopsis

AlWindow | 1079

#include <AlWindow.h> class AlWindow : public AlObject , public AlAnimatable enum AlViewType { kViewInvalid, kViewOther, kFront, kBack, /* unused */ kRight, kLeft, /* unused */ kTop, kBottom, /* unused */ kSbd, kPerspective }; enum AlCornerType { kBottomLeft, kTopLeft, kTopRight, kBottomRight }; enum AlAspectType { kNoScale, kScaleY, kScaleX }; AlWindow(); virtual ~AlWindow(); virtual AlObjectType type() const; statusCode create( AlViewType ); virtual AlObject* copyWrapper() const; virtual statusCode deleteObject(); AlWindow* next() const; AlWindow* prev() const; statusCode nextD(); statusCode prevD(); statusCode windowType( AlViewType& ); statusCode isZoom( boolean& ); statusCode isVisible( boolean& ); virtual AlCamera* camera( void ); virtual statusCode setCamera( AlPerspectiveCamera* ); statusCode position( Screencoord&, Screencoord& ); statusCode setPosition( Screencoord, Screencoord ); statusCode resolution( Screencoord&, Screencoord& );

1080 | Chapter 5 AlSet AlXEvents

statusCode setResolution( Screencoord, Screencoord, AlCornerType = kTopLeft, AlAspectType = kNoScale ); statusCode priority( int& ); statusCode setPriority( int ); double gridSize(); statusCode setGridSize( double size ); virtual statusCode mapToWorldSpace( Screencoord, Screencoord, double&, double&, double&, double&, double&, double& ); virtual statusCode worldSpaceBounds( double&, double&, double&, double&, double&, double& ); static statusCode aliasWindowSize( int&, int& ); static statusCode aliasWindowPosition( int&, int& );

Description
Alias modeling windows are the windows in which geometry information is actually viewed and modified. These are the Top, Front, Right and Perspective windows, as well as the SBD window. This class allows the creation, positioning and sizing of windows. You can also get the camera associated with a window. In addition, plug-ins can use the mapping functions to determine where in world space a screen event occurred. AlUniverse contains methods for getting the first modeling window, the current modeling window, and the SBD window.

AlWindow::AlWindow() Description
Constructs an AlWindow wrapper object.

AlWindow::~AlWindow() Description
Deletes an AlWindow wrapper object.

AlObjectType AlWindow::type() const Description

Returns the class identifier kWindowType.

AlWindow | 1081

statusCode AlWindow::create( AlViewType tp ) Description

Creates a window with the specified view type. The possible view types are kFront, kRight, kTop, kPerspective, or kSbd.

Arguments
tp - the view type to create

Return Codes
sSuccess - the window was created sFailure - the window could not be created sInvalidArgument - an unknown view type was specified

AlObject* AlWindow::copyWrapper() const Description

Returns an exact duplicate of this AlWindow wrapper.

statusCode AlWindow::deleteObject() Description

Deletes the window.

Return Codes
sSuccess - the window was deleted sFailure - the window was not attached to a layer sInvalidObject - the window was not valid

AlWindow* AlWindow::next() const Description

Returns a pointer to the next AlWindow. Otherwise, returns NULL if there is no next window.

1082 | Chapter 5 AlSet AlXEvents

AlWindow* AlWindow::prev() const Description

Returns a pointer to the previous AlWindow. Otherwise, returns NULL if there is no previous window.

statusCode AlWindow::nextD() Description

Destructively points this wrapper to next window. If there is no such window, the object pointer is unaltered.

Return Codes
sSuccess - the wrapper points to the next window sFailure - there is no next window sInvalidObject - the window is invalid

statusCode AlWindow::prevD() Description

Destructively points this wrapper to the previous window. If there is no such window, the object pointer is unaltered.

Return Codes
sSuccess - the wrapper points to the previous window sFailure - there is no previous window sInvalidObject - the window is invalid

statusCode AlWindow::windowType( AlViewType& tp ) Description

Returns the view type of the current window.

AlWindow | 1083

Arguments
> tp - the variable to return the view type in

Return Codes
sSuccess - the view type was returned sInvalidObject - the window is invalid

statusCode AlWindow::isZoom( boolean& b ) Description

Returns TRUE if the window is zoomed.

Arguments
> b - the variable to return the status

Return Codes
sSuccess - the status was returned sInvalidObject - the window is invalid

statusCode AlWindow::isVisible( boolean& visible ) Description:

Use this method to find out if this window is visible. A window may be hidden by another.

Arguments:
> visible - the variable to return the result

Return Codes:
sSuccess - the status was returned sInvalidObject - the window is invalid

1084 | Chapter 5 AlSet AlXEvents

AlCamera* AlWindow::camera( void ) Description

Returns the effective camera of a modeling window. This function returns either: a) its camera if it has one. b) if the window is a MagnifyWindow, and the parent window has a camera, then that camera. c) NULL, if the window is null, or we couldnt find a camera using (a) or (b).

statusCode AlWindow::setCamera( AlPerspectiveCamera* cam ) Description

Sets the windows camera to the given perspective camera.

Arguments
cam - the perspective camera

Return Codes
sSuccess - the camera was set sInvalidObject - the window is invalid sInvalidArgument - the camera is invalid

statusCode AlWindow::position( Screencoord& x, Screencoord& y ) Description

Retrieves the position of a window.

Arguments
x,y - the variables to return the windows positions in

Return Codes
sSuccess - the position was returned

AlWindow | 1085

sInvalidObject - the window is invalid

statusCode AlWindow::setPosition( Screencoord x, Screencoord y ) Description

Sets the position of a window.

Arguments
x,y - the windows new position

Return Codes
sSuccess - the position was set sFailure - the window could not be moved sInvalidObject - the window is invalid

statusCode AlWindow::resolution( Screencoord& x, Screencoord& y ) Description

Retrieves the resolution of a window.

Arguments
x,y - the variables to return the windows resolution

Return Codes
sSuccess - the resolution was returned sInvalidObject - the window is invalid

statusCode AlWindow::setResolution( Screencoord x, Screencoord y, AlCornerType c, AlAspectType t ) Description

Sets the resolution of a window.

1086 | Chapter 5 AlSet AlXEvents

Arguments
x,y - the windows new resolution c - the corner that the window is relative to t - the scale aspect type (kNoScale, kScaleY, kScaleX)

Return Codes
sSuccess - the position was set sFailure - the window could not be moved sInvalidObject - the window is invalid

statusCode AlWindow::priority( int& p ) Description

Retrieves the priority of a window as a number ranging from 1 to 9. If a windows priority is not contained within a PRIORITYICON, it is implied to be 3.

Arguments
p - the variables to return the windows priority

Return Codes
sSuccess - the priority was returned sInvalidObject - the window is invalid

statusCode AlWindow::setPriority( int p ) Description

Sets the priority of a window, as a number of range [1..9]. If priority is out of range, nothing is changed and sFailure is returned.

Arguments
p - the windows new priority

AlWindow | 1087

Return Codes
sSuccess - the priority was set sFailure - the priority was out of range sInvalidObject - the window is invalid

statusCode AlWindow::mapToWorldSpace( Screencoord x, Screencoord y,double& rx1, double& ry1, double& rz1,double& rx2, double& ry2, double& rz2 ) Description
Maps a screen pixel (x,y) coordinate pair to world space coordinates (rx1,ry1,rz1)-(rx2,ry2,rz2). This function will always return sFailure in OpenModel.

Arguments
< x,y - the screen position > rx1,ry1,rz1 - one corner of the mapped area > rx2,ry2,rz2 - the other corner of the mapped area

Return Codes
sSuccess - the priority was set sFailure - the priority was out of range sInvalidObject - the window is invalid

statusCode AlWindow::worldSpaceBounds( double& xmin, double& ymin, double& zmin, double& xmax, double& ymax, double& zmax ) Description
Retrieves the bounding box of the window.

Arguments
> xmin, ymin, zmin - lower corner of the bounding box > xmax, ymax, zmax - upper corner of the bounding box

1088 | Chapter 5 AlSet AlXEvents

Return Codes
sSuccess - the priority was set sFailure - the priority was out of range sInvalidObject - the window is invalid

statusCode AlWindow::aliasWindowSize( int& sizex, int& sizey ) Description

Retrieves the size of the window. This function will always return sFailure in OpenModel.

Arguments
> sizex, sizey - the returned size

Return Codes
sSuccess - the size was returned sFailure - size could not be determined

statusCode AlWindow::aliasWindowPosition( int& posx, int& posy ) Description

Retrieves the position of the window. This function will always return sFailure in OpenModel.

Arguments
> posx, posy - the returned position

Return Codes
sSuccess - the position was returned sFailure - position could not be determined

AlWindow | 1089

double AlWindow::gridSize() Description

Retrieves the size of the grid in world coordinates.

statusCode AlWindow::setGridSize( double size ) Description

Sets the size of the grid (in world coordinates) of a window.

Arguments
size - the windows new grid size

Return Codes
sSuccess - the grid size was set sInvalidObject - the window is invalid

AlXevents
X event interface to the Alias API. ( This class is not available on NT.)

1090 | Chapter 5 AlSet AlXEvents

Synopsis
#include <AlXevents.h> class AlXevents static statusCode installHandler( int (*)( XEvent* ) ); static statusCode uninstallHandler( int (*)( XEvent* ) ); static XtAppContext getXtAppContext( void ); static Widget getAppShell( void ); static statusCode addXdevice( const char *, int (*)(Widget, XDeviceInfoPtr) ); static statusCode getXdevID( const char *, int& ); static statusCode getXdevType( const char *, const char *, int& ); static statusCode getXdevice( const char *, XDevice ** ); static statusCode addXdevID( const char *, XDevice *, int ); static statusCode addXdevType( char *, const char *, int, int ); static statusCode applicationNotify(); static boolean belowAliasWindow( Widget );

Description
This static class contains methods to handle custom X event handling in the Alias API.

statusCode AlXevents::applicationNotify() Description

Called by an interrupt handler to notify Alias that the handler has serviced the interrupt.

statusCode AlXevents::installHandler( int (*func)( XEvent* ) ) Description

Adds a callback handler for X events. The handler function will be passed every X event before Alias handles it. If the callback handler returns 0, then Alias will ignore the event. If it returns 1, then Alias will handle the event normally.

Arguments
func - callback pointer

AlXevents | 1091

Return Codes
sInvalidArgument - func was NULL sSuccess - the event handler was installed sFailure - the event handler was not installed

statusCode AlXevents::uninstallHandler( int (*func)( XEvent* ) ) Description

Removes a callback handler for X events.

Arguments
func - callback pointer to an installed handler

Return Codes
sInvalidArgument - func was NULL sSuccess - the event handler was uninstalled sFailure - the event handler could not be found

XtAppContext AlXevents::getXtAppContext( void ) Description

Returns Alias XtAppContext.

Widget AlXevents::getAppShell( void ) Description

Returns the application shell widget used by Alias. This widget should be used as a top level shell when creating custom dialog widgets for user interface interaction. Alias is responsible for processing and dispatching all events.

1092 | Chapter 5 AlSet AlXEvents

statusCode AlXevents::addXdevice( const char * name,int (*devXopen)(Widget, XDeviceInfoPtr) ) Description

Adds the named X device to the list of Alias devices.

Arguments
< name - the name of the device < devXopen - function to call on opening of device

Return Codes
sInvalidArgument - name was NULL sSuccess - the value was returned sFailure - the variable could not be found

statusCode AlXevents::getXdevID( const char * dev, int& value ) Description

Retrieves the value of the named device from the Alias device list.

Arguments
< name - the name of the device > value - the returned value

Return Codes
sInvalidArgument - name was NULL sSuccess - the value was returned sFailure - the variable could not be found

AlXevents | 1093

statusCode AlXevents::getXdevType( const char * dev, const char * event, int& value ) Description
Retrieves the value of the named device event from the Alias device list.

Arguments
< name - the name of the device < event - the name of the event ID wanted > value - the returned value

Return Codes
sInvalidArgument - name was NULL sSuccess - the value was returned sFailure - the variable could not be found

statusCode AlXevents::getXdevice( const char * dev, XDevice **xdev ) Description

Retrieves the value of the named device from the Alias device list.

Arguments
< name - the name of the device > xdev - pointer to the XDevice structure

Return Codes
sInvalidArgument - name was NULL sSuccess - the value was returned sFailure - the variable could not be found

1094 | Chapter 5 AlSet AlXEvents

statusCode AlXevents::addXdevID( const char *name, XDevice *xdev, int dev_id ) Description
Adds the named device to the Alias device list.

Arguments
< name - the name of the device < xdev - pointer to the XDevice structure < dev_id - X device ID

Return Codes
sInvalidArgument - name was NULL sSuccess - the value was returned sFailure - the variable could not be found

statusCode AlXevents::addXdevType( char *name, const char *type,int type_id, int class_id ) Description
Adds the named device event to the Alias device list.

Arguments
< name - the name of the device < event - the name of the event ID wanted < type id - the event type to add < class id - the event class to add

Return Codes
sInvalidArgument - name was NULL sSuccess - the value was returned sFailure - the variable could not be found

AlXevents | 1095

boolean AlXevents::belowAliasWindow( Widget w ) Description

Returns TRUE if Widget w is lower than the Alias window. Otherwise FALSE is returned.

1096 | Chapter 5 AlSet AlXEvents

Index
A
actions definition 97 adaptive 795 adaptive_max 795 adaptive_min 795 AlAction 97 ~AlAction() 98 copyD() 101 deleteObject() 98 setComment(const char *newComment) 99 setExtrapTypePOST(AlActionExtrapType extrapType) 100 setExtrapTypePRE(AlActionExtrapType extrapType) 100 setName(const char *newName) 99 AlAction* AlAction copy() const 101 AlAction* AlChannel appliedAction(const int n) const 194 AlAction* AlObject asActionPtr() 672 AlAction* AlUniverse firstAction() 1021 nextAction( AlAction *curAction ) 1022 AlActionExtrapType AlAction extrapTypePOST() const 100 extrapTypePRE() const 100 AlAimConstraint 103 ~AlAimConstraint() 104 AlAimConstraint() 104 AlAimConstraint* AlAimConstraint asAimConstraintPtr() 106 AlAimConstraint* AlObject asAimConstraintPtr() 672 AlAimConstraintAxis AlAimConstraint aimAxis( void ) const 106 upAxis( void ) const 106 AlAmbientLight 106 ~AlAmbientLight() 107 AlAmbientLight() 107 AlAmbientLight* AlAmbientLight asAmbientLightPtr() 108 AlAmbientLight* AlObject asAmbientLightPtr() 672 AlAngleLocator 109 ~AlAngleLocator() 110 AlAngleLocator(void) 110 AlAngleLocator* AlObject asAngleLocatorPtr() 686 AlAnimatable 114 AlAnimatable *AlLight asAnimatablePtr() 584 AlAnimatable *AlSurfaceCV asAnimatablePtr() 906 AlAnimatable* AlObject asAnimatablePtr() 672 AlAnnotationLocator 121 ~AlAnnotationLocator() 122 AlAnnotationLocator(void) 122 AlAnnotationLocator * AlObject asAnnotationLocatorPtr() 686 AlArcAttributes 126 AlArcAttributes* AlObject asArcAttributesPtr() 672 AlAreaLight 132 ~AlAreaLight() 134 AlAreaLight() 134 AlAreaLight* AlAreaLight asAreaLightPtr() 134 AlAreaLight* AlObject asAreaLightPtr() 672 AlAttributes 137 AlAttributes* AlAttributes asAttributesPtr() 138 nextAttribute() const 138 AlAttributes* AlCurve firstAttribute() const 309 AlAttributes* AlObject asAttributesPtr() 673

1097 | Index

AlAttributes* AlSurface 876 firstAttribute() const 876 AlBehaviourType AlContinuousFunction behaviour() const 486 AlBlendCurve 138 ~AlBlendCurve() 140 AlBlendCurve() 140 AlBlendCurve* AlBlendCurve prev() 146 AlBlendCurve* AlBlendPoint blendCurve() 161 AlBlendCurve* AlObject asBlendCurvePtr() 687 AlBlendCurve* AlUniverse firstBlendCurve() 1031 AlBlendPoint ~AlBlendPoint() 151 AlBlendPoint() 151 AlBlendPoint* AlBlendCurve getPoint 144 AlBlendPoint* AlBlendPoint next() 161 prev() 161 AlBlendPoint* AlObject asBlendPointPtr() 687 AlBoxLight 166 ~AlBoxLight() 167 AlBoxLight() 167 AlBoxLight* AlObject asBoxLightPtr() 673 AlCallBack *AlPlayBack setCallBack (AlCallBack *callBack) 749 AlCamera 169 ~AlCamera() 171 AlCamera* AlCameraNode camera() const 179 camera(AlTM& tm) const 179 AlCamera* AlObject asCameraPtr() 673 AlCamera* AlWindow camera( void ) 1085 AlCameraNode 177 ~AlCameraNode() 178

AlCameraNode* AlObject asCameraNodePtr() 673 AlCameraNode* AlPerspectiveCamera eye() const 719 up() const 719 view() const 719 AlCategory ~AlCategory() 181 AlCategory(void) 181 AlCategory* AlObject asCategoryPtr() 687 AlCategory* AlUniverse firstCategory() 1041 nextCategory 1041 AlChannel 180 ~AlChannel() 187 AlChannel() 187 AlChannel* AlAction channelReference(const int n) const 103 AlChannel* AlAnimatable firstChannel() const 115 nextChannel( const AlChannel *channel) const 116 prevChannel( const AlChannel *channel) const 116 AlChannel* AlChannel asChannelPtr() 190 copy(AlAnimatable *anima, int field) 190 AlChannel* AlObject asChannelPtr() 673 AlChannel* AlUniverse firstChannel() 1009 nextChannel(AlChannel *curChannel ) 1021 AlChannelDataType AlChannel channelType() const 190 AlCharacter 195 ~AlCharacter() 197 AlCharacter() 197 AlCharacter* AlCharacterSpace createCharacter(const char *characterName) 208 findCharacterByName(const char *characterName) 209

1098 | Index

firstCharacter(void) 209 nextCharacter(void) 210 AlCharacter* AlObject asCharacterPtr() 674 AlCharacterSpace 205 ~AlCharacterSpace() 206 AlCharacterSpace() 206 AlCharacterSpace* AlCharacterSpace asCharacterSpacePtr() 208 AlCharacterSpace* AlObject asCharacterSpacePtr() 674 AlCharSnippet 210 ~AlCharSnippet() 213 AlCharSnippet() 213 AlCharSnippet *AlCharSnippet copyObject() 213 AlCharSnippet* AlCharacter createSnippet(const char *snippetName) 199 findSnippetByName(const char *snippetName) 201 firstSnippet(void) 202 nextSnippet(void) 202 AlCharSnippet* AlObject asCharSnippetPtr() 673 AlCharTransition 218 ~AlCharTransition() 221 AlCharTransition *AlCharTransition copyObject() 221 AlCharTransition* AlCharacter createTransition(const char *transitionName) 200 findTransitionByName(const char *transitionName) 201 firstTransition(void) 202 nextTransition(void) 203 AlCharTransition* AlCharSnippet firstTransition(void) 216 nextTransition(void) 216 AlCharTransition* AlCharTransition asCharTransitionPtr() 222 AlCharTransition* AlObject asCharTransitionPtr() 674 AlCloud ~AlCloud() 228 AlCloud() 227

AlCloud *AlCloud nextCloud() const 238 AlCloud *AlUniverse firstCloud() 1031 AlCloud* AlObject asCloudPtr() 687 AlCluster 225 ~AlCluster() 240 AlCluster() 240 AlCluster* AlCluster asClusterPtr() 241 nextCluster() const 241 prevCluster() const 242 AlCluster* AlClusterable firstCluster() const 245 nextCluster( const AlCluster* lastCluster ) const 245 prevCluster( const AlCluster* lastCluster ) const 246 AlCluster* AlClusterMember cluster() const 253 AlCluster* AlClusterNode cluster() const 255 cluster(AlTM& tm) const 255 AlCluster* AlObject asClusterPtr() 674 AlCluster* AlUniverse firstCluster() 1009 AlClusterable 244 AlClusterable *AlCurveCV asClusterablePtr() 340 AlClusterable* AlObject asClusterablePtr() 674 AlClusterMember 250 ~AlClusterMember() 252 AlClusterMember* AlCluster firstMember() const 242 AlClusterMember* AlClusterable isClusterMember( AlCluster* cluster ) const 249 AlClusterMember* AlClusterMember nextClusterMember() const 252 prevClusterMember() const 252 AlClusterMember* AlObject asClusterMemberPtr() 674

Index | 1099

AlClusterNode 254 ~AlClusterNode() 254 AlClusterNode *AlCluster clusterNode() const 242 AlClusterNode* AlObject asClusterNodePtr() 675 AlClusterPreTMItem ~AlClusterPreTMItem() 256 AlCommand 256 ~AlCommand() 259 AlCommand() 259 AlCommand *AlCommand asCommandPtr() 259 AlCommand *AlUserCommand command() const 1046 AlCommand* AlObject asCommandPtr() 675 AlCommandRef 264 AlCommandRef 267 AlCommandRef* AlObject asCommandRefPtr() 675 AlCommandRef* AlUserCommand firstConstructorRef() 1053 firstTargetRef() 1053 AlConeLight 274 ~AlConeLight() 274 AlConeLight() 274 AlConeLight* AlConeLight asConeLightPtr() 275 AlConeLight* AlObject asConeLightPtr() 675 AlConicAttributes 276 AlConicAttributes* AlConicAttributes asConicAttributesPtr() 277 AlConicAttributes* AlObject asConicAttributesPtr() 675 AlConicType AlConicAttributes form() const 281 AlConstraint 281 ~AlConstraint() 282 AlConstraint* AlConstraint asConstraintPtr() 282 next() const 282 AlConstraint* AlDagNode firstConstraint 413

AlConstraint* AlObject asConstraintPtr() 675 AlContact ~AlContact() 269 AlContact() 269 AlContact *AlContact asContactPtr() 269 AlContact* AlContact nextContact() 270 prevContact() 270 AlContact* AlObject asContactPtr() 676 AlContactType AlContact contactType() const 271 AlContinuousFunction* AlContinuousFunction asContinuousFunctionPtr() 483 AlContinuousFunction* AlFunction asContinuousFunctionPtr() 481 AlCoordinateSystem AlUniverse coordinateSystem() 1002 AlCoordinateType AlContinuousFunction keyboardCoordinateMode() 490 AlCurve 301 ~AlCurve() 307 AlCurve() 306 AlCurve *AlContact curve() 272 curveUV() 273 AlCurve* AlCurve asCurvePtr() 307 AlCurve* AlCurveCV curve() const 346 AlCurve* AlCurveNode curve() const 355 curve(AlTM& tm) const 355 AlCurve* AlObject asCurvePtr() 676 AlCurve* AlSurface getModelSpaceSurfaceBoundary() const 899 getParamSpaceSurfaceBoundary() const 900 localBoundary( int ne ) const 900

1100 | Index

parameterBoundary( int ne ) const 901 AlCurve* AlTrimCurve affected3DCopy 975 getWorldSpaceCopy( double tolerance ) const 970 unaffected3DCopy 974 worldSpace3DCopy 974 AlCurveAttributes 334 AlCurveAttributes* AlObject asCurveAttributesPtr() 676 AlCurveCV 337 ~AlCurveCV() 340 AlCurveCV *AlCurveCV asCurveCVPtr() 340 AlCurveCV* AlCurve firstCV() const 308 AlCurveCV* AlCurveCV next() const 341 prev() 341 AlCurveCV* AlObject asCurveCVPtr() 676 AlCurveLocator 353 AlCurveLocator* AlObject asCurveLocatorPtr() 685 AlCurveNode 353 ~AlCurveNode() 354 AlCurveNode() 353 AlCurveNode* AlBlendCurve curveNode 146 AlCurveNode* AlCurve curveNode() const 307 AlCurveNode* AlCurveNode asCurveNodePtr() 355 AlCurveNode* AlIKHandle curveNode( void ) const 516 AlCurveNode* AlMotionAction motionCurve() const 659 AlCurveNode* AlObject asCurveNodePtr() 676 AlCurveNodeJoinErrors AlCurveNode join(AlCurveNode* curveNode) 355 AlCurveOnSurface 357 ~AlCurveOnSurface() 359 AlCurveOnSurface() 359

AlCurveOnSurface *AlCommandRef curveOnSurface() 268 AlCurveOnSurface* AlContact curveOnSurface() 272 AlCurveOnSurface* AlCurveOnSurface nextCurveOnSurface() const 366 prevCurveOnSurface() const 367 AlCurveOnSurface* AlObject asCurveOnSurfacePtr() 676 AlCurveOnSurface* AlSurface firstCurveOnSurface() const 895 AlCurveOnSurfaceLocator 377 AlCurveOnSurfaceLocator* AlObject asCurveOnSurfaceLocatorPtr() 685 AlCylinderLight 367, 377 ~AlCylinderLight() 378 AlCylinderLight() 378 AlCylinderLight* AlCylinderLight asCylinderLightPtr() 378 AlCylinderLight* AlObject asCylinderLightPtr() 677 AlDagNode 381 ~AlDagNode() 386 AlCopyOptions ~AlCopyOptions() 415 AlCopyOptions() 414 AlDagNode() 386 AlDagNode * AlDagNode searchAcross( const char * name ) const 412 searchBelow( const char * name ) const 411 AlDagNode * AlTrimRegion parentDagNode() const 980 AlDagNode *AlCommandRef dagNode() 268 AlDagNode *AlDagNode copyObject 414 copyObject( AlCopyOptions* options ) 387 AlDagNode* AlConstraint destinationNode( void ) const 284 sourceNode( void ) const 283 AlDagNode* AlDagNode asDagNodePtr() 387 nextNode() const 388

Index | 1101

prevNode() const 389 AlDagNode* AlGroupNode childNode() const 504 childNode(AlTM& tm) const 504 AlDagNode* AlIKHandle endEffectorNode( void ) const 516 rootNode( void ) const 515 AlDagNode* AlObject asDagNodePtr() 677 AlDagNode* AlPickList getParentOfObject() 733 AlDagNode* AlTrimBoundary parentDagNode() 967 AlDagNode* AlTrimCurve parentDagNode() 975 AlDagNode* AlUniverse firstDagNode() 1009 AlDeviationLocator 425 ~AlDeviationLocator() 427 AlDeviationLocator(void) 426 AlDeviationLocator* AlObject asDeviationLocatorPtr() 687 AlDirectionLight 434 ~AlDirectionLight() 434 AlDirectionLight() 434 AlDirectionLight* AlDirectionLight asDirectionLightPtr() 435 AlDirectionLight* AlObject asDirectionLightPtr() 677 AlDistanceLocator 436 ~AlDistanceLocator() 437 AlDistanceLocator(void) 437 AlDistanceLocator* AlObject asDistanceLocatorPtr() 686 AlEnvironment 458 ~AlEnvironment() 460 AlEnvironment* AlObject asEnvironmentPtr() 677 AlEnvironment* AlUniverse firstEnvironment() 1026 AlFace 465 ~AlFace() 466 AlFace() 466 AlFace* AlFace nextFace() const 468 prevFace() const 467

AlFace* AlFaceNode firstFace() const 473 firstFace(AlTM& tm) const 474 AlFace* AlObject asFacePtr() 677 AlFaceNode 471 ~AlFaceNode() 472 AlFaceNode() 472 AlFaceNode* AlFace faceNode() const 466 AlFaceNode* AlFaceNode asFaceNodePtr() 473 AlFaceNode* AlObject asFaceNodePtr() 677 AlFunction 476 ~AlFunction() 481 AlFunctionHandle 492 ~AlFunctionHandle() 494 AlFunctionHandle() 494 AlFunctionHandle& AlFunctionHandle operator =( const AlFunctionHandle& f ) 494 AlGroupNode 501 ~AlGroupNode() 503 AlGroupNode() 503 AlGroupNode *AlShell unstitchShell( void ) 833 AlGroupNode* AlDagNode parentNode() const 388 AlGroupNode* AlGroupNode nextInstance() const 505 prevInstance() const 505 AlGroupNode* AlObject asGroupNodePtr() 678 AlHierarchyType AlDagNode AlCopyOptions hierarchy() const 418 AlIKHandle 507 ~AlIKHandle() 510 AlIKHandle* AlIKHandleNode IKHandle() const 521 IKHandle(AlTM& tm) const 521 AlIKHandle* AlJoint endEffectorHandle( void ) const 546 firstRootHandle( void ) const 547

1102 | Index

nextRootHandle( const AlIKHandle* ali ) const 547 AlIKHandle* AlObject asIKHandlePtr() 678 AlIKHandleGoalType AlIKHandle goalType( void ) const 514 AlIKHandleNode 519 ~AlIKHandleNode() 520 AlIKHandleNode* AlObject asIKHandleNodePtr() 678 AlIKHandlePositionType AlIKHandle 517 positionType( void ) const 516 AlIKHandleRotationOrder AlIKHandle rotationOrder( void ) const 514 AlIKHandleSolverType AlIKHandle solverType( void ) const 514 AlIKHandleTwistType AlIKHandle 517 twistType( void ) const 516 AlImagePlane 521 ~AlImagePlane() 526 AlImagePlane() 526 AlImagePlane* AlCamera firstImagePlane( void ) 172 AlImagePlane* AlImagePlane next() const 527 nextInCamera() const 527 prev() const 527 prevInCamera() const 528 AlImagePlane* AlObject asImagePlanePtr() 678 AlImagePlane* AlUniverse firstImagePlane( void ) 1017 AlInputType AlContinuousFunction translateInput( int event, int &button ) 488 AlIntersect 538 AlIntersectCurveCurveInfo* AlIntersectCurveCurveInfo Next() const 540 AlIntersectCurveSurfInfo* AlIntersectCurveSurfInfo Next() const 540 AlIntersectSurfSurfInfo ~AlIntersectSurfSurfInfo() 540 AlIterator 544

AlJoint 544 ~AlJoint() 546 AlJoint* AlDagNode joint() const 411 AlJoint* AlIKHandle endEffector( void ) const 515 root( void ) const 515 AlJoint* AlJoint asJointPtr() 546 AlJoint* AlObject asJointPtr() 678 AlKeyframe 559 ~AlKeyframe() 560 AlKeyframe() 560 AlKeyframe *AlKeyframe next() const 565 prev() const 564 AlKeyframe* AlKeyframe asKeyframePtr() 561 AlKeyframe* AlObject asKeyframePtr() 678 AlKeyframe* AlParamAction firstKeyframe() const 697 lastKeyframe() const 698 AlLayer 567 AlLayer 571 AlLayer * AlUniverse creationLayer() 1029 AlLayer *AlUniverse layerByNumber 1023, 1029 AlLayer* AlDagNode layer() 412 AlLayer* AlObject asLayerPtr() 679 AlLayer* AlUniverse firstLayer() 1022, 1028 nextLayer 1022 nextLayer(AlLayer *curLayer) 1028 AlLight 582 ~AlLight() 584 AlLight *AlLightNode light() const 593 light(AlTM& tm) const 594 AlLight* AlObject asLightPtr() 679

Index | 1103

AlLightNode 591 ~AlLightNode() 592 AlLightNode *AlDirectionLight lookAtNode() const 435 upNode() const 435 AlLightNode *AlLight lightNode() const 587 lookAtNode() const 587 upNode() const 587 AlLightNode* AlObject asLightNodePtr() 679 AlLinearLight 594 ~AlLinearLight() 595 AlLinearLight() 595 AlLinearLight* AlObject asLinearLightPtr() 679 AlLineAttributes 598 AlLineAttributes* AlLineAttributes asLineAttributesPtr() 598 AlLineAttributes* AlObject asLineAttributesPtr() 679 AlLinkItem 600 ~AlLinkItem() 601 AlList 601 ~AlList() 602 AlList( AlLinkItem *item ) 602 AlList* AlAnimatable globalParamList() 120 localParamList() 120 AlList* AlDagNode clusterPreTransformationMatrices()413 AlList* AlEnvironment fields() const 463 mappedFields() const 463 AlList* AlShader fields() const 823 mappedFields() const 823 AlList* AlTexture fields() const 942 mappedFields() const 942 AlList* AlUniverse stageNames( void ) 1014 AlLiveData 603 AlLocator ~AlLocator() 615 AlLocator(void) 615

AlLocator* AlObject asLocatorPtr() 684 AlLocator* AlUniverse firstLocator() 1025 nextLocator 1026 AlMappedFieldItem 619 AlMappedFieldItem* AlMappedFieldItem nextField() const 620 AlMeasure 620 AlMessage 636 AlMessageTypeHandle ~AlMessageTypeHandle() 639 AlMessageTypeHandle( const AlMessageTypeHandle& h ) 638 AlMessageTypeHandle( void ) 638 AlMessageTypeHandle AlMessage addMessageType( const char * name ) 645 AlMessageTypeHandle& AlMessageTypeHandle operator =(const AlMessageTypeHandle& h ) 639 AlMinmaxLocator 646 ~AlMinmaxLocator() 648 AlMinmaxLocator(void) 647 AlMinmaxLocator* AlObject asMinmaxLocatorPtr() 687 AlMomentaryFunction* AlFunction asMomentaryFunctionPtr() 481 AlMomentaryFunction* AlMomentaryFunction asMomentaryFunctionPtr() 482 AlMotionAction 657 ~AlMotionAction() 658 AlMotionAction() 658 definition 98 AlMotionAction* AlObject asMotionActionPtr() 679 AlNameItem 659 AlNameItem 660 AlNameItem* AlNameItem nextItem() const 660 prevItem() const 660

1104 | Index

AlNonAmbientLight 660 AlNonAmbientLight* AlNonAmbientLight asNonAmbientLightPtr() 661 AlNonAmbientLight* AlObject asNonAmbientLightPtr() 680 AlNotifyDagNode 663 AlObject 665 ~AlObject() 670 AlObject * AlMotionAction copyWrapper() const 658 AlObject *AlAimConstraint copyWrapper() const 104 AlObject *AlAngleLocator copyWrapper() const 111 AlObject *AlAnnotationLocator copyWrapper() const 122 AlObject *AlBlendCurve copyWrapper() 140 AlObject *AlBlendPoint copyWrapper() 151 AlObject *AlCamera copyWrapper() const 171 AlObject *AlCloud copyWrapper() 228 AlObject *AlCurve copyWrapper() const 307 AlObject *AlCurveOnSurface copyWrapper() const 360 AlObject *AlDagNode copyWrapper() const 387 AlObject *AlDeviationLocator copyWrapper() const 427 AlObject *AlDistanceLocator copyWrapper() const 437 AlObject *AlEnvironment copyWrapper() const 460 AlObject *AlFace copyWrapper() const 466 AlObject *AlIKHandle copyWrapper() const 511 AlObject *AlJoint copyWrapper() const 546 AlObject *AlKeyframe copyWrapper() const 561

AlObject *AlLightNode copyWrapper() const 593 AlObject *AlMinmaxLocator copyWrapper() const 648 AlObject *AlObject copyWrapper() const 671 AlObject *AlOrientationConstraint copyWrapper() const 691 AlObject *AlPerspectiveCamera copyWrapper() const 717 AlObject *AlPointConstraint copyWrapper() const 752 AlObject *AlRadialLocator copyWrapper() const 758 AlObject *AlSetMember copyWrapper() const 809 object() const 810 AlObject *AlShader copyWrapper() const 819 AlObject *AlShell copyWrapper() const 831 AlObject *AlShellNode copyWrapper() const 838 AlObject *AlSurface copyWrapper() const 866 AlObject *AlTexture copyWrapper() const 936 AlObject *AlTrimBoundary copyWrapper() const 965 AlObject *AlTrimCurve copyWrapper() const 970 AlObject *AlTrimRegion copyWrapper() const 980 AlObject* AlArcAttributes copyWrapper() const 127 AlObject* AlAttributes copyWrapper() const 138 AlObject* AlCameraNode copyWrapper() const 178 AlObject* AlCategory copyWrapper() 181 AlObject* AlChannel animatedItem() const 190 AlObject* AlCharacter copyWrapper() const 197

Index | 1105

AlObject* AlCharacterSpace copyWrapper() const 207 AlObject* AlCharSnippet copyWrapper() const 213 AlObject* AlCharTransition copyWrapper() const 221 AlObject* AlClusterMember copyWrapper() const 252 object() const 253 AlObject* AlClusterNode copyWrapper() const 254 AlObject* AlConicAttributes copyWrapper() const 277 AlObject* AlCurveAttributes copyWrapper() const 335 AlObject* AlCurveCV copyWrapper() const 340 AlObject* AlCurveNode copyWrapper() const 354 AlObject* AlFaceNode copyWrapper() const 473 AlObject* AlGroupNode copyWrapper() const 503 AlObject* AlIKHandleNode copyWrapper() const 520 AlObject* AlImagePlane copyWrapper() const 527 AlObject* AlLayer copyWrapper() const 571 AlObject* AlLight firstLinkedObject() const 588 nextLinkedObject( AlObject* toThis ) const 589 AlObject* AlLineAttributes copyWrapper() const 598 AlObject* AlOrthographicCamera copyWrapper() const 694 AlObject* AlParamAction copyWrapper() const 697 AlObject* AlPickList getObject() 733 AlObject* AlPlaneAttributes copyWrapper() const 745 AlObject* AlRevSurfAttributes copyWrapper() const 801

AlObject* AlSet copyWrapper() const 804 AlObject* AlSurfaceCV copyWrapper() const 906 AlObject* AlSurfaceNode copyWrapper() const 925 AlObject* AlTextureNode copyWrapper() const 947 AlObjectType AlAction type() const 98 AlObjectType AlAimConstraint type() const 105 AlObjectType AlAmbientLight type() const 108 AlObjectType AlAngleLocator type() const 111 AlObjectType AlAnnotationLocator type() const 122 AlObjectType AlArcAttributes type() const 127 AlObjectType AlAreaLight type() const 134 AlObjectType AlAttributes type() const 138 AlObjectType AlBlendCurve type() 142 AlObjectType AlBlendPoint type() 151 AlObjectType AlBoxLight type() const 167 AlObjectType AlCamera type() const 171 AlObjectType AlCameraNode type() const 179 AlObjectType AlCategory type() 181 AlObjectType AlCharacter type() 198 AlObjectType AlCharacterSpace type() const 208 AlObjectType AlCharSnippet type() const 215 AlObjectType AlCharTransition type() const 222 AlObjectType AlCloud type() 228

1106 | Index

AlObjectType AlCluster type() const 241 AlObjectType AlClusterMember type() const 252 AlObjectType AlClusterNode type() const 255 AlObjectType AlCommand type() const 259 AlObjectType AlCommandRef type() 267 AlObjectType AlConeLight type() const 275 AlObjectType AlConicAttributes type() const 277 AlObjectType AlConstraint type() const 282 AlObjectType AlContact type() const 269 AlObjectType AlCurve type() const 307 AlObjectType AlCurveAttributes type() const 335 AlObjectType AlCurveCV type() const 340 AlObjectType AlCurveNode type() const 354 AlObjectType AlCurveOnSurface type() const 360 AlObjectType AlCylinderLight type() const 378 AlObjectType AlDagNode type() const 387 AlObjectType AlDeviationLocator type() const 427 AlObjectType AlDirectionLight type() const 435 AlObjectType AlDistanceLocator type() const 438 AlObjectType AlEnvironment type() const 460 AlObjectType AlFace type() const 467 AlObjectType AlFaceNode type() const 473 AlObjectType AlGroupNode type() const 504

AlObjectType AlIKHandle type() const 511 AlObjectType AlIKHandleNode type() const 520 AlObjectType AlJoint type() const 546 AlObjectType AlKeyframe type() const 561 AlObjectType AlLayer type() const 572 AlObjectType AlLight type() const 585 AlObjectType AlLightNode type() const 593 AlObjectType AlLinearLight type() const 596 AlObjectType AlLineAttributes type() const 598 AlObjectType AlLocator type() const 616 AlObjectType AlMinmaxLocator type() const 648 AlObjectType AlMotionAction type() const 659 AlObjectType AlNonAmbientLight type() const 661 AlObjectType AlOrientationConstraint type() const 692 AlObjectType AlOrthographicCamera type() const 695 AlObjectType AlParamAction type() const 697 AlObjectType AlPerspectiveCamera type() const 718 AlObjectType AlPlaneAttributes type() const 744 AlObjectType AlPointConstraint type() const 753 AlObjectType AlPointLight type() const 754 AlObjectType AlRadialLocator type() const 759 AlObjectType AlRevSurfAttributes type() const 801 AlObjectType AlSet type() const 805

Index | 1107

AlObjectType AlSetMember type() const 809 AlObjectType AlShader type() const 819 AlObjectType AlShell type() const 831 AlObjectType AlShellNode type() const 838 AlObjectType AlSphereLight type() const 845 AlObjectType AlSpotLight type() const 848 AlObjectType AlSurface type() const 866 AlObjectType AlSurfaceCV type() const 906 AlObjectType AlSurfaceNode type() const 926 AlObjectType AlTexture type() const 936 AlObjectType AlTextureNode type() const 947 AlObjectType AlTorusLight type() const 963 AlObjectType AlTrimBoundary type() const 966 AlObjectType AlTrimCurve type() const 970 AlObjectType AlTrimRegion type() const 980 AlObjectType AlVolumeLight type() const 1065 AlObjectType AlWindow type() const 1081 AlObserver 688 AlOrientationConstraint AlOrientationConstraint() 691 AlOrientationConstraint* AlObject asOrientationConstraintPtr() 680 AlOrientationConstraint* AlOrientationConstraint asOrientationConstraintPtr() 693 AlOrthographicCamera 693 ~AlOrthographicCamera() 694 AlOrthographicCamera() 694

AlOrthographicCamera* AlObject asOrthographicCameraPtr() 680 AlOrthographicCamera* AlOrthographicCamera asOrthographicCameraPtr() 695 AlParamAction 695 ~AlParamAction() 697 AlParamAction() 697 definition 98 AlParamAction* AlChannel applyWarpO() 193 AlParamAction* AlObject asParamActionPtr() 680 AlParamAction* AlParamAction asParamActionPtr() 697 AlParamControlType AlDagNode AlCopyOptions\ \ parameterControl() const 418 AlPerformance 701702 AlPrecisionType AlPerformance motionPrecision( void ) 704 redrawPrecision( void ) 704 AlPersistentID 714 ~AlPersistentID() 715 AlPersistentID( int value0, int value1, int value2, int value3 ) 715 AlPersistentID() 714 AlPersistentID(AlPersistentID &that) 715 AlPersistentID &AlPersistentID operator=( const AlPersistentID &that ) 715 AlPerspectiveCamera 715 ~AlPerspectiveCamera() 717 AlPerspectiveCamera() 717 AlPerspectiveCamera* AlObject asPerspectiveCameraPtr() 680 AlPerspectiveCamera* AlPerspectiveCamera asPerspectiveCameraPtr() 718 AlPerspectiveCamera* AlUniverse firstCamera 1024 nextCamera 1025

1108 | Index

AlPickable 730 ~AlPickable() 731 AlPickable() 731 AlPickable *AlPickable pickablePtr() 731 AlPickable* AlObject asPickablePtr() 680 AlPickList 732 AlPixFile AlPixFile 741 AlPlaneAttributes* AlObject asPlaneAttributesPtr() 681 AlPlaneAttributes* AlPlaneAttributes asPlaneAttributesPtr() 745 AlPlayBack 746 AlPlayFrame 749 ~AlPlayFrame () 750 AlPlayFrame (boolean bAllChannels) 750 AlPointConstraint 751 ~AlPointConstraint() 751 AlPointConstraint() 751 AlPointConstraint* AlObject asPointConstraintPtr() 681 AlPointConstraint* AlPointConstraint asPointConstraintPtr() 753 AlPointLight 753 ~AlPointLight() 754 AlPointLight() 754 AlPointLight* AlObject asPointLightPtr() 681 AlPointLocator *AlAngleLocator endLocator() const 112 middleLocator() const 112 startLocator() const 112 AlPointLocator *AlDistanceLocator endLocator() const 439 startLocator() const 438 AlPointLocator* AlObject asPointLocatorPtr() 685 AlPrintf 755 AlProduct 757 AlRadialLocator 757 ~AlRadialLocator() 758 AlRadialLocator(void) 758

AlRadialLocator* AlObject asRadialLocatorPtr() 686 AlRender 763 AnimationRange AlRender animationRange() 768 Image DepthFormat AlRender Image depthFormat() 785 Fields AlRender Image fields() 785 Format AlRender Image format() 784 Misc GeometrySource AlRender\ \ Misc\ \ geometrySource()781 Quality AlRender qualityType() 770 Scope AlRender hiddenLineParms() 769 qualityScope() 770 Source AlRender render() 767 Subdivision Type AlRender\ \ Subdivision\ \ type( AlRender\ \ Quality q 1) 7 7 AlRenderInfo 794 AlRetrieveOptions 796 AlRevSurfAttributes 800 AlRevSurfAttributes* AlObject asRevSurfAttributesPtr() 681

Index | 1109

AlRevSurfAttributes* AlRevSurfAttributes asRevSurfAttributesPtr() 801 AlSet 803 ~AlSet() 804 AlSet() 804 AlSet* AlObject asSetPtr() 681 AlSet* AlSet asSetPtr() 805 nextSet() const 806 prevSet() const 806 AlSet* AlSetMember set() const 811 AlSet* AlSettable firstSet() const 812 nextSet( const AlSet* lastSet ) const 812 prevSet( const AlSet* lastSet ) const 813 AlSet* AlUniverse firstSet() 1009 AlSetMember 808 ~AlSetMember() 809 AlSetMember *AlSet firstMember() const 808 AlSetMember *AlSetMember asSetMemberPtr() 809 AlSetMember *AlSettable isSetMember( const AlSet *set ) const 815 AlSetMember* AlObject asSetMemberPtr() 682 AlSetMember* AlSetMember nextSetMember() const 809 prevSetMember() const 810 AlSettable 811 AlSettable* AlObject asSettablePtr() 681 AlShader 816 ~AlShader() 818 AlShader() 818 AlShader *AlShader copyObject() 825 AlShader* AlFace firstShader() const 468

nextShader( AlShader* last_shader ) const 469 AlShader* AlObject asShaderPtr() 682 AlShader* AlShell firstShader() const 833 nextShader( const AlShader* last_shader ) const 833 AlShader* AlSurface firstShader() const 892 nextShader( const AlShader* last_shader ) const 893 AlShader* AlUniverse firstShader() 1024 nextShader( AlShader* curShader ) 1024 AlShadingFieldItem 828 AlShadingFieldItem* AlShadingFieldItem nextField() const 829 AlShadingFields AlShadingFieldItem field() const 828 AlShell 829 ~AlShell() 831 AlShell() 830 AlShell* AlObject asShellPtr() 682 AlShell* AlShell asShellPtr() 831 AlShell* AlShellNode shell() const 839 shell(AlTM& tm) const 839 AlShellNode 838 ~AlShellNode() 838 AlShellNode* AlObject asShellNodePtr() 682 AlShellNode* AlShell shellNode() const 831 AlSnap 839 AlSpaceLocator* AlObject asSpaceLocatorPtr() 685 AlSphereLight 844 ~AlSphereLight() 845 AlSphereLight() 845 AlSphereLight* AlObject asSphereLightPtr() 682

1110 | Index

AlSpotLight 846 ~AlSpotLight() 848 AlSpotLight() 848 AlSpotLight* AlObject asSpotLightPtr() 682 AlSpotLight* AlSpotLight asSpotLightPtr() 848 AlSurface 858 ~AlSurface() 866 AlSurface() 865 AlSurface * AlFaceNode convertToTrimmedSurface( boolean worldSpace ) const 475 AlSurface* AlCurveOnSurface surface() const 365 AlSurface* AlObject asSurfacePtr() 683 AlSurface* AlSurface untrimmedToTrimmedSurface() const 898 AlSurface* AlSurfaceCV surface() const 913 AlSurface* AlSurfaceNode surface() const 926 surface(AlTM& tm) const 926 AlSurfaceCV 904 ~AlSurfaceCV() 906 AlSurfaceCV *AlSurfaceCV asSurfaceCVPtr() 906 AlSurfaceCV* AlObject asSurfaceCVPtr() 683 AlSurfaceCV* AlSurface firstCV() const 876 AlSurfaceCV* AlSurfaceCV nextInU() const 906 nextInV() const 907 prevInU() const 908 prevInV() const 908 AlSurfaceLocator 924 AlSurfaceLocator* AlObject asSurfaceLocatorPtr() 685 AlSurfaceNode 924 ~AlSurfaceNode() 925 AlSurfaceNode() 925 AlSurfaceNode* AlObject asSurfaceNodePtr() 683

AlSurfaceNode* AlSurface surfaceNode() const 866 AlSurfaceType AlCommand surfaceType() const 260 AlTexture 933 ~AlTexture() 935 AlTexture() 935 AlTexture* AlEnvironment firstTexture() const 462 nextTexture( AlTexture* last_texture ) const 462 AlTexture* AlObject asTexturePtr() 683 AlTexture* AlShader firstTexture() const 822 nextTexture( const AlTexture* last_texture ) const 822 AlTexture* AlTexture firstTexture() const 937 nextTexture( const AlTexture* last_texture ) const 937 AlTexture* AlTextureNode texture() const 948 texture(AlTM& tm) const 948 AlTextureNode 946 ~AlTextureNode() 947 AlTextureNode* AlObject asTextureNodePtr() 683 AlTextureNode* AlTexture textureNode() const 944 AlTM 948 AlTM( const AlTM& tm ) 952 AlTM( const double d0, const double d1, const double d2, const double d3 ) 952 AlTM( const double tm\ 952 AlTM AlTM diagonal( const double d0, const double d1, const double d2, const double d3 ) 957 identity( void ) 957 inverse( void ) const 956 operator -( const AlTM& tm ) const 954 operator *( const AlTM& tm ) const 954

Index | 1111

operator *( const double d ) const 955 operator +( const AlTM& tm ) const 954 rotate( double x, double y, double z, double angle ) 959 rotateX( const double rx ) 958 rotateY( const double ry ) 959 rotateZ( const double rz ) 959 scale_nonp( const double sx, const double sy, const double sz ) 958 scale( const double d ) 957 translate( const double tx, const double ty, const double tz ) 958 transpose( void ) const 956 zero( void ) 957 AlTM result( *this ) 954 AlTM& AlTM operator -=( const AlTM& tm ) 955 operator *=( const AlTM& tm ) 955 operator *=( const double d ) 955 operator +=( const AlTM& tm ) 955 operator =( const AlTM& tm ) 953 operator =( const double d ) 953 AlTorusLight 962 ~AlTorusLight() 962 AlTorusLight() 962 AlTorusLight* AlObject asTorusLightPtr() 683 AlTorusLight* AlTorusLight asTorusLightPtr() 963 AlTrimBoundary 964 ~AlTrimBoundary() 965 AlTrimBoundary* AlObject asTrimBoundaryPtr() 684 AlTrimBoundary* AlTrimBoundary asTrimBoundaryPtr() 966 nextBoundary() const 966 prevBoundary() const 966 AlTrimBoundary* AlTrimCurve parentBoundary() 975 AlTrimBoundary* AlTrimRegion firstBoundary() const 980

AlTrimCurve 968 ~AlTrimCurve() 970 AlTrimCurve* AlContact trimCurve() 272 AlTrimCurve* AlObject asTrimCurvePtr() 684 AlTrimCurve* AlTrimBoundary firstCurve() const 966 AlTrimCurve* AlTrimCurve getTwinCurve() const 970 nextCurve() const 973 prevCurve() const 973 AlTrimRegion 976 ~AlTrimRegion() 979 AlTrimRegion* AlObject asTrimRegionPtr() 684 AlTrimRegion* AlShell firstTrimRegion() const 833 AlTrimRegion* AlSurface firstTrimRegion() const 898 trimSurfaceToRegion() const 898 AlTrimRegion* AlTrimBoundary parentRegion() 967 AlTrimRegion* AlTrimCurve parentRegion() 975 AlTrimRegion* AlTrimRegion nextRegion() const 980 prevRegion() const 981 AlTripleComponent AlChannel appliedActionComponent(const int n ) const 195 AlUnits 988 AngularUnit AlUnits\ \ angularUnits( AlUnits\ \ Type type ) 989 LinearUnit AlUnits\ \ linearUnits( AlUnits\ \ Type type ) 990 AlUniverse 993 AlApplicationMode 1039

1112 | Index

AlFileType AlUniverse fileType( const char *fileName ) 1004 AlUserCommand 1040, 1042 ~AlUserCommand() 1046 AlUserCommand() 1046 AlUserCommand *AlCommand userCommand() 259 AlUserPickItem 1058 ~AlUserPickItem() 1059 AlUserPickItem( AlPickable& pickable ) 1058 AlUserPickList 1059 AlViewFrame 1059 AlVolumeLight 1062 ~AlVolumeLight() 1065 AlVolumeLight* AlObject asVolumeLightPtr() 684 AlVolumeLight* AlVolumeLight asVolumeLightPtr() 1065 AlWindow 1078 ~AlWindow() 1081 AlWindow() 1081 AlWindow *AlCamera firstWindow( void ) 173 nextWindow( AlWindow *window ) 173 AlWindow *AlUniverse firstWindow( void ) 1017 AlWindow* AlObject asWindowPtr() 684 AlWindow* AlUniverse currentWindow( void ) 1018 sbdWindow( void ) 1018 AlWindow* AlWindow asWindowPtr() 1082 next() const 1082 prev() const 1083 AlXevents 1090 annotation 799 anonymous_blocks 800

B
boolean AlAreEqual 671

boolean AlBlendCurve isPicked() 146 boolean AlBlendPoint isMaster() 160 boolean AlCameraNode isEyeNode() const 179 isInstanceable() 179 isUpNode() const 179 isViewNode() const 179 boolean AlCategory isPicked() 185 boolean AlCloud isPicked() 237 visible() 229 boolean AlCluster isEmpty() const 242 boolean AlClusterNode isInstanceable() 255 boolean AlConstraint on() const 282 boolean AlContact areEqual( AlDagNode *dagNodeThis,AlContact *contactOther, AlDagNode *dagNodeOther) const 273 boolean AlCurve isDisplayModeSet( AlDisplayModeType mode ) const 316 boolean AlCurveOnSurface inTrim() const 366 visible() const 366 boolean AlDagNode AlCopyOptions copyAnimation() const 416 copyClusters() const 417 instanceCopy() const 416 isAConstructionPlane() 413 isDisplayModeSet( AlDisplayModeType mode ) const 408 isInstanceable 389 boolean AlEscapeKeyPressed 613 boolean AlGroupNode isAncestorAnInstance() 504 isInstanceable() 504

Index | 1113

isInstanceNode() 504 boolean AlIKHandle on( void ) const 514 oneJointHandle( void ) const 516 worldOrientation( void ) const 515 boolean AlIsValid( AlObject* obj ) 671 boolean AlJoint charJoint() const 553 useBulge() const 554 boolean AlKeyframe isLocked() const 564 boolean AlLayer drawInstances() 576 invisible() 573 isPicked() 578 playback() 576 visibleInLayerBar() 579 boolean AlLight exclusivity() const 588 hasLinkedObjects() const 588 boolean AlLightNode isInstanceable() 594 isLookAtNode() const 594 isPositionNode() const 594 isUpNode() const 594 boolean AlMessageTypeHandle isValid( void ) const 639 boolean AlNonAmbientLight shadows() const 662 boolean AlPerformance actionWindowAfterModification( void ) 712 actionWindowDuringXform( void ) 712 blendDuringPlayback( void ) 711 constraintsAfterModification( void ) 707 constraintsDuringPlayback( void ) 708 constraintsDuringXform( void ) 708 constructionHistoryAfterModification( void ) 710 constructionHistoryDuringPlayback( void ) 710 constructionHistoryDuringXform( void ) 710

constructionHistoryRound( void ) 711 displayablesAfterModification 712 displayablesDuringPlayback 713 displayablesDuringXform 713 drawTrimBoundaries( void ) 706 expressionsAfterModification( void ) 706 expressionsDuringPlayback( void ) 707 expressionsDuringXform( void ) 707 ikAfterModification( void ) 709 ikDuringPlayback( void ) 709 ikDuringXform( void ) 709 trimBoundariesDuringPlayback( void ) 706 boolean AlPickable isPicked( void ) 731 boolean AlPickList isValid() 733 boolean AlPlayBack inPlayBack () 747 boolean AlRender animation() 768 Blur motionBlur() 780 postFilter() 778 Composite enabled() 777 HiddenLine useFillColor() 790 Image 788 ignoreFilmGate() 786 oddFirst() 786 XYRatioLock() 787 Limits createPreview( AlRender Quality q ) 775 Misc attenuateTransparency() 784 depthMapsInMemory() 784 keepNonglowedImage() 783 noTransparencyInDepth() 782 skeletons() 782 spotLightDepthMaps() 783 textures() 781

1114 | Index

Particle show() 792 boolean AlSet isEmpty() const 807 isExclusive() const 807 boolean AlShader isUsed() 825 boolean AlShell isDisplayModeSet( AlDisplayModeType mode ) const 836 isInShell( AlTrimRegion * region ) 832 boolean AlSurface isAffectedByViewFrame() const 879 isConstructionHistoryResultingSurface()880 isDisplayModeSet( AlDisplayModeType mode ) const 896 isPointActive( double u, double v ) const 880 isTargetSurface() const 888 trimmed() const 888 boolean AlTexture isParametric() const 942 boolean AlTextureNode isInstanceable() 947 boolean AlTrimCurve isReversed() 970 boolean AlUniverse constructionPlaneInEffect() 1040 isInitialized() 1000 isWireFile( const char *fileName, char * vbuf ) 1004 layersEnabled() 1023, 1030 boolean AlUserCommand isCurveOnSurfaceAConstructor( AlCurveOnSurface* curveOnSurface ) const 1057 isCurveOnSurfaceATarget( AlCurveOnSurface* curveOnSurface ) const 1058 isDagNodeAConstructor( AlDagNode* dagNode ) const 1057

isDagNodeATarget( AlDagNode* dagNode, boolean includeCoS ) const 1057 boolean AlVolumeLight shadows() const 1065 specular() const 1065 turbulenceAnimated() const 1066 turbulenceDirectional() const 1066 boolean AlXevents belowAliasWindow 1096

C
C4X options 798 castsShadow 795 coalesce 798 const char * AlCategory description() 183 name() 182 const char * AlGetAliasPreference( const char * pref ) 609 const char * AlInvokeSchemeCommand( const char *command ) 607 const char * AlLayer name() 575 const char * AlNameItem name() const 660 const char *AlAnnotationLocator string() const 123 const char *AlCharacter name(void) const 198 const char *AlCharSnippet name(void) const 215 const char *AlCharTransition name(void) const 222 const char *AlCloud name() 229 const char *AlFunction name() 481 const char *AlProduct productName 757 versionNumber 757 const char *AlUniverse backgroundSource( void ) 1013 windowSource( void ) 1012

Index | 1115

const char *AlUserCommand name() const 1053 const char* AlAction comment() const 99 name() const 98 const char* AlCamera name() const 171 const char* AlChannel parameterName() const 190 const char* AlDagNode name() const 387 const char* AlEnvironment name() const 461 const char* AlImagePlane imageFile() 530 name() const 529 const char* AlInvokeSchemeFile( const char * filename, const char *filenamePrefix ) 606 const char* AlLight name() const 585 const char* AlMappedFieldItem field() const 619 const char* AlObject name() const 670 const char* AlSet name() const 805 const char* AlShader name() const 819 shadingModel() const 821 const char* AlTexture fieldType() const 938 filename() const 939 firstPerObjectPixEntry() 940 getPerObjectPixFilename( const char* objname ) const 940 name() const 936 nextPerObjectPixEntry( const char* prev_objname ) 940 textureType() const 938 const char* AlUniverse currentStage( void ) 1010 stageWireFileName 1016 curvature_threshold 795 curveFormType AlCurve form() const 308

curveFormType AlCurveAttributes form() const 335 curveFormType AlCurveOnSurface form() const 363 curveFormType AlSurface uForm() const 874 vForm() const 875 curveFormType AlTrimCurve form() const 971 curveFormType AlTrimRegion uForm() const 981 vForm() const 981

D
double AlMeasure minDist( AlCurve* curve1, AlCurve* curve2,double* t1, double P1\ 623 minDist( AlCurve* curve1, double P2\ 624 minDist( AlSurface* surface1, AlCurve* curve2,double* u1, double* v1, double P1\ 622 minDist( AlSurface* surface1, AlSurface* surface2,double* u1, double* v1, double P1\ 621 minDist( AlSurface* surface1, double P2\ 622 double AlAction eval( double time, AlTripleComponent compo ) const 101 double AlAmbientLight intensity() const 109 shadeFactor() const 108 double AlArcAttributes radius() const 129 sweep() const 129 double AlChannel eval( double time ) const 194 double AlClusterable percentEffect( AlCluster* cluster ) const 247 double AlConeLight arc() const 275

1116 | Index

coneEndRadius() const 275 double AlConicAttributes zDisplacement() const 278 double AlConstraint weight() const 283 double AlContact nonisoparamMax() const 272 nonisoparamMin() const 272 paramValue() const 272 double AlCurveOnSurface knotValue( int index ) const 363 double AlCylinderLight arc() const 378 double AlDagNode AlCopyOptions timeOffset() const 419 double AlIKHandle 517 weight( void ) const 514 double AlKeyframe inTangent() const 562 location() const 561 outTangent() const 563 value() const 562 double AlNonAmbientLight intensity() const 661 double AlPerspectiveCamera angleOfView() const 727 focalLength() const 726 placementShift() const 729 twistAngle() const 723 double AlRender AntiAlias threshold( AlRender Quality q ) 774 Blur shutterAngle() 780 Composite coverageThreshold() 778 Image aspectRatio() 789 gammaCorrection() 787 Misc transparency() 782 Subdivision adaptiveThreshold( AlRender Quality q) 773

double AlRevSurfAttributes endAngle() const 801 startAngle() const 801 double AlSphereLight arc() const 845 double AlSpotLight dropOff() const 848 maxBias() const 849 minBias() const 849 penumbra() const 850 spreadAngle() const 849 double AlTorusLight arc() const 963 torusRadius() const 963 double AlUnits angularInDegrees( AlUnits\ \ AngularUnit unit ) 990 angularScale( AlUnits\ \ Type type ) 990 linearInCM( AlUnits\ \ LinearUnit unit ) 990 linearScale( AlUnits\ \ Type type ) 990 double AlUniverse currentTime() 1038 double AlVolumeLight concentric() const 1067 decay() const 1066 decayStart() const 1067 directional() const 1067 directionality() const 1067 dropoff() const 1067 dropoffStart() const 1068 intensity() const 1066 radial() const 1067 turbulenceGranularity() const 1068 turbulenceIntensity() const 1068 turbulencePersistance() const 1068 turbulenceRoughness() const 1068 turbulenceSpread() const 1068 turbulenceVariability() const 1069

Index | 1117

double AlWindow gridSize() 1090 doubleSided 795 DXF files options 800

E
extern AL_Window *create_dag_window( int, int, int, int, int, int ) 1081

G
group 798, 800

I
IGES options 798 int AlAction numChannelReferences() const 102 int AlBlendCurve degree() 142 numberOfPoints() 143 int AlCategory numberOfMembers() 184 int AlChannel numAppliedActions() const 194 parameter() const 190 int AlCharSnippet setTraversal(int traversalStatus) 216 int AlCharTransition setTraversal(int traversalStatus) 222 int AlCloud numberOfPoints() 235 int AlCluster numberOfMembers() const 243 int AlCommand execute( boolean freeIfInvalid ) 262 status() const 259 undo( boolean freeIfInvalid ) 262 int AlContact numberContacts() const 271 int AlContinuousFunction inputModifierMask() 489

int AlCurve degree() const 308 numberOfCVs() const 308 numberOfCVsInclMultiples() const 314 numberOfKnots() const 312 numberOfSpans() const 308 realNumberOfKnots() const 328 int AlCurveAttributes degree() const 335 numberOfCVs() const 336 numberOfKnots() const 337 numberOfSpans() const 336 int AlCurveCV index() 340 multiplicity() const 342 int AlCurveNode curvePrecision() const 356 int AlCurveOnSurface degree() const 362 numberOfControlPoints() const 364 numberOfKnots() const 363 numberOfSpans() const 363 int AlDagNode AlCopyOptions numCopies() const 417 int AlDebugOutputIterator 424 int AlFunctionHandle operator !() const 494 int AlLayer color() 577 number() 575 startNumber() 579 int AlList remove( AlLinkItem *item ) 603 int AlMessage getMessageType( const char * name ) 646 int AlMessageTypeHandle type( void ) const 639 int AlNonAmbientLight decay() const 662 int AlParamAction numberOfKeyframes() 700 int AlPerformance evaluationsPerUpdate 705

1118 | Index

int AlPerspectiveCamera placementFitCode() const 729 int AlPixFile height 743 numChannels 743 read 742 width 743 write 743 int AlRender AntiAlias max( AlRender Quality q ) 774 min( AlRender Quality q ) 774 Blur postAdjacent() 779 postCenter() 779 postDiagonal() 780 HiddenLine patchLinesU() 791 patchLinesV() 792 Image resolutionX() 789 resolutionY() 789 Limits maxReflections( AlRender Quality q ) 775 maxRefractions( AlRender Quality q ) 776 maxShadowLevels( AlRender Quality q ) 776 subdivideRecurse( void ) 777 Particle framesPerSecond() 793 simulationSubsteps() 793 Subdivision adaptiveMax( AlRender\ \ Quality q) 773 adaptiveMin( AlRender\ \ Quality q) 772 uniformU( AlRender\ \ Quality q ) 771

uniformV( AlRender\ \ Quality q) 772 int AlSet numberOfMembers() const 808 int AlSnap snappingTo( void ) 841 int AlSpotLight multFactor() const 850 offset() const 849 shadowSize() const 850 int AlSurface realuNumberOfKnots() const 890 realvNumberOfKnots() const 890 uDegree() const 875 uNumberOfCVs() const 875 uNumberOfCVsInclMultiples() const 885 uNumberOfKnots() const 883 uNumberOfSpans() const 875 vDegree() const 875 vNumberOfCVs() const 876 vNumberOfCVsInclMultiples() const 885 vNumberOfKnots() const 883 vNumberOfSpans() const 875 int AlSurfaceCV multiplicityInU() const 909 multiplicityInV() const 909 int AlSurfaceNode curvePrecision() const 926 patchPrecision() const 927 int AlTM operator !=( const AlTM& tm ) const 954 operator ==( const AlTM& tm ) const 954 int AlTrimCurve degree() const 971 numberOfCVs() const 971 numberOfKnots() const 971 numberOfSpans() const 971 realNumberOfKnots() const 972 int AlTrimRegion realvNumberOfKnots() const 984 uDegree() const 981

Index | 1119

uNumberOfCVs() const 982 uNumberOfCVsInclMultiples() const 983 uNumberOfKnots() const 983 uNumberOfSpans() const 982 vDegree() const 982 vNumberOfCVs() const 982 vNumberOfCVsInclMultiples() const 983 vNumberOfKnots() const 983 vNumberOfSpans() const 982 int AlUniverse numberOfBlendCurves() 1032 numberOfClouds() 1031 int AlUserCommand curveOnSurfaceModified( AlCurveOnSurface *surf ) 1049 dagModified( AlDagNode *dag ) 1048 debug( const char *prefix ) 1049 declareReferences() 1047 execute() 1047 geometryModified( AlDagNode *dag ) 1048 instanceDag( AlDagNode *oldDag, AlDagNode *newDag ) 1047 isValid() 1046 listModifiedDagNodes( const AlNotifyDagNode *dagMod, AlObject *obj ) 1049 type() 1052 undo() 1047 int AlVolumeLight turbulenceSpaceRes() const 1066 turbulenceTimeRes() const 1066

keep_backgrounds 798 keep_cameras 797 keep_renderGlobals 798 keep_unitsTolerances 798 keep_windows 797

L
lBlendCurve* AlBlendCurve next() 146 load_shaders 800

M
motion_blur 796 motion_blur_shading_samples 796 motion_blur_texture_sample_level 796

N
new_stage 797 numChannelReferences() 103

O
opposite 795

Q
qk_wire 797

R
reflection_only 796 return AlFriend isValid( obj ) 671

J
JAMA-IS formats options 798

S
statusCode AlTrimCurve CVsUVPosition( double knotVector\ 972 nextCurveD() 973 periodicToNonPeriodic() 975

K
keep_animation 797

1120 | Index

prevCurveD() 973 realKnotVector( double knotVector\ 972 statusCode AlCurveAttributes CVsUnaffectedPosition( double CVList\ 336 knotVector( double knotVector\ 337 statusCode AlSnap toCurve( Screencoord x, Screencoord y, AlObject* &obj, double &curveParam, AlWindow *window ) 841 toCV( Screencoord x, Screencoord y, AlObject* &obj, AlWindow *window ) 840 toGrid( Screencoord x, Screencoord y, double worldPos\ 840 statusCode AlTM getTM( double tm\ 953 setTM( const double tm\ 953 transNormal( double& x, double& y, double& z ) const 959 transPoint( const double pt\ 960 transPoint( double &x, double &y, double &z ) const 961 transPoint( double &x, double &y, double &z, double &w ) const 961 transPoint( double pt\ 960 transVector( double& x, double& y, double& z ) const 960 scale 799800 smooth_shading 796 statusCode AlAimConstraint at( double point\ 106 create(AlDagNode* srcNode, AlDagNode* destNode, AlAimConstraintAxis aim, AlAimConstraintAxis up) 104 setAimAxis( AlAimConstraintAxis axis ) 106 setUpAxis( AlAimConstraintAxis axis ) 106

statusCode AlAmbientLight create() 107 setIntensity( double newIntensity ) 109 setShadeFactor( double newShadeFactor) 108 statusCode AlAngleLocator angle(double &includedAngle) const 114 create(const AlPointLocator *startLocator, const AlPointLocator *middleLocator, const AlPointLocator *endLocator, boolean trueDisplay) 111 offset(double &offset) const 113 setOffset(double offset) 113 setTrueDisplay(boolean trueDisplay) 113 trueDisplay(boolean &trueDisplay) const 112 statusCode AlAnimatable applyIteratorToChannels( AlIterator* iter, int &rc ) 117 deleteAnimation() 118 globalParam( const char *paramName, boolean& state ) 119 localParam( const char *paramName, boolean& state ) 119 nextChannelD( AlChannel *channel ) const 116 prevChannelD( AlChannel *channel ) const 117 setGlobalParam( const char *paramName, boolean state ) 120 setLocalParam( const char *paramName, boolean state ) 120 statusCode AlAnnotationLocator create(const AlPointLocator *pointLocator, const char *string, double x, double y, double z) 122 leftJustify(boolean &leftJustify) const 126

Index | 1121

localLeaderPosition(double &x, double &y, double &z) const 125 setLeftJustify(boolean leftJustify) 125 setLocalLeaderPosition(double x, double y, double z) 124 setString(const char *string) 123 setWorldLeaderPosition(double x, double y, double z) 124 worldLeaderPosition(double &x, double &y, double &z) const 125 statusCode AlArcAttributes centerPoint(double& x, double& y, double& z) const 128 endPoint(double& x, double& y, double& z) const 129 setEndPoint(double x, double y, double z) 130 setRadius(double radius) 132 setStartPoint(double x, double y, double z) 130 setSweepFromEndPoint(double sweep) 131 setSweepFromStartPoint(double sweep) 131 startPoint(double& x, double& y, double& z) const 128 statusCode AlAreaLight cornerPoints( double &x1, double &y1, double &z1,double &x2, double &y2, double &z2) const 136 create() 134 longAxis( double &x, double &y, double &z) const 134 setLongAxis( double x, double y, double z ) 135 setShortAxis( double x, double y, double z ) 136 shortAxis( double &x, double &y, double &z) const 135 statusCode AlBlendCurve append 145 create 140 deleteObject() 140

insert 145 knotSpacingType 142 nextD 146 param 143 points 144 prevD 147 setDegree 142 setKnotSpacingType 143 statusCode AlBlendPoint attachConstraint 158159 attachedTo 160 constraintContinuityType 154 curvatureType 157 deleteObject() 151 directionType 156 disassociateConstraint() 159 interpolationDirectionType 155 makeMaster() 160 nextD 161 param 152 point 152 prevD 161 setConstraintContinuityType 154 setCurvatureType 157 setDirectionType 156 setInterpolationDirectionType 155 setPoint 152 setTangent 153 tangent 153 statusCode AlBoxLight create() 167 statusCode AlCamera addImagePlane( const char * fname ) 172 applyIteratorToImagePlanes( AlIterator* iter, int& rc ) 172 deleteObject() 171 farClippingPlane( double& fcp ) const 174 motionBlur( boolean& blur) const 176 nearClippingPlane( double& ncp ) const 174 nextWindowD( AlWindow *lastWindow ) 173

1122 | Index

setFarClippingPlane( double newFarDistance) 175 setMotionBlur( boolean blurEnabled ) 177 setName( const char *newName ) 171 setNearClippingPlane( double newNearDistance ) 174 setStereoView(boolean stereoEnabled, double eyeOffset) 176 stereoView(boolean& stereoEnabled, double& eyeOffset) const 175 statusCode AlCameraNode deleteObject() 178 statusCode AlCategory addMember 183 create 182 deleteObject() 181 members 184 pick 185 removeMember 184 setDescription 183 setName 182 statusCode AlChannel applyWarp() 192 copyD(AlAnimatable *anima, int field) 191 create(AlAnimatable *anima, int field,AlAction *faction, AlTripleComponent component) 188 create(AlAnimatable *anima, int field,const char *szExprText) 189 deleteObject() 187 link(AlAction* action, AlTripleComponent component) 192 removeWarp(AlAction* action) 193 statusCode AlCharacter characterStringInfo(AlCharacterStringInfo dataType,const char *& sValue) const 205

connectSnippets(AlCharSnippet *sourceSnippet,AlCharTransition *transition,AlCharSnippet *destinationSnippet) 203 convertTransitionToSnippet(AlCharTransition *transition,int transitionIsDeleted,AlCharSnippet **newSnippet,AlCharTransition **newSourceT ransition,AlCharT ransition **newDestinationTransition)204 create(const char *characterName) 198 deleteObject() 197 removeSnippet(AlCharSnippet *snippet) 200 removeTransition(AlCharTransition *transition) 201 setCharacterStringInfo(AlCharacterStringInfo dataType,const char* sValue) 205 setName(const char *newCharacterName) 199 statusCode AlCharacterSpace create() 207 deleteCharacter(AlCharacter *character) 208 deleteObject() 207 statusCode AlCharSnippet charSnippetIntegerInfo(AlCharSnippetIntegerInfo dataType,int& iValue) const 217 charSnippetStringInfo(AlCharSnippetStringInfo dataType,const char *& sValue) const 217 create(AlCharacter *character,const char *snippetName) 214 deleteObject() 214 setCharSnippetIntegerInfo(AlCharSnippetIntegerInfo dataType,int iValue) 218 setCharSnippetStringInfo(AlCharSnippetStringInfo dataType,const char* sValue) 218 setName(const char* newSnippetName) 215

Index | 1123

statusCode AlCharTransition charT ransitionIntegerInfo(AlCharT ransitionIntegerInfo dataType,int& iValue) const 223 charT ransitionStringInfo(AlCharT ransitionStringInfo dataType,const char *& sValue) const 223 create(AlCharacter *character,const char *arc_name) 221 deleteObject() 222 getSnippets(AlCharSnippet **sourceSnippet,AlCharSnippet **destinationSnippet) 223 setCharT ransitionIntegerInfo(AlCharT ransitionIntegerInfo dataType,int iValue) 224 setCharT ransitionStringInfo(AlCharT ransitionStringInfo dataType,const char* sValue) 224 setName(const char *new_transition_name) 222 statusCode AlCloud addPoints 236 boundingBox 233 create() 228 deleteObject() 228 merge 234 nextCloudD 238 pick() 237 points 235 rotation 231 scale 232 setName 229 setRotation 231 setScale 232 setTranslation 230 setVisibility 229 subset 233 translation 230 unpick() 237 statusCode AlCluster applyIteratorToMembers( AlIterator* iter, int &rc ) const 243 clusterRestrict( AlClusterRestrict& restrict ) const 243 create() 241 deleteObject() 240

nextClusterD() 241 originalTRS 244 prevClusterD() 242 setClusterRestrict( AlClusterRestrict newRestrict ) 244 setPercentEffect( AlClusterable* clustobj, double percentage ) 244 statusCode AlClusterable addToCluster( AlCluster* cluster, double percentage /* = 1.0 */) 248 applyIteratorToClusters( AlIterator* iter, int &rc ) 247 nextClusterD( AlCluster* lastCluster ) const 246 prevClusterD( AlCluster* lastCluster ) const 246 removeFromAllClusters() 250 removeFromCluster( AlCluster* cluster ) 249 setPercentEffect( AlCluster* cluster, double percentage ) 248 statusCode AlClusterMember nextClusterMemberD() 252 prevClusterMemberD() 253 removeFromCluster( AlCluster* cluster ) 253 statusCode AlCommand add( AlUserCommandAlloc *func, const char *name ) 263 create( const char *name ) 260 deleteObject() 260 install() 261 modified() 260 remove( const char *name ) 263 setDebug( boolean on ) 258 setSurfaceType( AlSurfaceType type ) 261 uninstall() 261 statusCode AlCommandRef nextRefD 267 prevRefD 268 statusCode AlConeLight create() 275 setArc( double arc ) 275

1124 | Index

setConeEndRadius( double cone_end_radius ) 276 statusCode AlConicAttributes centerPoint( double& x, double& y ) const 279 coefficients( double& c_a, double& c_b, double& c_c, double& c_d, double& c_e, double& c_f ) const 278 endPoint( double& x, double& y ) const 279 startPoint( double& x, double& y ) const 278 transform( AlTM& tm ) const 280 transform( double tm\ 280 statusCode AlConstraint deleteObject() 282 setOn( boolean onOff ) 284 setWeight( double weight ) 284 statusCode AlContact appendContact( AlContact *addcontact ) 271 calculate( AlDagNode *dagNode, double tolerance, boolean adjustTolerance ) 273 create() 269 deleteObject() 270 nextContactD() 270 prevContactD() 270 statusCode AlContinuousFunction clearGoButton( boolean do_redraw ) 491 create( const char *name, void (*init)( void ), AlMouseButtonFunction *down, AlMouseButtonFunction *move, AlMouseButtonFunction *up, void (*cleanup)( void ), boolean manipulatesPickList ) 484 create( void (*init)( void ), AlMouseButtonFunction *down, AlMouseButtonFunction

*move, AlMouseButtonFunction *up, void (*cleanup)( void ), boolean manipulatesPickList ) 483 createGoButton( void (*pressed)( void ) ) 490 finished( ) 485 setBehaviour( AlBehaviourType type ) 486 setMouseCoordinateType( AlCoordinateType type ) 485 setPostCleanupFunction( void (*postCleanup)() ) 487 setPreInitFunction( void (*preInit)() ) 486 setPrompt( const char *(*outputStringFunc)(), char *inputBuffer, AlFilterType filter ) 487 setPrompt( const char *staticPrompt, char *inputBuffer, AlFilterType filter ) 488 statusCode AlCurve adjustEndSpan 333 append 331 applyIteratorToCVs 331 applyIteratorToCVs( AlIterator* iter, int &rc ) 330 create( int deg, curveFormType form, const double knotVector\ 320 create( int deg, curveFormType form, int numKnots, const double knotVector\ 317 createArc( const double start\ 322 createConic( double c_a, double c_b, double c_c, double c_d, double c_e, double c_f, const double start\ 324 createEllipse( const double center\ 325 createHyperbola( const double center\ 326 createLine( const double start\ 322

Index | 1125

createParabola( const double vertex\ 325 CVsAffectedPosition( const AlTM& tm, double CVList\ 309 CVsAffectedPositionInclMultiples314 CVsUnaffectedPosition( double CVList\ 310 CVsUnaffectedPositionInclMultiples( double CVList\ 315 CVsWorldPosition 309 CVsWorldPositionInclMultiples( double CVList\ 314 deleteObject() 307 doUpdates( boolean newState ) 311 eval(double t, boolean worldCoordinates, double P\ 311 extendCurve 332 incrementDegree() 333 knotVector( double knotVector\ 313 length(double& len , boolean worldCoordinates, double tolerance ) 329 normal( double normal\ 330 periodicSplineToOpen( ) const 329 realKnotVector( double knotVector\ 328 reverseCurve() 332 setCVsUnaffectedPosition( const double CVList\ 311 setCVsUnaffectedPositionInclMultiples( const double CVList\ 315 setDisplayMode( AlDisplayModeType mode, boolean on_or_off) 317 setKnotVector( const double knotVector\ 313 setRealKnotVector( const double knotVector\ 328 trimCurve 333 statusCode AlCurveCV affectedPosition( const AlTM& tm, double &x, double &y,double &z, double &weight ) const 342

blindData( int user_type, long& size, const char *& data ) 346 doUpdates( boolean newState ) 344 nextD() 341 prevD() 341 removeBlindData( int user_type ) 347 setBlindData 347 setMultiplicity( int newMultiplicity ) 344 setUnaffectedPosition( double x, double y,double z, double weight ) 345 setWorldPosition( double x, double y, double z, AlTM tm ) 345 setWorldPosition( double x, double y, double z, boolean includeWorld ) 344 unaffectedPosition( double &x, double &y,double &z, double &weight ) const 343 worldPosition( double &x, double &y,double &z, double &weight ) const 342 statusCode AlCurveNode create( AlCurve *newCurve ) 354 setCurvePrecision( int precision ) 356 statusCode AlCurveOnSurface affected3DCopies 369 controlPoint( int index, double point\ 364 create(int deg,curveFormType form,int numKnots,const double knotVector\ 360 curveOnSurfaceData(double knotVector\ 361 deleteObject() 359 getControlPoint( int index, double point\ 364 getKnotValue( int index, double& knotVal ) const 363 hasPersistentID 371 nextCurveOnSurfaceD() 366 persistentID 370 prevCurveOnSurfaceD() 367

1126 | Index

setControlPoint( int index, const double point\ 365 setCurveOnSurfaceData(int deg,curveFormType form,int numKnots,const double knotVector\ 360 setKnotValue( int index, double knotValue ) 364 setPersistentID 370 unaffected3DCopies 369 worldSpace3DCopies 368 worldSpaceCopys( int& count, AlCurve **&ws_curves ) 366 statusCode AlCylinderLight create() 378 setArc( double arc ) 379 statusCode AlDagNode addJoint() 411 addSiblingNode( AlDagNode *sibling ) 389 affectedTransformationMatrix( const AlTM& tm, AlTM& matrix ) const 398 affectedTransformationMatrix( const AlTM& tm, double matrix\ 398 AlCopyOptions rotation( double& x, double& y, double& z ) const 420 scale( double& x, double& y, double& z ) const 420 setCopyAnimation( boolean animation ) 416 setCopyClusters( boolean clusters ) 417 setHierarchy( AlHierarchyType hier ) 418 setInstanceCopy( boolean instance ) 416 setNumCopies( int copies ) 417 setParameterControl( AlParamControlType control ) 418 setRotation( double x, double y, double z ) 420

setScale( double x, double y, double z ) 421 setTimeOffset( double offset ) 419 setTranslation( double x, double y, double z ) 419 translation( double& x, double& y, double& z ) const 419 blindData( int user_type, long &size, const char* &data ) 390 boundingBox( double corners\ 407 comment( long &size, const char* &data ) 390 create() 386 deleteObject() 386 doUpdates( boolean newState ) 401 globalTransformationMatrix( AlTM& matrix ) const 396 globalTransformationMatrix( double matrix\ 396 hasPersistentID( int user_type ) 392 inverseGlobalTransformationMatrix( AlTM& matrix ) const 397 inverseGlobalTransformationMatrix( double matrix\ 397 localRotateBy 406 localRotationAngles( double& x, double& y, double& z ) const 405 localRotationAxes( double x\ 404 localTransformationMatrix( AlTM& matrix ) const 394 localTransformationMatrix( double matrix\ 395 localTranslateBy 407 persistentID( int user_type, AlPersistentID *&id ) 391 removeBlindData( int user_type ) 394 removeComment( void ) 393 removeJoint() 411 rotatePivot( double &x, double &y, double &z ) const 400 rotatePivotIn( double &x, double &y, double &z ) const 409

Index | 1127

rotatePivotOut( double &x, double &y, double &z ) const 409 rotation( double &x, double &y, double &z ) const 399 scale( double &x, double &y, double &z ) const 399 scalePivot( double &x, double &y, double &z ) const 400 scalePivotIn( double &x, double &y, double &z ) const 410 scalePivotOut( double &x, double &y, double &z ) const 410 sendGeometryModifiedMessage()402 setBlindData( int user_type, long size, const char* data ) 393 setComment( long size, const char* data ) 392 setDisplayMode( AlDisplayModeType mode, boolean on_or_off) 408 setLayer 412 setLocalRotationAngles( double x, double y, double z ) 406 setLocalRotationAxes(double x\ 405 setName( const char *newName) 388 setRotatePivot( double x, double y, double z ) 404 setRotation( double x, double y, double z ) 403 setScale( double x, double y, double z ) 403 setScalePivot( double x, double y, double z) 404 setTranslation( double x, double y, double z ) 401 setWorldTranslation( double x, double y, double z ) 402 translation( double &x, double &y, double &z ) const 399 updateDrawInfo( void ) const 412 statusCode AlDebug 423 cleanUpUniverse() 422 statusCode AlDebugResetOptionBox( const char *editorName ) 612

statusCode AlDeviationLocator create(const AlCurve *baseCurve, const AlCurve *targetCurve, double baseParameter) 427 create(const AlCurveOnSurface *baseCurve, const AlCurve *targetCurve, double baseParameter) 428 create(const AlCurveOnSurface *baseCurve, const AlCurveOnSurface *targetCurve, double baseParameter) 428 deviation(double &dev) const 429 deviationComponents(double &x, double &y, double &z) const 429 leftJustify(boolean &leftJustify) const 433 length(double &len) const 432 offset(double &x, double &y, double &z) const 431 parameter(double &param) const 430 parameterTargetCurve(double &param) const 430 setLeftJustify(boolean leftJustify) 432 setLength(double len) 432 setOffset(double x, double y, double z) 431 setParameter(double param) 430 statusCode AlDirectionLight create() 435 direction( double &x, double &y, double &z ) const 435 setDirection( double x, double y, double z ) 436 statusCode AlDistanceLocator create(const AlPointLocator *startPointLocator, const AlPointLocator *endPointLocator, boolean trueDisplay) 438 distance(double &x, double &y, double &z) const 440

1128 | Index

offset(double &offset) const 440 setOffset(double offset) 440 trueDisplay(boolean &trueDisplay) const 439 statusCode AlEnvironment addTexture( const char* fieldName, const char* textureName, AlTexture** returnCreatedTexture ) 464 applyIteratorToTextures( AlIterator *iter, int &rc ) 464 deleteObject() 460 nextTextureD( AlTexture* last_texture ) const 462 parameter( const AlShadingFields field, double& result ) const 461 removeTexture( const char* fieldName ) 463 setParameter( const AlShadingFields field,const double "value" ) 461 statusCode AlFace area( double& area, boolean worldCoordinates, double tolerance ) 471 create( int degree, curveFormType form,int lengthKnotVector, const double knotVector\ 467 deleteObject() 466 nextFaceD() 468 nextShaderD( AlShader* last_shader ) const 469 normal( double norm\ 470 prevFaceD() 468 renderInfo( AlRenderInfo &render ) const 469 setRenderInfo( const AlRenderInfo &render ) const 470 statusCode AlFaceNode addFace( AlFace* face ) 474 create( AlFace *face ) 473 normal( double &x, double &y, double &z ) const 475 removeFace( AlFace* alFace ) 474

statusCode AlFileBrowser( AlFileBrowseMode mode, char **returnFilename, const char *acceptString, boolean showSample, const char *fileExtension ) 612 statusCode AlFunction deleteObject() 481 statusCode AlFunctionHandle addToMenu( const char * menuname ) 497 appendToMenu( const char * menuname ) 497 create( const char * popupLabel, AlFunction *func ) 495 create( const char * popupLabel, const char * command ) 494 deleteObject() 500 installOnMenu 498 removeFromMenu() 499 setAttributeString( const char * str ) 495 setHelpFile( const char* file ) 499 setIconPath( const char* path ) 499 setOptionBox( const char * schemeFileName, const char * editorName, const char * schemeFileNamePrefix ) 496 statusCode AlGetDouble( const char * name, double& value ) 607 statusCode AlGetInteger( const char * name, int& value ) 607 statusCode AlGetString( const char * name, const char *& value ) 608 statusCode AlGroupNode addChildNode( AlDagNode *child ) 506 create() 503 nextInstanceD() 505 prevInstanceD() 505 statusCode AlIKHandle createMulti(AlJoint* root, AlJoint* end, AlIKHandleGoalType goal ) 512

Index | 1129

createSingle( AlJoint* root, AlJoint* end ) 511 createSpline(AlJoint* root, AlJoint* end, AlCurveNode* curve, AlIKHandle* rHandle) 512 deleteObject( void ) 511 restRotation( double restRot\ 515 setGoalType( AlIKHandleGoalType tp ) 517 setOn( boolean f ) 517 setPositionType( AlIKHandlePositionType type ) 519 setRestRotation( const double restRot\ 518 setRotationOrder( AlIKHandleRotationOrder ro ) 518 setTwistType( AlIKHandleTwistType type ) 519 setWeight( double d ) 517 setWorldOrientation( boolean set ) 518 statusCode AlImagePlane deleteObject() 527 depthType(AlDepthType& dt,double* depth ) 536 displayMode( AlDisplayMode & dm ) 530 frameType(AlFrameType& ft,AlFrameTypeParams* ftp) 533 imageSpace(AlImageSpaceType spaceType,AlImageSpaceTypeParams* spaceTypeParams,AlImageSpaceParams* spaceParams ) 537 maskInvert( boolean& b ) 535 maskType(AlMaskType& mt,AlMaskTypeParams* mtp ) 534 nextD() 528 nextInCameraD() 528 prevD() 528 prevInCameraD() 529

RGBMult( double& r, double& g, double& b, double& a ) 531 RGBOffset( double& r, double& g, double& b, double& a ) 532 setDepthType(AlDepthType dt,double* depth ) 536 setDisplayMode( AlDisplayMode dm ) 530 setFrameType(AlFrameType ft,AlFrameTypeParams* ftp ) 533 setImageFile( const char * name ) 530 setImageSpace(AlImageSpaceType spaceType,AlImageSpaceTypeParams* spaceTypeParams,AlImageSpaceParams* spaceParams ) 537 setMaskInvert( boolean b ) 535 setMaskType(AlMaskType mt,AlMaskTypeParams* mtp ) 534 setName( const char * newName ) 529 setRGBMult( double r, double g, double b, double a) 531 setRGBOffset( double r, double g, double b, double a ) 532 statusCode AlIntersect intersect( AlCurve* curve, AlSurface* surface,AlList* &list ) 540 intersect( AlCurve* curve1, AlCurve* curve2,AlList* &list ) 541 intersect( AlSurface* surface1, AlSurface* surface2,AlIntersectSurfSurfInfo &ss ) 543 statusCode AlJoint applyIteratorToRootHandles( AlIterator* iter, int& rc ) 548 bulgeAttributes(int *bulgeCode, int *bulgeOrient,double *bulgeScale, AlBulgeSections *bulgeSections.... 555

1130 | Index

charJointLimits(double *upper, double *lower,AlJointInterpolationType *interpolation) const 554 charJointLimits(double &upper, double &lower,AlJointInterpolationType &interpolation) const 554 nextRootHandleD( AlIKHandle* ali ) const 547 restPose( double rotRest\ 550 rotation( double Min\ 549 setBulgeAttributes(int bulgeCode, int bulgeOrient,double bulgeScale, AlBulgeSections bulgeSections.... 557 setCharJoint(boolean isCharJoint) 555 setCharJointLimits(double upper, double lower,AlJointInterpolationType interpolation) 556 setRestPose( const double rot_rest\ 553 setRotation( const double Min\ 552 setTranslation( const double Min\ 552 setUseBulge(boolean useBulge) 556 setUseLimits(const boolean translations\ 551 setUseTransforms( const boolean translations\ 550 translation( double Min\ 549 useLimits( boolean translations\ 548 useTransforms( boolean translations\ 548 statusCode AlKeyframe deleteObject() 560 nextD() 565 prevD() 565 setInTangent(double inTangent) 562 setLocation(double newTime, boolean recompute) 561 setLock(boolean flag) 564

setOutTangent(double outTangent) 563 setTangentTypes(AlTangentType inTangentType, AlTangentType outTangentType, boolean recompute ) 566 setValue(double newVal, boolean recompute) 562 tangentTypes(AlTangentType& inTangentType, AlTangentType& outTangentType) const 566 statusCode AlLayer create 572 deleteObject() 571 pick() 578 pickability 574 setColor 577 setDrawInstances 576 setInvisible 573 setName 575 setPickability 574 setPlayback 576 setStartNumber 579 setVisibleInLayerBar 579 unpick() 578 statusCode AlLight applyIteratorToLinkedObjects( AlIterator *iter, int& rc ) 589 color( double &r, double &g, double &b) const 587 deleteObject() 584 linkObjectToLight( AlObject *obj ) 589 parameter( const AlLightFields field, double& result ) const 586 setColor( double r, double g, double b) 588 setExclusivity( boolean newExclusive) 590 setName(const char *newName) 585

Index | 1131

setParameter( const AlLightFields field,const double value) 586 unlinkObjectFromLight( AlObject *obj ) 590 worldPosition( double &x, double &y, double &z ) const 591 statusCode AlLightNode deleteObject() 593 statusCode AlLinearLight axis( double &x, double &y, double &z) const 596 create() 596 endpoint( double &x, double &y, double &z ) const 597 setAxis( double x, double y, double z ) 597 statusCode AlLineAttributes endPoint( double& x, double& y, double& z ) const 599 setEndPoint( double x, double y, double z ) 600 setStartPoint( double x, double y, double z ) 599 startPoint( double& x, double& y, double& z ) const 598 statusCode AlLocator deleteObject() 615 isPicked(boolean &picked) const 616 pick() 616 templated(boolean &tmpl) const 617 unpick() 616 statusCode AlMessage addMessageHandler( int msg, void * func ) 641 removeMessageHandler( int msg, void * func ) 645 sendMessage( int type, void *data,AlMessage\ \ AlPriorityType p ) 646 statusCode AlMessageTypeHandle addLock( boolean& b ) 640 sendLock( boolean& b ) 640

setAddLock( boolean b ) 640 setEpilogue( int (*func)( int, void * ) ) 640 setPrologue( int (*func)( int, void * ) ) 639 statusCode AlMinmaxLocator combDensity(double &density) const 654 combDisplay(boolean &display) const 651 combScale(double &scale) const 652 combThreshold(double &threshold) const 653 create(const AlCurve *curve1, const AlCurve *curve2) 648 create(const AlCurve *curve1, const AlCurveOnSurface *curve2) 649 create(const AlCurve *curve1, const AlSurface *surface2) 650 create(const AlCurveOnSurface *curve1, const AlCurveOnSurface *curve2) 649 create(const AlCurveOnSurface *curve1, const AlSurface *surface2) 651 create(const AlSurface *surface1, const AlSurface *surface2) 650 leftJustifyMaxDistance(boolean &leftJustify) const 656 leftJustifyMinDistance(boolean &leftJustify) const 655 maximumDistance(double &dist) const 654 minimumDistance(double &dist) const 654 setCombDensity(double density) 653 setCombDisplay(boolean display) 651 setCombScale(double scale) 652 setCombThreshold(double threshold) 653 setLeftJustifyMaxDistance(boolean leftJustify) 656

1132 | Index

setLeftJustifyMinDistance(boolean leftJustify) 655 statusCode AlMomentaryFunction create( const char *funcName, void (*action)(void)) 482 create( void (*action)(void) ) 483 statusCode AlMotionAction create(AlCurveNode *path) 658 statusCode AlNonAmbientLight setDecay( int newDecay ) 662 setIntensity( double newIntensity) 662 setShadows( boolean shadows ) 663 statusCode AlNotifyDagNode notify( AlDagNode *dag ) const 664 statusCode AlObject deleteObject() 670 setName( const char* ) 670 statusCode AlObserver create() 688 deleteObject() 689 installHandler 689 removeHandler 690 statusCode AlOrientationConstraint create(AlDagNode* srcNode, AlDagNode* dstNode ) 691 goalX( double ex\ 693 goalY( double ey\ 693 goalZ( double ez\ 693 statusCode AlOrthographicCamera create( AlWindow\ \ AlViewType viewType ) 695 deleteObject() 694 statusCode AlParamAction addKeyframe( double location, double value, AlKeyframe *& kf, boolean recompute, AlTangentType intan, AlTangentType outtan ) 699

addKeyframe( double location, double value, AlKeyframe &kf, boolean recompute, AlTangentType intan, AlTangentType outtan ) 698 addKeyframe( double location, double value, boolean recompute, AlTangentType intan, AlTangentType outtan ) 699 applyIteratorToKeyframes( AlIterator* iter, int &rc ) 700701 statusCode AlPerspectiveCamera autoFocus(boolean& enabled) const 728 changeTwistAngleBy( double deltaTwistAngle) 724 create() 718 deleteObject() 718 depthOfField(boolean& dofEnabled, double& fStop, double& focalDistance) const 727 filmBack(double& filmXSize, double& filmYSize) const 724 filmOffset(double& filmXOffset, double& filmYOffset) const 725 setAngleOfView( double angleOfView) 727 setAutoFocus( boolean enabled ) 729 setDepthOfField(boolean dofEnabled, double fStop, double focalDistance) 728 setFilmBack(double filmXSize, double filmYSize) 725 setFilmOffset(double filmXOffset, double filmYOffset) 726 setFocalLength( double focalLength) 726 setPlacementFitCode 730 setPlacementShift 729 setTwistAngle( double twistAngle) 724

Index | 1133

setWorldEye( double x, double y, double z ) 721 setWorldEyeViewUp( double ex, double ey, double ez,double vx, double vy, double vz,double ux, double uy, double uz ) 723 setWorldUp( double x, double y, double z ) 722 setWorldView( double x, double y, double z) 722 worldEye( double &x, double &y, double &z ) const 719 worldEyeViewUp( double &ex, double &ey, double &ez,double &vx, double &vy, double &vz,double &ux, double &uy, double &uz) const 721 worldUp( double &x, double &y, double &z ) const 720 worldView( double &x, double &y, double &z ) const 720 statusCode AlPickable pick( void ) 731 unpick( void ) 731 statusCode AlPickList applyIteratorToItems( AlIterator* iter, int& rc ) 734 applyIteratorToItems( AlIteratorWithParent *iter, int& rc ) 735 asynchronousPick( AlUserPickList& list ) 739 clearPickList( void ) 735 firstPickItem() 733 getPickMask( int& mask ) 739 nextPickItem() 733 pickAreaFromScreen( Screencoord x1, Screencoord y1, Screencoord x2, Screencoord y2 ) 737 pickByName( char* name ) 736 pickFromScreen( Screencoord x, Screencoord y ) 736 popPickList() 738 prevPickItem() 734

pushPickList(boolean copy) 737 setPickMask( int mask ) 738 statusCode AlPixFile close 742 fileFormat 743 openForRead 742 openForWrite 741 statusCode AlPlaneAttributes centerPoint( double& x, double& y, double& z ) const 745 coefficients( double& c_a, double& c_b, double& c_c, double& c_d ) const 745 statusCode AlPlayFrame viewFrame(const double frame, const boolean doRedraw) 750 statusCode AlPointConstraint create 752 create( AlDagNode* srcNode, AlDagNode* destNode ) 752 point( double pnt\ 753 statusCode AlPointLight create() 754 statusCode AlPromptBox( AlConfirmType type, char *msg, AlAnswerType* answer,short x, short y ) 610 statusCode AlRadialLocator center(double &x, double &y, double &z) const 760 create(const AlCurve *curve, double u) 759 create(const AlCurveOnSurface *curve, double u) 759 leftJustify(boolean &leftJustify) const 762 offset(double &offsetValue) const 761 parameter(double &u) const 761 radius(double &radiusValue) const 760 setLeftJustify(boolean leftJustify) 762 setOffset(double offset) 761 setParameter(double u) 760

1134 | Index

statusCode AlRender animationRange( double& start, double& end, double& by) 768 AntiAlias setMax( AlRender Quality q, int num) 774 setMin( AlRender Quality q, int num) 774 setThreshold( AlRender Quality q, double num ) 775 Blur setMotionBlur( boolean on ) 780 setPostAdjacent( int adj ) 779 setPostCenter( int center ) 779 setPostDiagonal( int diag ) 780 setPostFilter( boolean on ) 778 setShutterAngle( double shutter ) 781 Composite setCoverageThreshold( double cover ) 778 setEnabled( boolean on ) 778 HiddenLine fillColor( double& r, double &g, double &b) 790 lineColor( double& r, double& g, double& b) 791 setFillColor( double r, double g, double b ) 791 setLineColor( double r, double g, double b ) 791 setPatchLinesU( int lines ) 792 setPatchLinesV( int lines ) 792 setUseFillColor( boolean useFill ) 790 Image readResolutions( AlList* &resolutions ) 794 setAspectRatio( double aspect ) 790

setDepthFormat( AlRender Image DepthFormat depth ) 785 setFields( AlRender Image Fields setFields ) 786 setFormat( AlRender Image Format imageFormat ) 785 setGammaCorrection( double gamma ) 787 setIgnoreFilmGate( boolean ignoreGate ) 786 setOddFirst( boolean oddFirst ) 786 setResolutionX( int xres ) 789 setResolutionY( int yres ) 789 setXYRatioLock( boolean ratioLock ) 788 Limits setCreatePreview( AlRender Quality q, boolean on ) 775 setMaxReflections( AlRender Quality q, int num) 776 setMaxRefractions( AlRender Quality q, int num) 776 setMaxShadowLevels( AlRender Quality q, int num ) 777 setSubdivideRecurse( int num ) 777 Misc setAttenuateTransparency( boolean on ) 784 setDepthMapsInMemory( boolean on ) 784 setGeometrySource( AlRender Misc GeometrySource source ) 781 setKeepNonglowedImage( boolean on ) 783

Index | 1135

setNoTransparencyInDepth( boolean on ) 782 setSkeletons( boolean on ) 782 setSpotLightDepthMaps( boolean on ) 783 setTextures( boolean on ) 781 setTransparency( double trans ) 783 Particle setFramesPerSecond( int frames ) 793 setShow( boolean on ) 793 setSimulationSubsteps( int substeps ) 793 setAnimation( boolean on ) 768 setAnimationRange( AlRender AnimationRange range ) 768 setAnimationRange( double start, double end, double by) 769 setHiddenLineParams( AlRender Scope scope ) 770 setQualityScope( AlRender Scope scope ) 770 setQualityType( AlRender Quality q ) 770 setRender( AlRender Source source ) 767 Subdivision setAdaptiveMax( AlRender\ \ Quality q, int num) 773 setAdaptiveMin( AlRender\ \ Quality q, int num) 772 setAdaptiveThreshold( AlRender Quality q, double num ) 773

setType( AlRender\ \ Quality q, AlRender\ \ Subdivision\ \ Type t 1) 7 7 setUniformU( AlRender\ \ Quality q, int num ) 771 setUniformV( AlRender\ \ Quality q, int num) 772 statusCode AlSet applyIteratorToMembers( AlIterator* iter, int& rc ) 808 create( const boolean exclusive) 804 deleteObject() 804 nextSetD() 806 prevSetD() 806 removeFromAllSets( AlSettable *setobj ) 808 removeMember( AlSetMember *setMember ) 808 setName( const char* newName ) 805 statusCode AlSetDouble( const char *name, double val ) 609 statusCode AlSetInteger( const char *name, int val ) 608 statusCode AlSetMember nextSetMemberD() 810 prevSetMemberD() 810 removeFromSet( AlSet *set ) 811 statusCode AlSetString( const char *name, const char *val ) 609 statusCode AlSettable addToSet( AlSet *set ) 814 applyIteratorToSets( AlIterator* iter, int &rc ) 814 nextSetD( AlSet* lastSet ) const 813 prevSetD( AlSet* lastSet ) const 813 removeFromAllSets() 816

1136 | Index

statusCode AlShader addTexture( const char* fieldName, const char* textureName, AlTexture** returnCreatedTexture ) 824 applyIteratorToTextures( AlIterator *iter, int &rc ) 825 create() 818 deleteObject() 819 nextTextureD( AlTexture* last_texture ) const 822 parameter( const AlShadingFields field,double& result )const 820 removeTexture( const char* fieldName ) 823 setBlindData 826 setName( const char *newName) 820 setParameter( const AlShadingFields field,const double value ) 821 setShadingModel( const char* model ) 821 statusCode AlShell addToShell( AlTrimRegion * region, boolean shrink_surface ) 832 area( double& area, boolean worldCoordinates, double tolerance ) 837 assignShader( AlShader* shader ) 834 circumference( double& circ, boolean worldCoordinates, double tolerance ) 837 create( AlTrimRegion * region, boolean shrink_surface ) 831 layerShader( AlShader* shader ) 834 nextShaderD( AlShader* last_shader ) const 833 renderInfo( AlRenderInfo &renderInfo ) const 835

setDisplayMode( AlDisplayModeType mode, boolean on_or_off ) 836 setRenderInfo( const AlRenderInfo &renderInfo ) const 835 statusCode AlSphereLight create() 845 setArc( double arc ) 846 statusCode AlSpotLight create() 848 direction( double &x, double &y, double &z ) const 855 setDirection( double x, double y, double z ) 855 setDropOff( double newDropoff ) 850 setMaxBias( double newMaxBias ) 852 setMinBias( double newMinBias ) 851 setMultFactor( int newMultFactor ) 853 setOffset( int newOffset ) 853 setPenumbra( double newPenumbraAngle ) 854 setShadowSize( int newShadowSize ) 854 setSpreadAngle( double newSpreadAngle ) 852 statusCode AlSurface addCurveOnSurface( AlCurveOnSurface* AlCos ) 895 area( double& area, boolean worldCoordinates, double tolerance ) 880 assignShader( AlShader* shader ) 893 circumference( double& circumference, boolean worldCoordinates, double tolerance ) 881 create(int uDeg,int vDeg,curveFormType uForm,curveFormType vForm.... 867868

Index | 1137

createRevolvedSurface( const double startPoint\ 870 CVsAffectedPosition( const AlTM& tm, double CVList\ 877 CVsAffectedPositionInclMultiples( const AlTM& tm, double CVList\ 886 CVsUnaffectedPosition( double CVList\ 878 CVsUnaffectedPositionInclMultiples( double CVList\ 887 CVsWorldPosition(double CVList\ 876 CVsWorldPositionInclMultiples( double CVList\ 886 deleteObject() 866 doUpdates( boolean newState ) 878 eval(double u, double v, boolean worldCoordinates, double P\ 882 layerShader( AlShader* shader ) 894 nextShaderD( AlShader* last_shader ) const 893 project( AlCurveNode* curveNode, double vector\ 889 realuKnotVector( double knotVector\ 891 realvKnotVector( double knotVector\ 891 removeCurveOnSurface( AlCurveOnSurface* AlCos ) 896 renderInfo( AlRenderInfo &renderInfo ) const 894 setCVsUnaffectedPosition 879 setCVsUnaffectedPosition( const double CVList\ 878 setCVsUnaffectedPositionInclMultiples( const double CVList\ 887 setDisplayMode( AlDisplayModeType mode, boolean on_or_off ) 897 setRealuKnotVector( const double knotVector\ 891 setRealvKnotVector( const double knotVector\ 892

setRenderInfo( const AlRenderInfo &renderInfo ) const 895 setuKnotVector( const double uKnotVector\ 884 setvKnotVector( const double vKnotVector\ 885 trim( int count, const AlCurveOnSurface* uvTrimCurves\ 902 trim( int count, const double u\ 902 uKnotVector( double knotVector\ 883 uniformRebuild( AlSurfaceNode* &newSurfaceNode, int requested_nu, int requested_nv, boolean inU, boolean inV, boolean matchParameterization ) 904 unpileEndKnots( int whichEnds, const double interval\ 889 vKnotVector( double knotVector\ 884 statusCode AlSurfaceCV affectedPosition( const AlTM& tm, double &x, double &y,double &z, double &w) const 910 applyIteratorToCVsInU( AlIterator* iter, int &rc ) 915 applyIteratorToCVsInV( AlIterator* iter, int &rc ) 917 blindData( int user_type, long& size, const char *& data ) 913 doUpdates( boolean newState ) 911 nextInUD() 907 nextInVD() 907 prevInUD() 908 prevInVD() 908 removeBlindData( int user_type ) 914 setBlindData( int user_type, long size, const char * data ) 914 setMultiplicity( int u, int v ) 911

1138 | Index

setUnaffectedPosition( double x, double y,double z, double w ) 913 setWorldPosition( double x, double y, double z, AlTM tm ) 912 setWorldPosition( double x, double y, double z, boolean includeWorld ) 912 unaffectedPosition( double &x, double &y,double &z, double &w ) const 910 worldPosition( double &x, double &y,double &z, double &w) const 909 statusCode AlSurfaceNode create( AlSurface *newSurface ) 925 setCurvePrecision( int precision ) 926 setPatchPrecision( int precision ) 927 statusCode AlTexture addPerObjectPixEntry( const char* objname,const char* filename ) 941 addTexture( const char* fieldName, const char* textureName, AlTexture** returnCreatedTexture ) 943 applyIteratorToTextures( AlIterator *iter, int &rc ) 945 deleteObject() 935 eval( double u, double v, double x, double y, double z, double nx, double ny, double nz, double usize, double vsize.... 944 nextTextureD( AlTexture* last_texture ) 937 parameter( const AlShadingFields field,double& result)const 938 removePerObjectPixEntry( const char* objname ) 942 removeTexture( const char* fieldName ) 943

setFilename(const char* filename) 939 setName( const char *newName ) 936 setParameter( const AlShadingFields field,const double value) 939 setPerObjectPixFilename( const char* objname,const char* filename ) 941 statusCode AlTorusLight create() 963 setArc( double arc ) 963 setTorusRadius( double torus_radius ) 964 statusCode AlTrimBoundary applyIteratorToCurves 968 convertToUVPolyline( int &n, double *& CVList ) 967 nextBoundaryD() 966 prevBoundaryD() 967 statusCode AlTrimRegion CVsAffectedPosition( const AlTM& tm, double CVList\ 982 CVsAffectedPositionInclMultiples( const AlTM& tm, double CVList\ 984 CVsUnaffectedPosition( double CVList\ 983 CVsUnaffectedPositionInclMultiples( double CVList\ 984 CVsWorldPosition(double CVList\ 982 CVsWorldPositionInclMultiples( double CVList\ 984 eval(double u, double v, boolean worldCoordinates, double P\ 985 hasPersistentID 988 nextRegionD() 980 periodicToNonPeriodic 985 persistentID 987 prevRegionD() 981 realuKnotVector( double knotVector\ 984

Index | 1139

realvKnotVector( double knotVector\ 985 setPersistentID 987 uKnotVector( double knotVector\ 983 vKnotVector( double knotVector\ 983 statusCode AlUnits parseStringAngular( const char* string, char* &ret, const char* format ) 991 parseStringLinear( const char* string, char* &ret, const char* format ) 992 parseStringNoUnits( const char* string, char* &ret, const char* format ) 992 statusCode AlUniverse applyIteratorToActions( AlIterator* iter, int& rc ) 1033 applyIteratorToChannels( AlIterator* iter, int& rc ) 1034 applyIteratorToClouds 1036 applyIteratorToClusters( AlIterator* iter, int& rc ) 1035 applyIteratorToDagNodes( AlIterator* iter, int& rc ) 1033 applyIteratorToImagePlanes( AlIterator* iter, int& rc ) 1017 applyIteratorToLocators 1035 applyIteratorToSets( AlIterator* iter, int& rc ) 1034 applyIteratorToShaders( AlIterator* iter, int& rc ) 1035 applyIteratorToWindows( AlIterator *iter, int& rc ) 1017 blindData 1019 blindData( int type, long& size, const char*& ptr ) 1018 constructionPlaneTransform 1041 createNewStage( const char* name ) 1014 createNewStage( const char* name, char*& stagename ) 1014 deleteAll() 1026

deleteAllLocators() 1026 deleteAllStages( void ) 1011 deleteStage( const char *name ) 1011 doUpdates( boolean newState ) 1000 expandFileName( char expandedName\ 1002 frameRange(AlFrameRangeType rangeType, double &start, double &end, double &by) 1039 importCloudFile 1031 initialize( AlCoordinateSystem up, boolean initProjectEnv ) 1001 mergeAllStages( void ) 1011 mergeStage( const char *name ) 1010 nextCameraD 1025 nextChannelD(AlChannel *curChannel ) 1021 nextLayerD 1022, 1028 nextShaderD( AlShader* curShader ) 1024 redrawScreen( unsigned flags ) 1032 removeBlindData 1020 removeBlindData( int type ) 1020 renameStage( const char* oldName, const char *newName ) 1014 retrieve( const char *fileName ) 1006 retrieveOptions( AlRetrieveOptions &options ) 1006 retrieveStageSet 1015 saveStageSet 1015 setBackgroundSource( const char *name ) 1013 setBlindData( int type, long size, const char* ptr ) 1019 setCurrentStage( const char* name ) 1010 setLayersEnabled 1023, 1030

1140 | Index

setRetrieveOptions( const AlRetrieveOptions &options ) 1006 setStageWireFileName 1016 setVisibility( const char *name, boolean on_or_off ) 1012 setWindowSource( const char *name ) 1013 setWireFileWindowSize( int sizeX, int sizeY ) 1003 sortLayersInLayersBar 1030 store( const char * fileName, AlDagNode* dagNode ) 1008 userPrefColor 1039 visibility( const char *name, boolean& on_or_off ) 1012 wireFileWindowSize( int &sizeX, int &sizeY ) 1003 writeSDL( const char *filename, boolean store_active, double start, double end, double by ) 1038 writeSDLNoAnimation 1037 writeSDLNoAnimation( const char *filename, boolean store_active ) 1037 statusCode AlUserCommand addConstructorContact( AlDagNode *dagNode, AlContact *contact ) 1055 addConstructorRef( AlCurveOnSurface *curveOnSurface ) 1054 addConstructorRef( AlDagNode *dagNode ) 1054 addTargetContact( AlDagNode *dagNode, AlContact *contact ) 1056 addTargetRef( AlCurveOnSurface *curveOnSurface ) 1056 addTargetRef( AlDagNode *dagNode ) 1055 deleteAllReferences() 1057 retrieveWire( AlInput *input ) 1051 storeSDL( ofstream &outputSDL ) 1052

storeWire( AlOutput *output ) 1050 statusCode AlViewFrame viewFrame( AlAnimatable* obj, const double frame, AlViewFrame\ \ Options opts ) 1061 viewFrame( AlCurve* curve, const double frame, AlViewFrame\ \ Options opts ) 1061 viewFrame( AlSurface* surface, const double frame, AlViewFrame\ \ Options opts ) 1062 viewFrame(const double frame) 1060 statusCode AlVolumeLight setConcentric(double concentric) 1073 setDecay(double decay) 1072 setDecayStart(double decay_start) 1072 setDirectional(double directional) 1074 setDirectionality(double directionality) 1073 setDropoff(double dropoff) 1074 setDropoffStart(double dropoff_start) 1075 setIntensity(double intensity) 1071 setRadial(double radial) 1074 setShadows(boolean shadows) 1069 setSpecular(boolean specular) 1069 setTurbulenceAnimated(boolean animated) 1070 setTurbulenceDirectional(boolean directional) 1070 setTurbulenceGranularity(double granularity) 1077 setTurbulenceIntensity(double intensity) 1075 setTurbulencePersistance(double persistance) 1076

Index | 1141

setTurbulenceRoughness(double roughness) 1077 setTurbulenceSpaceRes(int space_res) 1070 setTurbulenceSpread(double spread) 1076 setTurbulenceTimeRes(int time_res) 1071 setTurbulenceVariability(double variability) 1077 statusCode AlWindow aliasWindowSize( int& sizex, int& sizey ) 1089 create( AlViewType tp ) 1082 deleteObject() 1082 isZoom( boolean& b ) 1084 mapToWorldSpace( Screencoord x, Screencoord y,double& rx1, double& ry1, double& rz1,double& rx2, double& ry2, double& rz2 ) 1088 nextD() 1083 position( Screencoord& x, Screencoord& y ) 1085 priority( int& p ) 1087 resolution( Screencoord& x, Screencoord& y ) 1086 setCamera( AlPerspectiveCamera* cam ) 1085 setGridSize( double size ) 1090 setPosition( Screencoord x, Screencoord y ) 1086 setPriority( int p ) 1087 setResolution( Screencoord x, Screencoord y, AlCornerType c, AlAspectType t ) 1086 windowType( AlViewType& tp ) 1083 worldSpaceBounds( double& xmin, double& ymin, double& zmin, double& xmax, double& ymax, double& zmax ) 1088

statusCode AlXevents addXdevice( const char * name,int (*devXopen)(Widget, XDeviceInfoPtr) ) 1093 addXdevID( const char *name, XDevice *xdev, int dev_id ) 1095 addXdevType( char *name, const char *type,int type_id, int class_id ) 1095 applicationNotify() 1091 getXdevice( const char * dev, XDevice **xdev ) 1094 getXdevID( const char * dev, int& value ) 1093 getXdevType( const char * dev, const char * event, int& value ) 1094 installHandler( int (*func)( XEvent* ) ) 1091 uninstallHandler( int (*func)( XEvent* ) ) 1092

T
trim_to_surf 799

U
uniform_u 795 uniform_v 796 units 800

V
VDAFS options 798 VDAIS options 798 void *AlUserCommand asDerivedPtr() 1053 void AlAllowMenuRebuilds 606 void AlDebug checkpoint 422 void AlLinkItem 601 void AlList append( AlLinkItem *item ) 602

1142 | Index

clear() 603 void AlPerformance setActionWindowAfterModification( boolean b ) 712 setActionWindowDuringXform( boolean b ) 712 setBlendDuringPlayback( boolean b ) 711 setConstraintsAfterModification( boolean b ) 708 setConstraintsDuringPlayback( boolean b ) 708 setConstraintsDuringXform( boolean b ) 708 setConstructionHistoryAfterModification( boolean b ) 710 setConstructionHistoryDuringPlayback( boolean b ) 711 setConstructionHistoryDuringXform( boolean b ) 710 setConstructionHistoryRound( boolean b ) 711 setDisplayablesAfterModification 713 setDisplayablesDuringPlayback 713 setDisplayablesDuringXform 713 setDrawTrimBoundaries( boolean b ) 706 setEvaluationsPerUpdate 705 setExpressionsAfterModification( boolean b ) 706 setExpressionsDuringPlayback( boolean b ) 707 setExpressionsDuringXform( boolean b ) 707 setIkAfterModification( boolean b ) 709 setIkDuringPlayback( boolean b ) 709 setIkDuringXform( boolean b ) 709

setMotionPrecision( AlPrecisionType t ) 705 setRedrawPrecision( AlPrecisionType t ) 704 setTrimBoundariesDuringPlayback( boolean b ) 706 void AlPersistentID id( int &value0, int &value1, int &value2, int &value3 ) 715 void AlPlayBack getStartEndBy (double &start, double &end, double &by) 748 gotoEnd () 748 gotoFrame (const double frame) 748 gotoStart () 748 nextFrame () 747 nextKeyframe () 748 playForward () 747 playReverse () 747 previousFrame () 747 previousKeyframe () 748 stop () 747 void AlPrintf( AlOutputType ot, const char* fmt, ... ) 756 void AlRebuildMenus 606 void AlResetAllMenus( void ) 606 void AlVprintf( AlOutputType ot, const char* fmt, va_list ap ) 756

W
Widget AlXevents getAppShell( void ) 1092

X
XtAppContext AlXevents getXtAppContext( void ) 1092

Index | 1143

1144