IRIS Explorer Module Writer's Guide (Windows NT/2000)
Prev   Next

IRIS Explorer Module Writer's Guide (Windows NT/2000)

Release 5.0 Edition

Table of Contents

Introduction
About This Guide
Contents of This Guide
1 Building a Module
1.1 Introduction to Module Building
1.2 Creating the User Function
1.2.1 Designing the Example Module
1.2.2 Writing the User Function
1.2.2.1 Example Code and Modules
1.2.2.2 The C User Function
1.2.2.3 The Fortran User Function
1.3 Setting up your Build Environment
1.3.1 C or Fortran?
1.3.2 Invoking the Module Builder
1.3.3 Saving the Module Resources
1.3.4 Exiting from the Module Builder
1.4 Defining the Internal Structure
1.4.1 Creating an Input Port
1.4.1.1 Defining the Data Type
1.4.1.2 Defining the Parameters
1.4.2 Creating an Output Port
1.4.3 Defining the Function Arguments
1.4.4 Connecting Ports and Function Arguments
1.4.4.1 Making the Right Connections
1.4.4.2 Using the Pseudo-Ports
1.5 Defining the User Interface
1.5.1 Creating a Menu Item
1.5.2 Testing the Menu Bar
1.6 Building the Module
1.6.1 Selecting Build Options
1.6.2 Running the Build Command
1.7 Building a Module which uses the API
1.7.1 The Function Arguments
1.7.2 The Connections
2 Understanding the Module Builder
2.1 Creating a User Function
2.1.1 Using the IRIS Explorer API
2.1.1.1 star Geometry Modules in Fortran
2.1.1.2 star The Scripting API
2.2 Running the Module Builder
2.2.1 Opening Modules
2.2.2 Moving Around the Windows
2.3 The Main Window
2.3.1 The Module Name
2.3.1.1 Naming Modules
2.3.1.2 Modifying Existing Modules
2.3.1.3 Saving Modules
2.3.2 The User Function File
2.3.2.1 Using Several Function Files
2.3.2.2 star Writing Fortran User Functions
2.3.3 The Include Files
2.3.4 Associated Libraries
2.3.5 Example Maps
2.4 Creating Ports
2.4.1 Defining Input Ports
2.4.1.1 Input Port Characteristics
2.4.1.2 star Firing Sequences
2.4.2 Setting Lattice Constraints
2.4.2.1 Defining Lattice Constraint Fields
2.4.2.2 star Automatic Type Coercion of Arrays
2.4.2.3 Returning to the Port Window
2.4.3 Setting Pyramid Constraints
2.4.3.1 Defining Pyramid Constraint Fields
2.4.3.2 Returning to the Port Window
2.4.4 Defining Output Ports
2.4.4.1 Defining Port Characteristics
2.4.4.2 star Checking the Port Status
2.5 Defining Function Arguments
2.5.1 Creating an Argument List
2.5.1.1 Func Name
2.5.1.2 Language
2.5.1.3 Arg Name
2.5.1.4 Type
2.5.1.5 References
2.5.1.6 Return Val?
2.5.2 Connecting Arguments to Ports
2.5.2.1 Understanding the Connections Menu
2.5.2.2 Creating a Link
2.5.2.3 Highlighted Connections
2.5.2.4 Passing Default Values
2.5.2.5 Using Pseudo Input Ports
2.5.2.6 star Allocating Storage Space
2.5.2.7 Mapping Rules
2.5.2.8 star Checking the State of Input Ports
2.5.2.9 star Copying Arrays
2.6 Creating File Prototypes
2.6.1 The User Function Prototype
2.6.2 Hook Function Prototypes
2.6.3 The Help File
2.7 Building Modules
2.7.1 Selecting Build Options
2.7.2 Building and Installing Modules
2.7.2.1 star Building Modules Outside of the Module Builder
2.8 Configuring the Build Environment
2.8.1 Defining EXPLORERUSERHOME
2.8.2 Debugging a Module
2.9 Examples of Simple Modules
2.9.1 The ChannelSelect Module
2.9.2 The Pass-Through Module
3 Using the Lattice Data Type
3.1 Understanding Lattices
3.1.1 The Lattice Data Type
3.1.1.1 The Dimension Variables
3.1.1.2 The cxData Structure
3.1.1.3 The cxCoord Structure
3.1.1.4 How Variables Interact
3.2 Manipulating Lattices
3.2.1 Storing Data Values
3.2.2 Defining Primitive Values
3.2.3 Storing Coordinate Values
3.2.3.1 Uniform Lattices
3.2.3.2 Changing the Aspect Ratio
3.2.3.3 Perimeter Lattices
3.2.3.4 Curvilinear Lattices
3.3 Limiting Lattice Values
3.4 Lattice Examples
3.4.1 A Colormap Example
3.4.2 A 2D Image Example
3.4.3 Preparing Your Data for Lattices
3.5 The Data Type Declaration
3.6 The Lattice API Routines
3.7 Code Examples
3.7.1 A 1D Lattice
3.7.2 A 2D Lattice
3.7.3 A 3D Curvilinear Lattice
4 Using the Pyramid Data Type
4.1 Understanding Pyramids
4.1.1 The Structure of a Pyramid
4.1.2 Pyramid Dictionaries
4.1.3 A Pyramid Reader Module
4.1.3.1 Reading Several Data Types
4.1.4 Using the Dictionary Elements
4.2 Finite Element Pyramids
4.2.1 Setting up the Lattice Structure
4.2.1.1 Contents of Layers
4.2.1.2 Designing a Finite Element Mesh
4.2.2 Creating a Tetrahedral Grid
4.2.3 Using a Pyramid Dictionary
4.2.3.1 Advantages
4.2.3.2 Disadvantages
4.3 Structure of a Dictionary
4.4 Pyramid Layer Connections
4.4.1 The Pyramid Layers
4.4.1.1 The Pyramid Connections
4.4.2 Connection List Components
4.4.3 Creating a Connection List
4.4.4 Using the Compressed Pyramid API
4.4.4.1 Designing a Compressed Pyramid Module
4.4.4.2 Dealing with Compressed Elements
4.4.4.3 Handling Compression at Non-Operational Levels
4.4.4.4 A Practical Example
4.5 Chemistry Pyramids
4.6 Data Type Declaration
4.7 The Pyramid API Routines
4.8 Code Examples
4.8.1 A Simple Example
4.8.2 More Complex Examples
5 Using the Geometry Data Type
5.1 Understanding Geometry
5.2 The Geometry Data Type
5.3 Creating Geometry Modules
5.3.1 An Example Geometry Module
5.4 Understanding Scene Graphs
5.5 Using Open Inventor in Geometry Modules
5.5.1 Creating Geometry
5.5.2 IRIS Explorer Node Classes
5.5.3 Receiving Geometry
5.6 Data Type Declaration
5.7 The Geometry API Routines
5.8 Code Examples
5.8.1 Modules using the Geometry API
5.8.1.1 Creating Line Segments
5.8.1.2 Creating More Geometry Objects
5.8.2 Creating Modules with Open Inventor Code
5.8.2.1 Texturing a Sphere
5.8.2.2 A Simple Renderer
6 Using the Pick Data Type
6.1 Understanding the PickingFunction
6.2 Using the Pick Data Type
6.2.1 Modules that Read Pick Data
6.2.2 Modules that Write Pick Data
6.2.3 The cxPick Structure
6.2.3.1 Terminology
6.2.4 Getting Data on the Hit Object
6.2.4.1 Labeling Items in Scene Graphs
6.2.4.2 Gathering Shape Information.
6.3 The Data Type Declaration
6.4 The Pick API Routines
6.5 Code Examples
6.5.1 Reading Pick Data
6.5.2 Writing Pick Data
7 Using the Parameter Data Type
7.1 Understanding Parameters
7.1.1 Control Panel Widgets
7.2 The Data Type Declaration
7.2.1 Fortran Type Enumeration
7.3 Using the Parameter API
7.4 Code Example
8 Creating User-Defined Data Types
8.1 Overview
8.2 Creating a Data Type
8.2.1 Type Declaration File
8.2.2 Naming Files and Data Types
8.3 Using the ETL
8.3.1 Conventions
8.3.2 Syntax
8.3.3 Rules for Type Definitions
8.3.4 Naming Conventions
8.3.5 Scalar Types
8.3.5.1 Signing Integer Types
8.3.5.2 Signing Other Scalar Types
8.3.6 Enumerated Constant Types
8.3.7 Composition Rules
8.3.7.1 Struct Structures
8.3.7.2 Switch Structures
8.3.8 Defining a New Type
8.3.9 Including Other Type and Header Files
8.3.10 Structures
8.3.10.1 In-line Structures
8.3.10.2 Reference-Counted Structures
8.3.10.3 Differences Between Structures
8.3.10.4 Examples of Reference-Counted Structures
8.3.11 Structure Member Declaration
8.3.12 Array Dimensioning
8.3.13 Assigning Labels
8.3.13.1 Constructing Labels
8.3.14 Inserting Comments
8.4 Differences between ETL and C
8.4.1 No Separating Comma
8.4.2 No Anonymous Structure Arrays
8.4.3 No Pointer Variables
8.4.3.1 star Recursive structures
8.5 Scoping
8.5.1 Ordering Array Members
8.5.1.1 Using Switch Discriminators
8.5.2 The Resulting C Structure
8.6 Summary of ETL Syntax
8.7 Building a Type Declaration
8.7.1 Building the Type and Related Files
8.7.2 What the Type Files Do
8.8 Visibility of Data Types in IRIS Explorer
8.8.1 In the GUI
8.8.2 Between Modules
8.9 Application Programming Interface
8.9.1 API Member Types and Functions
8.9.1.1 Functions for All Members
8.9.1.2 Functions for Reference-Counted Structures
8.9.1.3 Functions for Arrays
8.9.1.4 Dimensioning Arrays
8.9.1.5 Functions for Members in a Switch
8.9.1.6 Memory Handling
8.9.2 Fortran Wrappers
8.9.2.1 Suppressing char** Routines
8.10 Crossing Machine Boundaries
8.11 Example of a User-Defined Type
8.11.1 The GentstLattice module
8.11.2 The PrinttstLattice module
8.11.3 Reading and Writing the User-Defined Type
9 Advanced Module Writing
9.1 Controlling Module Functions
9.1.1 The Module Wrappers
9.1.1.1 Module Control Wrapper
9.1.1.2 Module Data Wrapper
9.1.1.3 The Generic Wrapper
9.1.2 Working with Module Wrappers
9.1.2.1 Modules Without MDW
9.1.2.2 Using the Windows MCW Option
9.1.3 Some Examples Using Windows Controls
9.1.3.1 The Drawing Area as an Input Mechanism
9.1.3.2 Using OpenGL in the Drawing Area
9.1.3.3 Dealing with Mouse Events in the Drawing Area
9.2 Sharing Module Executables
9.2.1 Types of Shared Executable
9.2.2 Using an Alternate Executable
9.3 Building Loop Controller Modules
9.3.1 Using the Loop Controller API
9.3.2 Using Generic Controller Modules
9.3.2.1 The For Module
9.3.3 The cxGeneric Data Type
9.4 Installing Interpreter Modules
9.5 Hook Functions
9.5.1 Hook Function Calling Sequence
9.5.2 Writing Hook Functions
9.5.3 Examples of the Use of Hook Functions
9.6 Understanding Reference Counting
9.6.1 Managing Data in Shared Memory
9.6.2 How Reference Counting Works
9.6.3 How IRIS Explorer Implements Reference Counting
9.6.4 Reference-Counting Data Types
9.6.4.1 Reference Counts for Contained Data Types
9.6.4.2 Manipulating Reference Counts
9.6.5 Shared Memory Arena
9.6.5.1 Allocating Memory Efficiently
9.6.5.2 Recovering from Memory Errors
9.7 Extending the Power of Modules
9.7.1 Timer Events
9.7.2 Expanding Filenames
10 Module Prototyping with Shape
10.1 Overview
10.2 The LatFunction Module
10.2.1 The LatFunction Module
10.2.2 The LatFunction-Based Module
10.2.2.1 Input Ports
10.2.2.2 Output Ports
10.2.3 Interfacing to IRIS Explorer Data Types
10.2.4 Building a LatFunction-Based Module
10.3 Prototyping on the Fly
10.4 Shape Language Particulars
10.4.1 Resemblances to C
10.4.2 Differences from C
10.4.2.1 Lattice Manipulations
10.4.2.2 The Define Operator :=
10.4.2.3 Promotion of Arrays
10.4.2.4 Reduction of Arrays
10.4.3 Other Operators
10.4.4 Data Types
10.4.5 Function Declaration Syntax
10.4.6 Loop Syntax
10.4.6.1 For Loop
10.4.6.2 While Loop
10.4.6.3 Continue and Break
10.4.7 Issues of Scope
10.4.8 Additional Features
10.4.8.1 Copy
10.4.8.2 Scatter and Gather
10.4.8.3 Shape
10.4.8.4 Allocate
10.4.8.5 Slice
10.4.8.6 Subshape
10.4.8.7 Stack
10.4.8.8 Send_indices
10.4.8.9 Min and Max
10.4.8.10 DotProduct +.*
10.4.8.11 BitProduct |.&
10.4.8.12 Conditional Evaluation ?:
10.4.9 Changing Promotion and Reduction Order
10.4.9.1 Inside
10.4.9.2 Outside
10.4.9.3 InsideOut
10.5 Data Output from Shape
10.5.1 Scalar_lattice_in and Scalar_lattice_out
10.5.2 List Operators
10.5.2.1 List
10.5.2.2 List_first and List_rest
10.5.2.3 Handling Perimeter Lattice Coordinates
10.5.2.4 Map and Apply
10.5.2.5 Pair_p and Null_p
10.6 The Module Prelude and Postlude
10.6.1 Prelude Set-up Functions
10.6.2 Prelude Execution Functions
10.6.3 Postlude Functions
10.7 Shape Function Tables
10.8 Sample Programs for LatFunction
10.8.1 To Create a Test Volume
10.8.2 To Carry Out a Color Transform
10.8.3 To Generate a Heat Flux
A The Firing Algorithm
A.1 Module Firing
A.1.1 Handling Topology Changes
A.1.2 Using Frames for Data Ordering
A.1.3 Identifying Frames
A.1.3.1 Propagation of Frame IDs
A.1.3.2 Frame Ordering
A.1.4 Frame Construction
A.1.4.1 Setting Frame Dependencies
A.1.5 Sending Data Downstream
A.1.6 Handling Fan-in Connections
A.1.7 Merging Frames on Input Ports
A.1.7.1 Disabled Modules
A.1.8 Incorporating Parameters
A.1.8.1 Setting Widgets

