333333333 3333 AVS DEVELOPER'S 333333333333GUIDE Release 4 May, 1992 Advanced Visual Systems Inc.33333333 Part Number: 320-0013-02, Rev B NOTICE This document, and the software and other products described or referenced in it, are con®dential and proprietary products of Advanced Visual Systems Inc. (AVS Inc.) or its licensors. They are provided under, and are subject to, the terms and conditions of a written license agreement between AVS Inc. and its customer, and may not be transferred, disclosed or otherwise provided to third parties, unless otherwise permitted by that agreement. NO REPRESENTATION OR OTHER AFFIRMATION OF FACT CONTAINED IN THIS DOCUMENT, INCLUDING WITHOUT LIMITATION STATEMENTS REGARDING CAPACITY, PERFORMANCE, OR SUITABILITY FOR USE OF SOFTWARE DESCRIBED HEREIN, SHALL BE DEEMED TO BE A WARRANTY BY AVS INC. FOR ANY PURPOSE OR GIVE RISE TO ANY LIABILITY OF AVS INC. WHATSOEVER. AVS INC. MAKES NO WARRANTY OF ANY KIND IN OR WITH REGARD TO THIS DOCUMENT, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. AVS INC. SHALL NOT BE RESPONSIBLE FOR ANY ERRORS THAT MAY APPEAR IN THIS DOCUMENT AND SHALL NOT BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION INCIDENTAL, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF OR RELATED TO THIS DOCUMENT OR THE INFORMATION CONTAINED IN IT, EVEN IF AVS INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. The speci®cations and other information contained in this document for some purposes may not be complete, current or correct, and are subject to change without notice. The reader should consult AVS Inc. for more detailed and current information. Copyright 1989, 1990, 1991, 1992 Advanced Visual Systems Inc. All Rights Reserved AVS is a trademark of Advanced Visual Systems Inc. STARDENT is a registered trademark of Stardent Computer Inc. IBM is a registered trademark of International Business Machines Corporation. AIX, AIXwindows, and RISC System/6000 are trademarks of International Business Machines Corporation. DEC and VAX are registered trademarks of Digital Equipment Corporation. NFS was created and developed by, and is a trademark of Sun Microsystems, Inc. HP is a trademark of Hewlett-Packard. CRAY is a registered trademark of Cray Research, Inc. Sun Microsystems is a registered trademark of Sun Microsystems, Inc. SPARC is a registered trademark of SPARC International. SPARCstation is a registered trademark of SPARC International, licensed exclusively to Sun Microsystems, Inc. OpenWindows, SunOS, XDR, and XGL are trademarks of Sun Microsystems, Inc. UNIX and OPEN LOOK are registered trademarks of UNIX System Laboratories, Inc. Motif is a trademark of the Open Software Foundation. IRIS and Silicon Graphics are registered trademarks of Silicon Graphics, Inc. IRIX, IRIS Indigo, IRIS GL, Elan Graphics, and Personal IRIS are trademarks of Silicon Graphics, Inc. Mathematica is a trademark of Wolfram Research, Inc. X WINDOW SYSTEM is a trademark of MIT. PostScript is a registered trademark of Adobe Systems, Inc. FLEXlm is a trademark of Highland Software, Inc. RESTRICTED RIGHTS LEGEND (U.S. Department of Defense Users) Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights In Technical Data and Computer Software clause at DFARS 252.227±7013. RESTRICTED RIGHTS NOTICE (U.S. Government Users excluding DoD) Notwithstanding any other lease or license agreement that may pertain to, or accompany the delivery of this computer software, the rights of the Government regarding its use, reproduction and disclosure are as set forth in the Commercial Computer Software Ð Restricted Rights clause at FAR 52.227±19(c)(2). Advanced Visual Systems Inc. 300 Fifth Ave. Waltham, MA 02154 TABLE OF CONTENTS 1 AVS Overview Introduction 1-1 AVS Overview 1-1 Modules 1-2 Data Types 1-3 AVS Flow Networks 1-4 Data Flow 1-5 Module Life Cycle 1-6 Use of Shared Memory 1-6 Heterogeneous Network Support 1-7 Data Flow Diagram 1-8 Multiple Module Processes in AVS 1-10 Release Compatibility 1-11 Portability Issues 1-11 Writing Portable Code 1-11 Porting Binary Data Files 1-12 Program Examples Online 1-13 2 AVS Data Types Introduction 2-1 Bytes 2-3 Integers 2-3 Floating-Point Numbers 2-4 Text Strings 2-4 Fields 2-4 Mapping Computational Space to Coordinate Space 2-4 Uniform Fields 2-5 Rectilinear Fields 2-6 Irregular Fields 2-6 AVS Mapping Information 2-7 Examples of Field Mappings 2-8 Example 1 2-8 AVS DEVELOPER’S GUIDE CONTENTS-1 TABLE OF CONTENTS Example 2 2-10 Example 3 2-10 Example 4 2-11 Example 5 2-12 Example 6 2-12 Field Components 2-13 Declaring Fields 2-16 Manipulating Fields from C 2-17 Manipulating Fields from FORTRAN 2-19 Creating Fields 2-20 Scatter Data 2-21 Image Data 2-21 Volume Data 2-22 Colormaps 2-22 Geometries 2-23 Manipulating Edit Lists 2-25 Templates for New Filter Utilities 2-26 Writing a New Filter Utility 2-27 Converting a Polyhedron 2-27 Converting a Polygon 2-28 Converting a Scalar Mesh 2-28 Converting a Mesh 2-28 Converting a Sphere 2-28 Converting a Disjoint Line 2-28 Converting a Polyline 2-28 Pixel Maps 2-29 Unstructured Cell Data 2-29 Molecular Data Type 2-30 User-Defined Data Types 2-30 3 AVS Modules Modules 3-1 Module Components 3-1 Name 3-1 Type 3-1 Ports 3-2 Parameters 3-3 Parameters As Input Ports 3-3 Functions 3-4 The Description Function 3-5 The Computation Function 3-7 Initialization Function 3-8 Destruction Function 3-8 Subroutines and Coroutines 3-9 Subroutine Modules 3-9 CONTENTS-2 AVS DEVELOPER’S GUIDE TABLE OF CONTENTS Coroutine Modules 3-11 Handling Errors in Modules 3-13 Selective Computation 3-15 Building and Linking Modules 3-15 Writing Subroutines 3-16 Writing Coroutines 3-16 Include Files 3-16 C Language Include Files 3-17 FORTRAN Include Files 3-17 avs_math.h Include File 3-18 Compiling and Linking Modules 3-18 Converting an Existing Application to a Module 3-19 Debugging Modules 3-20 Syntax of avs_dbx 3-20 Using avs_dbx 3-21 Module Examples 3-23 4 Advanced Topics Introduction 4-1 Memory Allocation Debugging 4-1 Run Time Environment Variables 4-2 Coroutine Synchronization 4-4 Coroutine Scheduling with X 4-5 Coroutine Scheduling with Other Devices 4-6 Synchronous Execution 4-6 Upstream Data 4-7 Overview of Upstream Data Feedback Mechanism 4-7 Implementing Upstream Data 4-8 Transformation Information 4-8 Selection Information 4-11 Rules for Picking Objects 4-13 Picking the Top Level Object 4-13 User-Defined Upstream Data 4-15 Automatic Connections of Ports 4-15 Port Classes 4-15 Port Visibility 4-17 User-Defined Data 4-18 Defining User-Defined Data 4-18 Using a User-Defined Data Type On an Input Port 4-19 Using a User-Defined Data Type On an Output Port 4-20 Image Picking Data Type 4-21 Multiple Modules in a Single Process 4-21 Restrictions 4-22 Implementing Multiple Modules Processes 4-23 Implementing Reentrant Modules 4-24 AVS DEVELOPER’S GUIDE CONTENTS-3 TABLE OF CONTENTS Modifying Modules that Share Processes 4-24 Linking Multiple Modules Together 4-24 Module Groups 4-27 5 Command Language Interpreter Introduction 5-1 Access to the CLI 5-1 Command Line Option 5-1 Server Option 5-2 Module Access 5-2 .avsrc File Option 5-3 Basic Concepts 5-4 Commands and Tokens 5-4 Case Sensitivity 5-4 Interrupting CLI execution 5-5 Multiple Line Commands 5-5 Variable References 5-5 Output Redirection 5-6 Identifiers 5-6 Module Names and Aliases 5-6 Parameter Names 5-7 Port Names 5-7 Combining Networks 5-7 Module Tags 5-8 Module Maps 5-8 Pend Operations 5-9 Writing CLI Scripts 5-9 Writing Scripts 5-10 Playing Back Scripts 5-11 The Script Controller Browser 5-11 Script Suites 5-12 Commands 5-12 Command Usage Notation 5-13 Basic CLI Commands 5-13 General Commands 5-14 Script Commands 5-14 Variables Commands 5-15 Network Editor Commands 5-16 Network Commands 5-17 Module Commands 5-18 Parameter Commands 5-20 Port Commands 5-20 Creating Macro Modules From CLI 5-21 Macro Module Description File 5-22 Another Way to Create Macro Modules From CLI 5-22 CONTENTS-4 AVS DEVELOPER’S GUIDE TABLE OF CONTENTS Geometry Viewer Commands 5-22 Geometry CLI State 5-23 Saving/Restoring Scenes and Objects 5-24 Geometry CLI Versus .obj and .scene Files 5-24 Saving Network Geometry State 5-25 Naming Objects, Cameras and Lights 5-25 Matrix Operations 5-26 Global Object Commands 5-26 Browser Commands 5-27 Object Commands 5-27 Light Commands 5-30 Camera Commands 5-31 Action Commands 5-33 Image Viewer Commands 5-34 Scene Commands 5-34 View Commands 5-34 Image Commands 5-35 Image Processing Technique Commands 5-36 Label Commands 5-37 Cycle Commands 5-37 Graph Viewer Commands 5-38 Reading Plot Data 5-38 Modes for Reading Data 5-39 Writing Plot Data 5-39 General Plotting 5-39 Titles and Labels 5-40 Plot Legend 5-40 Miscellaneous Dataset Information 5-41 User Interface Layout Commands 5-42 Introduction 5-42 Basic Layout Concepts 5-43 Widget Naming 5-44 Geometry 5-45 Module Based Layout Control 5-46 Dynamic Layouts 5-47 Layout commands 5-47 Application Commands 5-49 A AVS Library Routines Introduction A-1 Include File A-1 Type Declarations A-1 Routine Summary A-2 Routines for Module Initialization A-2 Routines for Module Description Functions A-2 AVS DEVELOPER’S GUIDE CONTENTS-5 TABLE OF CONTENTS Routines for Modifying and Interpreting Parameters A-2 Routines for Coroutine Modules A-3 Status Monitoring Routines A-3 AVS Command Language Interpreter Routine A-3 Routines for Selective Computation A-3 Routines for Creating Fields A-3 Field Accessor Routines A-4 Colormap Accessor