Preface How To Find Information in This Manual 1-xv Audience 1-xvi Conventions 1-xvi File Naming Conventions 1-xviii 1 AVS/Express Overview 1.1 Overview 1-2 Working with AVS/Express 1-2 AVS/Express Kits 1-5 1.2 Terms and Concepts 1-6 Objects 1-6 Base Types 1-6 Templates 1-7 Instances 1-7 Object-Oriented Paradigm 1-7 1.3 AVS/Express Object Hierarchy 1-10 Terminology 1-12 Projects and Your Development Environment 1-12 1.4 Object Characteristics 1-13 Name 1-13 Derivation Hierarchy 1-13 Properties and Attributes 1-13 Subobjects 1-14 1.5 Values and Connections 1-15 Connections and Object Execution 1-15 1.6 Object Manager 1-17 1.7 Project Mechanism 1-18 1.8 Application Components 1-20 1.9 Building Applications and Application Components 1-22 Building Application Components with AVS/Express 1-22 Adding Modules to AVS/Express 1-22 2 Starting and Exiting AVS/Express 2.1 Starting AVS/Express 2-2 Starting AVS/Express 2-2 2.2 Using Environment Variables 2-6 Setting Required Environment Variables 2-6 Using Shared Libraries on UNIX Platforms 2-7 Setting Environment Variables In A Startup File 2-7 Other Environment Variables Used By AVS/Express 2-8 2.3 Using Command Line Options 2-12 2.4 Exiting AVS/Express 2-16 3 Working with the Network Editor 3.1 Choosing Your Initial Application 3-2 The DataViewer Applications 3-4 The Default Application 3-6 The Module Stack Application 3-7 The Scratch Pad 3-7 Save Project's Default Application 3-7 Install Area Project 3-7 3.2 Network Editor Overview 3-10 The Network Editor Components 3-10 3.3 Building Networks in a DataViewer Application 3-13 Adding Modules 3-15 Using The Viewer Editors 3-15 3.4 Visual Programming 3-17 Object Types 3-17 Adding Modules To AVS/Express 3-20 3.5 Handling Objects in the Workspace 3-22 Selecting More than One Object 3-22 Repositioning an Object 3-23 Resizing a Window 3-24 Zooming In or Out on Objects in a Window 3-25 Resetting a Macro Window 3-25 Using Automatic Layout 3-26 Viewing and Setting a Scalar Object Value 3-26 Viewing and Setting an Array Value 3-26 Traversing an Array of Groups 3-27 Viewing and Setting an Object's Name 3-28 Viewing and Setting an Object's Type 3-28 Viewing and Setting an Object's Attributes 3-29 3.6 Manipulating Objects 3-30 Cut 3-30 Copy 3-30 Paste 3-30 Duplicating Objects 3-31 Deleting an Object 3-31 Saving Objects to a V File 3-32 Loading Objects from a V File 3-32 3.7 AVS/Express' Object-Oriented Paradigm 3-33 AVS/Express Object Hierarchy 3-34 3.8 Reusing Your Work 3-36 Saving Your Work in Applications 3-36 Saving Your Work In Projects 3-36 Generating Runtimes 3-37 3.9 Changing Your Project Configuration 3-38 3.10 Journaling 3-39 Recording 3-39 Stopping 3-39 Playback 3-39 3.11 Using On-line Help and On-line Documentation 3-41 To display on-line help for an object: 3-41 Displaying the Top-Level Contents 3-41 3.12 Displaying Errors 3-42 4 Using the DataViewerApplications 4.1 Overview of the DataViewer Applications 4-2 4.2 Connecting to the Viewer in the Network Editor 4-4 Using the Uviewer Modules 4-4 Three-Dimensional Scenes 4-5 Two-Dimensional Scenes 4-6 4.3 Understanding the AVS/Express Applications 4-8 User interface components 4-8 User Interface Regions 4-9 Adding Components to DefaultApplication 4-10 How Automatic UI Connections Are Made 4-10 Changing an Application's UI 4-11 Changing How Application UIs Are Constructed 4-11 4.4 Using the Viewer Window Controls 4-12 Selecting an Object in the Scene 4-12 The Execution Interrupt Toggle 4-13 The Module Execution Status Bar and Button 4-14 4.5 Using the Toolbar 4-15 Selecting the Transformation Mode 4-16 Reset, Normalize, and Center Tools 4-16 Perspective Toggle 4-17 Editor Tools 4-18 4.6 Using the DataViewer Editors 4-21 Working with an Editor 4-22 For More Information 4-24 4.7 The Module Editor Interface 4-25 Usage Notes 4-26 4.8 Using the Print Editor 4-28 The Print Editor Interface 4-28 Specifying the File Format 4-29 Page Orientation 4-30 Background 4-30 Page size 4-30 Width and Height 4-31 Resolution 4-31 Specifying an Output File 4-31 4.9 Using the View Editor 4-32 For More Information 4-33 4.10 Using the Transform Editor 4-34 Transforming View Objects, Cameras, and Lights 4-34 Transform Modes 4-35 For More Information 4-35 4.11 Using the Light Editor 4-36 About Lighting 4-37 For More Information 4-37 4.12 Using the Camera Editor 4-38 For More Information 4-38 4.13 Using the Object Editor 4-39 4.14 Using the Datamap Editor 4-40 For More Information 4-41 4.15 Using the Graph Editor 4-42 5 Objects in AVS/Express 5.1 Defining Primitive Data Objects 5-2 Using Pointer(Ptr) Objects 5-2 Constraining Primitive Data Objects 5-3 Examples (in V-code) 5-3 5.2 Defining Groups, Modules, and Macros 5-5 Groups 5-5 Modules 5-5 Macros 5-6 5.3 Using the AVS/Express Object Libraries 5-7 Navigating the Hierarchy of Libraries 5-7 Searching Libraries Using the Object Finder 5-8 5.4 Understanding Libraries 5-11 Adding Application-Specific Libraries to the Network Editor 5-11 Templates and Library Objects 5-11 Global Libraries 5-13 Derived Copies of Objects 5-14 Defining a Library that does NOT make Derived Copies 5-14 Creating a New Library 5-15 Customizing Network Editor Libraries 5-19 5.5 Instancing Template Objects 5-25 Object->Load Objects 5-26 Instancing and De-instancing Objects 5-26 Merging Objects 5-27 Parenting to Other Objects 5-27 Reparenting an Object 5-27 5.6 Inheritance and the Derivation Hierarchy 5-29 Single and Multiple Inheritance 5-29 Derivation Hierarchy 5-31 Modifications to Templates, Derived Templates, and Instances 5-33 5.7 Setting an Object's Display State 5-34 5.8 Connecting Objects 5-38 Understanding Ports 5-38 Viewing Subobject Port Information 5-39 Adding a Port 5-40 Exporting a Port 5-40 Removing a Port 5-41 Unexporting a Port 5-41 Making Connections 5-42 Disconnecting Objects 5-45 Connections Between Groups 5-45 5.9 Managing Object Attributes and Properties 5-47 Using the Properties Editor 5-47 Viewing and Setting an Object's Reference Mode 5-51 Viewing and Setting an Object's Array Declaration 5-52 Declaring the Dimensions of an Array 5-52 Setting Port Levels with the Properties Editor 5-55 5.10 Customizing the Appearance of Network Editor Objects 5-57 Customizing Port and Connection Colors 5-57 Specifying an Object's Pixmap 5-57 Customizing the Background of a Macro 5-59 Specifying User Preferences 5-59 5.11 Network Editor Properties 5-62 6 Managing and Editing Objects 6.1 The Object Editor 6-2 Using the Object Editor 6-2 The main Object Editor Pages 6-6 6.2 Editing an Object's Declaration 6-8 Naming an Object 6-8 Specifying the Base Type of a Primitive Data Object 6-8 6.3 Setting the Reference Mode of a Group, Module, or Macro 6-10 6.4 Values and Connections 6-16 Specifying a Primitive Object's Value or Connection 6-16 Exporting Parameters And Ports 6-16 Value Expressions 6-17 Connecting Objects by Name 6-27 Defining Link Objects 6-33 6.5 Declaring an Array Object 6-36 Defining Arrays Of Groups, Modules, And Macros 6-36 6.6 Methods and Parameters 6-41 Methods 6-41 Parameters 6-44 Defining Parameter and Method Interaction 6-45 6.7 Specifying Code Management Properties 6-47 6.8 The Library Editor Pages 6-52 6.9 The Field Object Editors 6-54 Mesh Editor 6-54 Using the Cell Set Editor Pages 6-59 Using the Node and Cell Data Editors 6-66 6.10 Editing File Access Objects 6-69 Editing the File Reader Objects 6-70 Editing the File Search Objects 6-71 7 V and the V Command Processor 7.1 Introduction 7-2 7.2 Using the V Command Processor 7-3 Accessing the VCP Window 7-3 Navigating the AVS/Express Object Hierarchy 7-4 7.3 V Comments 7-9 C-Style Comments 7-9 C++-Style Comments 7-9 Special Comments 7-10 7.4 V Statements 7-11 The V Create Statement 7-11 The V Modify Statement 7-15 The V Delete Statement 7-19 Value Expressions 7-20 7.5 V Commands 7-35 Syntax 7-35 Command Summary 7-36 7.6 V Functions 7-46 Mathematical Functions 7-46 Logical Functions 7-49 Array Functions 7-49 Miscellaneous Functions 7-53 8 Developing Modules 8.1 Introduction 8-2 Adding New Modules 8-2 The Add Module Tool 8-2 Modifying Existing Modules 8-3 8.2 Module Overview 8-4 Parameters 8-4 Methods 8-4 Setting Method and Parameter Attributes 8-6 Defining the Scope of a Method 8-10 Event Notification of Methods 8-11 Controlling Method Execution Order 8-13 8.3 Target Functions 8-15 Writing Target Functions 8-15 C Target Functions 8-16 C++ Target Functions 8-18 FORTRAN Target Functions 8-24 8.4 Providing Code Management Information 8-28 9 Object Manager APIs 9.1 Introduction 9-2 9.2 The C and C++ APIs: Overview 9-4 Using the Online Help System Descriptions 9-4 C and C++ API Routines 9-5 C and C++ API Header Files 9-14 9.3 C API Usage Notes 9-16 Object Manager Data Structures 9-16 Object Manager Return Values 9-19 Using the Mode Argument 9-20 Accessing the Object Hierarchy 9-21 Determining When Parameters Change 9-24 Setting and Getting Data Values 9-25 Creating and Deleting Objects 9-32 Manipulating Connections 9-35 Managing Arrays of Groups, Modules, and Macros 9-38 Manipulating Properties and Attributes 9-41 Saving and Restoring Object Descriptions 9-43 9.4 C++ API Usage Notes 9-48 Getting Pointers to C++ Objects 9-48 Accessing Subobject Values 9-50 Additional C++ Methods 9-56 Using OM Routines with an OMX Object as an Argument 9-57 Determining When Parameters Change 9-57 Manipulating Connections 9-58 Mapping AVS/Express Object Names to C++ Class Names 9-59 Managing C++ Generated Files 9-60 Managing Dependencies on Other Code 9-60 Importing Existing C++ Classes 9-62 Constructing User Classes 9-64 Defining Abstract User Classes 9-65 Adding Your Own Member Variables 9-65 Exporting C++ Classes 9-66 Example of Generated C++ Classes 9-69 9.5 The FORTRAN API: Overview 9-73 Using the Online Help System Descriptions 9-73 FORTRAN API Routines 9-73 FORTRAN API Header Files 9-76 9.6 FORTRAN API Usage Notes 9-77 Object Manager Data Structures 9-77 FORTRAN Arrays 9-79 Object Manager Return Values 9-79 Using a Mode Argument 9-80 Accessing the Object Hierarchy 9-80 Determining When Parameters Change 9-81 Setting and Getting Data Values 9-82 10 Projects and Processes 10.1 Overview 10-2 Creating and Compiling Projects 10-2 Creating and Compiling Processes 10-3 Creating a Runtime Project 10-3 10.2 Projects and Processes 10-4 The Main (express) Process 10-4 Setting the Process Type 10-5 Process Components 10-6 Defining Your Own Main Process 10-9 Defining Processes for Objects 10-12 Creating New Processes 10-14 Compiling Projects and Processes 10-14 10.3 AVS/Express Code Generation 10-22 Marking Needed Objects 10-22 Generating Code 10-23 10.4 Projects 10-26 Project Architecture 10-26 Saving Compiled Projects (Generating a Runtime Project) 10-30 10.5 Integrating with a Microsoft Foundation Class (MFC) Application 10-38 Creating a Project with Microsoft Developer Studio 10-39 Changing the Project Settings 10-41 Adding Required Code and Methods 10-42 Running the Project and Displaying Data 10-45 10.6 Creating ActiveX Controls using AVS/Express C++ Classes using VC ++ 10-46 11 Shared Libraries 11.1 Loading Methods Dynamically (UNIX) 11-2 Writing a Dynamically Shared Method 11-2 Building the Shared Library 11-2 Editing and Re-Loading a Dynamically Shared Module. 11-3 Understanding the dyn_libs Property 11-3 The dyn_libs Property and C++ code 11-4 11.2 Dynamic Link Library - DLL (Windows) 11-6 Required Changes for All Users who Build Projects 11-7 Do Not Statically Link Projects 11-9 Writing Dynamically Loaded Modules In AVS/Express 11-9 Building the External DLL 11-11 Editing and Re-Loading a DLL 11-11 Understanding the dyn_libs Property 11-11 Example: Using an External DLL Method 11-12 The dyn_libs Property and C++ code 11-16 12 Adding Status and Interrupt Controls 12.1 Status and Interrupt Capabilities 12-2 Displaying Status Information 12-2 Managing User Interrupts 12-2 12.2 The Scheduler 12-3 12.3 Connecting a User Interface to the Scheduler 12-5 Using the Standard Interface 12-5 Building and Using a Custom Interface 12-5 Widget Execution Priority 12-6 12.4 Declaring a Module's Behavior 12-7 Enabling and Disabling Status Information 12-7 Enabling and Disabling Interruptibility 12-7 12.5 Setting and Querying Information from an Update Function 12-8 Accessing Scheduler Information 12-8 Setting a Range for the Scheduler.percent_done Subobject 12-8 Additional Trapping for Memory Allocation Errors 12-9 13 Debugging Objects 13.1 Debugging Networks 13-2 General Debugging Guidelines 13-2 Accessing Object Information 13-3 Tracing Method Execution 13-4 Tracing Operations on Specific Objects 13-8 Additional Debugging Routines 13-8 13.2 Debugging Modules 13-10 Debugging the Main Process 13-11 Debugging an External Process 13-11 Getting Object Information While Debugging Your Module 13-15 Determining Why a Method Does Not Execute 13-16 Resolving Incorrect Method Execution Order 13-17 14 Properties, Attributes, Primitives, and Functions 14.1 Base Types 14-2 14.2 Properties and Attributes 14-3 General Properties and Attributes 14-3 Network Editor Properties 14-7 Module-Control Properties and Attributes 14-12 Code Management Properties 14-13 C++ Interface Properties 14-18 14.3 Defining Combinations of Properties and Attributes 14-22 The Merge Operation 14-22 Maintaining Properties and Attributes 14-22 14.4 Built-in Functions 14-24 Mathematical Functions 14-24 Logical Functions 14-25 Array Functions 14-25 Examples 14-27 Miscellaneous Functions 14-28 cache Function 14-28 index_of Function 14-29 merge Function 14-29 name_of Function 14-30 str_array Function 14-30 str_format Function 14-31 switch Function 14-32 15 Application Design Issues 15.1 Constructing Macros 15-2 Building Reusable Objects 15-3 Structuring Objects in Hierarchical Layers 15-4 Making Use of Templates 15-8 Constructing Objects with a Common Interface 15-9 15.2 Managing Projects and Files 15-11 templ.v 15-11 Project->Save vs. Object->Save Objects 15-11 Syntax for Referring to Library Objects 15-13 Organizing Objects into Libraries 15-14 Using build_dir 15-15 Structuring Project Directories 15-16 Source Code Control Systems 15-16 getenv V-function 15-17 Editing V-files 15-18 15.3 Cross-Platform Issues 15-19 Functional Differences 15-19 Cross-Platform Look and Feel 15-19 Using Formulas to Specify Widget Geometry 15-21 15.4 Dynamic Applications 15-22 15.5 Module Design: Error Handling 15-24 A Worldwide Language and Font Support A.1 Introduction A-2 A.2 Language Support A-3 Text Representations A-3 Local Character Sets A-4 A.3 Locales A-6 Locale Model A-6 Levels of Support A-6 Initialization A-7 Keyboard Input A-8 Input Encoding A-8 Output Encoding A-9 Errors A-9 Environment Information A-10 Supported Locales A-11 A.4 Text Processing A-17 Pathways A-17 Strings in V A-19 Hexadecimal Format A-20 V Output A-21 A.5 Localization A-22 Username Property A-22 Localized Projects A-23 Examples A-24 A.6 Internationalization A-26 Dictionary Property A-26 Dictionary Files A-27 Internationalized Projects A-28 Internationalizing a Localized Project A-30 Examples A-31 A.7 Adding Fonts to AVS/Express A-34 fonts.v A-34