List of Figures

Figure 1-1 The Module Builder Window for C Users
Figure 1-2 The Module Builder Window for Fortran Users
Figure 1-3 Module Builder File Menu
Figure 1-4 Input Ports Window
Figure 1-5 The Lattice Constraints Window
Figure 1-6 The Output Ports Window
Figure 1-7 Lattice Constraints for the Output Port
Figure 1-8 The Function Args Window for C Users
Figure 1-9 The Function Args Window for Fortran Users
Figure 1-10 The Connections Window
Figure 1-11 Input Port Popup Menu
Figure 1-12 Connections Popup Menu for an Array Item with "Copy" Switched Off.
Figure 1-13 Port Popup Menu for a Parameter
Figure 1-14 Function Argument Menu for an Array Item
Figure 1-15 Setting the Storage Size
Figure 1-16 Control Panel Editor and Prototype Control Panel
Figure 1-17 Menu Bar Editor
Figure 1-18 Menu Editor
Figure 1-19 The Build Options Control Panel
Figure 1-20 Build Menu Options
Figure 1-21 The Function Args Window for C Users
Figure 1-22 The Function Args Window for Fortran Users
Figure 1-23 The Connections Window
Figure 2-1 Module Builder Main Window
Figure 2-2 Input Ports Window
Figure 2-3 Lattice Constraints Window
Figure 2-4 Sequence of Type Coercions
Figure 2-5 Pyramid Constraints Window
Figure 2-6 Output Port Window
Figure 2-7 Function Arguments Window for a C Function
Figure 2-8 Function Arguments Window for a Fortran Subroutine
Figure 2-9 Function Argument Reference Menu for C
Figure 2-10 Function Argument Reference Menu for Fortran
Figure 2-11 Connections Window
Figure 2-12 Connections Menu for the Molecule Port
Figure 2-13 Highlights in the Connections Window
Figure 2-14 Setting a Constant Value for a Function Argument; bringing Up the Argument Value Window
Figure 2-15 Setting a Constant Value for a Function Argument; setting the Value in the Window
Figure 2-16 Connections Popup Menu for an Array Function Argument; Passing the Array Itself
Figure 2-17 Connections Popup Menu for an Array Function Argument; Passing a Copy of the Array
Figure 2-18 The Prototypes Menu
Figure 2-19 Function Prototype Window
Figure 2-20 The Module Menu
Figure 3-1 Data Flow Between Input and Output Lattices
Figure 3-2 Schematic Structure of the Lattice Data Type
Figure 3-3 Lattice Variables
Figure 3-4 Storing Arrays in C and Fortran
Figure 3-5 Array Neighbors
Figure 3-6 Storing Data Values
Figure 3-7 A 2D Uniform Lattice Structure
Figure 3-8 A 3D Uniform Lattice Structure
Figure 3-9 Data Set for a 2D Perimeter Lattice
Figure 3-10 Storing Perimeter Coordinates
Figure 3-11 Example of a 3D Perimeter Lattice
Figure 3-12 Storing Curvilinear Coordinates
Figure 3-13 Curvilinear Lattices with Various Values for nDim and nCoordVar
Figure 3-14 Defining Lattice Constraints
Figure 4-1 Pyramid Dictionary Reference Elements
Figure 4-2 Memory Layout of a 2D Lattice
Figure 4-3 Layers in a Tetrahedral Grid
Figure 4-4 Top and Bottom of Compressed Tetrahedral Grid
Figure 4-5 Layers in a Compressed Grid
Figure 4-6 Connections in a Tetrahedron
Figure 4-7 Preprocessing a Pyramid Dictionary
Figure 5-1 Schematic Structure of the Geometry Data Type
Figure 5-2 Inventor Scene Graph
Figure 5-3 Output from Geometry Example
Figure 6-1 Schematic Structure of the Pick Data Type
Figure 6-2 Schematic Structure of the PickHit Data Type
Figure 6-3 The Pick Map
Figure 7-1 Schematic Structure of the Parameter Type
Figure 8-1 The Build Type Control Panel in the Module Builder
Figure 9-1 Spectrum of Module Complexity
Figure 9-2 The Module Structure
Figure 9-3 The GLXWidget_C Module Control Panel
Figure 9-4 The Scribble Module Control Panel
Figure 9-5 The Hook Function Window
Figure 10-1 The LatFunction Module Control Panel
Figure 10-2 How Shape Assigns Variable Names
Figure 10-3 LatFunction in the testVol Map
Figure 10-4 Output from the color-xform Map
Figure 10-5 Output from the heat-flux Map
Figure A-1 Map Topology
Figure A-2 Multiple Firing in a Map
Figure A-3 Frame Identifiers
Figure A-4 Map Firings
Figure A-5 Frame Assembly
Figure A-6 Parallel Data Flows
Figure A-7 Data Handling in a Module

List of Tables

Table 1-1 Function Arguments for the C Function
Table 1-2 Function Arguments for the Fortran Subroutine
Table 2-1 Colormap Lattice Constraints
Table 2-2 Primitive Data Types in C and Fortran
Table 2-3 Function Argument References
Table 3-1 Lattice Primitive Types
Table 3-2 Lattice Subroutines
Table 4-1 Standard Dictionary Reference Elements
Table 4-2 User-Defined Values in the Chemistry Pyramid
Table 4-3 Pyramid Subroutines
Table 4-4 Pyramid Dictionary Subroutines
Table 5-1 IRIS Explorer Shared Memory Node Classes
Table 5-2 Geometry Subroutines
Table 6-1 Pick Subroutines
Table 7-1 Parameter Subroutines
Table 8-1 Scalar Types in IRIS Explorer
Table 8-2 A Simple-Typed Member
Table 8-3 Labels on Lattice Scalars
Table 8-4 Member of a Data Type
Table 9-1 While Module Ports
Table 9-2 Interpreter Module Files
Table 10-1 Data Types in C and Shape
Table 10-2 C-like Functions in Shape
Table 10-3 Functions Specific to Shape
Table A-1 Topology Influence Table for DisplayImg

ISBN 1-85206-187-1

NP3517
Prev Home Next
B The Skm Language Up Introduction