@database "r3dv2" @master "r3dv2.guide" @node main "r3dv2.guide" REAL 3D V2 - FULL DOCS ---------------------- Contents @{" Introduction " link "INTRODUCTION"} @{" Tutorial " link "TUTORIAL"} @{" Reference " link "REFERENCE"} @{" Appendices " link "APPENDICES"} @{" Glossary " link "GLOSSARY"} @{" Index " link "INDEX"} @endnode @node "Introduction" INTRODUCTION @{" Chapter 1 " link "I1"} FEATURES OF REAL 3D V.2 @{" Chapter 2 " link "I2.1"} INSTALLATION @{" 2.1 " link "I2.1"} HARDWARE REQUIREMENTS @{" 2.2 " link "I2.2"} INSTALLING THE SYSTEM @{" Chapter 3 " link "I3.1"} USING THE MANUAL @{" 3.1 " link "I3.1"} WELCOME TO THE WORLD OF REAL 3D V.2 @{" 3.2 " link "I3.2.1"} SUGGESTED METHOD OF READING @{" 3.2.1 " link "I3.2.1"} All Users @{" 3.2.2 " link "I3.2.3"} As a New User @{" 3.2.3 " link "I3.2.3"} As a User with Previous 3D Graphics Experience @{" 3 2.4 " link "I3 2.4"} Real-1.X User @{" 3.3 " link "I3.3.1"} MAJOR DEVELOPMENTS SINCE v1.42 @{" 3 3.1 " link "I3 3.1"} System Integration & Configurable Interface @{" 3.3.2 " link "I3.3.2.1"} Multi.Selection Support @{" 3.3.2.1 " link "I3.3.2.1"} Multi-selecting Objects @{" 3.3.2.2 " link "I3.3.2.2"} Multi-selecting Functions @{" 3.3.3 " link "I3.3.3.1"} Hierarchy @{" 3 3.3.1 " link "I3.3.3.1"} Animation System @{" 3.3.3.2 " link "I3.3.3.2"} Materials @{" 3.3.3.3 " link "I3.3.3.3"} Boolean Operations @{" 3.3.3.4 " link "I3.3.3.4"} Hierarchy References and Order @{" 3.3.4 " link "I3.3.4"} Freeform Curves and Surfaces @{" 3.3.5 " link "I3.3.5"} Built in Programming Language @{" Chapter 4 " link "I4.1"} GETTING STARTED @{" 4.1 " link "I4.1"} OPENING THE PROGRAM @{" 4.2 " link "I4.2.1"} FAMILIARIZE YOURSELF WITH THE MENUS & TOOLS @{" 4.2.1 " link "I4.2.1"} Menus @{" 4 2.2 " link "I4.2.2"} Tool Icons @{" 4.2.3 " link "I4.2.3"} Hot keys @{" 4.2.4 " link "I4.2.4"} Conclusion @{" 4.3 " link "I4.3.1"} INTRODUCTION PROJECT @{" 4.3.1 " link "I4.3.1"} Loading the Project @{" 4.3.2 " link "I4.3.2"} Refreshing and Rendering @{" 4.3.3 " link "I4.3.3"} Animating @{" 4.3.3.1 " link "I4.3.3.1"} Jump To/Play To" and the Time Slider @{" 4.3.3.2 " link "I4.3.3.2"} Wireframe/Ray Trace" Gadget @{" 4.3.4 " link "I4.3.4"} Rendering Revisited @{" 4.4 " link "I4.4"} END OF THE BEGINNING @endnode @node "Tutorial" TUTORIAL -------- @{" Chapter 1 " link "T1.1"} OBJECT CREATION & MODIFICATION @{" 1.1 " link "T1.1"} STARTING THE PROGRAM @{" 1.2 " link "T1.2"} THE WINDOWS @{" 1.3 " link "T1.3"} THE MOUSE @{" 1.4 " link "T1.4"} BASIC TERMINOLOGY @{" 1.5 " link "T1.5"} TUTORIAL EXAMPLE 1: SELECT WINDOWS AND HIERARCHY @{" 1.5.1 " link "T1.5.1"} The Current Level @{" 1.5.2 " link "T1.5.2"} Object Multiselection @{" 1.6 " link "T1.6"} TUTORIAL EXAMPLE 2: 3D MODELLING @{" 1.7 " link "T1.7"} MODIFYING @{" 1.8 " link "T1.8"} SAVING AND LOADING @{" 1.9 " link "T1.9.1"} VISIBLES @{" 1.9.1 " link "T1.9.1"} Polygon/Polyhedron/Polymids @{" 1.9.2 " link "T1.9.2"} Sector Visibles @{" 1.10 " link "T1.10.1"} COMPOUND TOOLS @{" 1.10.1 " link "T1.10.1"} Lathe @{" 1.10.2 " link "T1.10.2"} Tube tools @{" 1.10.3 " link "T1.10.4"} Rounded Polygons and Polyhedrons @{" 1.10.4 " link "T1.10.4"} Object-Pixel Tool @{" 1.11 " link "T1.11"} LIGHTSOURCES @{" 1.11.1 " link "T1.11.1"} The Brightness of Light Sources @{" 1.12 " link "T1.12"} MACROS @{" Chapter 2 " link "T2.1"} THE ENVIRONMENT @{" 2.1 " link "T2.1"} ASYNCHRONOUS ACTION @{" 2.2 " link "T2.2"} SCREENS @{" 2.3 " link "T2.3.1"} VIEW WINDOWS @{" 2.3.1 " link "T2.3.1"} Projection Types @{" 2.3.2 " link "T2.3.2"} Input&Output Planes @{" 2.3.3 " link "T2.3.3"} View Coordinates & Cameras @{" 2.3.4 " link "T2.3.4"} booming and Positioning the View @{" 2.4 " link "T2.4.1"} WIREFRAME DRAWING SPEED @{" 2.4.1 " link "T2.4.1"} Bounding Boxes @{" 2.4.2 " link "T2.4.1"} Refresh Modes @{" 2.4.3 " link "T2.4.1"} The Visible Range of the Objects @{" 2.4.4 " link "T2.4.1"} Other Methods @{" 2.5 " link "T2.5"} THE MEASURING WINDOW @{" 2.6 " link "T2.6"} GRIDS @{" 2.7 " link "T2.7.1"} THE UNDO FUNCTION @{" 2.7.1 " link "T2.7.1"} Undo and Memory Management @{" 2.8 " link "T2.8"} VECTOR STACK @{" Chapter 3 " link "T3.1.1"} MATERIALS @{" 3.1 " link "T3.1.1"} USING MATERIALS @{" 3.1.1 " link "T3.1.1"} General Information @{" 3.1.2 " link "T3.1.2"} Tutorial Project @{" 3.1.3 " link "T3.1.3"} Optical Properties @{" 3.2 " link "T3.2.1"} TEXTURE MAPPING @{" 3.2.1 " link "T3.2.1"} General Information @{" 3.2.2 " link "T3.2.1"} Textures @{" 3.2.3 " link "T3.2.3"} Texture Mapped Materials @{" 3.2.4 " link "T3.2.4"} Mappings @{" 3.2.5 " link "T3.2.5"} Sector Mappings @{" 3.2.6 " link "T3.2.6"} Spline Mapping @{" 3.2.7 " link "T3.2.7"} Index Format String @{" 3.2.8 " link "T3.2.8"} Animated Textures @{" 3.3 " link "T3.3.1"} ADVANCED MATERIAL FEATURES @{" 3.3.1 " link "T3.3.1"} Multiple Materials @{" 3.3.2 " link "T3.3.2"} Procedural Handlers @{" 3.3.3 " link "T3.3.3"} Nonhomogeneous Materials @{" 3.3.4 " link "T3.3.4"} Mappings and Hierarchy @{" 3.3.5 " link "T3.3.5"} Some Material Morphing Examples @{" Chapter 4 " link "T4.1.1"} MODELLING @{" 4.1 " link "T4.1.1"} FREEFORM MODELLING AND POINT EDITING @{" 4.1.1 " link "T4.1.1"} Curves @{" 4.1.1.1 " link "T4.1.1.1"} Special Curve Shapes @{" 4.1.1.2 " link "T4.1.1.2"} Multiple Control Points @{" 4.1.2 " link "T4.1.2"} Selecting Points @{" 4.1.3 " link "T4.1.3"} Freeforms as Levels @{" 4.1.4 " link "T4.1.4.1"} Freeform Surfaces @{" 4.1.4.1 " link "T4.1.4.1"} Example: Creating a Simple Mesh @{" 4.1.4.2 " link "T4.1.4.2"} Coplanar Sweeping @{" 4.1.4.3 " link "T4.1.4.3"} Orthogonal Sweeping @{" 4.1.4.4 " link "T4.1.4.4"} Rotate - Creating a Wine Glass @{" 4.1.4.5 " link "T4.1.4.5"} Swinging @{" 4.1.4.6 " link "T4.1.4.6"} Cross-sectional Surface Construction @{" 4.1.4.7 " link "T4.1.4.7"} Mesh-Pixel Tool @{" 4.1.5 " link "T4.1.5"} Modifying Curves and Meshes @{" 4.1.6 " link "T4.1.6"} Bending Functions @{" 4.1.7 " link "T4.1.7"} Example: Creating a B-Spline Head @{" 4.2 " link "T4.2"} BOOLEAN OPERATIONS @{" 4.2.1 " link "T4.2.1"} Wireframes of Booleans @{" 4.3 " link "T4.3"} OBJECT ATTRIBUTES @{" 4.3.1 " link "T4.3.1"} Infinite Primitives @{" 4.4 " link "T4.4.1"} SPECIAL FUNCTIONS @{" 4.4.1 " link "T4.4.1"} Use of Animation Methods for Creation @{" 4.4.2 " link "T4.4.1"} COG Modifications @{" Chapter 5 " link "T5"} RENDERING @{" 5.1 " link "T5.1"} LIGHTING SETTINGS @{" 5.2 " link "T5.2"} COLOR/IMAGE SETTINGS @{" 5.3 " link "T5.3"} RENDERING QUALITY SETTINGS @{" 5.4 " link "T5.4"} RAY TRACING QUALITY SETTINGS @{" 5.5 " link "T5.5"} RENDERING MODES @{" 5.6 " link "T5.6"} DITHERING @{" 5.7 " link "T5.7"} SPECIAL SETTINGS @{" 5.8 " link "T5.8"} HIERARCHY AND RENDERING @{" 5.9 " link "T5.9"} RENDERING A WIREFRAME PREVIEW OF AN ANIMATION @{" 5.10 " link "T5.10"} RENDERING AN ANIMATION @{" 5.11 " link "T5.11"} RENDERING TO A FILE @{" 5.12 " link "T5.12"} CONTINUING A CANCELLED RENDERING PROCESS @{" 5.13 " link "T5.13"} RENDERING TO AN EXTERNAL SCREEN @{" 5.13.1 " link "T5.13.1"} Rendering an Animation Using External Screen @{" 5.13.2 " link "T5.13.2"} External Screen Aspect Ratio @{" 5.13.3 " link "T5.13.2"} Other Information @{" 5.14 " link "T5.14"} BOXES @{" 5.15 " link "T5.15.1"} OBJECT ATTRIBUTES AND RENDERING @{" 5.15.1 " link "T5.15.1"} Scene gadget @{" 5.15.2 " link "T5.15.1"} Backdrop and Matte Objects @{" 5.16 " link "T5.16.1"} OPTIMIZATIONS @{" 5.16.1 " link "T5.16.1"} Rendering Mode @{" 5.16.2 " link "T5.16.2"} Resolution @{" 5.16.3 " link "T5.16.2"} Recursion @{" 5.16.4 " link "T5.16.2"} Re-interpreting B-splines @{" 5.16.5 " link "T5.16.2"} Reflections & Not Reflected. @{" 5.16.6 " link "T5.16.6"} Shadows @{" 5.16.7 " link "T5.16.6"} Other Optimizations @{" 5.17 " link "T5.17"} USING ALPHA CHANNEL @{" 5.18 " link "T5.18"} RENDERING FIELDS @{" 5.19 " link "T5.19"} MOTION BLUR @{" 5.20 " link "T5.20.1"} TROUBLESHOOTING @{" 5.20.1 " link "T5.20.1"} Not Enough Memory @{" 5.20.2 " link "T5.20.1"} Disappearing objects @{" Chapter 6 " link "T6.1"} ANIMATION @{" 6.1 " link "T6.1"} PATH @{" 6.1.1 " link "T6.1"} Move Object along a Path @{" 6.1.2 " link "T6.1.2"} Move Objects along a Path Like a Snake @{" 6.1.3 " link "T6.1.2"} Bouncing Sphere @{" 6.1.4 " link "T6.1.4"} Hierarchical Animations and Bouncing Sphere @{" 6.1.5 " link "T6.1.4"} Move Elastic B-Spline Mesh along a Path @{" 6.1.6 " link "T6.1.6"} Talking Head @{" 6.1.7 " link "T6.1.6"} Moving Objects along a B-Spline Mesh @{" 6.1.8 " link "T6.1.8"} Customized Paths @{" 6.2 " link "T6.2"} ROTATION @{" 6.2.1 " link "T6.2"} Rotating Objects Around an Axis @{" 6.2.2 " link "T6.2"} Rotating with Different Speeds and Directions @{" 6.2.3 " link "T6.2.3"} Hierarchical Rotations @{" 6.2.4 " link "T6.2.3"} Tornado @{" 6.3 " link "T6.3"} SWEEP @{" 6.3.1 " link "T6.1"} Walking Legs @{" 6.3.2 " link "T6.3.2"} Tracking Guns @{" 6.4 " link "T6.4"} SIZE @{" 6.4.1 " link "T6.4"} Beating Spheres @{" 6.4.2 " link "T6.4"} Bubbles @{" 6.5 " link "T6.5"} STRETCH @{" 6.5.1 " link "T6.5"} Elastic Cube @{" 6.5.2 " link "T6.5"} Bouncing Elastic Sphere @{" 6.6 " link "T6.6"} DIRECTION @{" 6.6.1 " link "T6.6"} Move a Logo Text along a Direction Path @{" 6.6.2 " link "T6.6"} Swimming Fish @{" 6.7 " link "T6.7"} MOVE&DIR @{" 6.7.1 " link "T6.7"} Rocking Logo Moving along a Straight Line @{" 6.7.2 " link "T6.7"} The Rally Driver @{" 6.8 " link "T6.8"} CONTROL CURVES @{" 6.8.1 " link "T6.8"} Beating and Moving Slime Ball @{" 6.8.2 " link "T6.8"} Elastic Flying Carpet @{" 6.8.3 " link "T6.8"} Flying Viewpoint @{" 6.9 " link "T6.9"} SIMPLE SKELETON @{" 6.9.1 " link "T6.9"} A SIMPLE SKELETON and a Logo Text @{" 6.9.2 " link "T6.9.2"} Rotate a Simple Skeleton around an Axis @{" 6.9.3 " link "T6.9.2"} Elastic Skeleton and Logo Text @{" 6.9.4 " link "T6.9.2"} Moving Objects along a Skeleton @{" 6.9.5 " link "T6.9.5"} Rocking Spheres @{" 6.9.6 " link "T6.9.5"} A Hydrogen Atom and its Electron Orbit @{" 6.10 " link "T6.10"} SKELETON @{" 6.10.1 " link "T6.10"} Another Logo Text Animation @{" 6.10.2 " link "T6.10"} Rotating Skin around Bones @{" 6.11 " link "T6.11"} INVERSE KINEMATICS @{" 6.11.1 " link "T6.11"} Curl a Finger @{" 6.11.2 " link "T6.11.2"} Push a Button with the Finger-tip @{" 6.11.3 " link "T6.11"} Interactively Controlled Hierarchical Skeletons @{" 6.11.4 " link "T6.11"} An Animated Robot Arm @{" 6.12 " link "T6.12"} MORPHING @{" 6.12.1 " link "T6.12"} Second Talking Head @{" 6.12.2 " link "T6.12"} Singing Heads @{" 6.12.3 " link "T6.12"} Sing the Same Song Ten Times @{" 6.12.4 " link "T6.12"} Morphing Hierarchical Objects @{" 6.12.5 " link "T6.12.5"} Morphing Texture Maps and Materials @{" 6.12.6 " link "T6.12.5"} Camera Flight Animation @{" 6.13 " link "T6.13"} TRANSFORM @{" 6.13.1 " link "T6.13"} Piston @{" 6.13.2 " link "T6.13.2"} Hesitating Piston @{" 6.13.3 " link "T6.13.3"} Three Dimensional Time @{" 6.14 " link "T6.14"} RADIAL FORCE @{" 6.14.1 " link "T6.14"} Gravity @{" 6.14.2 " link "T6.14.2"} The Simplest Possible Particle Animation @{" 6.14.3 " link "T6.14"} Customized Radial Force @{" 6.15 " link "T6.15"} DIRECTED FORCE @{" 6.15.1 " link "T6.15"} Turbulence @{" 6.15.2 " link "T6.15.2"} Snow in the Wind @{" 6.16 " link "T6.16"} TANGENT FORCE @{" 6.16.1 " link "T6.16"} Centrifugal Force @{" 6.17 " link "T6.17"} INTERACTIVE COLLISION DETECTION @{" 6.17.1 " link "T6.17"} Colliding Spheres @{" 6.17.2 " link "T6.17"} Multiple Collisions @{" 6.17.3 " link "T6.17"} Bowling Alley @{" 6.17.4 " link "T6.17.4"} Drop a Ball to a Tube @{" 6.17.5 " link "T6.17"} A Rolling Ball @{" 6.18 " link "T6.18"} NON-INTERACTIVE COLLISION DETECTION @{" 6.18.1 " link "T6.18"} A Planet and Meteorites @{" 6.19 " link "T6.19"} FRICTION @{" 6.19.1 " link "T6.19"} Friction and Spheres with Different Sizes @{" 6.19.2 " link "T6.19"} Customized Friction @{" 6.20 " link "T6.20"} CREATION @{" 6.20.1 " link "T6.20"} A Sphere Tube @{" 6.20.2 " link "T6.20"} Boiling Water @{" 6.20.3 " link "T6.20"} A Wriggling Snake @{" 6.21 " link "T6.21"} PROCESSOR @{" 6.22 " link "T6.22"} RPL @{" 6.22.1 " link "T6.22"} An Easy Way to Write a RPL Procedure @{" 6.23 " link "T6.23"} WAVE @{" 6.23.1 " link "T6.23"} Waving Sea @{" 6.23.2 " link "T6.23"} A Water Drop @{" 6.23.3 " link "T6.23"} Parallel Waves @{" 6.23.4 " link "T6.23"} Waves and Ripples @{" 6.23.5 " link "T6.23"} Waving Particles @{" Chapter 7 " link "T7.1"} RPL @{" 7.1 " link "T7.1"} INTRODUCTION @{" 7.1.1 " link "T7.1"} Basic Concepts @{" 7.2 " link "T7.2"} TUTORIAL @{" 7.2.1 " link "T7.2"} Getting Started @{" 7.2.2 " link "T7.2"} Stacks @{" 7.2.3 " link "T7.2"} Reverse Polish Notation @{" 7.2.4 " link "T7.2"} Parameter Stack @{" 7.2.5 " link "T7.2.5"} Data Types @{" 7.2.5.1 " link "T7.2.5"} Integers @{" 7.2.5.2 " link "T7.2.5"} Floating-points @{" 7.2.5.3 " link "T7.2.5"} Strings @{" 7.2.6 " link "T7.2.6"} Stack Manipulation Words @{" 7.2.7 " link "T7.2.7"} Compiling New Words @{" 7.2.8 " link "T7.2.8"} Constants and Variables @{" 7.2.8.1 " link "T7.2.8"} Constants @{" 7.2.8.2 " link "T7.2.8."} Variables @{" 7.2.9 " link "T7.2.9"} Flow Control @{" 7.2.10 " link "T7.2.9"} Conditional Execution @{" 7.2.10.1 " link "T7.2.9"} Comparisons @{" 7.2.10.2 " link "T7.2"} IF.ENDIF Structure @{" 7.2.10.3 " link "T7.2"} IF.ELSE.ENDIF Structure @{" 7.2.10.4 " link "T7.2"} Inverting Flags @{" 7.2.10.5 " link "T7.2"} Nesting Conditionals @{" 7.2.11 " link "T7.2.11"} Loops @{" 7.2.11.1 " link "T7.2.11"} Definite Loops @{" 7.2.11.2 " link "T7.2.11"} Indefinite Loops @{" 7.2.11.3 " link "T7.2.11"} Nested Loops @{" 7.2.12 " link "T7.2.12"} Words and the Vocabulary @{" 7.2.13 " link "T7.2.13"} Loading a File @{" 7.2.14 " link "T7.2.14"} Using RPL Windows @{" 7.3 " link "T7.3"} USING RPL FOR CUSTOMIZING EDITOR @{" 7.3.1 " link "T7.3"} Communicating with RPL Programs @{" 7.3.2 " link "T7.3"} "Master" ENVIRONMENT @{" 7.3.3 " link "T7.3"} Binding Macros to Keys @{" 7.3.4 " link "T7.3"} Binding Macros to Icons @{" 7.4 " link "T7.4"} CREATING ANIMATIONS USING RPL @{" 7.4.1 " link "T7.4"} Modifying Objects Directly @{" 7.4.2 " link "T7.4.2"} Creating New Methods @{" 7.4.2.1 " link "T7.4.2"} Do Nothing Method @{" 7.4.2.2 " link "T7.4.2.2"} Move Absolutely Along a Path @{" 7.4.2.3 " link "T7.4.2.3"} Chain @{" 7.4.2.4 " link "T7.4.2.4"} Strange Force @{" 7.5 " link "T7.5"} USING EVAL @{" 7.6 " link "T7.6"} OBJECTS @{" 7.6.1 " link "T7.6"} Object Creation @{" 7.6.2 " link "T7.6.2"} Object Instances @{" 7.6.3 " link "T7.6.2"} Grouping Objects Together @{" 7.6.4 " link "T7.6.4"} SphereMan @endnode @node "Reference" REFERENCE @{" Chapter 1 " link "R1.1"} MENU FUNCTIONS @{" 1.1 " link "R1.1"} PROJECT @{" 1.2 " link "R1.2"} CREATE @{" 1.3 " link "R1.3"} MODIFY @{" 1.4 " link "R1.4"} VIEW @{" 1.5 " link "R1.5"} ANIMATE @{" 1.6 " link "R1.6"} EXTRAS @{" 1.7 " link "R1.7"} SETTINGS @{" 1.8 " link "R1.8"} TOOLS @{" Chapter 2 " link "R2.1"} ANIMATION METHOD SYNTAX @{" 2.1 " link "R2.1"} PRINCIPLES @{" 2.1.1 " link "R2.1"} General Information @{" 2.1.2 " link "R2.1"} Built-in Methods @{" 2.1.3 " link "R2.1"} User Defined Methods @{" 2.1.4 " link "R2.1"} Evaluating Parameters @{" 2.1.5 " link "R2.1"} Animation Oriented Tags @{" 2.1.6 " link "R2.1"} Particle System Principles @{" 2.1.6.1 " link "R2.1.6.1"} Converting Motion Properties into Real Motion @{" 2.1.6.2 " link "R2.1.6.1"} Forces in the Particle System @{" 2.1.6.3 " link "R2.1.6.1"} Real Time and Particle Motion @{" 2.1.6.4 " link "R2.1.6.1"} Side-effects of Particle Animations @{" 2.1.7 " link "R2.1.6.1"} Creating New Methods @{" 2.2 " link "R2.2"} ANIMATION METHODS @{" 2.2.1 " link "R2.2.1"} PATH @{" 2.2.2 " link "R2.2.2"} ROTATION @{" 2.2.3 " link "R2.2.3"} SWEEP @{" 2.2.4 " link "R2.2.4"} SIZE @{" 2.2.5 " link "R2.2.5"} STRETCH @{" 2.2.6 " link "R2.2.6"} DIRECTION @{" 2.2.7 " link "R2.2.7"} MOVE & DIR @{" 2.2.8 " link "R2.2.8"} CONTROL CURVES @{" 2.2.9 " link "R2.2.9"} SIMPLE SKELETON @{" 2.2.10 " link "R2.2.10"} SKELETON @{" 2.2.11 " link "R2.2.11"} INV KINEMATIC @{" 2.2.12 " link "R2.2.12"} MORPHING OPEN & CLOSED @{" 2.2.13 " link "R2.2.13"} TRANSFORM @{" 2.2.14 " link "R2.2.14"} WAVE @{" 2.2.15 " link "R2.2.15"} RADIAL FORCE @{" 2.2.16 " link "R2.2.16"} DIRECTED FORCE @{" 2.2.17 " link "R2.2.17"} TANGENT FORCE @{" 2.2.18 " link "R2.2.18"} COLLISION @{" 2.2.19 " link "R2.2.19"} INT COLLISION @{" 2.2.20 " link "R2.2.20"} FRICTION @{" 2.2.21 " link "R2.2.21"} CREATION @{" 2.2.22 " link "R2.2.22"} PROCESSOR @{" 2.2.23 " link "R2.2.23"} RPL @{" Chapter 3 " link "R3.1"} RPL SYNTAX @{" 3.1 " link "R3.1"} KERNEL WORDS @{" 3.2 " link "R3.2"} OBJECT CREATION WORDS @{" 3.2.1 " link "R3.2"} Geometry @{" 3.2.1.1 " link "R3.2"} fStAngle & fEnAngle @{" 3.2.1.2 " link "R3.2"} wGeomFlags @{" 3.2.1.3 " link "R3.2"} wFreeType @{" 3.2.2 " link "R3.2.2"} iColor @{" 3.2.3 " link "R3.2.2"} Attributes @{" 3.2.3.1 " link "R3.2.2"} Name @{" 3.2.3.2 " link "R3.2.2"} Object Flags @{" 3.2.4 " link "R3.2.4"} Tags @{" 3.2.5 " link "R3.2.4"} Return Value @{" 3.2.6 " link "R3.2.4"} Word Definitions @{" 3.3 " link "R3.3"} MODIFICATION WORDS @{" 3.3.1 " link "R3.3"} Modify Flags @{" 3.3.2 " link "R3.3"} Locking Object Data @{" 3.3.3 " link "R3.3"} Word Definitions @{" 3.4 " link "R3.4"} OBJECT WORDS @{" 3.4.1 " link "R3.4"} Return Value @{" 3.4.2 " link "R3.4"} Locking Data Structure @{" 3.4.3 " link "R3.4"} Word Definitions @{" 3.5 " link "R3.5"} ANIMATION WORDS @{" 3.6 " link "R3.6"} I/O WORDS @{" 3.7 " link "R3.7"} MATERIAL WORDS @{" 3.8 " link "R3.8"} MISCELLANEOUS WORDS @{" 3.9 " link "R3.9"} USER INTERFACE WORDS @{" 3.10 " link "R3.10"} AREXXWORDS @{" 3.11 " link "R3.11"} VECTOR OPERATIONS @{" Chapter 4 " link "R4.1"} GEOMETRIC OBJECT PROPERTIES @{" 4.1 " link "R4.1"} GEOMETRIC PROPERTIES @{" 4.1.1 " link "R4.1"} Surface Definition @{" 4.1.2 " link "R4.1"} COG @{" 4.1.3 " link "R4.1"} Direction @{" 4.1.4 " link "R4.1"} Size @{" 4.2 " link "R4.1"} DEFAULT GEOMETRIC PROPERTIES @{" Chapter 5 " link "R5.1"} TAGS @{" 5.1 " link "R5.1"} TAG IDENTIFIERS @{" 5.2 " link "R5.1"} RESERVED TAG IDENTIFIERS @{" Chapter 6 " link "R6.1"} AREXX INTERFACE OF REAL 3D @{" 6.1 " link "R6.1"} GENERAL @{" 6.2 " link "R6.1"} AREXX VS. RPL @{" 6.3 " link "R6.3"} SENDING AREXX COMMANDS TO THE PORT OF REAL 3D @{" 6.4 " link "R6.3"} RETURN VALUES @{" 6.5 " link "R6.3"} RESULT STRING @{" 6.6 " link "R6.3"} CLIP LIST @{" 6.7 " link "R6.7"} SENDING AREXX COMMANDS FROM REAL 3D @{" 6.8 " link "R6.1"} RETURN VALUES FROM OTHER APPLICATIONS @{" 6.9 " link "R6.1"} RESULT STRINGS FROM OTHER APPLICATIONS @endnode @node "Appendices" APPENDICES Appendix @{" A " link "AA"} PREDEFINED ICONS Appendix @{" B " link "AB"} HOT KEYS AND MENUS Appendix @{" C " link "AC"} UTILITY SOFTWARE @{" C.1 " link "AC"} CONVERSION SOFTWARE @{" C.1.1 " link "AC"} RealConvert @{" C.1.2 " link "AC"} DxfToRPL @{" C.2 " link "A2"} IMAGE & ANIMATION DISPLAY @{" C.2.1 " link "A2"} Display @{" C.2.2 " link "A2"} DeltaConvert @{" C.2.3 " link "A2"} DeltaPlay @endnode @node "I1" @title "Chapter 1 FEATURES OF REAL 3D V.2" Chapter 1 FEATURES OF REAL 3D V.2 --------------------------------- Program Description REAL 3D V.2 is a design and animation program for producing high quality realistic images of three-dimensional objects. 3D Desktop animators, creative computer artists, product designers, teachers and everyone interested in compiler generated imagery will find REAL 3D V.2 a very useful and unique tool. This new version introduces a large collection of state-of-art features, making REAL 3D V.2 one of the most powerful 3D packages available to desktop computer platforms. Integrated Environment The mode-less design principles of REAL 3D V.2 mean that the user can directly access most functions of the program simultaneously. F or example: it is possible to modify a material and immediately see how the modification affects the rendered image. Configurable Environment Expendability The REAL 3D user interface is fully configurable. You easily are able to design different working environments to meet requirements of different applications. For example: REAL 3D V.2 can be used as a single view editor, a tri-view editor or perhaps a 9-view editor. It is possible to expand the program by defining new functions and binding them to icons and keys. Zero Wait State Design The asynchronous software design, implemented using the latest techniques of object-oriented programming, takes extensive advantage of multi-tasking operating systems. In this way maximum convenience and productivity are achieved when modelling. The user never has to wait until some function has finished; instead, he can continue with new actions while old ones execute as background tasks. Hierarchical Object-Oriented Construction of Objects With REAL 3D V2, objects can be created with hierarchical structure. This means that the objects are made of sub-objects, and these sub-objects may have their own sub-structure and so on. This kind of tree structure is well known in the context of disk operating systems in which directories are created inside other directories. In REAL 3D the counterparts of these directories combine objects into logical groups. This approach makes, for example, object modifications extremely easy because it is possible to perform operations to each logical entity separately or collectively. When copying a DOS directory, it is not necessary to take care of the individual files and directories inside it. In the same manner , a complex object can be stretched in REAL 3D as easily as one part of it. Ray Tracing The ray tracing calculations of REAL 3D are strongly based on the optical properties of materials in the real world. REAL 3D produces images by simulating the laws of optics, and consequently they represent reality with astonishing accuracy. Speed Innovative methods and new ray tracing algorithms make REAL 3D extremely fast. Ray tracing in REAL 3D V.2 is so incredibly fast that it is usable as a primary re-drawing method instead of wire-frames during the interactive modelling process. Rendering Techniques As well as the ultra fast wire-frame refreshing, REAL 3D V.2 includes six different rendering techniques: hidden-line wire-frames, high speed basic surface rendering, simple ray tracing with non-interactive environment-mapped reflections, single light-source ray tracing, rendering without shadows, and full featured ray tracing. Light-sources it is possible to use an unlimited number of light-sources with any desired color and intensity. Smooth edged shadows can be produced using diffuse light-sources. Anti-aliasing REAL 3D V.2 includes adjustable anti-aliasing. There are 9 different degrees of anti-aliasing, from which the user can select a suitable level. The most accurate level uses 256 * 256 adaptive over-sampling, which is enough for any application! Depth-of-Field Using a highly optimized algorithm, depth-of-field can be used even for very complex scenes. There is no significant impact on rendering time. Motion Blur The Rendering Engine also supports a sophisticated motion blur evaluation system that can be applied to whole scenes or individual objects selectively. The use of adaptive over-sampling makes this evaluation faster than other software on equivalent platforms. Draft rendering For drafting purposes it is possible to render with low resolutions to produce images faster. Rectangular areas of an image can be individually selected and rendered with any desired techniques: resolution, anti-aliasing level, etc. True Solid Modeling REAL 3D V.2 includes CSG (Constructive Solid Geometry) modelling. Solid modelling is the most sophisticated way to represent three dimensional objects. For example, solid modelling offers general boolean operations and makes it possible to simulate optical devices, like lenses, correctly. Mathematical Surfaces In addition to polygonal surfaces, REAL 3D V.2 includes several curved surfaces such as: ellipsoids, cylinders, cones and hyperboloids. The surface descriptions of these surfaces are defined mathematically. This means that no matter how much a sphere created by REAL 3D V.2 is enlarged, no edges, corners, or other artifacts become visible on its surface. This makes the program much faster, and most importantly, the resultant images are of very high quality. Boolean Operations Using boolean operations between objects, you can for example, split an object into two pieces and move the pieces apart so that the inner structure of the object is revealed. Operations can alter the properties of the material of the target object using the properties of the tool. By using a shiny cylinder, a shiny hole can be drilled into a matt object. These operations are a powerful way to create and modify objects. When modelling technical objects these boolean operations are especially indispensable. Compound Tools Complex shapes constructed by automatically combining basic primitive objects. Polygonal Surfaces Conventional polygonal surfaces with optional Phong Shading are included. B-spline Surfaces Uniform cubic B-spline surfaces provide the user with a very powerful way of representing curved free-form surfaces and organic shapes. The quality of shaded B-spline surfaces is far superior to polygonal surfaces with Phong Shading. Free-form Construction A large collection of free-form surface construction functions are provided including: co-planar and orthogonal sweeps, rotation, cross- sectional building, etc. Linear Modifications All the necessary functions for modifying the basic shape and properties of objects are included. Non-linear Transformations Nearly one hundred non-linear transformations and bending functions are available for altering the shape of free-form surfaces. Fractal Generators Two fractal generators are included for constructing "landscapes" and "trees". Material Properties Using the hierarchical structure it is possible to construct objects from different materials having suitable physical properties. All material properties can be adjusted without any restrictions. Even the refractive index of light is freely adjustable so that it is possible to create optical devices from glass lenses. These devices act as their real-world counterparts: a magnifying glass in REAL 3D really magnifies! Texture Mapping The texture mapping properties of REAL 3D V.2 are not restricted to any fixed patterns. Any image file can be used to paint objects. Pictures created with any paint program, video digitizer, or scanner can all be used to color the surface of an object. For example, by digitizing a wood-grain pattern, it is easy to create wooden objects that look very realistic. In REAL 3D V.2 textures are treated as objects and are a part of the object hierarchy which means that textures can be modified and animated just as easily as any other object. B-spline Mapping Textures and images can be mapped over the surface of a B-spline mesh so that they exactly follow the curvature of the mesh object. The B-spline object can be modified or animated and its texture will move with it like a skin. Procedural Textures As well as using image files to define material properties, an unlimited number of mathematical handlers can be used. The user can write arbitrary formulas defining the color, bump-mapping, and other material properties. Many built in procedural handlers are included. Multiple Textures Objects can have multiple textures and materials. Furthermore, the materials can be faded and mixed. Animation Support The new version introduces a revolutionary animation system which extends the object-orientation principles to the process of defining the animation methods for each object. In the new animation system, the motion description is a natural part of the object structure. The built-in animation methods include such features as: basic motion and shape modification, morphing and skeletonal control using inverse kinematics. Particle Animation There is also one of the most powerful particle animation systems available integrated into the animation system. Using these animation methods objects are treated as particles that can have various physical properties like: velocity , spin, mass, and surface-friction. They can then be made to collide and interact just like objects in the real world. Interactive Replay REAL 3D also includes software for showing rendered animations interactively. Macro Functions it is possible to combine REAL 3D functions to form macros either by recording the mouse and keyboard actions, or by creating the descriptive text using the built in programming language. With macros the user can easily create complex symmetrical forms or produce animation effects. Macros can be saved, loaded, and bound to keys and icons. RPL Language REAL 3D contains a fully featured programming language called RPL. The language offers the most powerful interface to the software and can even be used for accessing operating system functions. RPL is used for: - expanding the program features - macro recording - scene description and saving - particle and procedural animation methods - procedural material properties Two formats are available: a binary and an ASCII format. The binary format offers efficient and fast way of storing a scene description, whereas the ASCII format, based on RPL programming language, is machine independent. Tag Expansion Object and material data structures can be expanded using tags. Tags are also used in particle animations where the tag data attached to an object can determine the behavior of the object. AutoCAD Interface REAL 3D supports importing AutoCAD DXF format. Mattes and Background The 3D images rendered by REAL 3D are easily integrated with digital backgrounds. By using other objects to act as "mattes", rendered objects can be made to "pass behind" parts of the background. When used correctly with the animation system these techniques allow direct combination of 3D graphics and "live" action. Alpha channel The REAL 3D Rendering Engine provides support for graphics hardware with an alpha-information channel. By using the alpha-channel as a video key, ray traced scenes can be combined with video without the need to digitize it in advance. image Output The protocol for output devices is well designed and flexible. This allows for graphics hardware manufacturers to easily write the software needed for using their hardware with REAL 3D. Field Rendering Rendering of separate fields is also supported by the software. @endnode @node "I2.1" @title "Chapter 2 INSTALLATION" Chapter 2 INSTALLATION ---------------------- 2.1 HARDWARE REQUIREMENTS REAL 3D V.2 has the following hardware requirements: - At least 3 megabytes of RAM memory - A hard disk with at least 5 megabytes of free-space for the software - MC68020 (or higher, e.g. 68030/68040) processor - A math coprocessor For professional users we recommend a configuration with at least 5 megabytes of RAM memory and at least 10 megabytes of hard disk space reserved for the REAL 3D environment. The special 68040 optimized program version has been tested to be up to 8 times faster in rendering than the 68030 version running equal clock frequency. @endnode @node "I2.2" @title "Chapter 2 INSTALLATION" 2.2 INSTALLING THE SYSTEM Before you use your REAL 3D disks, make working copies of the originals by using either Workbench-duplicate operation or some copying program. This guarantees that if a disk is corrupted accidentally, you will still have a good copy. To use the software, you need a hard disk. To install the software to your hard disk, just double click the InstallHD-icon on the first program disk and follow the instructions. For successful installation, there must be at least five megabytes of free hard disk space. After installation, remember to add "assign R3D2: Partition:R3D2" command to your startup-sequence (preferably to the s:user-startup file), where "Partition" refers to the hard disk partition you chose. For your convenience, REAL 3D maintains information of the DOS directories that contain the data structures created with the program, for example: project, material, and object structures. The default directories are the directories found in the software package. You can change them by using Settings/Paths function and then by using Project/Environment/Save function , save the working environment as "s:real-startup". The directory paths are included in the project file, and when you next run the program and try to load some data, the relevant directory is immediately displayed (if it still exists). The automatic installation procedure creates a directory under which it copies the contents of the program disks. Furthermore, it adds two files to the s: directory, real-startup and RPL-startup. Real-startup is a project file, containing the default user interface. RPL-startup contains the initial RPL definitions of which the most important are the default keyboard binding definitions or Hot-Keys. @endnode @node "I3.1" @title "Chapter 3 USING THE MANUAL" Chapter 3 USING THE MANUAL -------------------------- 3.1 welcome to the world of REAL 3D V.2 REAL 3D V.2 is an extremely powerful tool for creating realistic computer graphics images and animations. Once you have grasped a few basic principles you will find it very interesting to use. This manual is designed to gently take you through the learning process. Very soon you will be creating some very cool images and animations that previously you didn't think possible on a desktop 3D platform. @endnode @node "I3.2.1" @title "Chapter 3 USING THE MANUAL" 3.2 Suggested Method of Reading 3.2.1 All Users The manual contains six different sections: @{"Introduction" link "INTRODUCTION"} - Introduces you to the program and gets you started. @{"Tutorial" link "TUTORIAL"} - Takes you through all the functions in easy steps with lots of examples. There are also text and files in the "Examples" directory to help. @{"Reference" link "REFERENCE"} - This contains concise descriptions for the menu functions and for each gadget on all the requesters. @{"Glossary" link "GLOSSARY"} - REAL 3D V.2 uses a number of special terms and phrases to describe the items you create and how certain functions operate. These are all defined in this section. @{"Appendices" link "APPENDICES"} - All the miscellaneous information: diagrams of icons, descriptions of hot-keys, and using the support software is contained in this section. @{"Index" link "INDEX"} - A full index. In Chapter 4, "Getting Started", there is a special project for you to load with instructions to follow so that you can experiment and get a quick taste of the power of REAL 3D V.2. @endnode @node "I3.2.2" @title "Chapter 3 USING THE MANUAL" 3.2.2 As a New User If this is the first time you have ever used a 3D graphics program then using REAL 3D will be a real experience! You should go straight to Chapter 4 and follow the instructions carefully. Take your time, be patient, the whole world of Virtual Reality and Computer Generated Images & Animations lies before you... You should now go to Chapter 4 "Getting Started". @endnode @node "I3.2.3" @title "Chapter 3 USING THE MANUAL" 3.2.3 As a User with Previous 3D Graphics Experience If you have used 3D graphics packages before, but never any of the previous versions of REAL 3D then you should pay special attention to the Tutorial. REAL 3D is on the cutting-edge of 3D graphics software, and contains many new ideas and principles which make it probably the most powerful computer graphics development tool available on ANY platform. It is quite different from other packages; but in this difference lies its power. REAL 3D V.2 gives you, the user, a highly flexible editor for creating the shapes and materials you desire using a working environment you can configure to your own personal requirements (or even the requirements of a particular project). This editor is smoothly integrated with a highly optimized rendering engine that will provide you with ray-traced images in the minimum of time. If draft rendering is used on a fast workstation then it is quite practical to edit using shaded surfaces. The next sub-chapter is directed at users who already have some experience with REAL 3D from the original version. To get immediately into learning the new program just go to Chapter 4; but if you are interested in the history of REAL 3D's development then read on... @endnode @node "I3.2.4" @title "Chapter 3 USING THE MANUAL" 3.2.4 Real-1.X User About 4 man-years of programming effort has been put into developing version 2.0 from 1.42. Understandably the program has changed considerably, but the basic principles of creating objects using primitives, arranged in a hierarchy, remains. The way that hierarchy is used to control and construct objects has been expanded. Animation is no longer based upon "exposed' frames or objects but upon new structures created in the hierarchy to describe how objects should move and transform. The whole user-interface has changed radically and many new features have been added. Once you discover the power behind these new features they will rapidly become essential tools that you would not want to do without. Almost all of your old friends are still there, they are just living in different places! Some functions have been replaced by much more powerful and flexible tools to cope with the expanded features of the program. The next sub-chapter is for you. It describes briefly most of the new developments, but it is not supposed to be a substitute for learning the new version. By all means experiment with the new features using your experience of the earlier versions of REAL 3D, but if you don't get the results you expect then consult the @{"Tutorial" link "TUTORIAL"}, it's there to help! @endnode @node "I3.3.1" @title "Chapter 3 USING THE MANUAL" 3.3 MAJOR DEVELOPMENTS SINCE v1.42 3.3.1 System integration & Configurable interface The most immediately obvious change is that there are no longer three separate parts to the program. In REAL 3D V.2 object creation, modification, animation, and rendering can all be carried out on ONE screen. It is possible and often necessary to use more than one screen but the way in which screens are used can be configured by the user. This is handled by allowing the user to open screens that suit a particular requirement and opening one or more windows on that screen.- These windows do have specific functions depending upon their type, but each can be configured to meet your needs. It is also possible to declare one of these screens the default public screen (OS 2.0 feature). This means that certain OS 2.0 compatible programs can be integrated into REAL 3D. Conversely it may also be possible to integrate into those packages that also use public screens. A particular configuration of screens and windows can be saved as an "environment" and then loaded at any time. This configurable environment allows the creation of user-defined tool gadgets and single-key macros to extend the user interface. @endnode @node "I3.3.2" @title "Chapter 3 USING THE MANUAL" 3.3.2 Multi-selection Support The OS principle of multi-selection has been included in v.2. It is now possible to select lists of objects or even menu selections or tool icons. @endnode @node "I3.3.2.1" @title "Chapter 3 USING THE MANUAL" 3.3.2.1 Multi-selecting Objects Multiple objects can be selected from a Select Window using or in the same way as selecting icons on WorkBench. These objects then form a list which can be used as a target for any of the modification functions or as operands for some creation functions. This is an essential technique for those functions which require two or more objects as operands. @endnode @node "I3.3.2.2" @title "Chapter 3 USING THE MANUAL" 3.3.2.2 Multi-selecting Functions An Action List is maintained for keeping all functions selected by the user. As many functions as required can be placed on this list by clicking either on the Tool Icons or on a menu selection. These functions can then be used consecutively until the list is empty. The list operates on a First In First Out (FIFO) basis. @endnode @node "I3.3.3" @title "Chapter 3 USING THE MANUAL" 3.3.3 Hierarchy The use of the hierarchy has been substantially expanded by the addition of many new primitives and the functions to control them. Probably the most important changes to the hierarchy concern: the animation system, materials, and boolean operations. @endnode @node "I3.3.3.1" @title "Chapter 3 USING THE MANUAL" 3.3.3.1 Animation System The animation system is completely new. Animations are no longer based upon frames and exposed objects. Instead time is now a global value that controls how objects are animated and there is a special window (the animation window) for controlling time. Time is continuous and any moment in time can be selected and the position and state of all animated objects can be viewed for that time. Moments in time, or frames, only become animations when they are rendered. Animation effects (called methods) i.e. PATH, SWEEP, COLLISION, etc., are now attached to objects in the hierarchy. These "methods' can effect all those objects at the same hierarchical level, and some can even effect other methods. This means it is possible to build the animation of a complex object up in stages: - Make a thigh rotate about a hip. - Make a shin rotate about the knee of the thigh. - Make the whole leg run along a path. This whole object can then be positioned anywhere in space and it will carry out its actions when animated. All methods can be copied and modified by the modification functions just like any other object. If their animation effects are controlled by other objects which have some geometry then their effect will be modified with them. So the running leg can be duplicated to make a pair and, with a little bit of modification of size and position, can also become the arms for a running man. These animated objects can then be saved by the user. @endnode @node "I3.3.3.2" @title "Chapter 3 USING THE MANUAL" 3.3.3.2 Materials Materials are now associated with objects in the hierarchy in the same way as methods. These textures also effect objects in the same level. This means that several material properties can be applied to a visible (object) to produce extremely complex properties. For example: - A "shiny" material with no geometric texture can be used with a cylinder to make a metal tin can - A picture of a label can be used as an image and "wrapped" onto the tin with a cylindrical texture. - A third material can have mathematically defined circular "ridges" bump- mapped onto the ends of the can using a procedural handler. Since the textures can also have a geometrical representation, that is, a rectangular parallel projection would be represented by a dotted rectangle on the editor screen, they can be modified just like any other geometric. This means they can be re-positioned, sized, and stretched until they are in precisely the required place. Also a texture is just another object so of course it can be animated! @endnode @node "I3.3.3.3" @title "Chapter 3 USING THE MANUAL" 3.3.3.3 Boolean Operations Boolean operations are now applied to all objects at the same level of hierarchy instead of between just two operand objects. This means that if a level is turned from boolean type OR (the default) to AND then the resultant visible will consist of the over-lapping volume of ALL the objects in that level, including any other booleans. The AND NOT operation is achieved by applying the "Inverted" attribute to one or more of the objects in the level. By setting an objects "Paints" attribute, the "WITH PAINT" effect from the earlier versions is produced. All these settings are available in the object attributes requester opened with MODIFY/properties/Attributes, or there are functions under the CREATE/Boolean menu which use operands selected from the hierarchy with multi-selection to create the final composite. @endnode @node "I3.3.3.4" @title "Chapter 3 USING THE MANUAL" 3.3.3.4 Hierarchy References and Order In addition to the old feature of "logical objects" (now called levels), which allowed new objects to be grouped at different levels of hierarchy, there are two new objects which alter the evaluation of the hierarchy. These are groups, which are references to a collections of points on a free-form, and links, which allow other parts of the hierarchy to be referenced at the current level. @endnode @node "I3.3.4" @title "Chapter 3 USING THE MANUAL" 3.3.4 Free-form Curves and Surfaces The major new feature is the addition of cubic B-spline curves and surfaces for the construction of free-form objects. B-splines can be controlled in a similar way to the original free-form objects in v1.42, but the quality when rendered is significantly higher even when the surface is constructed from very few data points. There are some restrictions about using B-splines and some basic tricks to learn. Also the calculations involved in rendering them are staggering, so although the rendering engine has been specially optimized to cope, they are not as fast as Phong Shaded surfaces. The quality is well worth the wait though. @endnode @node "I3.3.5" @title "Chapter 3 USING THE MANUAL" 3.3.5 Built-in Programming Language Finally, REAL 3D V.2 has its own programming language, RPL, which allows any function the user requires to be integrated easily into the software. @endnode @node "I4.1" @title "Chapter 4 GETTING STARTED" Chapter 4 GETTING STARTED ------------------------- This chapter takes you through the first stages of using REAL 3D V.2. The main part of this chapter takes you step by step through a REAL 3D project which has been prepared specially to introduce you to most of the fundamental principles. It should also show you the potential of this incredibly powerful computer graphics design tool. 4.1 OPENING THE PROGRAM You should have already installed the program to your hard-drive, if not go through the steps in 2.2 above before proceeding. Now open the drawer where you installed the REAL 3D system and double- click the icon "Real" using the left mouse button. From now on this will just be described as double-clicking and the left mouse button will be abbreviated to . The program is quite large and will take a few moments to load. When the program first loads you will be presented with your first REAL 3D working environment. This initial environment consists of just three windows. The large almost square window with a thin border is a view window. Through this window you look into the REAL 3D universe. The small window in the bottom right corner is a tool window or tool-box. This contains a number of tool icons. The third window on the right is a select window. This is used for selecting objects from the hierarchy which is the special way that REAL 3D stores all its objects. In some ways this is the most important of all the windows in the REAL 3D system. Understanding how hierarchy and object selection works it the key to unlocking the power behind REAL 3D. This may seem to be a very simple arrangement, but it provides you with all the basic windows and tools you will need to experiment with the introduction project. Later you will learn how to re-configure your environment to suit your own requirements. @endnode @node "I4.2.1" @title "Chapter 4 GETTING STARTED" 4.2 FAMILIARIZE YOURSELF WITH THE MENUS & TOOLS 4.2.1 Menus Just use the right mouse button (this will be shown as from now on) to browse through the menu lists. Soon you will find that they are very logically laid out and it is easy to remember where each function lives. Example 1: Create a sphere with a menu function. 1. Select the menu function Create Visibles/Sphere. Note: This means hold the down and slide the pointer along the top menu strip until you come to the second heading "Create". Then move the pointer down to the first sub-menu called "Visibles" . Still holding the down move over the sub-menu until the pointer is over the function "Sphere". Finally release the . The name of the function you selected appears at the top of the view after the text "Next:". This tells you that the next function on the Action List will be to create a sphere. 2. Click the once somewhere near the middle of the view. Note: You must just quickly click the button, don't hold it down otherwise you will get a box which has a special use. If you do get a box don't worry, just let go of the and REAL 3D will automatically select the start point for your sphere. 3. Move the pointer. As you move the pointer you will see the wire-frame representation of the sphere you are creating drawn with a dark broken line. A wire-frame is just a very fast way of representing the shape of a three-dimensional object on the two dimensional surface of your monitor. 4. When the sphere is the size you want just click the again to complete the creation process. The wire-frame is drawn with a solid white line, and the name "ellipsoid" appears in the select window. @endnode @node "I4.2.2" @title "Chapter 4 GETTING STARTED" 4.2.2 tool icons You can also see a window containing a number of tool icons which provide single click access to many of the most frequently needed functions. There are more icons available, only the basic ones are currently in the tool window. You can find out how to add more icons to your tool box and even create your own in the @{"Tutorial" link "TUTORIAL"} section. Example 2: Using the Create/"Sphere" tool icon to create a second sphere. 1. Click on the icon in the tool-box. The icon is second one of the fourth icon row. 2. Select the center for the sphere using the as you did in step 2 of Example 1 . Select a point away from your first sphere so that the new one will not overlap. 3. Follow steps 3 & 4 above. You should now have two wire-frames of spheres and the Select Window will have the names "ellipsoid" and "ellipsoid.1" on the list of objects. @endnode @node "I4.2.3" 4.2.3 Hot-keys You might want to see what your spheres look like when shaded so follow the following example. Example 3: Invoking the rendering engine using a hot-key. 1. Press and hold the right Amiga key ( from now on). 2. Press the "r" key. Pressing the shift key is unnecessary, the hot-keys are not case sensitive. Note: Make sure you have the view window active. Click on it or check to see if it is "highlighted". You have just used the hot-key r to start rendering. The rendering engine will produce a shaded image of your two spheres using its Draft setting. Your environment was set up with 8 levels of gray, but most other graphics modes are supported. The rendering engine is the part of the REAL 3D system that draws your objects as shaded surfaces instead of wire-frames. @endnode @node "I4.2.4" @title "Chapter 4 GETTING STARTED" 4.2.4 Conclusion That is how easy it is to create and render objects using REAL 3D. Obviously it will take some practice to create complex scenes and animations, but follow the next sub-chapter through and you will begin to see the potential... @endnode @node "I4.3.1" @title "Chapter 4 GETTING STARTED" 4.3 INTRODUCTION PROJECT A special set of files have been prepared to accompany this manual, you will use the first of these now in order to get a brief taste of the power of REAL 3D V.2. If you are new to REAL 3D and especially if the whole process of using the Amiga is new to you, take your time and read the instructions carefully. Everything has been arranged in a concise and logical fashion to make it easy for you. Just follow the instructions and the manual will guide you through. 4.3.1 Loading the Project The first thing you need to do is load the introduction project. A REAL 3D project contains the information necessary to define a scene or animation in the REAL 3D universe. Example 4: Load a new project. 1. Select the menu function Project/Project/Replace using the same process for menu selection as described in Example 1 above. A standard file selector is opened. This is the basic style of requester for loading and saving files. It shows the files that are available in the current drawer as a selection list, and a number of other gadgets for controlling which types of files are shown and for moving to different drawers and partitions of your disk. Note: To select a file, move the pointer over the name of the file in the list and click . The file name will be high-lighted and at the same time it will appear in the "File" text-gadget box. 2. Select the "Intro.prj" file. Then move the pointer over the OK button- gadget and click . REAL 3D has loaded a new set of windows as part of the working environment for the "Intro" project. You can see a view, a select window, and an animation window. The animation window contains all the gadgets for controlling animation playback and recording (much like VCR controls). You will find out how to use some of these gadgets shortly, the rest are explained in the @{"Tutorial" link "TUTORIAL"}. This window has been opened on its own private screen. For the moment slide the animation window down out of the way by following the method : 3. Move the pointer over the dark bar at the top of the Animation Screen, press and hold the and then move the pointer down to slide the screen out of the way. When you can see all the view then release the to let go of the screen bar. Now you can begin to investigate the features of the project. @endnode @node "I4.3.2" @title "Chapter 4 GETTING STARTED" 4.3.2 Refreshing and Rendering Example 5: Testing refreshing and view projection types. 1. Move the pointer onto the view window, click to make it the active window, then press the key. Pressing has refreshed all the windows. Now you can see the wire-frame representations of the objects in this REAL 3D universe. Note: An object is any item like a shape or surface that is stored in the special structure called the hierarchy. The principle of how objects are stored in hierarchy is very important to understanding REAL 3D, but for now just think of the hierarchy as like your hard-drive. It can contain different types of objects and can have different "drawers" for putting objects in. 2. To see the wire-frames in perspective select the View/Type menu, and click the once on the "Perspective" item. A check mark will appear on the left to show that this type is now selected. Note: Before you clicked on "Perspective" you may have noticed that the View Projection Type was "Parallel". This type of projection produces the kind of wire-frame views used by most CAD programs. 3. Now try pressing each of the different cursor keys several times. You will see that as you press the keys the wireframe image rotates. You can continue to rotate in any direction until you come right back to the starting position. Note: If you find the direction of the rotation confusing then you should realize that it is rotating the View about the objects in the same way as you move a camera or turn your head. If you turn your head to the left (left cursor key or ) then what you are looking at moves to the right. 4. To re-display your starting position use View/Display/Reset or e. The view returns to its original viewing position and the wireframes are re-drawn. Example 6: Experimenting with rendering techniques. 1. For the simplest rendering select the function View/Render/Window. "Simple Shaded View of Introduction Project" The wire-frame image is quickly replaced by one showing the objects as gray shaded surfaces. As it was when you pressed r, the view has been refreshed using the simple shaded surface rendering mode called "Draft". This is a special very high-speed technique used by the rendering engine which just gives you the fastest possible truly three dimensional representation of your visible objects. It is possible, on a fast workstation, to use this mode as part of your interactive editing of objects. 2. Select the function View/Render/Settings. This will open a Render Settings Requester Window with many gadgets that covers most of the screen. Note: These gadgets are easy to learn and will give you complete control of how the rendering engine converts your scene into an image. 3. Move the pointer up towards the top left hand corner of the render settings requester and find the gadget labelled "Mode". You will see that the actual button is showing that it is in "Draft" mode. Click once on this cycle-gadget and the rendering mode will change to "Environment. 4. Now move down to the bottom left corner and select "OK" to confirm the change. This will close the window. 5. You should now render the view again. Note: You have used the hot-key r before, so you can use it from now on whenever you want the rendering engine to refresh a view. Remember: Using r ONLY affects view windows, so you must make sure that one is active by clicking it; otherwise nothing will happen. The scene is re-drawn, only this time the big sphere is striped and shows the realsoft Logo, and the base has a chequered pattern. Note: "Environment mode is the first rendering mode that uses materials when it creates the image. If you want to create realistic looking scenes you have to be able to describe how an object affects the light which falls on it. This is done by defining a material and applying it to the object. The @{"Tutorial" link "TUTORIAL"} explains all the details of creating and using materials. 6. The image looks a bit "over-exposed" so you should make another small adjustment to the render settings. To open the render settings requester, you can use the menus, or the hot-key s. Now find the slider-gadget labelled "Brightness'. (It's on the left, near the bottom.) To the right of the slider is a number, currently it shows the value of "Brightness' as 100. Move the slider until this value is between 70 and 80; then confirm the change with "OK', and render the view again. Note: To move the slider, just position the pointer over the dark rectangle, hold the , and move the mouse from right to left. When the rendering engine produces the image this time, the over-all level of light is reduced so those bright parts of the scene that had become overexposed are now at a more natural level. This is just like adjusting the "Contrast' control of your monitor. 7. If you want to see what this scene looks like now in color, select View/Render/HAM. This will open render settings so you can make any last minute adjustments before rendering. You can look at one more feature of the rendering engine by clicking on the check-gadget labeled "Backgr. gradient". A check mark will appear on the button to show that this feature is enabled. Everything else should be just perfect so click "OK". REAL 3D automatically opens a HAM screen with a full-screen window with no border. This type of window is called a borderless view. The rendering engine is also started. You will see the scene rendered in color this time. The background will be shaded from a light to a darker gray. We will now have a look at some of the features of the animation system. @endnode @node "I4.3.3" @title "Chapter 4 GETTING STARTED" 4.3.3 Animating Example 6: Playing an animation. 1. First you should close the HAM screen. Select the function Project/Environment/Close - Current. REAL 3D closes the borderless view and the HAM screen leaving you with your original environment. 2. Use the same method as you did in Example 4, step 3 to get hold of the title bar of the animation screen and drag it so you can see all the gadgets as far down as the one on the right showing "Wireframe'. 3. Click the "Play Forwards" gadget labelled with "->|". This will play a wire-frame pre-view of the animation. 4. When the anImatIon play stops, click the play backwards gadget on the Animation Window. "l<-". 5. The wire-frame animation will now play backwards. You will notice that the small bouncing sphere has not ended up in its original position. The reasons for this is that its animation is influenced by "Particle Animation" and it requires some special handling that will be discussed later in the manual. For now, just remove this part of the animation: 6. Move the pointer onto the select window and click once on the object name "Particle_Sys". The name "Particle_Sys" is now high-lighted to show that it is a selected object. 7. Now select the function Modify/Structure/Delete. The object "Particle_Sys" has been deleted. Its name is removed from the select window and the wire-frame of the bouncing ball is missing from the view. This is because the Particle_Sys object was actually several objects, including the visible ones, contained in a single drawer-like object which is called a level in REAL 3D terminology. 8. Now you can try all the other "VCR-like" button-gadgets on the animation window, and the animation will behave exactly as you expect. Note: As you play with the gadgets notice what happens with the "knob" on the "Time" slider gadget and to the numbers in the box to the right of it. They show the animation time which is always between 0.0 and 1.0. @endnode @node "I4.3.3.1" @title "Chapter 4 GETTING STARTED" 4.3.3.1 "Jump To/Play To" and the "Time Slider" Example 7: Testing the "Time Slider" controls. 1. Use the to hold the "knob" of the slider as you did with the "Brightness" control of render settings. Now move it to a new time. Time goes immediately to the new value, and the view is refreshed showing the position of "Animation Obj" for that time. If you cannot clearly determine the position from the wireframes just click on the view and use r to render the image. Remember: If "Environment" mode is too slow for your workstation then change it to "Draft" using render settings. 2. Click on the cycle-gadget which is showing "Jump To". It will change to "Play To". Now when you change time with the slider the animation is played from the current time to the new value. @endnode @node "I4.3.3.2" @title "Chapter 4 GETTING STARTED" 4.3.3.2 "Wireframe/Ray Trace" Gadget There is one last gadget that you should look at while "Getting Started". This controls how the animation system refreshes your view while it plays back the animation. Example 8: Testing Animation Refresh 1. Use one of the Time controls to set the animation at the start. Now click on the cycle-gadget showing "Wire frame". It changes to "Ray Trace". 2. Now change time slightly. The animation system updates the position of the animated objects and invokes the rendering engine to update the view. The system continues shading new images until the time value you gave is reached. You can stop the process by clicking the CANCEL button. @endnode @node "I4.3.4" @title "Chapter 4 GETTING STARTED" 4.3.4 Rendering Revisited Just before you leave the @{"Introduction" link "INTRODUCTION"} to begin the @{"Tutorial" link "TUTORIAL"} you might like to look at the full power of the rendering engine. The following example does not describe any details of the functions you will use. It is just here to allow you to see how realistic the images are that REAL 3D can produce. Example 9: Producing an image with soft-shadows and depth-of-field. 1. Use Project/Project/Replace to load a new copy of "Intro.prj". 2. Click on the view and then change the View/Type to "Perspective". Then use - twice to zoom the display out. Note: You may have to press the key to get the "-" function. 3. Now change the "Jump To" control for the time slider to "Play To" and set the time to about half-way through the animation. Remember: If you want the bouncing ball to be correct, you can only move timeforward. 4. To start the rendering, click on the view and select View/Render/HAM or use h. 5. When render settings opens, change the "Mode" to "Normal", set "Brightness" to about 75, and enable "Background gradient" as you did before. 6. Now use the two slider gadgets above "Backgr. gradient" to set "Antialiasing" to 3 and "Lightsamples" to 1. 7. Finally click the pointer in the numeric-gadget box labelled "DOF scale" , then enter the value 1.0. Check the settings, then confirm them and start the rendering with "OK". This will take a few minutes to produce the finished image, as REAL 3D is having to carry out a phenomenal number of calculations to produce such a very realistic image. @endnode @node "I4.4" @title "Chapter 4 GETTING STARTED" 4.4 END OF THE BEGINNING Hopefully this @{"Introduction" link "INTRODUCTION"} has whetted your appetite and demonstrated a little of the power of REAL 3D V.2. In the @{"Tutorial" link "TUTORIAL"}S that follow, you will find that the program is logically arranged and with a little practice you will very soon be able to create fantastic images and animations. @endnode @node "T1.1" @title "Chapter 1 OBJECT CREATION & MODIFICATION" TUTORIAL -------- Chapter 1 OBJECT CREATION & MODIFICATION ---------------------------------------- Before you start to read the tutorials, remember that most tutorial examples include an example of the finished result. You will be informed about the presence of this kind of support material in the following way: Support example: Examples/..... This means that you can verify the result of the tutorial example by replacing your current project (use menu Project/Project/Replace) with the given file, which you can find in the "Examples" directory of the REAL 3D drawer. If you worked through Chapter 4 GETTING STARTED of the @{"Introduction" link "INTRODUCTION"}, then you have already created some spheres, and you will have seen a few of the other objects which can be created when you looked at the Intro.prj. This first chapter of the tutorial is intended to give you an overview of the user interface of the software. It will familiarize you with the use of the hierarchy and basic creation and modify functions. 1.1 STARTING THE PROGRAM REAL 3D can be activated from the Workbench interface by double-clicking the icon of the program "Real", or from the command line interpreter (CLI/SHELL) by the command REAL. If you are going to modify a project that you have created earlier, then you can start the program by opening the icon for that object as described in Amiga user interface manuals. The same method is valid for all data structures created by the program. For example, you may choose to start the program from different environment files instead of the program icon itself, depending on what kind of modelling you are planning to do. If the purpose is to create animations, run the program directly to the animation environment; if you are going to do accurate CAD type modelling, pick a tri-view environment with plenty of grids. The user interface of REAL 3D is configurable and you may customize it to suit your needs. The "Environments" drawer of the software package contains some sample environments. Note: If you start the program from CLI, make sure that the stack size is large enough. We recommend the stack size be at least 40 000 bytes. You can use the CLI stack command to set a proper stack size. When studying this chapter, you should use the standard environment, and therefore start the program from its icon. @endnode @node "T1.2" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.2 THE WINDOWS When the program is started from its program icon, it loads the environment definition stored in the s:real-startup file. The original environment contains a basic 3 window interface in which all the creation and modifying functions can be done. The largest window, a view window, shows the object under construction. By default, it displays the object from the front as parallel projection. The construction of objects is done in view windows using the mouse. You can see a symbol _+_ in the view window. This symbol is the "hot-point", which displays the latest given coordinate position in space. You can move the hot-point to a new location by clicking in a desired place. The third coordinate value for the points, which the user defines with the mouse, is read from the hot-point position, because a mouse button click defines only two coordinates at a time. The top border of the view displays some useful information. First, you can see a window name identifier. Second, the projection type of the view; parallel or perspective. Finally, the view border displays two selected functions, current one and the next one in the FIFO list of the view. The window in the top right corner of the display is called a selection window. This window displays the names of the objects you have constructed. You can select an object by clicking on its name in the select window. Multi-selection happens by pressing the key down and clicking the names, or by dragging with the in the select window. The names of selected objects are highlighted as an indication of the selection. The select window is very important part of the working environment. Extensive use of object hierarchy is one of the most important principles of REAL 3D. The third window, in the bottom right corner of the screen, is a tool window. It contains tool icons from which you can activate functions. It is possible to modify the contents of the tool window and add user- defined icons. @endnode @node "T1.3" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.3 THE MOUSE When using REAL 3D, the mouse is the most important input device, and the actions the user can do with it can be divided in two categories in the following way: - The right button is used for menu selection. In addition to this, certain object creation procedures can be cancelled by clicking the right mouse button. - All the other actions are done using the left mouse button, such as drawing. Remember: Left mouse button is abbreviated as , and right one as . Most of the actions in REAL 3D can be performed by menu selection in a way which is defined by the Workbench user interface: to select a menu item, press the right mouse button, point to the menu bar, then point to the desired menu item and release the right button, The highlighted menu item is the one which is being selected. You can experiment by selecting Extras/Refresh/Wire-frame. The program replies by redrawing the display. Also, menu multi-selection is supported: to select several menu items at the same time, keep the right mouse button down and select the menus with the left mouse button. The multi-selected actions are executed in First In First Out order (FIFO). Note that each window type may have its own menu system which may be different from other windows menus, and some windows may have part of the menus inactive. For example, it is not possible to select the function View/Render/Window when a "select" window is active. You must have a "view" window active (selected). In this manual menus are represented in the following way: - Menu/Item. - Menu/Item/Sub-item. For example: Create/Visibles/Sphere. Instead of using menus, most functions can be activated using keyboard equivalents (Hot-Keys) or tool window icons. When using the left mouse button, use sharp clicks instead of keeping the button down and moving the mouse. Left mouse button dragging is reserved for certain point selection functions. For example, when shaping a rectangle, click on the top left corner, and then release the button. Then you may freely move the mouse, or even select some menus, or have a cup of coffee. When you are certain of the position of the bottom right corner of the rectangle, click a second time in the desired place. When modelling objects with exact coordinates, it may be difficult to obtain high enough accuracy using the mouse. In such a situation, you can replace left mouse button clicks using either the vector stack or a measuring window. These will be described in detail later. Left mouse button "dragging", moving the mouse while keeping the left button pressed, has some special functions in REAL 3D. If you try this in the view window, you see that a box is shaped according to the mouse pointer movements. By default, the average is projected to the input plane, which is the plane in 3D space along which the coordinates run when you move the mouse. If you want to consider only the points of the selected objects instead of the whole scene, keep the key pressed when dragging. The other important combinations are: - , which pushes the points inside the drag box onto the vector stack. This operation does not project the average into the input plane. - , which creates a point group for point editing of freeform objects. Although the averaging operation is simple, it is very useful. Using this feature, you can easily lock the mouse coordinates to any existing point when modifying or creating an object; just drag the box around the one single point. The following examples demonstrate how the dragging feature can be used. Try these examples if you are already familiar with the software. (come back to these later, once you've learned the basics) To lengthen a cylinder: 1 . Activate the cylinder and select the Extend function. 2. Drag a box around the points of one end of the cylinder. 3. Drag a box around the other end. 4. Extend the object. To create a circle precisely in the middle of another circle: 1. Select the circle creation function. 2. Drag a box around the points of the circle; this defines the middle point of the new circle. 3. Define the radius. To move a triangle so its top will be in the middle of an edge of a rectangle, assuming that the two objects do not lie originally in the same plane: 1. Activate the triangle and select the Move function. 2. To ensure the operation is done correctly in all three dimensions, press and drag a box around the top point of a triangle; this puts the top point to the vector stack. 3. Hit . (right-Amiga-period). This pulls the true 3D coordinates of the triangle top from the vector stack. 4. a box containing the two end points of the desired edge of the rectangle. 5. Hit. @endnode @node "T1.4" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.4 BASIC TERMINOLOGY The term "object" in REAL 3D is used to describe all the items which are stored in the hierarchy. Objects take many different forms, depending upon their purpose. Not all objects have wire-frames, and some with wire-frames do not have a visible surface when they are rendered. Some objects cannot be seen at all, except as a name in a select window. There is one special class of object, which you need to know about, called a "primitive". A primitive is the most basic kind of object. In the REAL 3D universe, a primitive cannot be divided into smaller sub-objects. They are a bit like the fundamental particles of matter. Objects can be made from primitives and even other objects. One final point of terminology; a primitive is an object, but not all objects are primitives. If no special keys are pressed while dragging, the program calculates an average of all the points of the scene inside the dragged box, and moves the hot-point to the average point. There are six main classes of primitives, but you will only look at the first four in this chapter. Most of these types also have some sub-types. visibles - These primitives produce a visible surface when rendered unless you take some action to alter their basic nature. structures - These primitives have no wire-frame and do not render, but despite that, they are in many ways the most important kind of primitive in the hierarchy. Structures control how other primitives are arranged and accessed by all the different functions of REAL 3D. controls - Although these have wire-frames, they do not have any surface and so do not render. As their name implies, they are used for controlling the action of various REAL 3D functions. freeforms - A collection of points describing a free-form line or surface is called a freeform in REAL 3D terminology. This may seem a little confusing at first, but as you work through the tutorial, how, when, and where to use each of these objects will become clear. @endnode @node "T1.5" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.5 TUTORIAL EXAMPLE 1: SELECT WINDOWS AND HIERARCHY All the objects created by REAL 3D consist of so called primitives. These are the basic components and tools from which you can construct more complex objects. To create a primitive "rectangle": 1. Choose the menu Create/Visibles/Rectangle. 2. Move the mouse pointer to a desired location and click the left button. 3. Now you can shape the rectangle by moving the pointer. 4. Click the left button, and REAL 3D creates a primitive "rectangle". Now the view displays a rectangular wireframe. You can look at the rectangle from different directions using cursor keys, or X for (front view), y for (side view), or z for (top view). The rectangle is a plane, and therefore it appears as a line when you look at it from the side. You can also see a peak perpendicular to the rectangle. The purpose of this peak is explained in the context of Boolean operations. Remember: x means that you first press the right Amiga key down, then you hit "x" key, and then you release right Amiga key. You can see the logical structure of your object in the select window. Your scene "Root" consists of one single primitive, "rectangle". If you now move the pointer on the name "Root" and click the left button, you can see the name being highlighted on the instruction window as an indication of the selection. Figure @{"T1-1:" system "display dh9:docs/r3ddoc/r3dv2pics/T1-1"} Select Window (PICTURE: T1.1) The names "Root" and "rectangle" are printed in different text types in the select window: "Root" is written with bold typeface, and "rectangle" is in normal type. The bold or normal gives an indication that the objects are of different "types" i.e. "Root" is a hierarchical object having a substructure, whereas rectangle does not have any sub-hierarchy. The object type, which "Root" represents, is called a level in REAL 3D. REAL 3D uses levels to collect the parts of an object into groups. It is possible to select and modify very complex levels without having to deal with their substructures. For example, if you have grouped all the parts of a robot arm under one single level "robot arm", then you can rotate the whole arm, and there is no need to pay any attention to each finger etc. A well known example of this kind of a hierarchical data management are disk operating systems: the level "Root" corresponds to a directory in DOS, and the counterpart of the object "rectangle" is an actual DOS file. @endnode @node "T1.5.1" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.5.1 The Current Level Next we will study some basic functions of the select window. For this, we need an object hierarchy which is a bit more complex: 1. Select menu Create/Structure/Level. A new level appears in the select window: Root rectangle level The new level was inserted after the rectangle, to the same hierarchy level as the rectangle. This happens because "Root" is the so called current level. Each select window stores the information of its own current level, and the program inserts new objects under the current level of the select window which was used last. This global object insertion level is called the current level. It is quite simple once you experiment a little. To change the current level: 2. Move the mouse pointer on the name "level" on the select window and Double-click . The contents of the select window should change to display "level" only. Now "level" is the current level, which can be seen in the following way: 3. Select menu Create/Visibles/Sphere, click once in the middle of the view, shape a circle and click again. This adds a new primitive to your hierarchy. The select window displays: level ellipsoid This means the sphere was inserted under "level", not immediately under "Root". The whole hierarchy is: +------+ | Root | +------+ / \ +-----------+ +-------+ | rectangle | | level | +-----------+ +-------+ | +----------+ |ellipsoid | +----------+ The same structure can be described using indentation: Root rectangle level ellipsoid or graphical presentation: +-------+ | level |--- /+-------+ \ +-----------+ / \| ellipsoid | +------+/ +-----------+ +-----------+ | Root |--| Rectangle | +------+ +-----------+ Figure T2-1: Simple Object Hierarchy All three methods are used throughout the manual, depending on which one is the most convenient. If you double-click name "rectangle", the result of the action is highlighting the name of the object in the select window. This is because the object "rectangle" represents the lowest level of the hierarchy, and there is no substructure to be displayed on the select window. To change the current level back to "Root": 4. double-click the topmost item, "level", on select window. Now the contents of "Root" level are displayed again. You are now on the top of the object structure hierarchy, and if you double-click "Root", nothing happens. If "Root" had been a part of a larger object, then you could have moved one step upwards in the hierarchy, and REAL 3D would have revealed all the objects in the same hierarchy level as "Root". @endnode @node "T1.5.2" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.5.2 Object Multi-selection Next we will experiment with modifying an object. But first, since we are going to consider multi-selection, continue with the previous example by creating one more primitive (make sure that "Root" is the current level): 1. Select Create/Visibles/Cube and shape a cube just as you created the rectangle. The size and position of the cube doesn't matter for this example. So, now you have the following hierarchy: Root rectangle level ellipsoid cube To move the cube to another position in space: 1. Select the cube by clicking its name on select window. Note: After creating the cube, it should be automatically selected, unless Settings/Creation/Auto _selected feature is switched off. Clicking the name again to re-select it does no harm. 2. Choose the menu Modify/Linear/Move. 3. Move the mouse pointer, for example, to the middle of the cube and click the left mouse button. 4. Move the cube to a new location and click. Note: Right mouse button cancels the modification. Now experiment with multi-selection: 5. Move the mouse pointer over "rectangle" on the select window, press and keep down, move the mouse down until all the three names under "Root" are highlighted, and release the . 6. Repeat the Move function and verify that all the three objects you selected are moving. Multi-selection can also be accessed in the following manner: 7. Click on select window below all the names in order to deselect all objects. Highlighted names now become normal. 8. Press key down and keep it there. 9. Click the name "Rectangle". 10. Click the name "level". 11. Click the name "cube". 12. Release key. Again, you multi-selected the same three items, this time one by one. The next test explains another useful trick: 13. Press key down and keep it there. 14. Click the name "level". 15. Release key. This deselects "level". This way it is possible to deselect individual objects which you have selected by mistake without starting the whole selection process from the beginning. To finish this example, do the following: 16. Multi-select the three objects in "Root" level as you did before. 17. Select Modify/Structure/Delete. You have deleted the scene of a rectangle, sphere and cube. Note: You cannot delete the root object. Summary: REAL 3D uses a hierarchy tree for describing and managing the structure of the scene. There are two important concepts related to the hierarchy tree: - The Current Level, under which new objects are inserted - List of Selected Objects, which defines the target of object modifications. @endnode @node "T1.6" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.6 TUTORIAL EXAMPLE 2: 3D MODELLING In this example, we create a simple table. The example demonstrates how to use object hierarchy, and especially the principles of 3D modelling. The table consists of a cover and a base, and the base consists of two stands and a brace. We will create the table only using cubes. The following picture illustrates the structure of the table: Figure @{"T1-3:" system "display dh9:docs/r3ddoc/r3dv2pics/T1-3"} Table (PICTURE: T1-3) You can continue modelling this example from the situation of where the last example ended, or start from new. You have the standard 3 window configuration and no objects built yet. You may also select Project/Project/New or restart the program before commencing. We start building the table by creating the hierarchy level, which contains all the parts of the table: 1. Choose Create/Structure/Level. 2. Choose the menu Modify/Properties/Name. A requester is opened. 3. Write the name "table" and hit or select OK. Figure @{"T1-4:" system "display dh9:docs/r3ddoc/r3dv2pics/T1-4"} The Name Input Device (PICTURE: T1-4) To create the cover of the table: 4. Open a palette window: use Project/Windows/Palette or hit p. 5. Choose a nice color for the cover by pressing down on the color bar of the palette window. When a good color is found, release and click the OK gadget. Then close the window using the standard window close gadget. 6. To ensure accurate positioning, select View/Grid/Snap to Grid. From now on, mouse coordinates are rounded to suitable intervals, and it becomes easy to line up objects. 7. Activate the view window by clicking it and hit e. Now you've got the standard front view. 8. Hit z. Now you've got top view; now click in the middle of the view. This moves the hot-point to the middle and guarantees that the third coordinate (z-coordinate) will be correct when you do front view modelling. (you have defined the z input coordinate). 9. Go back to front view by hitting x. 10. Choose Create/Visibles/Cube, and shape a low but wide cube to represent the cover as it is seen from the front. ---------------- Figure T1-5: Front View of the Cover of the Table. 11. "Cube" is not a good name for the cover of the table, so change it: choose the menu Modify/Properties/Name. Enter the name "cover" and hit . Now you have created a table which consists of a cover only. Now lets create an object "base": 12. Choose Create/Structure/Level. 13. Choose the menu Modify/Properties/Name, enter the name "base" and hit RETURN. Your table now consists of a cover and a base. Next we will start to build the base, but remember that we have to instruct the program to insert the new objects under the "base" level: 14. double-click the name "base" on the select window. This changes the current level to "base", and the contents of "base" are displayed. As it was shown in the previous chapter, as long as the current level is "base", every new object or primitive you create will become a part of the base. Now the hierarchy is: +------+ | Root | +------+ / \ +-------+ +------+ | cover | | base | +-------+ +------+ The base is a hierarchy level, which so far has nothing in it. To create a stand for the table: 15. Choose Create/Primitives/Cube and shape a narrow, high cube to represent a stand, as shown below. ---------------- | | | | | | Figure T1-6: Front View After Step 15. 16. Rename the new cube as "stand1" by choosing Modify/Properties/Name. The stands of the table are identical, therefore you can create the second stand by using the duplicate function: 17. Choose the menu Modify/Structure/Duplicate, having the stand as the selected object. 18. Move the copy to the right place by choosing Modify/Linear/Move. ---------------- | | | | | | | | | | | | Figure T1-7: Front View After Step 18. As you have seen, REAL 3D automatically gives names to primitives according to their types. This is handy when you are making a relatively small object, and therefore it is easy to identify the different parts of the object. Anyway, it is usually wise to give a name to each part of the object which describes its purpose. Therefore: 19. Choose Settings/Creation/Qry Prim. Name. 20. It is best to create the brace of the table using side the view, so hit y. 21. Shape a narrow, high cube in the middle of the stands (see figure below). When REAL 3D asks the name of the primitive, type "brace". ----------------- | | ----------------- | | | | | | |brace | | | | | | |_| | | | |_______________| Figure T1-8: Side View After Step 21. 22. Also, the cover of the table should be modified so it becomes wider than the stands. The side view you have now is suitable for this: change the current level back to root and select the cover. Then select menu Modify/Linear/Move and move the cover slightly (e.g. 2 grid units) to the left. 23. The cover is too narrow, so select menu Modify/Linear/Extend. Then click on the top left corner of the cover and then on the top right corner - when you move the mouse, you see that the cover width is changing accordingly. Move the mouse e.g. 4 grid units to the right from the original top right corner, so that the right edge reaches out over the edge of the stands as much as the left edge does. ----------------- | | ----------------- | | | | | | | | | | | | | |_| | | | |_______________| <------- move ----------------- | | ------------------ | | | | | | | | | | | | | |_| | | | |_______________| extend -------> --------------------- | | --------------------- | | | | | | | | | | | | | |_| | | | |_______________| Figure T1-9: Modifying the Cover. Now the side view shows the correct shape. But there are still some things to do: 24. Hit x to get front view again. The brace cube probably doesn't fit between the stands properly. So: 25. Select the brace object again using the select window. 26. Move the brace so its left edge matches the inner side of the left stand. 27. Extend the brace just as you extended the cover earlier, until it matches the stands (See the Figure @{"T1-3:" system "display dh9:docs/r3ddoc/r3dv2pics/T1-3"} ). 28. Use the cursor keys to find a good viewing angle and select View/Render/Window or hitr. Now the table is ready. The final hierarchical structure of the table is the following: +------+ | Root | +------+ | +-------+ | table | +-------+ / \ +-------+ +------+ | cover | | base | +-------+ +------+ / | \________ / | \ +--------+ +--------+ +--------+ | stand1 | | stand2 | | stand3 | +--------+ +--------+ +--------+ Support example: Examples/Objects/Table. In the example, we named the objects so that the name of an object described the purpose of it, to make the identification easier. If your model includes several objects of the same name, you can identify them according to the order you created them; the first object you created is the topmost in the select window. If you don't remember which one you created first, there is one further way to select primitives: a box containing the points of desired primitives. This operation pushes the points included in the drag box onto the vector stack of REAL 3D. If dragging was successful, you should see the points marked with a cross symbol. Then press , and selection happens. You can check which object is the active one by hitting key. The wireframe of the selected object will flash. In the next paragraph, we will modify the table in different ways so you can get some idea of REAL 3D's powerful hierarchical object oriented construction method. @endnode @node "T1.7" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.7 MODIFYING Now you already know how to use some modification functions. You also know that modifications are done to the selected objects. You can select any part of the table and modify it, regardless of the complexity of the modification. We can continue to modify the table of the previous example (You can load the file Project/Project/Replace Examples/Objects/Table). To move the brace of the table: 1. Select "brace". 2. Choose the menu Modify/Linear/Move and move the brace. To move the whole base: 3. Select "base". 4. Hit the key "m" (move) which is the default keyboard short-cut for Move function and move the base. If the table seems to be too high: 5. Select the whole "table". 6. Select Modify/Linear/Stretch, click on the top left corner of the table, then click on the bottom right corner of the table. Then move the mouse until the shape is desired. You can also rotate the table with the Modify/Linear/Rotate function, or change the size of it using Modify/Linear/Size function. The Mirror function inverts the object with respect to an axis defined by you. If the result of a modification was unexpected: - Select Extras/Undo or hit u key. - The Undo-function restores the situation to the situation before the latest action. Actually, the depth of undo buffer is 3 by default, so you can undo three steps backwards. It is possible to change the undo depth to other values using the Settings/Undo/Set depth function, but remember that the greater the value, the more memory is required. You can also relocate the table by choosing Modify/Linear/Move COG. This function moves the target to a given point using the so called COG point of the object (COG = Center of Gravity). Every primitive you create has some default value for COG. For example, the COG of a ball is its middle point. You can redefine the COG point by the function Modify/Properties/ COG. To move a stand of the table to the bottom left corner of the window: 1. Select a stand. 2. Choose Modify/Linear/Move COG. 3. Click the view near the desired place. 4. Move the pointer to the desired place and click the left button. To modify the color of the table cover: 1. Select the cover. 2. Open the palette window (p). 3. Select the palette window menu Project/Fetch. The color of the cover is read and displayed in the color square above the OK gadget. Also the RGB sliders are adjusted accordingly. 4. Modify the red component to 100 by moving the R-slider. 5. Click OK. This changes the current color. 6. Activate the view window and select Modify/Properties/Color. This writes the modified color back to the cover. Move, Rotate, Color and Stretch are functions which affect only the physical structure of the table. Next we turn to functions which change the hierarchical structure. In fact, you already know some, namely the Delete and Duplicate functions. The hierarchical structure of the table created in the previous example seems to be quite a logical one. The stands are a part of the base, but the cover is not. Anyway, you can move the parts of the table in the hierarchy tree, just as you can move files and directories in DOS to new directories. If you want to move the cover to be a part of the base: 1. Select "cover". 2. Choose Modify/Structure/Cut. 3. Double-click the level "base" on select window, so it becomes the current level. 4. Choose Modify/Structure/Paste. You have modified the hierarchy of your table to be as follows: Root table base stand1 stand2 brace cover If you don't want any part of the table to belong to the base: 1. Multi-select stand1, stand2, brace and cover. 2. Choose Modify/Structure/Cut. 3. Double-click the name "base" on top of the select window; the window changes the current level to be the parent level, "table". 4. Choose Modify/Structure/Paste. If you want to move the base now, you won't move any of the parts of the table. The base is now empty, and the structure of the table is quite peculiar. Root table stand1 stand2 brace cover base As a final example of modifying object hierarchy, we consider the use of two select windows. As it has been mentioned, each select window has its private current level, which becomes the global current level when you activate it. You can use this feature in the following way: 1. Open a second select window. 2. Set the current level of the original select window to "base". 3. Set the current level of the new select window to "table". 4. Activate the new select window. 5. Use Create/Visibles/Sphere to create a new primitive. It appears under "table" level in hierarchy. 6. Activate original select window and create another sphere. It appears under "base" in hierarchy. 7. Drag multi-select the objects under "table" using the new select window, which still displays those objects. 8. Select Modify/Hierarchy/Cut. 9. Activate the old select window. 10. Select Modify/Hierarchy/Paste. The objects are pasted under "base". As you see, you can use multiple select windows to quickly access different parts of the hierarchy. @endnode @node "T1.8" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.8 SAVING AND LOADING An object you have created, or any part of it, can be saved on disk and later be recalled to be used again. For example, to save the table you created before to the directory "Objects" of drawer R3D2: 1. Select "table". 2. Choose Project/Objects/Save. A device will then appear on the screen. With the file requester, you can define all the names and paths that REAL 3D needs to load and save data. In the device, you can see a DOS directory. Using the mouse, you can select any of the names moving in the directory tree until you have reached the directory you want. Then you can type the name to save the object with to the "File" field in the lower part of the device. Naturally, you can also select an existing file. In this case, the old contents of the file will be overwritten. Similarly , you can type any name in the file field with its directory path regardless of which directory is shown in the device. Continue saving with the following actions: 3. Click the drawer name "Objects" on the file selector, unless "Objects" is already displayed (check the drawer field). 4. REAL 3D already proposes the name "table" in the File field, so choose OK. In the same manner, you may want to insert the name and object "table" in a scene from the "Objects" directory of r3d2: 1. Make the object in which you want to insert the table (for example a garden furniture set) the current level. 2. Choose Project/Objects/Insert. 3. Select the drawer "objects" and the file "table" from the file requester and choose OK. If the object is found, it will become a part of the garden furniture set. The table is now the active object, so you can modify it in various ways, for example, move it to an appropriate location. Note: If you save on object to an existing file name, REAL 3D gives a warning to guard against mistaken overwriting, unless the Settings/General/ Confirm_save gadget is deactivated. The third entry in the Project/Objects menu: Replace, replaces the whole object hierarchy starting from root with the new one loaded from the disk. Where as Insert, inserts the loaded object to the old object structure. Most other IO menus include a similar group of three functions: Insert, Replace and Save. They work in a similar way: Save is for saving to disk, Insert adds new data to the current project, and Replace replaces the current data with the one loaded from disk. Note: REAL 3D binary format is an IFF type collection of different data sections. This means that a file can contain both objects and materials, but you can only load the objects from it using Objects/Replace or Insert. When replacing Projects, you can define the sections which you want replaced from the file. For example, if you Project/Project/Replace from a file which does not contain an environment section, you do not lose your current user interface definition. Also, you can specify which sections you want replaced by using Project/Project/Replace Sections. When you create objects, it is advisable to compose them of reasonable sub-objects, which can be saved to appropriate sub-directories. Although this means more work in the beginning, it does allow you to create libraries of reusable objects. @endnode @node "T1.9.1" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.9 VISIBLES The examples presented earlier already have explained how to create some basic visibles. The main classes of visibles are: - Flat planar visibles - Polygonal visibles - Cylinders - Cones - Ellipsoids - Hyperbolic visibles REAL 3D includes a variety of tools for creating these visibles. Also, tools for creating sector versions of most visibles are included. Thirdly, the so called compound tools combine visibles to obtain more complicated shapes. This chapter introduces some new visibles. The rest are described in the reference section. 1.9.1 Polygon/ Polyhedron/ Polymids With the polygon tool, you can create plane polygons. Use it in the following way: 1. Select Create/Visibles/Polygon. 2. Use the left mouse button to add new edge points when drawing a polygon. 3. You may undo the points one by one using key. 4. Right mouse button ends the function. 5. key cancels the function. Note that the edge curve of the polygon is closed automatically. Creating a polyhedron (extruded polygon) happens exactly in a similar way. Polymids are slightly different. A Polymid is a pyramid type of shape with a sharp top peak.A Cut polymid is the same shape with a cut top. Use the latter in the following way: 1. Select the menu Create/Visibles/Cut polymid. 2. First define the intersection shape of the object, in other words, the shape of the bottom plane of the object. You can do this in the same way as with the polygon tool. Use the right mouse button to end the shape definition. 3. Click the left mouse button in the position to which you want to place the first point of the polygon which forms the top cover of the object. 4. Now you can size the top cover by moving the mouse, and when the size is suitable, click the left button. @endnode @node "T1.9.2" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.9.2 Sector Visibles As an example of sector visibles, we will create a cylinder sector, which is an useful shape for say 3D pie charts. 1. Select Create/Sectors/Cylinder. 2. Click in the center point of the cylinder. 3. Move the mouse until the distance from the center point is correct. Also, the line which the function draws defines one side of the sector, so direct it accordingly. Then click again. 4. Now rotate the mouse counter clockwise until the sector angle is desired. Then click. @endnode @node "T1.10.1" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.10 COMPOUND TOOLS REAL 3D includes a set of special tools to ease creation of certain types of objects, such as objects turned in a lathe. Objects which consist of several primitives can be created fast and easily with these special tools. Compound tools have some advantages over freeform based creation methods: - They perform certain shape constructions very easily and quickly - They produce memory efficient models - Compound tool objects are fast to render - True volume representation is produced - Excellent rendering quality The disadvantage is the inherent geometric restrictions, although this is partly compensated for by the large number of different compound tools available. In the following, some compound tools are introduced. The rest work in quite a similar manner. Exact details can be found in the reference section of the manual. 1.10.1 Lathe To use the lathe tool: 1. Choose Create/Compound Tools/Lathe. 2. Define the direction of the axis of the lathe by selecting two spatial points with the mouse. 3. Then click the starting point and define the direction of the surface at that point by drawing a line segment. Click when the direction is suitable. 4. Now you can shape a curve. When the shape is suitable, click the left mouse button and shape the next curve. 5. If you want to make a sharp edge, use right mouse button to cancel the current curve shaping and then define the new direction. 6. Sometimes the smooth profile curve breaks because of precision problems in calculations. This can be avoided by defining the shape in shorter segments. 7. When the required shape has been defined, turning can be terminated by pressing the right mouse button twice. Figure @{"T1-10:" system "display dh9:docs/r3ddoc/r3dv2pics/T1-10"} Candlesticks turned in a lathe. (PICTURE: T1-10) @endnode @node "T1.10.2" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.10.2 Tube tools With the tube tools, you can create a continuous tube. The tools can be used, for example, for creating 3D fonts. The tube tools are divided into sub-classes according to the following properties: - Rounded edges/sharp edges ("rounded" option) - Constant radius/varying radius ("Conical" option) - Circular/rectangular intersection shape ("Circular/"Rectangular") - Automatic subdivision/no subdivision ("Subdivided" option) The tube tools use various primitives like cylinders, polyhedrons, and spheres to create the tube you define. For example, to use the rounded circular tube tool: 1. Choose Create/Compound Tools/Rounded Circular. 2. Define the diameter of the tube by shaping a circle. 3. Draw the tube in space as long as you want and then cut it with the button. As a second example of tube tools, we consider the Conical tube. With this tool it is possible to create spheres connected with cones. The result is a tube with a changing radius and rounded joints. For example, this tool is suitable for creating a robot finger. 1. Select Create/Compound Tools/Conical 2. Shape as many circles as needed. These circles define the joints of a finger. 3. End the joint definition by clicking the button. If you try the same with Conical Subdivided tube tool, you get more joints and smoother result. Try the previous example with the subdivision factor 5, just to see the difference. Figure @{"T1-11:" system "display dh9:docs/r3ddoc/r3dv2pics/T1-11"} The Tube Tools. (PICTURE: T1-11) Top row: (IN PICTURE) Circular Subdivided, Rounded Circular Subdivided, Sharp Circular, Rounded Circular. Second row: (IN PICTURE) Conical, Conical Subdivided. Bottom row: (IN PICTURE) Rectangular, Rectangular Subdivided, Rectangular Conical, Rectangular Conical Subdivided. @endnode @node "T1.10.4" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.10.3 Rounded Polygons and Polyhedrons Compound tools include functions for creating polygons and polyhedrons with rounded corners. They are handy for example for logotype creation. You can use all the four tools in a similar way as when you created the polygon, but the tool automatically rounds the corners. "Rounded" tools use fixed maximal rounding radius, whereas "Ellipsed" tools round the corners all the way to the middle of each edge. The following figure shows example shapes created with the tools. Figure @{"T1-12:" system "display dh9:docs/r3ddoc/r3dv2pics/T1-12"} Rounded Polyhedron (left) and Ellipsed Polyhedron (right). (PICTURE: T1-12) 1.10.4 Object-Pixel Tool The object-pixel tool is a very powerful link between two and three dimensional computer graphics. The idea is to easily and quickly obtain complex 3D solid objects by replacing the two dimensional pixels of a picture with some three dimensional objects, such as spheres. When using the pixel tool, the user can define which object replaces the pixels. Only the pixels which have some other color than the background color (color 0) are replaced, and the colors of objects created are the same as the colors of the pixels. With 24 bit and HAM images, all the pixels are replaced. For example, you can create 3D text using the usual 2D fonts. There is a wide variety of different fonts available, and furthermore, there are an infinite number of ways to define the object with which the pixels are replaced. For the creative user, pixel tool offers an excellent method to produce 3D pictures and animations. It is especially handy for producing particle groups for particle animations (text which is exploding etc.). To create text with the pixel tool: 1. Start a paint program, choose a suitable font, write the word "Real", define a brush containing the word and then save the brush for example, to the RAM disk. 2. Create, for example, a small sphere in REAL 3D. Make sure that it is selected. 3. Choose Create/Compound Tools/Object-Pixel Tool. Now the file selector is displayed, and you can select the brush you saved to ram disk. 4. Next, you can define the size and location of the object which will be created by shaping a rectangle in a view window. 5. When the object is created, you probably don't need the original sphere any longer, so delete it. Figure @{"T1-13:" system "display dh9:docs/r3ddoc/r3dv2pics/T1-13"} Text Created with Object-Pixel Tool. (PICTURE: T1-13) Note: Pixel tool tends to create a "heavy" object. For example, in a paint program a brush of 30 times 30 pixels looks very small, but it includes 900 pixels. A slightly larger brush, say 80 times 80 pixels, includes 6400 pixels already. This may lead to memory problems. @endnode @node "T1.11" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.11 LIGHT SOURCES A light source is a primitive which radiates light of its own color. If the primitive is black, it does not radiate light at all. A white object radiates all the main components (R,G,B) of light in the same amounts. In real life, it is usually very difficult to observe objects in lighting which has only one wavelength. Also, there is not any material which would reflect only one wavelength . In REAL 3D, all this is possible, so you should be careful when selecting the colors of light sources. For example, a totally red object is not visible at all under blue lighting, because a red object does not reflect any blue light. A violet object looks red under yellow lighting. Usually, it is advisable to create white light sources, so all objects will be rendered in their "true" colors. Although the number of light sources is unlimited, they should not be used indiscriminately. The time taken by rendering is greatly dependent on the number of light sources. In the next example, we will test different light sources. The example includes a cylinder floating above a rectangle (floor), and two light sources casting shadows onto the floor. 1. Reset the view window by activating it and then pressing e. 2. Take a top view by hitting z. 3. Create a rectangle (Create/Visibles/Rectangle), almost filling the whole view. 4. Create a cylinder (Create/Visibles/Cylinder) to the middle of the rectangle. 5. Select a suitable current color for the light sources using palette window. Pure white (255,255,255) is a good choice. 6. Choose Create/Light-sources/Point and click on the left side of the cylinder. 7. Choose Create/Light-sources/Wall and shape a small square to the right side of the cylinder. 8. Go back to front view by hitting x. 9. All the objects lie at the same level. Select the rectangle and move it to the bottom, select cylinder and move it above the rectangle. Select the light sources and move them well above the cylinder. 10. Hit s to get the Render settings requester. When it opens, set Mode to Normal and click OK. 11. Adjust the viewing angle with the cursor keys and hit r to render. Now you should see the shadows of the cylinder on the floor. The edges of the shadows from both lights appear both to be sharp. Do this to see a soft shadow: 12. Open render setting requester again (you can do it while the program is still rendering!) and adjust the Lightsamples slider at the right side of the requester to the value one. Then hit OK. 13. Hit r to re-render the view. Support example: Examples/Objects/lightsources This time, one of the shadows has a smooth edge. Rendering is much slower (about 4 times), but probably the extra realism is worth the time penalty. You can adjust the size of the smooth area on the shadow edge by increasing the size of the wall light source. Nevertheless, you may then have to increase Lightsamples level respectively, which again slows down the rendering. So, the smoother the shadows, the more calculations and rendering time is required. Figure @{"T1-14:" system "display dh9:docs/r3ddoc/r3dv2pics/T1-14"} Light Source Test Scene (PICTURE: T1-14) @endnode @node "T1.11.1" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.11.1 The Brightness of Light Sources When you create light sources, you don't have to worry about their brightness; the program will scale their intensities to a suitable level, and fine tuning can be done by settings of the solid model. You can set the relative brightness of various light sources by giving them suitable colors. A lamp having lower values for RGB components has a lower light intensity than a lamp which has higher RGB values. These differences will be preserved in automatic scaling. The automatic scaling of light intensities can be thought of as being analogous to the automatic exposure functions of a camera, where the exposure level is based on the overall brightness of the picture. Notice that if you position a light source near an object, there will be a great difference in light level (in other words contrast is high). If you illuminate the object from a distance, the light falling on the object will be much more evenly distributed. A good example of this phenomenon is the comparison of sunlight and lamp light. If you place a lamp near an object to act as a spot light, and another further away to give ambient light, the latter should have much higher intensity than the former to produce any visible effect. Light sources don't show directly in shaded pictures. So, if you want to see lamps or reflections of the light source on reflecting surfaces, you must put a cover made of, say, matt glass around the light source. This is just like in the real world! You may find it useful to save some suitable light sources as objects to disk so light sources can be brought to use as the need arises. Nevertheless, if you want to produce a ray traced picture of an object, you don't always have to create light sources. The rendering unit of REAL 3D includes some fast ray tracing modes in which one light source is created automatically. For more information, see the chapter on Rendering. @endnode @node "T1.12" @title "Chapter 1 OBJECT CREATION & MODIFICATION" 1.12 MACROS The macro facility, an important feature of REAL 3D, is very useful when you must execute the same modifying operations to a large number of objects. A macro is a series of modification operations which the user can define to best suit his/her needs. Macros can be stored to hard disk, bound to keyboard short-cuts, and made into tool window icons. They can later be executed on any object. Macro definition is started by the operation Record. The current macro, usually automatically stored as t:macro.rpl, is deleted. After this, all these new operations are stored in the t:macro.rpl file. These operations include all functions of Modify/Linear, Modify/Structure, and Modify/Bend functions. When the macro has been fully defined, the recording is stopped by selecting Record again. An example of macro definition: 1. Create an object. 2. Choose Project/Macros/Record. A checkmark will appear in the menu showing that macro recording is active. 3. Flatten the object with the Stretch function. 4. Rotate the object with the Rotate function. 5. Move the object with the Move function. 6. Choose Projects/Macro/Record again. Now you have defined a macro which consists of three modifying operations. To execute the macro: 1. Select the object to modify. 2. Choose Project/Macros/Execute Current. If you want to execute the macro 20 times: 1. Select the object to modify. 2. Choose Project/Macros/Repeat Current. 3. Type 20 into the requester, then click OK. This is a very powerful method for creating symmetrical objects. As an example, let us create a set of ball bearings: 1. Create a sphere with a suitable size and place it near the top of the view window. 2. Select menu Project/Macro/Record. 3. Modify/Structure/Duplicate the sphere. 4. Modify/Linear/Rotate the sphere around the center point of the view. 5. Select menu Project/Macros/Record. 6. Select menu Project/Macros/Repeat Current. 7. Estimate the number of spheres needed to form the entire ball bearing and enter this value. Figure @{"T1-15:" system "display dh9:docs/r3ddoc/r3dv2pics/T1-15"} Ball Bearing Macro (PICTURE: T1-15) Spread macro is another useful macro feature. It spreads the macro over the selected objects, incrementing the number of macro repetitions by one after processing each selected object. Try the following with the spheres you created in the example above: 1. Multi-select all the spheres. 2. Select Modify/Linear/Move COG, and click twice in the middle of the view. The result is that all the spheres are collected to the same position. 3. Select Project/Macro/Record. 4. Still having all the spheres multi-selected, move the spheres to the right, half the diameter of a sphere. 5. Select Project/Macro/Record to end the macro. 6. Select Project/Macro/Spread Current. If you repeated the steps correctly, you got a horizontal row of spheres. You can save the macro by using Project/Macros/Current to Named function (or by copying/renaming t:macro.rpl with a suitable name). Current macro is just an ascii file stored in system t: directory. It is a small RPL program, and you can edit it with any text editor. You can also pick any RPL program/macro and execute it using the menu Project/Macro/Execute Named. There is also Named_to_Current function, which makes a given macro the current one, so you can use it with the repeat and spread functions. @endnode @node "T2.1" @title "Chapter 2 THE ENVIRONMENT" Chapter 2 THE ENVIRONMENT ------------------------- 2.1 ASYNCHRONOUS ACTION REAL 3D makes extensive use of the Amiga multitasking operating system. This helps make using the software more comfortable, faster, and consequently more productive. The user interface is designed using the "zero wait state" principle: even if the user starts a time consuming process, the program continues to monitor the users actions and gives immediate responses. In REAL 3D, this happens by the asynchronous execution of multiple tasks. The following test demonstrates this: 1. Use Create/Compound tools/Circular subdivided to create a tube; use at least 10 clicks to define the tube shape and use 10 subdivisions. This should create a rather complex object. 2. Activate a view and select View/Render/Window. The program starts shading the window. 3. Now immediately select another creation function; create a sphere, and start shaping it in the view which is still rendering. It is possible to initiate new tasks even though the program is redrawing the window. Another useful test can be opening more views and then selecting Extras/Refresh All/Ray Trace: Views are rendered independently of each other. If you try Modify/Linear/Move to move the tube, you will see another zero wait state feature: even though the wireframe is complex, REAL 3D responds to your mouse moves easily. Note that certain functions can momentarily block your actions. For example, IO functions (saving and loading). Secondly, modal requesters, such as render and drawing settings block the view where they are opened, but other windows are still fully available. For example, if you are defining the render settings for a View window and you need to open the Palette window, activate a Select window and open the Palette window from it. One very useful technique which utilizes asynchronous action is material editing. When testing materials, you can open a material window, edit a material, and then activate the rendering of a view without closing the material editor. While the rendering proceeds, you can edit the material library and restart the rendering as soon as the changes are made. Especially useful is the technique using "Box" rendering (see the chapter "Rendering") where you can very quickly and interactively test critical materials in their correct environments. @endnode @node "T2.2" @title "Chapter 2 THE ENVIRONMENT" 2.2 SCREENS REAL 3D supports all Amiga display modes for the user interface display. If you select the menu Project/Environment/Open screen, a requester is displayed which will include the, display modes which are supported by your workstation. You can adjust your display with the folloWing options: The Color gadget slider allows you to select the number of colors to be used for the screen display. The minimum value 1 allows two colors, and the current maximum value of 8 allows 256 (or more in HAM) colors. The greater the depth, the more chip memory the display requires. Also the display updating slows as the screen depth increases, but on the other hand, shading quality is improved. Width and Height gadgets define the size of the screen in pixels. When you select a screen mode, the dimensions are updated automatically to the system default values, but you can modify them freely. If you specify larger than default dimensions, a virtual screen is automatically opened. You can also give a name to the screen you open. The name can be used for example in the Animation window when rendering animations; you can specify which screen should be saved using the name. Furthermore, the HAM gadget and overscan selectors are included. Note that not all the mode combinations are possible at the same time. You will get an error message if a mode is incompatible. REAL 3D can operate on multiple screens simultaneously. The user can freely create a multiple screen configuration. For example, you can have a HAM screen open for color shading and a fast four color HIRES screen for editing, with the ability to easily jump between them. You can edit the screen palette using the Environment/Screen Palette function. The palette requester includes two built-in palette options: grey scale and color scale palettes. They are both optimized for ray trace rendering, but you can adjust them slightly without loosing shading quality. Also, you can re-arrange the order of the colors freely. Ray trace shading with color scale palette on non-HAM screens works properly only if the screen depth is at least 6 (AGA machines). If you use the color palette, you have to activate the Render settings/Color shading menu function in order to get proper results. You can change certain screen properties using the screen window of REAL 3D; for further details, see the reference manual. @endnode @node "T2.3.1" @title "Chapter 2 THE ENVIRONMENT" 2.3 VIEW WINDOWS The main purpose of the View window is visualization (seeing) the properties and the shapes of the models created by the user. Secondly, Views input coordinate data from the mouse in an intuitive way, making it easy to construct and modify objects. The whole modelling process can also be entered using written instructions in a RPL window, but the approach is much less intuitive. Using RPL written input can provide you with exact modelling precision if need be. REAL 3D supports a variety of different Amiga window types including borderless and superbitmap windows. Their usage is not restricted; the environment can be freely configured according to your personal preferences. Some suggestions: - The borderless window, because it fill the whole screen, is often used for the final rendering of animations. - The superbitmap window can be used for rendering selected parts from the scene, only the visible part of the window is shaded at once. - The window borders of normal Views can be removed using Project/Windows/ No Gadgets function. This gives more work space. 2.3.1 Projection Types For each View window, you can define the so called projection type. This type defines how the shape of the model is rendered to the window. If the type is Parallel, the scene is drawn as if it was seen from an infinite distance. When using this projection, you cannot see any perspectivity in objects, and visualizing the depth direction (the direction from your "eyes" toward the objects) can be more difficult than when using the perspective projection. Nevertheless, accurate modelling is easier. For example, a front view of a cube in parallel projection is a rectangle, and it is easy to align other objects with the sides of the cube regardless of their positions in the depth direction. If the type is Perspective, the objects can be seen in a natural perspective way which corresponds to normal cameras. In this projection, the View window area corresponds to the film in the camera; the film is perpendicular to the line from the camera to the point of focus of the camera. The perspective projection may be more appropriate in intuitive, less accurate modelling such as creating compositions from the camera view. It is normally used when the final images are rendered. Note that the rendering engine supports the rendering of both types of projections; the parallel projection the faster of the two to render. @endnode @node "T2.3.2" @title "Chapter 2 THE ENVIRONMENT" 2.3.2 Input &Output Planes The term "output plane" means the image plane to which the rendering algorithms project the shape of the model. You can consider the rectangular surface of the View window to be this plane; it is always perpendicular to the direction you are looking at through the View window in question. Each View window has its own private output plane definition, which can be also described as the "internal camera" definition of the View. This is presented in more detail in the next chapter @{"2.3.3" link "T2.3.3"}. The term "input plane" means the plane in which the mouse coordinates run. For example, the input plane can be the XZ plane passing through the origin (the normal horizontal "ground" surface). When you move the mouse, the Y coordinate remains zero, and only X and Z vary. An intuitive way to describe this is: if an object is lying on the ground and the ground is the input plane (please forget the fact that the earth is actually spherical), you cannot lift an object above the ground by applying the Move function. You can just slide the object along the ground. The input and output planes can be the same or separate planes. In the previous "ground surface" example, the input and output planes coincide when you look at the ground directly from above or from below. But you can also use a perspective arbitrary view (perhaps the final camera view) while moving the object along the ground surface. Normally, both planes are automatically connected to each other so that when you adjust one (e.g. using cursor keys), the other follows. The following example shows how to disconnect them. 1. Activate the View, hit e and click in the middle of the View to move the hot-point (set by mouse click) near the origin. The hot- point will define the third "depth direction" coordinate of the input plane. 2. Select View/Drawing_Set, activate the "Abs Grid" gadget and select OK. This shows a grid pattern on the horizontal XZ plane, which is helpful when doing perspective modelling. 3. Hit z to get the top view. x, y, and z hot keys always set both planes to the same position. 4. Select Create/Visibles/Cube and create a cube. 5. Select View/Type/Perspective. Then select the View/Type/Separate IO menu. 6. Now use the cursor keys to adjust the View angle so that it is no longer directly from above. The output plane is rotated but the input plane remains unaltered. 7. Select Modify/Linear/Move, grab the cube and move it. The cube moves in the XZ plane and you see it growing when it comes nearer to the camera position. Figure @{"T2-1:" system "display dh9:docs/r3ddoc/r3dv2pics/T2-1"} Separate IO (PICTURE: T2-1) The x, y, and z keyboard shortcuts set the input and output planes parallel to the absolute space axes, regardless if the Separate IO is selected or not. Cursor keys rotate and move the output plane only when the Separate IO is used. As it was already mentioned, the hot-point "+" which you can set by mouse clicks, also plays a role in the View IO system: the input plane always goes through that point. The input plane can be defined using the local coordinate systems of the objects. This enables you to edit the objects in their natural orientation. For example, if you want to stretch a cube which has been rotated several times and you stretch it in the absolute space orientation, the shape of the cube becomes distorted. To get a controlled modification, you have to set the input plane parallel to one side of the cube. The input plane can be set to the object coordinate system by using the function View/Input Crd./Obj. Space to View. To get the full advantage of this feature, it is recommended that you add a reference coordinate system to objects when originally creating them. Using the default orientation of the compound or freeform objects may not be accurate enough. The following example demonstrates this: 1. Create a level called "house" and add a cube (walls) and a triangular polyhedron (roof) under the house level to represent a simplified shape of a house. 2. Select Create/Controls/Coordsys, click in the middle of the house and shape a coordinate system primitive: set the three directions of the coordsys primitive parallel to the walls of the cube and press . If the coordinate system directions do not match the wall directions perfectly, adjust the coordsys using Modify/Linear/Rotate. 3. Now rotate the whole house to an arbitrary angle using Modify/Linear/ Rotate. Change the View angle using the cursor keys and rotate it again to make its orientation irregular. 4. Go back to the front view using x. Now the problem is how to make the house higher or wider? The solution is: 5. Select the coordsys primitive and select View/Input Crd./ Obj. Space to View. The view orientation is changed so that editing the house becomes easy using the e.g. Modify/Linear/Stretch function. @endnode @node "T2.3.3" @title "Chapter 2 THE ENVIRONMENT" 2.3.3 View Coordinates & Cameras Every View window includes a description of its internal camera system. This camera information includes the following items: - The position of the camera (viewpoint) - The point at which the camera is aimed (aimpoint) - The camera tilt angle - The scale factor (the angle of the lens) - Two depth of field factors. The View displays the objects according to this information. The depth of field information becomes relevant only when the scene is rendered using ray tracing. The camera information can be stored to the object hierarchy tree by creating a camera object. This makes it possible to animate the camera as any other object, for example: morph between key positions and attributes of the camera. The camera object can be created using the menu View/Camera/Create Camera. This function creates a new level, and puts two primitives, an aimpoint and a viewpoint, under it. They together include all the camera information, and the currently displayed situation on the view is stored to them. The camera object consists of two primitives in order to allow easy tracking of animated objects. For example, if the viewpoint primitive is placed in a moving car and the aimpoint primitive is in an airplane, the camera automatically follows the airplane regardless of the complexity of the motions involved. The purpose of the aimpoint is to define where the camera aims. It is very easy to move the aimpoint to any desired point in the scene and redirect the camera that way. Secondly, the distance from the viewpoint to the aimpoint defines the focal length of the camera in the depth of field rendering effect: objects near the aimpoint (and at a similar distance in general) are sharper in the image. The viewpoint primitive contains the rest of the camera information. For example, by rotating the viewpoint, you can adjust the tilt angle. As it was mentioned, every View window contains a full camera description internally. You can use the camera object consisting of the aimpoint and the viewpoint to store a suitable viewing angle more permanently. The following example demonstrates this: 1. Hit x to get a front view, and use Create/Visibles/Cube to create a cube (just something to look at). 2. Use the cursor keys to find a suitable viewing angle. 3. Select View/Camera/Create Camera. The carefully selected camera position becomes safely stored. 4. Hit z to get the top view, and create another cube. 5. Select View/Camera/Camera->View. You see the camera view again. 6. Adjust the view angle slightly using the cursor keys and "record" the adjustments to the camera object using View/Camera/View->Camera. This way, you can take the camera information from a camera object, modify it in the View and put it back. You can adjust the camera settings visually and interactively through the View. It is also possible to create multiple cameras. This feature can be used in the following ways: - You can store several "important" camera positions to multiple cameras making it possible to quickly check the scene from those critical positions during the model creation. - Multiple cameras are needed when animating the camera using the morphing method. - When designing your animation, it is possible to "take" from one camera position to the next similar to directing an actual movie set. When you want to take a particular camera view and you have multiple cameras, you can specify which one to use by selecting it and then selecting the menu View/Camera/Camera->View. When playing and rendering animations, it is sometimes necessary to specify, whether a View should follow motions of an animated camera or not. If you are using a camera object, it is useful to play the animation from such a point of view that the motions of the camera itself can be seen. Therefore, automatically taking the camera view during the animation play is not always appropriate. You can select the automatic usage of the camera view during animation play by selecting the toggle menu View/Camera/Camera View function. This selection is private for each View window: one View can follow the camera, while another one shows the animation from a fixed position. If you are using multiple cameras, you can specify which one to use in each window during an animation play from the camera view by adding the tag "SWND windowname" to viewpoints and aimpoints. Each window checks the hierarchy tree and chooses the first view-point and aimpoint it finds. The SWND tag makes the view or aimpoint window specific. NOTE: The Camera View function is used only during the animation play. It does NOT connect a camera object to the View so that the camera object follows cursor key adjustments. Instead, use the View->Camera function to store the adjustments to the camera. @endnode @node "T2.3.4" @title "Chapter 2 THE ENVIRONMENT" 2.3.4 Zooming and Positioning the View The visible contents of a View window, in addition to the camera position and orientation, also depend on the scale factor of the View. The scale defines the "lens angle" of the camera; it is a certain kind of a magnification factor. The bigger the scale, the bigger the objects appear on the display and the smaller part you can see of the total scene. Defining a small scale factor corresponds to using a fish-eye lens: the camera angle is wide, and a big part of the scene fits into the View even if the camera is close to the objects under observation. Note that in perspective View windows, the size in which the objects appear on the display, depends on two factors: - The scale - The distance from the camera to the objects There are no other factors involved. So, if you try to find a good camera angle in an interior room scene and the objects do not fit well into the picture, resizing the room does not help. The problem could be best solved by moving the camera and/or changing the scale. This is the same as real world situations. The camera distance does not matter at all on parallel projection Views. The scale alone defines the object magnification. To change the scale: 1. If you intend to enlarge an object on a View, choose the operation View/Display/Pos&Zoom In. 2. Then move the mouse pointer to that part of the View you want to enlarge. When you press the left mouse button, you can draw a rectangle on the screen. The region inside the rectangle will be enlarged so that it takes up the whole window. You can reduce the scale by choosing the operation View/Display/Pos&Zoom Out. Then you can define a rectangle that will, after reduction, contain that part of the space that is visible on the View when the operation was started. A quick way to change the scale is to use the - and + keys which correspond to the Zoom In and Zoom Out functions. Using the Position operation you can change the position of the windows in space. You can, for example, observe in detail an object that is on the edge of the space. To move a View window in space: 1. Choose menu View/Display/Position. 2. Grab an object and move it to any place you want. Instead of moving the object, REAL 3D moves the window so that the object will show in a different part of the window. The auto focus function offers a fast way to position and scale the View around the selected objects: 1. Select the desired objects. 2. Select View/Display/Auto Focus. The active View window will be centered around the objects, and the scale is modified so that the objects fill the window. If you want to reset the scale and the position of the View to the default values: 1. Choose View/Display/Reset or hit e keys. @endnode @node "T2.4.1" @title "Chapter 2 THE ENVIRONMENT" 2.4 WIREFRAME DRAWING SPEED The asynchronous design of REAL 3D normally means that the user does not have to pay much attention to wireframe refreshing of the View windows. In some extreme cases with very complicated wireframes, it may be necessary to control screen updates in order to obtain more speed. 2.4.1 Bounding Boxes When modifying objects, it is possible to use the Bounding Box representation instead of accurate wireframe drawing. You can select this method using the Modify/Draw mode menu. When the bounding box representation is selected and you select an object modification function, as soon as you click on a View, REAL 3D constructs a box shape around each selected object and uses the boxes to show the effect of the modification. The bounding box representation may be suitable e.g. when resizing a complex object; the new size can be seen immediately from the box shape, without the possible redrawing delays. 2.4.2 Refresh Modes You can speed up screen updates by choosing menu Settings/Refresh/Current. Then the program updates only the active View window. If the previous technique is not fast enough, select Settings/Refresh/ None. Then the program does not update at all. Settings/Refresh/All turns the normal automatic updating on. 2.4.3 The Visible Range of the Objects Often it is unnecessary to have objects drawn on the screen other than the object you are creating. For example, if you are creating a rocking chair inside a house, it is of no use to draw the house all the time. The house should be drawn only when the rocking chair is ready and can be positioned in the living room. In REAL 3D, you are able to allow only a portion of the object to be drawn which can be useful when creating complex scenes. The visible range of an object can be defined in relation to the current level. You can define the number of the parent levels of the current level to be drawn using the Settings/Oper. Level/Depth function, and by selecting Settings/Oper. Level/Active menu. If the Active toggle is unset, the whole project is drawn to the screen regardless of which level is the current one. If the Active toggle is set and the Depth is 0, only objects under the current level are drawn. 2.4.4 Other Methods - Using lower screen depth, for example 2 instead of 4, may speed up screen refreshing considerably. - Drawing speed of B-Spline objects can be adjusted using the View/ Drawing_Set function. The lower the Surface and Curve subdivision, the faster the updating. Control Polygon representation without Knots and Curves is the fastest method. - You can make individual objects invisible using the WF-invisible gadget of the Modify/Properties/Attributes function. If it is important to see some wireframe, add a visible cube with a suitable size to the same level and make it RT-invisible. Then it shows the size and the location of the invisible object quickly, but the "cube" is not visible when test rendering. @endnode @node "T2.5" @title "Chapter 2 THE ENVIRONMENT" 2.5 THE MEASURING WINDOW The measuring window can be used to substitute for the mouse or for numerical input when accurate control is required. The window displays the mouse coordinates of the active View. The measuring windows input fields can modify the coordinates. The coordinates can be expressed using the following alternatives: - Hot-point or absolute space origin related coordinates. - Input-plane oriented or absolute space oriented coordinate directions. - Polar or normal 3D coordinates. Furthermore, the measuring unit can be specified to be meters, millimetres, inches etc. The following examples demonstrate how to use the measuring window. Open a View window and a measuring window: To create a square rectangle: 1. Activate the View and hit e to reset it. 2. Select Create/Visibles/Rectangle. 3. Activate the X gadget of the measuring window, enter 0 and hit . Then activate the Y gadget, enter 0 and hit . Leave Z as it is. 4. Press the ACCEPT gadget. 5. Activate the X gadget again, enter 0.8 and hit . Then activate the Y gadget, enter 0.8 and hit . You should see the rectangle on the display. 6. If the size of the rectangle is not suitable, re-enter the X and Y values. 7. Press ACCEPT to create the rectangle. To move the rectangle 0.2 units to the X direction and 0.3 units to the Z direction: 1. Select the rectangle and select Modify/Linear/Move. 2. Activate the "Hot-P" gadget of the measuring window. 3. Press the ACCEPT gadget to "grab" the rectangle. 4. Enter X = 0.2, Y = 0, Z = 0.3. Every time you enter a new value, you see the rectangle moving. 5. Press ACCEPT To create a cylinder sector of 45 degrees: 1. Activate the "Origin" and "Polar" gadgets. 2. Select Create/Sectors/Cylinder. 3. Enter X = 0, Y = 0 , Z = 0, and press ACCEPT. 4. Enter X = 0,Y = 0,Z = 2 and press ACCEPT. 5. Enter X = 45, Y = 0 , Z = 2. By modifying Z and N values, you can adjust the size and the depth of the sector. X defines the angle. 6. When the sector is suitable, press ACCEPT. To rotate the cylinder 1 5 degrees around its center: 1. Activate the "Origin", "I-Plane" and "Polar" gadgets. 2. Select the sector and select Modify/Linear/Rotate. 3. click in the center of the cylinder. 4. Press down and click directly to the right of the sector center. Keeping the down when pressing defines a new coordinate but leaves the hot-point unaltered. This is necessary to measure the rotation around the sector center 5. Now use the measuring window: enter the angle to the X gadget. When the angle is suitable, hit ACCEPT. As you see, it is possible to swap from the normal mouse input to the measuring system input. If you want to start using the mouse again while executing a function, activate the View by clicking its title bar. @endnode @node "T2.6" @title "Chapter 2 THE ENVIRONMENT" 2.6 GRIDS The grid function of REAL 3D rounds the mouse coordinates to a desired grid. The grid system is based on a set of grids, of which one is the so called current grid. The current grid can be "activated" so that the coordinates snap to it, and it can be made visible. The number of grids is not limited, and the current grid collection can be edited and expanded freely. If you do not know the grid function yet, experiment with it in the following way: 1. Activate a View window and hit e to reset it. 2. Select Create/Visibles/Rectangle and shape a rectangle. Observe that you can freely control the size of the rectangle. 3. Select the View/Grid/Snap to Grid toggle menu. 4. Create another rectangle. This time the shape of the rectangle can be defined only in grid units. 5. Create a third rectangle beside the second one. Observe how easy it is to match one edge of the new rectangle with an edge of the second rectangle. 6. Select View/Grid/Visible. When you create new rectangles, it is easy to align them with the previous ones because you can follow the visible grid lines. In the previous example, the internal default grid of 0.1 units was used. You can specify another grid by using the View/Grid/Select function: it allows you to pick a grid from the current grid collection. This grid collection can be loaded, saved, or replaced using the Project/Project/ Load Sections, Save Sections or Replace sections functions and by selecting the "Grids" gadget in the sections requester. You can also save a suitable grid collection as a part of your working environment by using Project/Project/Save Sections (e.g. to s:real-startup) and by including "Grids" to the selected sections. You can create a new grid using the menu View/Grid/Create. The most important definitions are the "Name" and the three "Grid" gadgets, which Specify the lengths of the grid units. It is good idea to name the grids according to the grid unit sizes, so that selecting them using the name is easy. You can also specify the grid origin. The visible grid plane position, size, color and line pattern can be controlled. The default pattern 65535 corresponds to a solid line, 21845 gives a dense dotted line and 4369 gives a less dense dotted line. Grids can be modified using the View/Grid/Modify function and individual grids can be deleted using the View/Grid/Delete function. @endnode @node "T2.7.1" @title "Chapter 2 THE ENVIRONMENT" 2.7 THE UNDO FUNCTION The undo function can be used to restore the situation before the latest action affecting the object structure. The undo depth can be specified using Settings/Undo depth function; if the depth is greater than one, you can restore the state of the scene several steps earlier. After restoring the earliest state included in the undo buffer, the undo function jumps back to the current situation. This means that you can safely step through the undo buffer, because it works as a closed loop. To use the undo feature, select Extras/Undo or hit the U keys. Note that Project/New function clears the undo buffer, thus deleting its contents permanently. Undo stores only the object data structure. You cannot undo e.g. window closing or material modifications. You can use undo to restore an animation to its original state after the playback. This is handy when creating particle animations, which cannot be "rewound". 2.7.1 Undo and Memory Management There are some tricks which can be helpful when meeting memory problems. If the program does not execute a selected function, but gives a message "NOT ENOUGH MEMORY", it is recommended that the scene is saved before further actions. Deactivating the undo feature using the Settings/Undo/Active menu usually helps with low memory problems. You may also define a lower undo depth, for example 1 instead of the default 3 steps. Note: If your scene causes memory problems while editing, it is almost certain that you cannot render shaded images of it. @endnode @node "T2.8" @title "Chapter 2 THE ENVIRONMENT" 2.8 VECTOR STACK The Vector stack of REAL 3D is a general purpose storage for 3D vectors. Many built-in functions use it in their operation, and you can use the vectors stack for storing and manipulating coordinate data for all kinds of modelling purposes. REAL 3D includes a menu based "3D-calculator", which can do vector subtraction, addition and other useful operations. It uses the vector stack to store the parameters and results of such operations. You can store 3D coordinates to the vector stack by entering the coordinates from the keyboard or by using mouse operations. The coordinates can be modified and combined using the vector operations and later when creating or modifying objects, you can pick vectors from the stack, instead of using clicks. The following example demonstrate using the vector stack. An example: creating a polygon using information from existing objects 1. Create two objects, a sphere and a rectangle. The purpose is to create a triangle from the middle of the sphere to the middle of one side of the rectangle and to a given 3D point (1,1,0.5). 2. Press down and drag a box (keep down and move the mouse, so that REAL 3D displays a dotted-line rectangle) around the sphere. A set of crosses should appear on the View. These crosses show the current contents of the vector stack. 3. Select Extras/Vectors/Average All. This operation calculates an average of all the vectors in the stack. The vectors are removed from the stack and the result (the average) is pushed to the stack. So, only one cross is left in the middle of the sphere. 4. another box around the two points of an edge of the rectangle. Two more vectors are pushed to the stack. 5. Select Extras/Vectors/Average. This operation replaces the two topmost vectors in the stack with their average. So, the result is that the middle point of the rectangle edge is put into the stack. 6. Now the stack contains two vectors, and we enter the third one from the keyboard: select Extras/Vectors/Enter and type the coordinates 1, 1 and 0.5 to the three fields of the numeric requester. 7. Select Create/Visible/Polygon. Instead of using , select three times Extras/Vectors/Pull (or hit.), and then use to finish the polygon. If the View window was not active when you selected the Polygon function, activate it with a click on the title bar, so that the creation is started. If it is a borderless View, you can activate it with a click and then undo the first point with the key. In some cases, you just have to activate the View first and then select the creation function. @endnode @node "T3.1.1" @title "Chapter 3 MATERIALS" Chapter 3 MATERIALS ------------------- 3.1 USING MATERIALS 3.1.1 General Information When creating photorealistic images and animations, it is necessary not only to create complex shapes, but to simulate different real world material properties. REAL 3D includes excellent tools for this purpose. REAL 3D represents objects as solids whose physical properties can be defined using materials. Materials contain information about molecular surface structure, colouring, and optical properties. Basic material properties can be adjusted easily using slider gadgets. More accurate control over properties can be achieved using so called texture maps, which are bitmap images whose colors can be used to define object surface colouring and other material properties. Mathematical textures, which are mathematical formulas that define desired properties, are also used. Since mathematical textures can be expressed as RPL programs or user-defined formulas, there are again unlimited possibilities to enhance and expand the built-in material features of REAL 3D. Many advanced material features of REAL 3D utilize the solid modelling principle of the program. Correct light refraction evaluation and non- homogenous materials, such as gas clouds with a desired spatial density distribution, are good examples. When working with REAL 3D, you store the materials you may need in a material library, which is a memory resident collection of individual materials. A material is a collection of information which defines the characteristics of a real world material such as wood, glass, steel, marble, water, etc. You can manipulate the material library in many different ways: you can delete materials from it, empty it, load an old library from disk and join it to the current one, save the library , and last but not least, create brand new materials using the material editor , and add them to the library. When you want to use a material for an object in your scene, you create a new object in the hierarchy. This new "material" object acts as a reference to one of the materials in the library, and at the same time, defines certain geometric properties which are used in the precise placement of the texture (material object) on the object (target solid object) when texture mapping. This new material reference object is called the mapping object. All the objects in the same hierarchy level with the mapping object are affected by the material to which the mapping refers. So, the principle is to have a library of materials and to use the hierarchy tree to combine shapes with materials. For example, to model a wooden candlestick, you first add the material wood to the material library, then create a level "Wooden-Stick", and under that level you place the stick shape object and the wood mapping object. You can interpret this so that the wooden stick consists of stick and wood, shape and the material. Natural, isn't it! WoodenStick Stick Wood Note: That the hierarchy tree contains references to the materials, not the materials themselves. This approach has several advantages. First of all, often you have to adjust the material properties afterwards; it is sufficient to modify only one material to get the desired change in all objects which are made of that material. Secondly, a material is very large collection of information and therefore this method saves a lot of memory. A real example of using materials will clarify this rather abstract description. We will experiment with materials in the following tutorial project. @endnode @node "T3.1.2" @title "Chapter 3 MATERIALS" 3.1.2 Tutorial Project Creating a shiny sphere standing on a marble cube is a suitable exercise to demonstrate various aspects of using materials. First create a simple object containing two primitives: 1. Start the program with the standard environment. 2. Create two shapes using Create/Visibles/Cube and Sphere functions. The hierarchy tree should look like the following: Root cube ellipsoid 3. Open the material editor using the menu Project/Windows/Material This opens a new window with many gadgets. Don't worry, most gadgets contain good default values, and you will only have to define a couple of things in order to create a material. 4. Type the name of the first material "shiny" to the name field. The properties of "shiny" can be adjusted using a couple of sliders: 5. Move the Specularity slider to the middle, so that the percentage displayed at the right end of the slider becomes approximately 50%. 6. Adjust Brilliance to 80%. Specularity creates high-lights, which make the object look shiny. The higher the specularity, the sharper the high-lights. The second specularity adjustment, specular brightness, defines the brightness of the high-lights. The default value 25% is suitable, so you do not have to change it. Brilliance is the "mirror-like" property: the higher the value, the clearer the reflections you see on the surface of the material. Brilliancy level 0 produces a matt surface with no reflections, like unpolished paper. Now that the properties are defined: 7. Hit APPLY button. This creates the material "shiny", that is, adds the material to the material library. The second material can be created in a similar way. 8. Hit RESET button to remove old material properties. 9. Define the name of the second material, "marble". 10. Select material editor menu Texture/Define. 11. Select the file "r3D2:textures/marble1", using file selector. 12. Activate both Tile gadgets, X and Y 13. Press APPLY. Now you have created the second material, marble. It includes a texture map, which defines the color pattern of marble surface: if you look at the high column of gadgets at the left side of the material editor, you can see that only Color map gadget is activated. The tile gadgets were used to repeat the marble pattern in both x and y directions on the surface of the object. At this point, you have both shapes and materials created, but there is still no connection between the two. As it was already mentioned, this connection is expressed by using the hierarchy tree. You can proceed in the following way: 14. Select the object ellipsoid. 15. Select function Create/Boolean/OR. This creates a new level and puts the sphere under the level. 16. For the sake of clarity, now select the function Modify/Properties/ Name and type the new name "shiny_sphere" for the new level. 17. Double-click the name shiny_sphere on the select window. You can see the original object "sphere" on selection window. 18. Select the function Create/Mapping/Default. The list selector of REAL 3D is opened, displaying the names of the materials in the material library. 19. Click the material name "shiny" and Click OK. Now the material of the sphere is defined. The hierarchy tree is this: Root cube shiny_sphere ellipsoid shiny(T) The symbol(T) after the name shiny denotes the type of the object as "mapping". We chose the mapping type Default, because the material shiny does not require any mapping geometry definition: there are no patterns painted to the sphere which we would like to position accurately. The marble texture is different, because you may want to define, for example, the density (or size) of the marble pattern. To apply the marble texture, do the following: 20. Select the cube, and use Boolean/OR to create a new level containing the cube. Again, you may modify the name of the new level to be "marble_obj". 21. Open the new marble obj level by double-clicking on it in the select window. 22. Select the function Create/Mapping/parallel. 23. Select the material marble and Click OK. 24. This time, a mapping geometry is needed. The function waits for you to shape a rectangle in a view window. Define the rectangle by clicking on top left corner and on bottom right corner of it. The size of the rectangle that you shape will define the size of the first "tile". Now the marble mapping is created; hit return to refresh the display. You see a new item on select window, "marble (T)", and a rectangle drawn with a dotted line is visible in the view window. Note: It is possible to control the wireframe visibility of textures by using View/Drawing Set function. So, if you do not initially see the dotted texture rectangle, select View/Drawing Set and make sure that the Mapping gadget is selected. The final hierarchical structure of the example is this: Root marble_obj cube marble(T) shiny_sphere ellipsoid shiny(T) Support example: Examples/Marble&Shiny. Now it is time to render the scene. Activate the view window you want to use for rendering, use the arrow keys to find a suitable viewing position, select View/Render/Settings and set mode to Lampless, accept the rendering setting by hitting OK and then select View/Render/Window. If you have successfully performed the actions described earlier, you should get an image where the material properties are clearly visible. Often, when using parallel texture mapping on cubes, the image can contain surfaces where the texture pattern looks striped even though that is not the purpose. This artifact can be avoided by modifying the mapping object in a suitable way. We can experiment this in the following way: 25. Select the mapping object "marble(T)" using the select window. 26. Activate a view window and hit X to get the front view. 27. Select Modify/Linear/Rotate and rotate the mapping rectangle, say, 30 degrees. 28. Change the viewing direction for example by using Y, and rotate the mapping again. 29. Experimentally adjust the density of the marble pattern, select Modify/Linear/Size and increase the size of the mapping rectangle. Now render a new image; you should see a different result. After rotating the marble mapping rectangle, it is no longer parallel to any of the sides of the cube. Therefore, each side gets a nicely varying color pattern. We will now modify this example further in order to demonstrate how the hierarchy and materials depend on each other. Do the following modifications: 30. Use the select window to make the level "marble_obj" the current or active level. 31. Create a new object, for example a cylinder, under the marble_obj. 32. Go to the level "shiny_sphere", select shiny(T), and select Modify/ Structure/Cut. 33. Go to the root level, and select Modify/Structure/Paste. Now the hierarchy looks like the following: Root marble obj cube marble(T) cylinder shiny_sphere ellipsoid shiny(T) Support example: Examples/Marble&Shiny2 You inserted a new cylinder under the marble_obj level, and because there was already a marble mapping in that level, the cylinder automatically becomes made of marble. Moving shiny(T) to Root level has such an effect that shiny material affects all the objects in the hierarchy. The material of the ellipsoid remains the same, but the cube and the cylinder become made of a mixture of marble and shiny, which looks like a well polished marble. @endnode @node "T3.1.3" @title "Chapter 3 MATERIALS" 3.1.3 Optical Properties Real world material appearances and properties can often be analyzed best by considering the properties in suitable classes. The classification can be for example: - How is the color defined - What happens when light hits the surface of the material - What happens when light travels inside the material. In REAL 3D, color is always included in the objects themselves, not in the materials. This is quite natural, because in the real world, the same material can appear in different colors (green glass and brown glass, etc.). For maximum flexibility, in REAL 3D materials may also contain various colouring methods which overrule the default object color or modify it. These methods include bitmap texture maps and mathematical texture maps, which are both described in detail later. The second important property class are the properties which define what happens when light hits the surface of the material. You can define these properties from the sliders at the right side of the material editor of REAL 3D. When light hits the surface, part of it penetrates the surface, part of it is absorbed, and part is reflected back. Figure @{"T3-1:" system "display dh9:docs/r3ddoc/r3dv2pics/T3-1"} Absorbed, Penetrating and Reflected Components of Light. (PICTURE: T3-1) First of all, the object color itself defines the amount of absorbed light: the darker the color, the more absorption. What happens to the rest of the light is defined by Transparency property. The higher the transparency, the more light penetrates the surface. The maximum amount of penetration depends on the angle in which the light hits the surface. If the light hits perpendicular to the surface, then all the light can penetrate. When the angle gets smaller, more and more is reflected. As we know from the laws of optics, if the light travels from optically thicker material to thinner (e.g. from water to air), there is an angle of total reflection after which all light is reflected back, no matter how transparent the materials are. So, the non-absorbed light is split into two components. The behavior of both components is defined by Brilliance property. If Brilliance is zero, the surface is a diffuse matt surface, and each reflected/refracted light ray is directed randomly into the surrounding environment. This means, that no reflections of other objects can be seen on the surface. If Brilliance is maximum, 100%, the surface acts as a mirror, showing clear images of surrounding objects. If the Transparency is also high, then you get a clear glass appearance. Figure @{"T3-2:" system "display dh9:docs/r3ddoc/r3dv2pics/T3-2"} Light Travelling in Different Materials (PICTURE: T3-2) When we combine the extreme values of Brilliance and Transparency, these are the results: Transparency O% | 100% ------------------+------------ Brilliancy 0% | Default matt | Matt glass ------------------+------------ Brilliancy 100% | Mirror | Clear glass When you create transparent materials, you can also define the refraction index using the Refraction slider. The higher the value, the less refraction that happens. Other "Surface class" properties are: - Specularity: the sharpness of high-lights or "hot-spots" created by light sources. - Specular brightness: the intensity of high-lights created by light sources. - Roughness: defines molecular level roughness of the surface. The last class are the properties which define what happens inside the materials while light travels in them. Both of the Turbidity adjustments belong to this class. Turbidity defines the degree of turbidity (fogginess) of the material. For example, you may use it when simulating atmospheric phenomena such as: fog, mist, and clouds, also when simulating water or not perfectly clear glass. Turbid saturation gives extra accuracy in simulations, as it defines the relation between the turbidity effect and the distance which the light travels inside the turbid material. The higher the value, the more easily the turbidity effect reacts to distance variations, whereas turbid saturation 0 produces "flat" turbidity. As an example of these properties, lets create a fog cloud and a glass ball: 1. Open the material editor. Name the first material as fog. 2. There are no highlights on a surface of a fog cloud, so leave specularity to zero. 3. There is no diffuse, clear boundary surface in a fog cloud. Therefore, set Brilliance to maximum level 100%. 4. There is no boundary resisting light penetration. Therefore, set Transparency to 100%. 5. It is best to avoid strong Refractions in this case, so adjust Refraction to 100%. 6. Set Turbidity to 10%. The default saturation level of 25% is suitable. 7. Activate the Smooth gadget; this allows the light to penetrate the cloud better. 8. Press APPLY 9. Next create glass material: change the name to glass. 10. Glass always reflects light, so deactivate the Smooth gadget. 11. Adjust specularity to 75%, to get nice highlights. 12. Set refraction to 70%, to get "glass" refractions. 13. Reset turbidity back to zero to get clear glass. 14. Now glass is ready, so press APPLY. 15. To visualize the properties of these materials, we need something on the background, so we will create one more material: a checker texture. First press RESET to get rid of old definitions, and then type the name checker. 16. Define the texture name, r3d2:textures/bluewhite. After material RESET, Color map is automatically active. 17. Activate TileX and TileY 18. Press APPLY 19. Now the materials are ready, so you may close the material editor. 20. Create a level (Create/Structure/Level) and name it "wall". 21. Create a large rectangle (Create/Visibles/Rectangle) filling the view. 22. Select Create/Mapping/Parallel, select checker from the material list and click OK, shape a small parallel mapping rectangle. 23. Step back to the root level in the hierarchy, and create a new level "fog". 24. Create a white sphere (Create/Visibles/Sphere). 25. Select Create/Mapping/Default, select the fog-material and click OK. 26. Step back to the root level in the hierarchy and create a new level "glassball". 27. Create another white sphere beside the fog sphere. 28. Select Create/Mapping/Default, select glass from the material selector, and click OK. 29. Now the model is ready. Take a top view of the scene and make sure that the rectangle is behind the spheres. Then find a good viewing angle using the cursor keys, so that you see the rectangle through the spheres. 30. Open the render settings dialog (View/Render/Settings). Set mode to Lampless - in Environment mode, the renderer ignores transparency settings in order to produce a rendered image faster. Click OK, and render an image. Support example: Examples/Materials/gas&glass @endnode @node "T3.2.1" @title "Chapter 3 MATERIALS" 3.2 TEXTURE MAPPING 3.2.1 General Information In REAL 3D, Image files can be used as parameters for materials. The technique of using bitmap images for defining various material properties is called texture mapping, and the images themselves are called textures. A typical example of texture mapping is modelling a floppy disk with a disk label. After creating a blue disk shape, it is necessary to "glue" the white label with text on to it. This label can be drawn using a paint program and then projected as a parallel texture map on to the disk. To use texture mapping, you need: - A texture- Any digitized/painted/scanned IFF image and also a 24/32-bit true color Targa image created by REAL 3D can be used. - A material referring to the texture. The material contains the name of the texture and other desired properties. - A mapping referring to the material. The mapping can be created by using Create/Mapping menu. - An object to which the material is applied using the mapping. As described earlier in this section; the object and mapping should be placed under the same hierarchy level. The tutorial chapter 3.1.2 has already demonstrated how to create a texture mapped object. In the following chapters, we will consider different aspects of texture mapping in more detail. 3.2.2 Textures It is possible to use from 1 to 24-bit IFF files or true color Targa files as textures. The image format, size, and depth that is the most suitable, depends on the application. The following examples demonstrate some basic rules of how to choose the correct texture type. - 24-bit textures are usually only necessary when outputting 24-bit graphics. Using smaller image depths saves a lot of memory and are faster to render. - Grade-function can be used to obtain 24-bit color resolution with lower texture depths. For example, to get a texture with a 24-bit color gradient from blue to white: you can use a two pixel, 1 bit deep image, (which contains only one white pixel and one blue pixel), and "grade" the texture. This saves memory, because this image occupies only a couple of bytes of memory , whereas the corresponding 24-bit texture may require several hundred kilobytes of memory or more. Nevertheless, the texture gradient function is a time-consuming one, and sometimes 24-bit textures can be faster to render. - Regular geometric patterns can often be represented with very low resolution textures. For example, for a checker pattern, you need only a 4 pixel, one bit deep tiled texture. The Tiling feature, repeating the same pattern, is handy in situations like this. - If you are creating an animation where you zoom in very close to a texture mapped surface, you will probably need a quite high resolution texture in order to avoid clearly visible pixelization effects. Also, the "grade" function is useful for this purpose. @endnode @node "T3.2.3" @title "Chapter 3 MATERIALS" 3.2.3 Texture Mapped Materials In REAL 3D, texture mapping is a material property. Each material of the material library can contain a texture map. If you want to apply multiple texture maps for an object, you can create several materials and link them all with the object. This is demonstrated later in the chapter "Multiple Materials". A material can use a texture for defining various properties independently from each other. For example, a texture can act as a bump map and as a color map at the same time. There are seven different usages for texture mapping: - Color mapping: maps the color of the texture to the material. - Bump mapping: uses the red component of the texture as a local height information when shading the surface of the material. - Transparency mapping: uses the green component of the texture to define Transparency of the material. - Brilliancy mapping: uses the blue component of the texture to define brilliance of the material. - Shadow mapping: filters the original color of the object with the texture colors. - Clip mapping: can be used to clip/cut surfaces. - Scope masking: defines the spatial scope/visibility of the material using the texture shape as a mask. Note : Clip mapping is actually a material property. It does not reshape the object - the Renderer just treats clip mapped areas as fully transparent material. Clip mapping usually does not work properly in Environment rendering mode where transparency in general cannot be simulated convincingly. @endnode @node "T3.2.4" @title "Chapter 3 MATERIALS" 3.2.4 Mapping Mathematically, the term "mapping" means; a rule which defines how to attach to every point of a space, exactly one counterpart in another space. REAL 3D uses this kind of rule to define how a point in 3D absolute space is mapped into the 3D material space, where the properties of the materials are defined. The data item which defines the rule is called mapping. You can create mappings using the functions in the menu Create/Mapping. There are five basic mappings available: - Default - Parallel - Cylinder - Sphere - Disk Each mapping performs a 3D coordinate transformation in a natural way. For example, Default mapping leaves the coordinates unchanged and sphere mapping maps normal 3D coordinates to polar coordinates (horiz. angle, vert. angle, radius). Each mapping (except Default) includes a geometry (or shape), which visualizes and defines how the coordinate transformation happens. You define the geometry when creating the mapping, and because REAL 3D stores the mappings in the hierarchy tree, you can easily modify (resize, move etc.) or even animate them. The mappings can be customized using the Mapping handler from the material editor. For example, a cylinder mapping can be modified to a spiral style mapping by activating the built-in Mapping/Tilt handler. Note : Although the geometric properties of mappings are mainly used with texture mapping, REAL 3D uses mappings as a way of connecting a material to an object. The coordinate transformation of a mapping may not be used at all. @endnode @node "T3.2.5" @title "Chapter 3 MATERIALS" 3.2.5 Sector Mappings Sometimes when using cylinder, disk, or sphere texture mapping, it is desirable to map the texture into a sector instead of full 360 degrees. The following example demonstrates how to do this, and at the same time, it shows how to use a lower level interface of REAL 3D for defining mappings. Let us assume that the task is to create a cylindrical can, which has a label covering 1/3 of the side of the can. The following actions give the desired result: 1. Create the can using Create/Visibles/Cylinder function. 2. Use Create/Sectors/Cylinder to create a cylinder sector, using the same axis as the "can" cylinder. Position the sector suitably so that the cylinder sector defines the correct area for the label on the surface of the can. 3. Make sure that the cylinder sector is selected and select Modify/ Properties/Attributes function; REAL 3D opens the attributes requester. Activate Mapping gadget and select OK. 4. Now open the material editor and create a material with a suitable color texture. Activate Color map and define the image name. Name the material as "label", and press APPLY. Then close the material editor. 5. Make sure that the cylinder sector is still selected and select Modify/Properties/Tags menu. When requester opens, click the Add gadget. Then type the four capital letters SMAT , then click in the empty space and finally type the name of the material, "label". In other words, type the string "SMAT label". It is important that the string is exactly correct, including upper/lowercase characters, otherwise the material will not be found. Then click OK. 6. Now the scene is ready for rendering; select environment rendering mode and start the rendering. Support example: Examples/Materials/sector_mapping @endnode @node "T3.2.6" @title "Chapter 3 MATERIALS" 3.2.6 Spline Mapping In addition to the basic mappings and sector mappings presented earlier, REAL 3D offers an advanced method for using cubic B-spline parameter space mapping. This technique means that you can use a cubic B-spline surface as a mapping for itself so that the mapping automatically follows the shape of the B-spline surface. When using this mapping method, the texture pattern follows the surface deformations in a natural way, no matter how much the surface is bent or stretched. A good example is a roll of chequered paper rolled open during an animation; if the paper roll is modelled using a cubic B-spline surface, and the pattern is a spline mapped color texture, then the desired result is achieved. To use spline mapping: 1. Create an object using a cubic B-spline surface. 2. Open the material editor and create a material having the desired texture map. Select the desired texture mapping type, for example color mapping. 3. Activate the Spline map gadget, and press APPLY to create the material. 4. Use Create/Mapping/Default and create a mapping on a view. You can use Default or any other mapping, because spline mapping overrules the original mapping geometry. 5. Link the object and the mapping together in the hierarchy unless you have done it already, for example by multi-selecting both and using Create/Boolean/OR. 6. Render the scene using Environment rendering mode. Make sure that B-Spline->Phong rendering setting is not active - spline mapping does not work with Phong shaded surfaces. Note: That you can use spline mapping to map: bumps, other properties as well as colors, tiling, and other texture mapping options. When tiling, you may use the two rightmost fields of S-map uvwh gadgets of the material editor to scale the tile size: for example, a value 0.25 produces four tiles to the surface. Support example: Examples/Materials/spline_mapping @endnode @node "T3.2.7" @title "Chapter 3 MATERIALS" 3.2.7 Index Format String REAL 3D supports automatic indexing of texture file names. This feature can be used for creating animated textures. In this chapter, the indexing system is described in detail. There are several places in REAL where an index must be included in a file name, e.g. a sequence of Backdrop Image files. When such an index is needed, it is included in the name by using an Index Format String. The inclusion of this string not only specifies that an index is to be used, but also what format is to be used for the index, and where in the name it is to be placed. For those familiar with the "C" programming language this Index Format String uses the same conventions as the "C" function "sprintf". For most indexing, use of the following information should suffice: "%" Start of format string This is then followed by either or none of: "-" To specify that the index should be left-justified "Field width specifier". if the index has less digits than the field width, then it will be padded either to the left or right if "-" is used. If this width is specified with a leading zero then the padding character will be a zero, otherwise it will be a space. The format string is then ended with the conversion character "d". This specifies the index to be in decimal format. Examples: If the index variable is 3 File_Name_%d produces: File_Name_3 File_Name_%2d produces: File_Name_3 File_Name.%-2d.IFF produces: File_Name.3.IFF File_Name.%03d produces: File_Name.003 @endnode @node "T3.2.8" @title "Chapter 3 MATERIALS" 3.2.8 Animated Textures When creating animations, it is often desirable to also animate textures instead of using static texture maps. For example, one can animate a walk through a room where a television is displaying changing images; in this case, the TV screen should contain an sequence of varying color textures. REAL 3D offers flexible tools for creating such effects. In order to create a animated texture, do the following: 1. Create the texture sequence. For example, draw ten images, and save them with the same name appended with a growing index. The indexing convention can be selected quite freely, you can find the exact rules from the previous chapter "Index Format String". The actual name must be the same for all the images. For example: "txr0", "txr1", "txr2", etc. 2. Create a material, and type the name of the textures you created without index to the texture name field (e.g."txr"). Append the index format string after the name as presented in the previous chapter. For example, the texture name definition can be "txr%d". 3. Select the desired Index handler for the material using the material editor. The default handler goes through the textures incrementing the index frame by frame. If you are going to use cyclic texture animation instead of having a new index for each new frame, you should set the parameter b to be the amount of textures, (e.g. 10). 4. Use the material in your animation. Instead of using the cyclic handler , you can use the pingpong handler, which goes back and forth in the texture sequence. You can also define the rule which defines which texture to use in each frame/time value by using RPL/Formula handlers, as presented in the chapter "Procedural Handlers" of this section and in the reference section. When using those alternatives, you can refer to the global/local animation time or to the frame counter. The tutorial example file "Examples/Materials/Water" contains an example of using an animated bump texture to simulate waves. It uses default index handler with a 30 frame cycle, and therefore, if you want to produce a loop animation, you should set the animation window resolution gadget to a multiply of 30 frames: 30, 60 or 90 etc. @endnode @node "T3.3.1" @title "Chapter 3 MATERIALS" 3.3 ADVANCED MATERIAL FEATURES 3.3.1 Multiple Materials This chapter explains one very important part of the material handling of REAL 3D, namely the usage of multiple materials per object. Actually, the tutorial example presented earlier used this method when demonstrating the connection between the hierarchy and materials ("shiny marble"). Using mutiple materials is quite easy. You just create the object and the materials you want to apply to the object. Then you create a hierarchy level, put the object under it and create as many mappings as necessary under the same level. For example: multimatobj myobject colormat(T) bumpmat1(T) bumpmat2(T) topmat(T) Different materials may be used to define different properties for the object. For example: a material including a colour texture for defining the color, a material with a dense bump texture to define surface roughness, and a material with a large scale bump texture to define bigger bumps. Secondly, different materials may be used to define object properties in different spatial locations. For example: a sphere can be textured so that the north pole is made of wood and the south pole is made of marble. Often, when multiple materials are applied, the material definitions do not overlap, and it is easy to predict what the result is. For example: if you map two non-tiled parallel colour textures, say, two labels, to a box so that the labels do not overlap, you just get two separate coloured areas on the box surface. A more interesting case occurs when the materials overlap. By default, if two mappings define two different values for a material property in apoint in space, REAL 3D uses the average of the two at that point. In other words, the materials get automatically blended. Different bump definitions are: - A bitmap bump texture: Image + Bump map - A math. bump texture: Bump handler = built-in/RPL/formula. The material editor includes some functions with which you can control material blending more accurately. First of all, the Effect slider offers global adjustment which determines how much the material affects the objects to which it is applied. For example, if you apply marble to an object and marble has 50% Effect setting, you get a marble-default material mixture. When the materials are blended, the Effect values are used as weights which define how big a proportion of each material is put to the mixture. Secondly, scope handlers can be used as spatial weight distributions. This means that the effect of a material can vary in different points of 3D space. For example, you may create a spot of marble in a wooden object so that the marble smoothly fades away and turns into wood. One of the most useful scope handlers is the built-in Local scope handler. It weights the material effect so that the effect is maximum in the middle point of the mapping used (e.g. in the middle point of a sphere mapping or in the top left corner of a parallel mapping). The maximum effect, defined by the effect slider, fades smoothly away within a certain radius. By default, this radius is the radius of the mapping, but it can be overruled by defining a non-zero parameter in a. Other built in scope handlers are described in the reference section. As an example, we can create a bumpy sphere whose north pole is made of wood and south pole is made of marble. 1. Create a new level. 2. Create a sphere under the level. 3. Open material editor. 4. First create the bumpy material: define name bumpy, define texture r3d2:bumpmaps/irregular, deactivate Colour map and activate Bump map, set bump height to 5% and adjust specularity to 50%. Hit APPLY. 5. Create wood: hit RESET, then define name wood, texture R3D2:textures/ wood1, activate tile gadgets, and set specularity again to 50%. Then click Scope handler gadget until it displays "Local". Hit APPLY. 6. Create marble: do NOT reset the material editor, just change material name to marble and change texture name to R3D2:textures/marble1. Hit APPLY. Now the materials are ready, so you may close the material editor. 7. First create the global bumpy material mapping: select Create/Mapping/ Sphere, select bumpy and click OK, click in the middle of the sphere and size the texture sphere.The size can be equal to the size of the original sphere. t does not matter in this case. 8. Select Create/Mapping/Sphere again, select wood, and shape the mapping so that the north pole is in the middle of the mapping sphere. The size should be almost twice the size of the original sphere. 9. Select Create/Mapping/Sphere, select marble, and shape an equally big mapping around the south pole. 10. Render the image in environment mode. Support example: Examples/Materials/Localscope. The Scope mask feature offers an easy way to define the scope distribution. You can use an image to define which parts of the space are affected by the material. The following example, writing "rough" letters to a matt surface, demonstrates this. 1. Start the example by drawing white text on black background in a paint program. Save the image or suitable part of it as a brush. 2. Open the material editor of REAL 3D and type the name of a material, "rough". 3. Define the texture name to be the text brush name. 4. Deactivate Colour map gadget. 5. Activate Scope mask gadget. 6. Activate Transp. col gadget, and set transparent colour to black using Transp.R, Transp.G and Transp.B gadgets (all zero). This means that you will not map the black background colour of the text. 7. Adjust roughness to 30% and hit APPLY. 8. Create a rectangle on a view window. 9. Create a parallel mapping for the rectangle having equal size and position as the rectangle. 10.Render an image in environment mode. Support example: Examples/Materials/Scopemasking @endnode @node "T3.3.2" @title "Chapter 3 MATERIALS" 3.3.2 Procedural Handlers Each handler row of the material editor of REAL 3D includes four main types of handlers: Default handler, additional built in handlers, RPL handler and formula handler. The two last ones, RPL and formula, make it possible for the user to easily and quickly define new custom handlers. For example, it is possible to define an infinite number of different mathematical colour textures. The Formula handler is based on the EVAL word of RPL. When using the Formula handler, you can type in a formula directly which defines the desired properties from a certain set of parameters. These parameters could include for example: material space coordinates x, y and z. It is possible to use all the usual mathematical functions in these formulas; the exact list is given in RPL EVAL documentation. It is possible to create quite interesting bump map textures using trigonometric functions. The following example of a bump mapped surface where the bumps are also time dependent, demonstrates this: 1. Open the material editor and name the new material as wave. 2. Set Bump handler to Formula and type the following formula to the string gadget of the handler: bx = sin(3*sin(5*x)+y+T*3.14),by = sin((x+T)*3.14)*cos(5*x*y) 3. Add some specularity to the material and hit APPLY. 4. Create a blue rectangle and create a parallel mapping referring to the wave material. 5. Render an image or an animation. Support example: Examples/materials/mathbumps RPL handlers offer even more flexible way of expanding the material features. In this case, the string gadget associated with the RPL handler may contain any RPL expression, including the EVAL word. RPL coded expressions are faster than Formula expressions, but require more RPL knowledge. The RPL expression used may also be a full RPL procedure defined in the master RPL environment. For more details, see RPL documentation. The following examples demonstrate the usage of formula handlers. Example: y = y + 10*sin(4*a*x/100) where a = 6.28 When used with an image file 100 pixels wide to be mapped onto the surface, this formula produces a series of vertical sine wave ripples. The parameter a is being used to convert x into radians, so that using the constant 4 produces four cycles of sine waves. The constant 10 in the expression makes the sine deviation +/- 10 pixels. Example: s = 25 This combines 25% of the properties of the material with the existing properties. Example: s = x When used with a texture file 100 pixels wide will apply the image such that its effect becomes stronger over the whole width of the image. The scope handler is also the most appropriate place to assign procedural values to the Material Variables controlling the basic physical material properties. Example: br = 100.0*x When used with a parallel mapping texture and no image file causes brilliance to increase linearly along the width of the mapping rectangle. Example: bx = sin(5*a*x), by = sin(2*a*y) when a = 6.28 Applies sine wave ripples in x and y direction to the surface. The "a" parameter is again being used as 2*pi to convert x & y to radians so that the constants 5 & 2 produce five ripples along the x axis and 2 ripples along the y. Since x & y are not normalized, these expressions only produce the correct results when used without a texture file. Example: R = 255*x, G = 255*y, B = 255*z The above expressions replace any existing colour components with a Red value, which increases along the x axis of the texture, and a Green value which increases along y. The Blue value is derived from the z coordinate. Using these expressions would mean that the colour of the surface would depend upon its position in the texture. The size variable can be used to bind a formula to the size of a texture, as in the following example: Example: R = if(z <= sz, 255, 0) This replaces the red component of the surface with a full intensity value, if the point on the surface is inside the texture size. Example: i = F/a when a = 3 The index increases at one third of the rate of the Global Animation Index. Example: i = 10*t%5 % - modulus function As the local time "t" changes from 0.0 to 1.0 the index will change from 0 to 4 twice. @endnode @node "T3.3.3" @title "Chapter 3 MATERIALS" 3.3.3 Non-homogeneous Materials The Scope feature can be used for defining non-homogeneous materials. There are two ways to do this: by using Formula/RPL scope handler with an RPL expression, which defines the desired property directly, or by using multiple scope-weighted materials, in which case the blending process produces different results in different parts of space. An example of the formula method is a shiny material with a formula scope handler and formula sb = 50*(sin(x)+1) This formula modifies specular brightness; trigonometric sin function produces a repeating horizontal brightness wave pattern. As an example of the second method, blending two materials, let us consider modelling a planet with atmosphere. The purpose is to make the atmosphere glow when sun shines through it. 1. Open the material editor. First create a planet surface material: name it as planet, set texture map to r3d2:textures/planet, and press APPLY. 2. Create a star sky material: change the name of the material to space, and change the texture name to r3d2:textures/space. Activate TileX/ TileY gadgets, and set Unshaded flags, because the image will be used as an unshaded back ground plate. Press APPLY. 3. Create gas material: hit RESET button to get a clean start, name the material as gas, activate the Smooth gadget to eliminate surface reflections, set Transparency, Brilliancy and Refraction to 100%, turbidity to 10%, turbid saturation to 50%, and specularity to 100%. Hit APPLY. 4. Create glowing gas by modifying the previous material: change the name to glow, and adjust specular brightness to 10%. Then select Local scope handler, and select APPLY to insert the new material into the material library. 5. Now you may close the material editor, and start building the objects. First create a level and name it star plane. Create a rectangle under the level, and create a parallel mapping, which refers to space material. The space textured rectangle will act as a background plate, so place it behind the rest of the scene and size it accordingly. It is probably necessary to use Modify/Properties/Attributes/Infinite gadget to make the plane infinite. 6. Go back to the root level of the hierarchy and create a level called planet. Create a sphere under the planet level. Then take a view from above to the planet and create a sphere mapping referring to the planet material. 7. Step back to root level and create a new level called atmosphere. Under that level, create another sphere, white or light blue, around the planet sphere, make it a little bigger than the planet. Then define two sphere mappings, one referring to gas and the second one referring to glow. Both mappings should match exactly the size and position of the atmosphere. 8. Create a light source between the star plane and the planet. 9. Adjust the camera so that you look towards the planet with the star plane behind it. Also, make sure that you see the light source through the atmosphere. 10. Open render settings requester. Select Normal rendering mode, set Mat. samples to one and hit OK. Then render an image. The hierarchical structure of the scene is: Root starplane rectangle space(T) planet ellipsoid planet(T) atmosphere ellipsoid gas(T) glow(T) lamp It is important that the planet is above the atmosphere object in the hierarchy, because the two overlap. The planet object should replace atmosphere, not the other way around. The higher an item is in the hierarchy, the higher priori it has. In this example, the specular glow of gas fades away towards the outer edge of the atmosphere because of the Local scope property. What is left is the other non-glowing gas. The Mat. sampling value 1 was very important: it instructs REAL 3D to study the material not only on the surface of the atmosphere, but inside it too. Therefore, the non-homogeneous nature of the gas is detected and the proper effect is created. Note: That using a nonzero Mat.sampling value has meaning only if transparent materials are used. Support example: Examples/Materials/Planet. @endnode @node "T3.3.4" @title "Chapter 3 MATERIALS" 3.3.4. Mappings and Hierarchy Hierarchical manipulation of mappings requires some consideration. When creating certain animation effects (e.g. material metamorphosis), mappings must be grouped using hierarchy, or referred to across the hierarchy. It has already been pointed out that a mapping connects a material only to those objects which are located in the same hierarchy level as the mapping itself. How do you connect a hierarchical group of mappings into an object? This can be done by using the "Mapping flag" of the Modify/Properties/ Attributes function. Anywhere in the hierarchy you can replace a mapping with a level or a symbolic link by setting the "mapping flag" of the level or link. The level may contain the actual mappings or the link may refer to the actual mapping. Anyway, REAL 3D looks at the whole hierarchy regressively checking all the objects labelled with texture flags. If a level or link without a Mapping flag is found, recursion does not proceed under it. All the mappings found in this way will affect the result. As an example, consider the following simple hierarchy of an animated texture map group: Root candlestick motion_ mat(T) mappings(T) wood(T) marble(T) level(M) line Support example: Examples/Materials/moving_texture @endnode @node "T3.3.5" @title "Chapter 3 MATERIALS" 3.3.5. Some Material Morphing Examples The following examples may help clarify how to morph materials. Example 1: Material morphing using built-in "Temporal Scope" handler This material handler can be used for modifying the effect (scope) field of the material from one value to another. These values are defined by using Scope a & b fields. The field "a" defines how strongly the material in question affects objects in the beginning of the time and "b" is used for defining the effect for the end of the animation. For example, if you would like to create a wooden sphere whose material is morphed to marble during the animation, you could create two materials so that the effect level of the first material starts from the zero and gets stronger while the effect of the second material gets weaker and weaker. In order to do this: 1. Create two materials named "wood" and "marble". Use colour mapping and appropriate textures so that you can see when the material changes from wood to marble. Set the Scope cycle gadget of both materials to "Temporal" and use the following values for "a" and "b" fields: Material a b -------------- wood 1 0 marble 0 1 When the time is 0, marble has no effect at all while the material "wood" is at its maximum level. When the time proceeds, the material "marble" gets stronger and stronger, whereas the "wood" material is faded away. 2. Create a sphere. +------+ | Root | +------+ | +--------+ | sphere | +--------+ 3. Add both materials using Create/Mapping/Parallel. +------+ | Root | +------+ / | \ / | \ / | \ +--------+ +------+ +--------+ | sphere | | wood | | marble | +--------+ +------+ +--------+ Note: You can use different mapping methods for the different materials, for example: parallel projection for the wood and cylinder projection for the marble. Not only can the texture be morphed, but also the projection type can be morphed over the time. 4. Play the animation. Support example: Examples/Materials/temporal_scope Example 2: Mapping geometry morphing Because mappings are really primitives defining the size, position and orientation for the actual bitmap textures, you can animate the mappings using all the animation methods available. For example, you could use mappings as particles and animate them using the particle system oriented animation techniques, such as wind and gravity, or perhaps you just want to rotate the texture about your objects using ROTATE method. The following example demonstrates how to move a texture over an object during an animation by using PATH method. 1. Create a "wood" material using an appropriate texture. 2. Create an object, say tube. +------+ | Root | +------+ / +------+ | tube | +------+ / | \ / | \ +----+ +----+ +----+ | p1 | | p2 | | p3 | +----+ +----+ +----+ 3. Create a mapping using parallel projection (Create/Mapping/Parallel). This sets the material of your object "Tube" to wood (remember the philosophy: if your object consists of a car and a motion, the result is a moving car, if your object consists of a "Tube" and a "wood", the result is a wooden tube). +------+ | Root | +------+ / \ +------+ +---------+ | tube | | wood(T) | +------+ +---------+ / | \ / | \ +----+ +----+ +----+ | p1 | | p2 | | p3 | +----+ +----+ +----+ 4. Now animate "wood" primitive by applying the function Animate/Create/ path to it (i.e. define what kind of path the wood texture should follow). Now the hierarchical structure of your object is as follows: +------+ | Root | +------+ / \ / \ +------+ +------+ | tube | | wood | +------+ +------+ / | \ / \ / | \ / \ +----++----++----+ +---------+ +--------------+ | p1 || p2 || p3 | | wood(T) | | level (PATH) | +----++----++----+ +---------+ +--------------+ / +------+ | line | +------+ 5. Set the texture flag of the level object/Root/wood. This tells the renderer to look inside the level to seek out actual mapping primitives. 6. Render the animation Support example: Examples/Materials/mapping_path Example 3: Material/Mapping geometry morphing using MORPHING animation method You can use morphing to animate the shape of mapping primitives. This also causes the properties of the corresponding materials to be morphed. In this example, we will create three "key" materials which are used as key frames for morphing the "result" material and mapping geometry. 1. Create four materials called "result", "key1", "key2" and "key3". Use, for this example, different specularity levels for the different key materials. Properties of the result material do not matter, because they will be determined by the key materials during the animation. 2. Create a sphere +------+ | Root | +------+ | +--------+ | sphere | +--------+ 3. Create a level object named as "level" and set the mapping flag of it, using Modify/Properties/Attributes. +------+ | Root | +------+ / \ / \ +--------+ +-----------+ | sphere | | level (T) | +--------+ +-----------+ 4. Create the "result" mapping using parallel mapping. +------+ | Root | +------+ / \ / \ +--------+ +-----------+ | sphere | | level (T) | +--------+ +-----------+ / +--------+ | result | +--------+ 5. Create a level object called "keys" with the animation method MORPHING CLOSED. +------+ | Root | +------+ / \ / \ +--------+ +-------+ | sphere | | level | +--------+ +-------+ / \ +--------+ +----------+ | result | | keys (M) | +--------+ +----------+ 6. Create parallel mappings key1, key2 and key3 inside the morphing object "keys". Each mapping should have different shape, size and position. +------+ | Root | +------+ / \ / \ +--------+ +-------+ | sphere | | level | +--------+ +-------+ / \ +--------+ +---------+ | result | | keys(M) | +--------+ +---------+ / | \ / | \ +------++------++------+ | key1 || key1 || key1 | +------++------++------+ 7. Set the Modify/properties/Attributes/WF-Invisible flag for "keys(M)" level if you don't want to see all mapping wireframes. 8. Now use one material window and two view windows for rendering the animation. Load the material "result" into the material window so that you can see how the properties of it are morphed during the animation. Set the View/Drawing Set/Render_Wire flag of one view window so that you can see how the wire-frame representation of the result mapping is morphed. Use, for example, Lampless mode shading on the second view window so that it shows the animation using ray tracing. Support example: Examples/Materials/mat_morphing Example 4: Using an intelligent object to modify material properties One possible way to morph material properties over the time is to use one intelligent object for that purpose. Usually methods are used for defining how objects with which they are associated behave, but nothing prevents us from using them for defining how materials behave as well. 1. Create one material, "wood". 2. Create one sphere, one (parallel) mapping and one empty level. +------+ | Root | +------+ / | \ / | \ +--------++------++-------+ | sphere || wood || level | +--------++------++-------+ 3. Select the "level" and select the menu Animate/Create/RPL. This function opens a requester allowing you to define a short RPL program to be associated with the selected object. Type the following program: "attr(wood->bril)=Time*100" EVAL DROP 4. Open the material window and load "wood" material into it. Play the animation and you will see how the object "level" modifies the brilliance of the material "wood". Support example: Examples/Materials/mat_RPL_anim Hint: It is pretty easy to think of more sophisticated ways to use this technique to animate material properties. First of all, the procedure itself could be much more complex. Furthermore, the object with which the procedure is associated, could contain sub-objects, tags etc. For example, the velocity tag (which defines the speed of the object for particle system methods) could be used for defining the brilliancy of the object. The higher the speed the more reflective the object becomes. The techniques that have been presented here are not the only ones. There are some even more fundamental ways of implementing material morphing. For example: - you can recreate the material for each frame instead of modifying the existing one. This makes it possible to define all the material properties without any limitations. - you can define a set of materials, save them to a file and just load them in when the time reaches a certain value. - you can write your own material handler formulas or RPL procedures which may depend on animation time. - you can use SIZE method to resize spherical mappings with Local scope handlers about their center points with the effect of each material growing respectively. The possibilities are many... @endnode @node "T4.1.1" @title "Chapter 4 MODELLING" " Chapter 4 MODELLING ------------------- 4.1 FREE FORM MODELLING AND POINT EDITING In this chapter we shall investigate the modelling techniques of REAL 3D which are best suited for creating free form objects such as a human face. The approach is based on curves and mesh surfaces whose points can be freely edited to obtain a desired shape. The usual procedure for creating a free form surface is the following: 1. Create some curves which contain enough information of the basic shape of the surface. 2. Manipulate and edit curves if needed. 3. Use a suitable tool to build a surface from the curves. 4. Use linear and nonlinear modifications to edit the overall shape. 5. Use point editing for details and fine tuning. 4.1.1 Curves A curve, which is a sequence of pints in space, is an important object in free form modelling. The free form tools of REAL 3D create surfaces by combining curves in different ways. Another context where curve data is needed regularly is animations: motions in REAL 3D animations can be defined using curves. There are two classes of curves in REAL 3D: open curves and closed curves. The result of many operations depend on this difference. For example, when defining a path for an object, a closed curve gives a different result than an open one, even if the start and the end point of the latter coincide. A curve can be "evaluated" in two ways: - as a polygonal line, "polyline" - as a Cubic B-Spline The term "evaluate" in this context means that the points which define the curve and which are used to control the curve are used as an input in a calculation process which produces another curve. The result curve, which may not pass through the original points, is the actual shape which is used. A "polyline" simply connects the points of the curve with straight lines. The curve will have sharp edges. To create a polyline: 1. Select Create/Controls/Open line. 2. Use the left mouse button to add new pints to the end of the curve. 3. When the curve is ready, use the right mouse button to end the definition. The following special options are available during curve creation: - key removes the given points one by one. - key closes/opens the curve. The B-Splines in R3D2 are controlled in a conventional way using control polygons. The actual curve generated from control polygons can produce somewhat surprising results until the properties of B-Splines are understood. So called "knot-points" are the points that the curve actually passes through. To experiment with B-Splines, select a View window and use View/ Drawing_Set to open the Drawing Settings requester. Turn on "C. Polyg." and "Knots" gadgets and make sure that "Curves" is also on. Now try creating some B-Spline curves and observe the effects. With the Drawing settings set as above, you will see the control polygon, a smooth B-Spline curve (evaluated from the control polygon), and a series of "knot points" on the curve. The first knot-point tends to be near the second control point, and there are always two less knot-points than control points. This means there must always be at least 4 control points. Don't become confused by closed B-Splines, their first knot-point and last knot-point are the same point. Open B-Spline: knots = cpoints - 2 Closed B-Spline: knots = cpoints When using Controls/B-Spline Ctrlp, you define the curve by defining the control points. This usually produces the "smoothest" result, although it requires some experience when it comes to shape control. Controls/B-Spline Knot inputs the actual knot-points, and then constructs a B-Spline which passes through these points. This method can be the easiest to control. Controls/B-Spline Curve shows the actual B-Spline curve while you define new points. The following simple test shows one new property of B-Spline curves: 1. Select View/Drawing Set menu, deactivate "C. Polyg." gadget and exit Drawing settings requester by clicking OK. 2. Draw a B-Spline curve. 3. Select Modify/Linear/Move and move the curve to a new position. You can see that even though your drawing settings leave the control polygons invisible, when you modify B-Splines REAL 3D automatically uses the control polygon representation for speed reasons. @endnode @node "T4.1.1.1" @title "Chapter 4 MODELLING" 4.1.1.1 Special Curve Shapes There are several useful curve shapes available in the Create/Controls menu. Some examples are presented below. Circular curves can be created using the Circular Line or the B-Spline Circle functions. Both work in a similar way: 1. Select e.g. Create/Controls/Circular Line. 2. Click the center point position. 3. Shape a circle. 4. Type a suitable point number for the curve when the program asks for "Subdivision" click OK. Usually the default value 8 is sufficient. You can also easily create Helix curves: 1. Select Create/Controls/B-Spline Helix. 2. Define a suitable point number and an angle for the helix. For example, the default angle 6 gives about one revolution around the axis. Select OK. 3. Click the center point position. 4. Shape a cylinder, which defines the size of the helix. @endnode @node "T4.1.1.2" @title "Chapter 4 MODELLING" 4.1.1.2 Multiple Control Points The term "mutiple control point" means defining several control points at the same location. The corresponding curve points are called "multiple knot points". The alternatives and their results are: - Single control point - normal "smoothing" - Double control point - almost sharp angle, still somewhat rounded - Triple control point - sharp angle, or "corner" curve goes through the control point. - Higher number of control points do not produce further changes in shape Figure @{"T4-1:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-1"} The Effect of Single, Double, and Triple Control Points. (PICTURE: T4-1) Controls/B-Spline Curve function uses triple knot points at the beginning of the curve automatically to pull the curve to the given start and end positions. Note: Multiple control points not only alter shape but also the "evaluation speed". This means that when using such curves as motion paths, the speed slows down in those curve parts which correspond to multiple control points and can even stop at the triple knot points. @endnode @node "T4.1.2" @title "Chapter 4 MODELLING" 4.1.2 Selecting Points When free form modelling it is often necessary to make fine adjustments to selected points on the surface of an object. Manipulation of the object as a whole does not always allow for sufficient detail to get the desired result. REAL 3D includes support for single and multiple point selection enabling pointwise editing of freeforms. This kind of point editing is only possible with free form curves and meshes. Point editing is not possible with CSG objects such as cubes and spheres etc. There are two ways to point edit freeforms: - Direct B-Spline knot point editing one point at a time (using Move Knotpoint) - Point editing using sub-groups. The following examples demonstrates both: 1. Draw an "s" with a B-Spline curve. Use e.g. Create/Controls/B-Spline Ctrlp., and define the shape using 8 control points. 2. Select View/Drawing Set and activate "C.Polyg. , "Knots" and "Curve" gadgets, so that REAL 3D displays all the B-Spline information. 3. Select the B-Spline curve you created. 4. Select menu Modify/Freeform/Move Knot point and click near one of the "knots". Then move the mouse to a new position; you can see the curve follow the mouse. click at the new position. The second point editing method offers a more the abili to put selected points in a "group" or "sub-group" relating to a free form. Example: 5. While having key down, drag a box around top half of the curve. 6. Select Create/Structure/Group. A new object called "group" appears in myour Select window. 7. Select a modification function, for example Modify/Linear/Rotate, and modify the "group". Only the points in the "group" are affected by the modification action while the rest of the curve remains unchanged. 8. When the modifications are complete and you no longer need to reference the particular "group" that you have defined, use Modify/Hierarchy/ Delete to delete the "group". This example demonstrated how to create a sub-group of a freeform, Groups are "objects" in a hierarchy and they can be saved along with the freeform object. Also, you can modify groups with all the modification functions, Groups can even be animated: for example, the action of a mouth forming words could be the metamorphic between "mouth" sub-group key shapes of a "face" freeform! @endnode @node "T4.1.2" @title "Chapter 4 MODELLING" 4.1.3 Freeforms as Levels In the previous example "Selecting Points", the technique of creating groups consisting of points of a curve was explained. The usage of a group in many cases can be temporary and its modification straight forward. Attention to its position in hierarchy was not of great importance. However all freeforms can contain hierarchical sub-structures in the same way as levels. The main intention for this feature is for storing groups related to the freeform. If groups are multi-selected along with their parent freeform, and a modification is applied , then the points of the group will be modified at least twice; once for the freeform and once for the group itself. If the groups are placed within the parent freeform then accidental multiple-modification can be controlled. Secondly, it is natural to put sub-groups of a freeform under itself in the hierarchy. The following examples of freeform surfaces will demonstrate how to use this feature. @endnode @node "T4.1.4.1" @title "Chapter 4 MODELLING" 4.1.4 Freeform Surfaces REAL 3D includes a set of powerful functions which can create point editable freeform meshes from curves. The program supports 3 mesh classes: open meshes, cylindrical meshes, and tours meshes. A mesh surface consists of a regular grid of curves which usually shows the shape very clearly. The regular representation also allows some special surface manipulation techniques such as "remapping" which is described later. Mesh objects are always hollow. This means that you can use the Boolean operations to cut them, but you cannot use them as tools to cut with. Freeform surfaces are similar to curves in the sense that the actual point data defining the mesh can be "interpreted" or "evaluated" in several ways such as: - Polygonal surface - Phong shaded surface - Cubic B-Spline surface The first two produce the same shape, although their shading is different. B-Spline surface approximates the control polygon mesh in a similar way as B-Spline curve approximates the control polygon: the result is a strongly "smoothed", nicely curved surface. You can control the evaluation method (the "type" of mesh; polygonal, phong, b-spline) using Modify/Freeform/ Type function. 4.1.4.1 Example: Creating a Simple Mesh The easiest way to produce a freeform surface is to use Create/Freeform/ Mesh function. This function produces an open, rectangular mesh with the desired control point resolution. To make the tutorial example more interesting, we will experiment using a freeform as a level as described earlier in chapter 4.1.3, "Freeforms as Levels". 1. Hit d to open Drawing settings requester, deselect "Knots" and "Curve", select "C, Polyg.", and exit the requester using the OK gadget. 2, Take a top view - z - and select Create/Freeform/Mesh. 3. When REAL 3D asks the resolution of the mesh, suggesting 8*8, click OK. 4. Shape a square in the same way that you would create a rectangle (remember: two separate clicks on opposite corners- do not "drag" it!) 5. REAL 3D creates a primitive "mesh". Double-click it on the Select window, and you notice that it becomes the current level even though it is a primitive. 6. Next create some subgroups, this time by using the quick keyboard method. Press the keys and drag a box around every 3rd point of each of the four middle rows, as shown in the Figure @{"T1-1:" system "display dh9:docs/r3ddoc/r3dv2pics/T1-1"} T4-2. Create 3 more similar four point groups. The four groups together should cover the middle square of the mesh. Figure @{"T4-2:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-2"} Sub-grouping a Mesh (PICTURE: T4-2) Now you have created a mesh with a sub-structure consisting of 4 groups. The groups are in the right place in hierarchy, under the mesh itself. Now modify the mesh in the following way: 7. Hit x to get front view. 8. Select 1st and 3rd group and Modify/Linear/Move them upwards. Then select 2nd and 4th group and Modify/Linear/Move them downwards (see the figure below). This will produce a zig-zag of ridges and valleys on the mesh. Figure @{"T4-3:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-3"} Modified Mesh (PICTURE: T4-3) Support example: Examples/Freeform/simple_mesh Now the test mesh is ready for visualization experiments (or lets "see" what we've got). So far the simple mesh looks quite simple indeed, but by adjusting the drawing settings a beautiful B-Spline surface is revealed: 9. Hit d, deactivate "C. Polyg", activate "Curves" and select OK. A smooth surface is drawn. It is "smaller" than the original control point mesh. Remember how B-Spline curves were influenced and controlled by "control points" , B-Spline meshes are controlled in a similar way. It will take 2 additional curves (in both u and v directions) to define a B-Spline mesh than for a similar polygon or Phong shaded mesh. You must be careful when modelling to keep in mind that the mesh shape that you define as a polygon will not yield the same shape if converted to a B-Spline. To get a more detailed visualization of the B-Spline surface: 10. Hit d, adjust both "Curve Subdiv." "and "Surface Subdiv" to 7, activate "Draw v" gadget and select OK. Figure @{"T4-4:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-4"} Dense Wire-frame Representation (PICTURE: T4-4) Now the densely draw wireframe very clearly shows the shape of the mesh These tests have shown some useful properties of B-Splines: - A small amount of control points are sufficient for producing curved surfaces making point editing easy and memory consumption low. - Visualization density is independent of the shape. Next we will get a ray traced visualization of the mesh: 11. Use s to open Render settings requester. Select Environment mode, activate B-Spline->Phong gadget, adjust "Subdivision" to 1 and click OK. 12. Use r to render an image in your view window. The B-Spline mesh is rendered using Phong-shading. This produces a faster preview of the surface and will properly represent the shape of the B-Spline. This technique is an excellent way of getting a quick preview of your B-Spline object. Rendering B-Splines will take more time than a quick Phong shaded representation and this can be used when modelling as a time saving feature. Rendering using Phong shading looks smooth but there may be some visible artifacts, especially the profile of the mesh may look a bit "edgy". The Phong shading quality can be controlled using "Subdivision" gadget in the Render settings: the higher the value, the better the quality, but unfortunately more memory and time is required. The value 1 is usually suitable. To get true high-quality B-Spline shading you can deactivate the "B-Spline->Phong" function gadget and set the subdivision back to 2. The advantage of this method is that it shades with extremely good quality with no "edge stepping", and still does not require much memory. The complexity of the calculations do however involve longer rendering times. Finally, try rendering the mesh in Draft mode. You automatically get shaded polygons in shortest possible time. @endnode @node "T4.1.4.2" @title "Chapter 4 MODELLING" 4.1.4.2 Coplanar Sweeping Another easy way to define a surface is using a coplanar sweep. The surface is obtained by sweeping a curve along another curve. For example, to create "a roll of paper": 1. First define a "profile curve", which shows the intersection shape of the surface. Take a side view (y) and use Create/Controls/B-Spline Knot to draw a straight horizontal line between two points. 2. Then Define a "sweeping curve": Use x to get front view again and select Create/Controls/B-Spline Curve. Then draw a spiral, starting from the point where you see the "profile curve", drawing smaller and smaller circles (see the figure below). 3. Multi-select the two curves and select Create/Freeform/Coplanar sweep. 4. Delete the two curves (the mesh is created and you don't need the original two curves any longer). Figure @{"T4-5:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-5"} Coplanar Sweep (PICTURE: T4-5) Support example: Examples/Freeform/roll_mesh Now lets bend "the paper roll". There is a problem: the profile curve was a straight line, and there are no control points in the middle to bend. You can verify this by activating Drawing Set/Control Polygon drawing gadget and deactivating Curve gadget. Therefore: 5. Select Modify/Freeform/Reparametrize, select "w" gadget and OK. A new curve should appear in the middle of the roll. If not, select the function again and use "h" gadget this time. 6. Take a side view to the roll, select Modify/Bend Global/Move 2D, click at the top end and bottom end of the roll. Then grab the roll from the middle and bend it until the form is suitable. @endnode @node "T4.1.4.3" @title "Chapter 4 MODELLING" 4.1.4.3 Orthogonal Sweeping Othogonal sweep is quite similar to the coplanar sweep. But while moving the profile curve along the sweeping curve, the profile curve is also rotated according to the direction of the sweeping curve. An example - creating a freeform tube: 1. Use y to take a side view, Select Create/Controls/B-Spline Circular and create a 6 point B-Spline circle (the profile curve in this example); the size of it defines the radius of the tube. 2. Hit x for front view, select e.g. Controls/B-Spline Knot and draw a sweeping curve, starting from the middle of the profile curve. For best results, draw/modify the sweeping curve so that the profile circle is perpendicular to it at the beginning (see the figure below). 3. Multi-select the profile curve and the sweeping curve, FOLLOW THIS SELECTION ORDER. Order is important Deselect all objects, press , click the profile curve on Select window, then click sweeping curve, then release . 4. Select Create/Freeform/Orthogonal. Figure @{"T4-6:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-6"} Orthogonal sweep (PICTURE: T4-6) Support example: Examples/Freeform/orth_sweep It is important that you place the profile curve at the beginning of the sweeping curve, orthogonally to it (see the figure above) because the profile is swept relative to the initial position. If the radius of the tube seems to vary too much, delete the mesh and then use Modify/Freeform/Reparametrize to increase the points on the sweeping curve control polygon before applying the orthogonal sweeping again. @endnode @node "T4.1.4.4" @title "Chapter 4 MODELLING" 4.1.4.4 Rotate - Creating a Wine Glass Rotation-function is a special case of orthogonal sweep: the sweeping curve is circular. We use the classical example of creating a wine glass for the demonstration: 1. Hit e to get a good orientation. 2. Select Create/Controls/Axis and draw a vertical line on the window. The length of the line does not matter, except that a long line is helpful when drawing the glass profile. 3. Select Create/Controls/B-Spline curve and start drawing the profile curve from the middle of the inner surface of the glass (that point is on the vertical axis). Shape the glass profile upwards, then down along the outer surface of the glass, and finally pull the curve back to the axis (see the figure below). 4. Multi-select first the profile curve, then the axis, in this order. 5. Select Create/Freeform/Rotate. When REAL 3D asks "Subdivision", enter 6 and hit OK. Figure @{"T4-7:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-7"} Wine Glass (PICTURE: T4-7) Support example: Examples/Freeform/wineglass The rotation produces somewhat thinner glass than the original profile curve. You can compensate for this easily by taking a top view and using Modify/Linear/Size 2D to increase the diameter of the glass until it is suitable. Also, increasing the subdivisions has a similar effect, but is not wise to use too many control points which will consume extra memory for this simple shape. @endnode @node "T4.1.4.5" @title "Chapter 4 MODELLING" 4.1.4.5 Swinging Swinging is a generalization of the previous rotation function. It inputs a swinging curve, which scales the radius of the rotated profile curve or moves it. An example of applying swinging is the creation of a spiral shaped surface as shown in the Figure @{"T4-8:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-8"} 1. To make accurate modelling easier, select View/Grid/Snap to Grid; also, hit e to reset the scale. 2. Use Create/Controls/Axis to draw a vertical line on the display. Modify/Properties/Name it "axis". 3. Select Create/Controls/B-Spline Closed and draw a low rectangle to the left side of the axis. Use double clicks in each corner, to get suitably rounded edges. Modify/Properties/Name the curve as "profile". 4. Take a top view by hitting z. Then select Create/Controls/B-Spline Helix, set "Subdivision" to 24 and "Angle" to 24 (this will give about 4 revolutions). Then shape the helix around the axis; the exact size of the radius does not matter. Modify/Properties/Name the helix as "swingcurve". 5. Use to place the "cursor-hot-point" at the center of the helix. We need the "cursor-point" to define the center of the helix so that we can easily define the bending axis for a radial bending that we are going to perform next. It is easy to define the 'pint when looking at the helix from the top view, then, when we go to the side view the middle point is already defined. Now hit x. 6. Make sure that the helix is still selected and choose menu Modify/Bend Linear/Size Radial. Then click in the middle of the bottom of the helix, and then in the middle of the top of the helix (so you draw a line along the original axis having the same height as the helix curve). Then "grab" the helix curve at its topmost outer edge point with a click and move the point to the axis by clicking on the axis. The shape of the helix should then become conical. 7. Take a top view again (z) and verify that all the 3 curves are properly positioned. Modify/Linear/Rotate the helix curve so that the lowest point, furthest away from the axis, starts from the profile curve. See the figure below. 8. Then go back to the front view; select Modify/Linear/Extend, click in the middle of the bottom of the helix, then on the top, and extend the helix upwards, until the length is suitable. Also, move the profile curve in direction of the axis until the start point of the swinging curve is at the same height as the profile curve. 9. Multi-select the profile curve, the axis, and the swinging curve, in this order. 10. Select Create/Freeform/Swing&Size. REAL 3D creates a freeform shape. You can then delete the three curves. Figure @{"T4-8:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-8"} Example of Swinging (PICTURE: T4-8) Support example: Examples/Freeform/swinging @endnode @node "T4.1.4.6" @title "Chapter 4 MODELLING" 4.1.4.6 Cross-sectional Surface Construction Surfaces can be constructed by joining cross-section curves together. This is demonstrated by the following example creating a smooth edged "L" shaped logotype letter. The logotype consists of two flat polygons which form the front and back surfaces, and a cylindrical B-Spline mesh which bevels the edges and forms the side surface of the logo. 1. Start the example by resetting the display: Activate the View, hit e, select View/Type/Parallel, and activate View/Grid/Snap to Grid, and select View/Drawing Set/Curves & Knots & C. Polyg. 2. Select Create/Visibles/Polygon and draw a "L" shape (Figure T4-9:). +---+ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | +----------+ | | | | | | +--------------+ Figure T4-9: Front Surface of the Logo is a Polygon 3. The first cross-section curve must match the polygon edge. Because we use B-Splines, we must use triple control points in every corner Select Create/Control/B-Spline Closed, start from top left corner of the polygon and draw the curve along polygon edge clockwise, carefully clicking 3 times in each corner. After defining the points in the last (bottom left) corner, finish the curve by hitting . If you did everything correctly, the new curve travels exactly along the edge of the polygon. Just as we used triple control points to pull a curve to a point, we now use the triple curves to pull a B-Spline surface to a curve! 4. Select the curve and use Modify/Structure/Duplicate twice, so that the result is three identical curves. This triple curve technique is important when modelling with B-Splines and you will probably need it frequently. But now, lets create the next cross- section; a slightly larger rounded B-Spline, around the polygon. 5. Select Create/Controls/B-Spline Closed and start drawing a new curve around the polygon. This time maintain a suitable constant distance from the polygon, say two grid units. Remember this distance: it will be used as a general "rounding" radius during the later steps of this example. To get the best result, use the same amount of control points as in previous curves, three points at each corner, but do not put them at the same positions. Distribute the three points symmetrically around each corner as shown in the Figure @{"T4-10:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-10"} one point 2 grid units before the corner, one at the corner and one point two grid units after the corner (in the Figure @{"T4-10:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-10"} it is assumed that the first three curves were drawn starting from the top left corner). Remember that you can undo points using key. Figure @{"T4-10:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-10"} Fourth Cross-section (PICTURE: T4-10) The 4th curve was drawn to the same plane as the polygon. This will allow the B-Spline surface to join the polygon smoothly and tangentially. The next cross-section will make the surface bend backwards: 6. Use Modify/Structure/Duplicate to create a copy of the 4th curve. 7. Take a side view (y) and move the copy two grid unit backwards. 8. Duplicate the 5th curve and move it again, say, 4 grid units backwards. 9. Duplicate the 6th curve and move it 2 grid units backwards. After steps 5-9, you should have four identical B-Spline curves in a row, as in the figure below. Continue working using the side view in the following way. 10. Multi-select the first three curves (the ones matching the front polygon edge) and Modify/Structure/Duplicate them. 11. Move the three copies 2+4+2 = 8 grid unit backwards, to the same position as the backmost curve is located. 12. Select the front polygon, duplicate it, and move it to the back as well. 13. Use x to go back to the front view and verify that all the items are correctly centered around the first polygon. 14. Now multi-select all the cross-section curves in their creation order (do not include polygons) and select Create/Freeform/Build from Curves. 15. If the result seems to be OK, delete the curves. Figure @{"T4-11:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-11"} Side View of the Section Curves and the Final Surface (PICTURE: T4-11) Support example: Examples/Freeform/Logo. When using cross-sectional surface construction, for best results, each curve should have the same number of pints and the curves should be oriented in the same direction (not one clockwise and one in a counter clockwise loop). Also the start points of the section curves should be located along the same longitudinal direction. @endnode @node "T4.1.4.7" @title "Chapter 4 MODELLING" 4.1.4.7 Mesh-Pixel Tool When using the second variation of the pixel tool, Mesh-Pixel Tool, the bitmap is taken as a height map when creating a free form surface. The brighter the pixel colour, the higher the peak there will be on the correspnding place of the surface. For example, you can create a free form ground surface for a landscape: 1. Start a paint program and draw a small (try 20*20 pixels) height map or edit a digitized map image (remember that the intensity of the colour red defines the height of the bump). Save this map as a brush to the ram disk. 2. Choose Create/Freeform/Mesh-Pixel Tool. Now the file selector is displayed, select the brush you saved to ram disk. 3. Next, you can define the size and location of the object mesh that will be created by defining a rectangle in a View Window. The object is then created. @endnode @node "T4.1.5" @title "Chapter 4 MODELLING" 4.1.5 Modifying Curves and Meshes The functions of the menu Modify/Freeform can be used to manipulate free form objects in many ways. Remap function is a very powerful feature of REAL 3D. With it, you can modify the number of the points with which a curve or a mesh is represented. Increasing the point number makes it possible to add more detail to the shape. The basic form can first be roughly defined then the remap function can be used to add more points and thus obtain more control over local details. The ability to decrease the point number is useful if a shape must be substantially altered, a small number of points is easier to control. Remember of course that if you first decrease the point number and then increase back to the original number, you do not always get the same exact shape. A small number of points cannot contain the same amount of detail as a larger number of points. To modify the pointnumber of a mesh: 1. Select the mesh. 2. Select Modify/Freeform/Remap. 3. REAL 3D displays the current counts and requests the new point counts. Define suitable numbers and click OK. Another reason for decreasing the point count is related to memory: if you cannot render a free-form surface because of lack of memory, you can reduce the number of points in the scene until the rendering succeeds. Modify/Freeform/Reparametrize is a special case of Remapping. It can only increase the point count-it doubles the amount of control points in each dimension, but it does this so that the shape does not change. Normal remapping may cause minor changes. The distribute-function re-distributes the control points of a curve evenly along the curve length. This can be used to smoothen the shape of a curve or a mesh. For example directly hand drawn or bitmap vectorized curves tend to have unwanted irregularities; these can be eliminated with this function. (Another way to do this kind of modification is to Remap the point count down until the shape is smooth). If the object to be re-distributed contains relatively few points, the operation may change the shape quite radically. The results of distributing a mesh which is densely populated with points are easier to predict. When creating a curve, the curve can be closed using the key option. An open curve can be closed afterwards using the closing function: 1. Select the curve. 2. Select Modify/Freeform/Open/Close. 3. Select "u" gadget and hit OK. Note that you can use the same function to open the curve; by deactivating the "u" gadget. In a similar way, you can use the function to change the mesh type between open, cylindrical, and torus types. It is possible to connect two curves together using the Concatenate function: 1. Select the curves that you want to concatenate (join). 2. Select Modify/Freeform/Concatenate. A new curve is created; original curves remain unaltered. If the result is not what you wanted, just delete the new curve and check the following things: - If the second curve was concatenated (joined) to the beginning of the first, multi-select the curves in the opposite order before applying the concatenate function. - If the concatenation (joining) occurs from the beginning of the first curve, not from the end, select the first curve and use Modify/Freeform/ Swap Direction function to reverse the curve before concatenation. Similarly, if concatenation uses the wrong end of the second curve, swap the direction of that curve before joining. In the same way, you can concatenate meshes. But with meshes there are even more ways to do the concatenation. Each mesh has four sides instead of two ends. The additional control is provided by "Exchange u&v" function, which exchanges the two mesh dimensions internally. In general, this u & v orientation and evaluation direction of freeforms play quite a big role in freeform modelling. When you activate View/ Drawing Set/Knots gadget, REAL 3D displays u & v symbols and arrows on curves to assist you. Many freeform surface manipulations are easier to perform by splitting the surface back to curves.The curves can then be manipulated and then surfaces can be rebuilt from curves. The menu Modify/Freeform/Surf. to Curves performs this task. You can control the direction in which the surface is split into curves by using Exchange u&v function. For example, to break a mesh into two: 1. Select the mesh. 2. Select Modify/Freeform/Surf. to Curves; the curves are produced, and you can delete the original surface. 3. Multi-select the first half of the curves and use Create/Freeform/Build from Curves function. Then select the rest of the curves and apply "Build from Curves" again. You may also include the "break-point curve" in both halves or even duplicate it twice to get a triple curve before joining the curves. This will help to close the gap between the surface halves when using B-Splines. Another example is removing a point from a mesh. To do this, you must remove the whole curve containing the point: 1. Select the mesh and apply Freeform/Modify/Surf. to Curves. 2. Delete the curve that contains the desired point. 3. Join the curves back to form a surface. 4. If operation was successful, delete the original mesh. @endnode @node "T4.1.6" @title "Chapter 4 MODELLING" 4.1.6 Bending Functions In addition to conventional modification functions such as move, rotate or size, REAL 3D contains a large set of nonlinear functions for freeform deformations. The first group of such functions consists of "bending" functions. There are 24 different bending variations available: four different bending functions combined with six different bending mode combinations. All the bending functions of the Modify menu first require an input line (curve) called the "bending axis", which defines the bending interval. The following picture illustrates the differences between the bending functions: Figure @{"T4-12:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-12"} Bending (PICTURE: T4-12) In the picture, the arrow on the left (1-2) is the bending axis, and the straight cylinder is the original object. The small arrow (3-4) defines the amount of bending. The lines 1-2, and 3-4 are defined by clicks. Local bending affects the object only inside the bending interval. Global bending affects the object everywhere. End point bending bends the object so that in the start point of the bending axis the bending effect is zero and the effect grows to the direction of the axis. Linear bending is the skew transformation. (a straight bend originating from the end of the cylinder defined by the point "1".) For example, to bend a small curve to a tube mesh: 1. Select the mesh. 2. Select Modify/Bend Local/Move 2D. 3. Draw a line in the middle of the tube and to the direction of the tube; the length and position of the line defines the interval (the interval is where the bending affects the object). 4. Grab the object by clicking with the left mouse button. 5. Move the mouse to the direction you want to bend the object. 6. When the result is OK, use the left mouse button again. Each bending method includes two sets of bending options. If the "Move" version is used, all the points of the object modified are moved as much to the bending direction regardless of the distance from the point to the bending axis. If the option "Size' is used, bending becomes multiplicative: the further the point lies from the bending axis, the more it is moved. The following picture demonstrates this: Figure @{"T4-13:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-13"} Bend&Move vs Bend&Size in Local 2D Bending (PICTURE: T4-13) When using the Bend&Size mode, the distance from the bending axis to the object is important. For example in Fig T4-13, the bending axis was positioned precisely to the left edge of the cylinder half, therefore that edge of the object remained the same in the modification. Also the distance from the point which you "grab" to the bending axis is important: the greater the distance, the more accurate control you have. If the point lies on the axis, moving the pointer even a little bit produces a dramatically change in the shape. The second set of bending options (3D) defines how the coordinate direction (the plane perpendicular to where the bending is defined - could also be called the depth coordinate direction) is taken into account in the modification. When the "2D" bend function is used, the bending affects the object on a 2D plane and the depth coordinate is not considered. The option "3D" affects the object in the depth direction precisely in the same way as . in the direction of the bending axis; the cursor defines the middle point of the bending interval in the depth direction. In other words it affects the object in 3 planes with the "bending axis" defining the center point. The "Radial" option directs the modification radially away from the bending axis. Figure @{"T4-14:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-14"} Bending Examples (PICTURE: T4-14) @endnode @node "T4.1.7" @title "Chapter 4 MODELLING" 4.1.7 Example: Creating a B-Spline Head Use one View window and one Select window for this example. 1. Take a side view (y) and create a profile curve of your face using the function Create/Controls/B-Spline Curve; about 20 points is enough. This function automatically creates triple control points at both ends thus pulling the curve to them. Remember that by using triple control points you can produce sharp edges, double control points produce rounded edges while single control points only pull the curve slightly towards them producing a smooth curve. If the result is not what you expected, use key to delete misplaced points as you are forming the curve. Figure @{"T4-15:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-15"} Face Profile (PICTURE: T4-15) 2. Modify the created profile curve using Modify/Freeform/Move Knotpoint so that it really starts to look like your profile. This function finds the nearest knot point of the curve (or mesh) and allows you to move it. 3. Create six more cross-section curves each defining a new radial "slice" so that the left side of the head is fully represented. Figure @{"T4-16:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-16"} Cross-sections. (PICTURE: T4-16) 4. Take a view from above. Select all curves except the first, set "Project/Macro/Record", rotate the curves about 25 degrees, end macro recording and select Project/Macro/Spread Current. Hand-adjust the first curve and make minor hand adjustments to the other curves if necessary. The result should be similar to Figure @{"T1-1:" system "display dh9:docs/r3ddoc/r3dv2pics/T1-1"} T4-17. Figure @{"T4-17:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-17"} Cross-sections, Top View (PICTURE: T4-17) 5. Select all curves in reverse order, duplicate them, and "mirror" them in order to create curves for the right side of the head. Figure @{"T4-18:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-18"} Cross-sections Doubled and Mirrored. (PICTURE: T4-18) 6. Select all curves and execute Create/Freeform/Build From Curves. This creates a B-Spline mesh which interpolates through all selected cross-section curves. Delete the curves. (NOTE: you can save the project at any time to be able to start again from any point) 7. Now comes the trick! There are some advantages in creating the head using vertical cross-sections (for example, you only have to create 50% of the curves needed for the head, because the head is symmetrical). However, some details on the face can be defined more easily using horizontal cross-sections. So swap the surface parametrization using the function Modify/Freeform/Exchange_u_&_v and then execute the function Modify/Freeform/Surf.to_Curves. Delete the mesh and modify the horizontal cross-section curves (you may have to close them if they are open, using Modify/Freeform/Open/Close). Figure @{"T4-19:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-19"} Horizontal Cross-sections (PICTURE: T4-19) 8. Now create the head again with Create/Freeform/Build_From_Curves, Modify/Freeform/Exchange_u_&_v, Modify/Freeform/Surf.to_curves, edit vertical cross-sections and so on until your B-Spline head is perfect. 9. You can use more dense wire-frame representation to render the scene by setting the Surface Subdiv field in the View/Drawing_Set requester to 5. Figure @{"T4-20:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-20"} Dense Wireframe of the Head (PICTURE T4-20) 10. Finally you can render an image: select the menu View/Render/Settings, set Mode to LAMPLESS, Subdivisions to 1 and render the head. Figure @{"T4-21:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-21"} Ray Traced B-Spline Heads (PICTURE: T4-21) Support example: Examples/Freeform/Head @endnode @node "T4.2" @title "Chapter 4 MODELLING" 4.2 BOOLEAN OPERATIONS Boolean operations offer one of the most powerful means of creating and modifying objects. Let's consider a situation where an engineer cuts an object made of pine with a tool that has just been painted. Since the paint on the tool is still wet, it sticks on the object and the cut surface is "painted" with the wet paint. The engineer notices this and replaces the tool with another clean tool, the new cut surface is clean showing the beautiful texture of the pine. The Boolean operations of REAL 3D work in a similar way. All Boolean operations are executed in the same way. 1. First select an object to be operated on. (Work piece or target) 2. Then select an object to operate with. (the Tool) Note: This is a multi-select process where the order of selection is important. Target first, then with the key down click on the tool. 3. Choose an operation. Both "parameters" of the Boolean operation should be selected when you execute the operation. A simple example of a object created with a Boolean operation is a lens. A lens can be thought of as the intersection of two partially intersecting spheres. 1. Create a sphere and Modify/Properties/Name it as "lens". 2. Modify/Structure/Duplicate the sphere and move the copy to the right so that the spheres are partially intersecting (see the figure below). 3. Use modify/Structure/Name to rename the copy as "tool". 4. Select the first sphere (lens). 5. Press down and select the second tool sphere so that the both spheres become selected.(multi-select) 6. Choose Create/Boolean/AND. The resuming object will be the part of the work piece that is inside the tool. It is a lens. In the View windows there are still two partially intersecting wireframes of spheres visible. Therefore: 7. Select the menu Create/Boolean/Rethink. This creates a new wireframe representation for the resume of the Boolean operation. If you look at the Select window, you can see that the two objects have been replaced with a new level having the name "lens (A)". The symbol (A) shows the object type, Boolean AND. If you render your creation, you will notice that you really have created a lens shaped body. If you change the material of the lens to glass, it can be used as a magnifying glass! The results of different Boolean operations between the two spheres are: Figure @{"T4-22:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-22"} Boolean Operations (PICTURE: T4-22) OR is the default operation, which is executed if no other operation is specified by the user. In other words, when you create objects, you add matter from one to the other. Note: If you position two objects in OR operation so that they partially intersect, their materials will not fuse. What happens is that REAL 3D will automatically remove material from the second object to make room for the first object. Let's continue experimenting with the lens object. Select the new level created with the Boolean operation and select Modify/Properties/ Attributes. The AND gadget on the top right corner of the requester is set, and OR gadget is unset. If you double-click the "lens" level on the Select window to make it the current level, you will find the two original spheres under it. These observations reveal the nature of Boolean operations in REAL 3D: again, everything is based on hierarchy, and a Boolean operation is just a hierarchy level. The objects used in these operations can be complex ones with many levels of hierarchy, and they can contain objects that resume from previous Boolean operations. This means that instead of using the procedure described above you can also make Booleans by adjusting the "attributes" of the level. When you create a new level, its type is by default OR, but if you want to do intersection instead of union you can change it to AND using Modify/ Properties/Attributes function. After that, just add the parameters (the target and tool) under the level. To modify the lens further, we can cut an oval hole through the lens: 8. Make the boolean AND level "lens" the current level. 9. Create a cylinder and stretch it to an oval form. 10. Locate the cylinder so that its axis goes through the focal points of the lens (see the figure below). Make sure that the cylinder is long enough to pass through the whole lens. The hierarchy of the scene is now the following: Root lens(A) lens tool cylinder Now render an image of the object. You will notice that there is no lens with a hole but rather a hole without a lens! All right, actually one thing was forgotten deliberately, namely inverting the volume of the cylinder. The resume was the intersected volume inside all three primitives. To get the correct result: 11. Select cylinder. 12. Select Modify/Properties/Attributes. 13. Activate "Inverted" gadget and click OK. Now render the object again to see what was originally expected. If a member of a Boolean operation is inverted, the exterior of it is used to intersect other objects. In other words, inverted objects cut material in the volume that they occupy leaving untouched the volume exterior to them. Figure @{"T4-23:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-23"} A Lens with an Oval Hole (PICTURE: T4-23) The object volume inversion is handled automatically when you use Boolean AND NOT operation. Then all the objects except the first selected one will automatically get the "Inverted" flag set. Note: As the example already shows, Boolean operations may contain any number of objects. In previous REAL 3D versions, AND was a binary operation accepting only two parameters. In REAL 3D it is possible to execute the Boolean operations so that the tool affects not only the volume but also the surface of the object that is operating on. This is a very useful feature of REAL 3D. For example, if you cut a notch in a pine board using a "shiny reflecting" (material attributes) tool and use AND NOT "with paint operation, you get a "shiny reflecting" notch on the board. Likewise, if you use a red lathe you get a red notch. And if you use a chimney to cut a notch, you get a piece of wood with a notch of brick coating. On the other hand, if you use any of the non painting operations, you get a clean notch of pine on your pine board (the wood texture of the pine board "x-rays" right through the object so that you get a continuity of the texture). In this case the surface of the tool does not affect the object that is operated on. To test this feature: 14. Open palette window (p) and change the current colour to black. Verify the colour selection by pressing OK gadget and close the palette window. 15. Select the cylinder and use Modify/Properties/Colour. 16. Open the Modify/Properties/Attributes requester and activate the "Paints" gadget. 17. Render an image. This time you got a real black hole! You can obtain the same results by using Create/Boolean/AND with Paint or AND NOT with Paint functions directly, instead of changing the attributes afterwards. Finally, we can make a section diagram of the lens by spItting the lens in two, using a plane surface. You are already familiar with the two dimensional plane primitives; circles, rectangles, and triangles. When used in Boolean operations, these plane primitives are not extremely thin two dimensional surfaces, but, on the contrary, infinitely thick halves of space. In other words, a plane divides the space into two halves and involves one of these halves. The wireframe representations of plane primitives have a small peak that tells you which side of the plane is defined by the primitive. If you set a plane so that it goes through the focal points of a lens, and then execute AND NOT operation, the half of the lens that is on the same side of the plane as the spike is removed. The AND operation would preserve the half that is on the spike's side of the plane. To remove half of a lens: 18. Make "lens (A)" the current object. 19. Create some plane primitive e.g. a rectangle and place it so that it goes through the focal points of the lens. 20. Render. Support example: Examples/Objects/split_lens Figure @{"T4-24:" system "display dh9:docs/r3ddoc/r3dv2pics/T4-24"} A Split, Drilled Lens. (PICTURE: T4-24) Now you have made half a lens with an oval hole through it. To REAL 3D it is a very simple object. You can, for instance, stretch it if you want. In a similar way you can create more and more complex objects which can be saved to disk, and used to create new objects, As you complete useful new objects and tools, using the program becomes easier and faster. When you execute a Boolean operation, the hierarchical structure of the object is modified to reflect the resuming object. If you move "lens (A)" object, you notice that the "hole" faithfully follows the cube when you relocate the cube. On the other hand, you can select the hole and make it bigger by re-sizing the cylinder and immediately get another result. Or you can even create animations where the hole moves, or where the progression of the hole being drilled is animated, or an object being turned in a lathe etc. can be demonstrated. Hierarchical implementation of Boolean operations makes all this very easy in REAL 3D. @endnode @node "T4.2.1" @title "Chapter 4 MODELLING" 4.2.1 Wireframes of Booleans Wireframe representation of Boolean operations do not necessarily correspond to the true shape of the object. The easiest way to modify the wireframe of a boolean operation is to use Modify/Boolean/Rethink functions: 1. Select the object to be modified 2. Select Create/Boolean/Rethink All. 3. If the resume is not good enough, use the Undo function. This operation makes all wireframe line segments outside the volume of the selected Boolean object invisible, usually giving a better representation. The result of this automatic wireframe modification can then be further improved by hand. Drawing curves and placing them under the Boolean operation level can be helpful, and possibly by making some wireframes invisible. Rethink functions may sometimes leave not enough wireframe. REAL 3D will try to represent the objects with a minimum number of lines. The difference between Rethink and Rethink All is that Rethink All regressively goes through the hierarchy under the selected objects, whereas Rethink considers only the highest hierarchy level of the selected objects. @endnode @node "T4.3" @title "Chapter 4 MODELLING" 4.3 OBJECT AT TRIBUTES You can use the Modify/Properties/Attributes operation to get some information about the objects and to modify this information when necessary. For example: - An object can be made invisible in the editor. - An object can be protected from modifications. - An object can be made infinite by removing so walled standard limits from it. - An object can be made hollow. - The bounding planes, i.e. the surfaces at its ends, can be removed from a hollow object. - An object's ray tracing attributes can be changed: it can be made invisible, non-existent, shadowless, motion blurred or matt shaded in ray trace rendering. - Object volume and Boolean operation properties can be modified (AND/OR type, volume inversion, "Paints" property). To make a cone invisible in the wireframe mode: 1. Select the cone. 2. Choose Modify/Properties/Attributes. 3. Set the WF-Invisible field on. 4. Choose OK. After this the cone is invisible in wireframe rendering, but you can still notice its existence in the Select window and in ray trace rendering. To make a cylinder into a thin walled tube: 1. Select the cylinder. 2. Choose Modify/Properties/Attributes. 3. Set the Hollow, No 1 st BP and No 2nd BP fields on. 4. Choose OK. Note: If the object is not hollow, you cannot remove its bounding planes. Note: When the bounding planes are removed from a cube, the planes are removed so that you can look through the cube in the direction from which the cube was created. The following fields: - No 1st BP - No 2nd BP - Infinite of the Attributes requester affect only primitives: those properties are not inherited in the hierarchy. Conversely, you can make any complex object e.g. "Hollow or WF-Invisible". The "WF-Invisible" function is needed when, for example, the outcome of a Boolean operation needs editing. All unwanted details, like slight roundings of the edges of a cube, should be made invisible to make the wireframe rendering faster. The "Protected" flag locks the object so that any modification does not affect it. This can be useful in animations for example. @endnode @node "T4.3.1" @title "Chapter 4 MODELLING" 4.3.1 Infinite Primitives REAL 3D includes many primitives which can be expanded to infinite shapes in a natural way. For example, a cylinder is a body bounded by a cylindric surface and two plane surfaces. Such primitives can be made "Infinite" using Modify/Properties/ Attributes/Infinite gadget. Applying this function makes three dimensional primitives infinitely long and plane primitives infinitely wide. To create an infinitely long cylinder: 1. Create a cylinder. 2. Choose menu Modify/Properties/Attributes. 3. Set the Infinite field on and choose OK. The wireframe of the cylinder is not changed, but if you render an image of the object you will notice that it is infinitely long. Plane primitives (polygons, disks, and ellipsoids) are automatically made infinite when they are used in Boolean operations, unless their "Hollow" attribute is set; then they act as two dimensional thin surfaces. @endnode @node "T4.4.1" @title "Chapter 4 MODELLING" 4.4 SPECIAL FUNCTIONS 4.4.1 Use of Animation Methods for Creation Read this Chapter 4.4.1 after getting acquainted with the basic features of the REAL 3D animation system. The flexible animation system of REAL 3D can be used as a modelling tool in many different ways. The following example, creating a chain of objects demonstrates this: 1. Create an object, for example a cube. 2. Select the cube, then select menu Animate/Create/Direction, and draw a path starting from the cube. 3. Select Modify/Properties/Animation, choose "CREATION" method from the method list and click OK. 4. Find the original cube from the hierarchy (it is under the level whose animation type you just changed to CREATION) and select it. 5. Select Modify/Properties/Tags, click ADD, type "SCRE I=1", hit and select OK. This adds the creation condition tag to the cube. 6. Open Animation window, set "Resolution" field to the number of cube copies you want to create along the path and play the animation. 7. Delete the creation method level. Support example: Examples/Objects/cubesource. 4.4.2 COG Modifications In addition to ordInary "linear" modifications found in the menu Modify/ Linear , REAL 3D includes two sets of "component" modifications: "COG" modifications and "About COG" modifications. For example: 1. Use a macro to create a row of cubes. 2. Multi-select the cubes, select Modify/About_COGs/Size 3D, click in the middle of one of the cubes and resize it. The rest of the cubes are resized similarly around their middle (COG) points. 3. Select Modify/COGs/Rotate, click in the middle of the cube row and rotate it. The cube row is rotated, but each cube maintains its local orientation. Figure @{"T1-1:" system "display dh9:docs/r3ddoc/r3dv2pics/T1-1"} T4-25: COG modifications (PICTURE: T4-25) For example, you can use About - COGs/Size 3D to resize the objects you have used in Object_Pixel Tool, or leaves of a fractal tree (it is a good idea to use Modify/Properties/COG function to set the COG to a suitable position before using the object with the above mentioned tools; this makes after-processing easier and more controlled). @endnode @node "T5" @title "Chapter 5 RENDERING" Chapter 5 RENDERING ------------------- In this chapter we will learn about the rendering engine which is a very flexible and sophisticated part of REAL 3D. This part of the software renders images of your scenes using the so called ray tracing principle. The surfaces of the objects that you have created in the editor are coloured by creating a mathematical model of reality around them. In this model light rays are emitted from light sources and then reflected from object to object until they hit a place which causes vision: your eye (the camera). You will find that rendering in REAL 3D is very flexible and quite easy to learn. From simple draft mode to full ray tracing, you are able to employ the most suitable modes for your rendering needs. The first tutorial chapters mainly used draft rendering mode without colours, now we will explore more exciting rendering modes: To render a ray traced image of a group of different coloured spheres: 1. Create the spheres. 2. Find a suitable viewing point using the cursor keys. 3. Select View/Render/HAM. REAL 3D opens the render setting requester with which you can select: rendering accuracy, picture size, etc. Now change the "Mode" field to "Lampless" and select OK. 4. If you want to save the picture after it has rendered in the HAM window, use Project/Environment/Save Screen function. 5. Use Project/Environment/Close_Current to get back to the original screen, or you could leave the HAM screen open and edit the scene there. You can use m to jump between the screens. Note: If you have started rendering and for some reason you want to stop, select Extras/Cancel All or hit the space bar. @endnode @node "T5.1" @title "Chapter 5 RENDERING" 5.1 LIGHTING SETTINGS The following gadgets of the render setting requester affect the light balance and brightness of the image: Ambient: These gadgets define the amount of diffused reflected light that is present in the scene. A good real world example of a diffuse reflecting surface is a white wall in an unlit room on a cloudy day. In the world of REAL 3D this light is called ambient light. The greater you set the ambient light intensity , the less contrast there is between lit and the shadowed surfaces of the objects. Brightness: The intensities of the light sources can be set to a proper level with the brightness gadget. When you create light sources in REAL 3D, you don't have to pay attention to their brightness since the differences in intensities will be automatically scaled to the appropriate levels. The scaling is based on the amount of light these light sources cast on the scene, the brightness ratios of the light sources are preserved. The outcome of the scaling depends on the value of the brightness control. Overlight: This gadget defines what happens in the bright parts of the picture. If overlight is zero, even the colour of the brightest objects does not turn to white. On the other hand, if you start to increase the overlight value, you get more and more overexposed pictures. Autoexposure: This field sets on the automatic scaling of light sources. Then the brightness of the picture is determined on the overall brightness of the scene. This option can be compared with a automatic exposure function of a camera. This feature is active by default. @endnode @node "T5.2" @title "Chapter 5 RENDERING" 5.2 COLOR/IMAGE SETTINGS Background: These 3 gadgets specify the background colour for the picture. You can set the RGB values by typing them into the numeric gadgets or by using the Colours/Background local menu. Backgr. grad: Selects the second background colour which is used for gradients. Backgr. gradient: When you activate the Backgr. gradient gadget, REAL 3D will automatically render the image using the specified colour gradient as a background. Environment: The environment colour defines the colour of the surrounding "space". Reflected light rays, which do not hit any visible objects, will have this colour. Envir. grad: The second environment colour used in environment gradients. Envir. gradient: When you activate the Envir. gradient gadget, REAL 3D will use a gradient to specify the colour of the surrounding space instead of a fixed colour. The gradient starts from the Environment colour above (at the "north pole") and ends to the Environment gradient colour below (at the "south pole"). The background colours specify an artificial background for the image. The colours do not interfere with the true objects in the scene. The environment colours are the colours which are used in the actual ray tracing calculations. The possibility of specifying these two colour definitions separately gives extra flexibility, but also means that incorrect settings can produce a clearly unrealistic or undesirable results. Therefore, remember the following recommendations: - If the scene contains transparent objects (especially when clip mapping is applied), the environment colour and the background colour should be equal, and neither gradient function should be used. If gradients are required, use e.g. a hollow 3D sphere around the scene with a suitable texture map. - If the scene contains mirror-like objects but no transparent objects, the environment colours and the back ground colours should be equal. You can use the gradient functions if you use them both simultaneously. Other combinations are sometimes useful for effect purposes (e.g. a shiny golden logo type on a black background). Note: The Environment colours have importance only when the scene contains reflecting/refracting objects. Background colour can also be provided from an image file. This happens by specifying the name of the image file to the Backdrop image string field and by activating the corresponding gadget on the bottom right coiner of the requester. This overrides the colour and gradient settings. The backdrop image always fills the background completely and its size and aspect ratio are adjusted accordingly. Similarly , the "mathematical" environment colour map (a solid colour or a gradient) can be replaced with an image file based environment map. To do this, enter the name of the environment image file to the "Environment map" string field and activate the corresponding "Environment mapping" gadget. The image is mapped using spherical mapping to the surrounding space: the top edge of the image will be mapped to a single point at the "north pole" above, and the bottom edge of the image is squeezed to the "south pole" below. If you have to contrOl the mapping type more accurately, create true 3D objects around the scene (e.g. rectangular walls or a hollow sphere) and texture map them appropriately. Both the Environment map and the Backdrop image can be animated by simply adding an index format string to the name. For example, if the backdrop image name is "images/backpic%d", REAL 3D uses the name "images/backpic0" in the first frame, and increments the index in each frame by one. @endnode @node "T5.3" @title "Chapter 5 RENDERING" 5.3 RENDERING QUALITY SETTINGS The following gadgets of the render settings requester affect image output quality. Anti-aliasing: You can select a suitable level of anti-aliasing using the Anti-aliasing gadget. The effect of this function is that jaggies caused by insufficient picture resolution are smoothed using colour gradients. If the value is 0, no anti-aliasing is done, but if the value is 2 or 3, you get quite nice smooth pictures. The only disadvantage is that rendering gets slower as the anti-aliasing factor increases. If the rendering is done in 24 bit, increasing the factor may give a visible improvement in the picture quality. Normally, there is no need to use a higher anti-aliasing value than 4. The Draft and Outline rendering modes do not support anti-aliasing. Resolution: The resolution gadgets specify the resolution of the rendered picture, that is, how many picture elements are rendered with a single calculated point. This function is useful for previewing. Using lower than 1 by 1 resolution, for instance 2 x 2, speeds up the rendering and gives you a quick visual representation of the scene. Width and Height: It is possible to define the size of the image to be rendered using Width and Height fields. When the rendering output target is a View window, the gadgets only display the current dimensions. When the rendering target is an external screen, the dimensions are truncated to fit the external screen size; smaller sizes can be specified. When the target is a disk file (in IFF/ Targa/BMP formats), the picture size is limited only by the operating system of the Amiga: under Workbench 2.0 or greater the theoretical maximum is 32768 * 32768 pixels. @endnode @node "T5.4" @title "Chapter 5 RENDERING" 5.4 RAY TRACING QUALITY SETTINGS The render settings requester includes some adjustments which control the accuracy which the rendering engine uses in ray tracing calculations. Recursion depth: The recursion depth field defines how far light rays are traced when they reflect from surface to surface. i this field has a value of three for example, then only the first three reflections of any light ray can have any effect on the environment. When an object does not contain any reflecting or transparent bodies this field does not have any meaning. If your object contains transparent and reflective materials, the bigger the value of this field the better and the more realistic the result. Unfortunately , the rendering time may increase dramatically, so it is best to keep it as small as possible. For example, if your target includes one glass sphere, recursion depth of 3 is probably enough. If your model represents two glass balls and you are looking through both of them at the same time, recursion depth must be at least five. Mat. samples: when using non-homogeneous transparent materials, this value defines how densely the material properties are sampled. Usually the value can be zero. Some effects will improve with a value 1. Only some special simulations (e.g. gas clouds) may require higher values. Subdivision: B-Spline shading quality. The default value 2 is suitable for most purposes. The higher the value, the "smoother" and better quality shading, but rendering time will increase. The Subdivision value also defines the subdivision density when converting B-Spline meshes to Phong or polygon shaded surfaces. This happens when the Draft and Outline rendering modes are used or when the B-Spline->Phong gadget is activated. Usually the 0 or 1 level subdivision is sufficient; higher values consume significant amounts of RAM. @endnode @node "T5.5" @title "Chapter 5 RENDERING" 5.5 RENDERING MODES Mode/Draft: When Draft mode is used, rendering is executed using the so called draft mode. Here all the objects are converted to a white basic material which is neither mirror-like nor transparent. It also does not have any texture. The rendering is done using a single light source that is in the same place as the observer. The output is always in grey scale. Draft mode is the fastest ray tracing mode in REAL 3D. Although the speed is partly obtained by simplifying the model, the mode is adequate for many purposes such as; previewing before final rendering, or the representation of technical objects. In the latter example, shadows and reflections may cause unwanted visual confusion. Fast mode, in combination with a high resolution, offers an excellent alternative for producing clear and detailed graphics. Mode/Normal: When the Normal mode is set, a complete model is used. The rendered picture will have shadows, reflections, etc. Mode/Shadowless: In this mode rendering is done as in the previous mode with one exception: the shadows of objects are not calculated. This makes rendering considerablely faster. The mode is especially suitable for animation production. Mode/Lampless: This mode is even faster than shadowless mode. One automatically inserted light source placed at the view point is used. Textures, properties of materials, etc. are all taken into account. Mode/Environment: This mode is almost as fast as the Draft mode. It is equal to the Lampless mode except that the reflection calculations take only the Environment colour/gradient or Environment map into account. The result is that the rendering time is quite constant regardless of the complexity of the scene, typically from 1 to 1 5 minutes per image. Nevertheless, some realism is lost, especially when the scene contains transparent objects. Mode/Outline: the Outline mode renders a contour picture of the object which is a hidden line wire frame image. Note: If you use Normal or Shadowless mode, remember to create a light source to illuminate your object. Otherwise all the objects in your picture would have only ambient light. @endnode @node "T5.6" @title "Chapter 5 RENDERING" 5.6 DITHERING Dithering is a method to increase the number of colours available by mixing existing colours. Dithering works best in high resolution pictures. You can choose between different dithering methods using the Dithering cycle gadget. The first dithering method, None, switches dithering off. The second dithering type, Rnd RGB (Rnd = Random), uses a separate random deviation for each of the R, G, and B components. The third dithering type, Rnd intensity, adds the same random deviation to each colour component. The next dithering method, Fixed rnd int, also adds the same random deviation to each colour component, but the dithering pattern is kept the same in each rendered image. This means that when rendering animations, the dithering pattern does not "move", and delta compression methods work better. This is the default method. Row dithering mixes the colours linewise, not pointwise, thus giving slightly faster rendering and better image compression. Raster dithering mixes the colours using regular geometric patterns. The best one for you depends on the application. Usually, random dithering gives a good impression of "rough" surfaces, whereas no dithering or raster dithering produce "sharper and clearer" images. Line dithering is usually not suitable for interlaced video applications, but it can be used as a "style" effect for printed images. The Dither scale slider can be used to define the maximum amount of colour deviation in dithering. The default value is 64 and the maximum is 256. The higher the value, the more mixed colours you get. Note: That 24 bit rendering output does not use dithering. @endnode @node "T5.7" @title "Chapter 5 RENDERING" 5.7 SPECIAL SETTINGS HL-Shade: This option offers an alternative shading mode. The default shading mode maintains the proportions of the RGB colour signals when calculating different shades for the colour of an object. This principle, which is theoretically correct, does not always produce good looking pictures when using a limited number of colours and outputting the image. This happens especially when colours are not pure, that is, when there are not significant differences between R-, G-, and B- components. HL-Shade uses additive method instead of proportional method: all the RGB- components are changed as many units between consecutive shades of a colour. The original colour may distort, but the result is fine. Pixel h/w: This gadget allows the user to define the pixel aspect ratio pixel height/pixel width for rendering. If a value 0 is given, then the program uses default ratios (for example in LORES-HAM-INTERLACE this default aspect ratio for PAL is 0.5). If a nonzero value is given, then it replaces the default pixel aspect ratios. DOF scale and DOF Strength: These values define the depth of field of the image. If either is zero, the picture will be sharp everywhere (a pinhole camera). The higher the values, the more "blurred" the image you get. DOF scale is a distance-related adjustment: it specifies how quickly the image goes out-of-focus in front of and behind the sharp zone in the scene. 1.0 is a good default value. DOF strength specifies the maximum amount of DOF blur in the image. Typically, the value 2 is quite suitable. Note: Draft and Outline modes do not use the DOF feature. No bgr. antial.: When this gadget is set, REAL 3D does not anti-aliase object colours with the background colour. This is necessary when the computer generated image will be combined with video backgrounds. See also the example "Using Alpha Channel" later in this chapter. Alpha output: Activates alpha channel output. The alpha information can be written to the external screen or to a disk file. See the example "Using Alpha Channel". Field rendering: When this gadget is set, the renderer calculates every odd frame half a pixel lower. This feature is designed for producing the interlaced fields of e.g. the PAL video standard. See the example "Rendering Fields" in this chapter. @endnode @node "T5.8" @title "Chapter 5 RENDERING" 5.8 HIERARCHY AND RENDERING If two objects overlap, then their materials are not blended, but one object replaces the other in the space occupied by both. During rendering, this is significant only when it is possible to see inside the overlapping space, that is, when transparent materials are used (or when a boolean cuts the overlapping spice). For example: if a metal sphere is inside a fog cloud, and the fog cloud has a higher priority, then the metal sphere is not visible. If the priority is reversed, the metal sphere can be seen through the fog. @endnode @node "T5.9" @title "Chapter 5 RENDERING" 5.9 RENDERING A WIREFRAME PREVIEW OF AN ANIMATION As a first example of rendering animations, we will consider the fast wireframe preview. To verify the quality of the motions, you need 25 fps (PAL) or 30 fps (NTSC) playback speed, which is not possible interactively. Therefore, you have to save the wireframe images to disk and then create a delta file which can be played at the desired speed. Do the following: 1. Create/Load the animation. 2. Use Project/Environment/Open screen to open a screen with suitable properties. As this is going to be only a motion preview, we recommend that you use for example 1 or 2 deep HIRES screen. 3. Select Project/Windows/View Borderless; this opens a full screen window. 4. Close other REAL 3D screens and windows. Note: that you can perform the steps 2-4 by replacing the environment (Project/Environment/Replace) with a ready-made wireframe preview interface. 5. Open the animation window and set its gadgets as specified in the following steps. 6. Set Time to zero by: moving the Time slider or by entering the time value to the Time gadget. 7. Select the screen to be saved by clicking the name of the screen you opened in the screen name list gadget (REAL 3D may already proposed the correct screen name on the "Saved" string gadget below the list). 8. Set the Wireframe/Ray trace cycle gadget to "Wireframe". 9. Specify a Screen file name with a full path (e.g. "R3d2:images/ wireimage"). Verify also that the Format string is suitable. The default "%d" is suitable for the REAL 3D deltaconverter. 10. Enter the amount of frames you want to render to the Resolution field. Use the same amount of frames as you plan to use with the final production, for example 200 frames. 11. Activate the Save gadget. 12. Press the play animation gadget "..>|" and wait until the animation is played and saved to the end (you can see it from the time value). 13. Use the Deltaconvert program to create a delta animation as specified in the Appendix "Utility Software". Then delete the original frames and use Delta Play to play the delta-animation. It is strongly recommended that you always create a wireframe preview of your production before final rendering. @endnode @node "T5.10" @title "Chapter 5 RENDERING" 5.10 RENDERING AN ANIMATION When you want to render an animation using ray traced shading, follow the steps of the previous example 5.9, except that in the step 8, select "Ray trace" instead of wireframe. Otherwise the procedure is the same. You can specify the image format to be used by opening a suitable screen. For example, you may open a LORES-HAM-Overscan screen, or a 16 colour HIRES-Interlace greyscale screen. Usually it is best to use one screen with a borderless window as in the previous wireframe example. REAL 3D always saves the whole screen, the contents of individual windows cannot be saved separately. If you want to render small images, open a screen with small dimensions and use a borderless window. For example, to render a shaded miniature-size HAM preview of an animation: 1. Use Project/Environment/Open Screen to open a HAM screen. Set the Width e.g.to 160 and the Height to 128 (or to 100 NTSC) before opening the screen. Then use Project/Windows/View Borderless to open a full screen window. 2. Close other REAL 3D screens and windows. 3. Open the animation window, define the HAM screen to be the saved one, reset the time, specify the screen file name, select Ray trace shading and activate the Save gadget. You may use lower frame resolution this time because the wireframe animation preview has already shown the motions. The purpose of this preview is to check the shading. Rendering one fourth of the final frames is a suitable sample for shade checking. Enter e.g. 50 frames to the Resolution field. 4. Render the animation and Delta convert and then Deltaplay. It is strongly recommend that you always create shaded previews of your productions before final rendering. Using 1/4 of the final frames and 1/20th of the full video resolution, this preview rendering time may be only 1% of the final rendering time. @endnode @node "T5.11" @title "Chapter 5 RENDERING" 5.11 RENDERING TO A FILE It is possible to render an image directly to a disk file. This may be necessary if the image resolution is very high (for example more than normal video resolution). Secondly, this makes it possible to create 24 or 32 bit graphics without having a special frame buffer or other such display device. File rendering is selected by setting the Output cycle gadget to one of the "file" targets. This selects 24 bit rendering and the image is constructed using over 16 million colours. The renderer writes the image directly to disk with the file name defined in the "File" string field and appended by the index specified in the index format string of the animation window. As usual, remember to add a suitable directory path at the beginning of the file name, otherwise the images are saved to the current directory. Note: 24 bit rendering can create large files, for example, a picture with 1024*1024 pixels may require three megabytes. The file format alternatives currently available are: Output/IFF file: The IFF-24 field selects compressed 24-bit IFF ILBM format output in rendering. Output/Targa file: The file format REAL 3D uses is the true colour Targa format which is a popular standard on IBM PC compatible systems. Output/BMP-file: This gadget selects BMP format output which is also a popular format on the IBM PC compatible platform. The following example describes how to render an animation in 24-bit directly to a disk file. 1. Create/Load the animation. 2. Modify the environment for rendering: leave only one View window open and open the animation window. 3. Activate the View and hit s to open the render settings requester. 4. Set "Output" to IFF file. 5. Enter the name for the images to the "File" field. 6. Define the size of the image in the Width and Height gadgets, for example: 736*564 (PAL) or 736*482 (NTSC) pixels. 7. If the default aspect ratio 1.0 is not suitable, enter the exact value to the "Pixel h/w" gadget. 8. Modify other settings to suit and select OK to close the requester. 9. Adjust the camera position and the scale of the View window. The disk file will include exactly the same view of the scene as you see in the window. If you have created a camera object (possibly an animate one), activate the View/Observer/Camera view feature to make sure that the camera settings will be used. 10. Next define the animation window settings: reset the time to zero, enter a suitable amount of frames to the Resolution field, and check the index format string. Select "Ray trace" shading. You do NOT have to specify a screen to be saved, nor a screen file. DON'T activate the Save gadget, unless you really want to save BOTH wireframe images from the screen AND the 24 bit images. 11. Press the "..>|" gadget to render the animation. The essential steps of the file rendering are the steps 4, 5 and 6. Especially remember to check the image size because the Output cycle gadget automatically adjusts. The second important, to avoid double saving, is to not activate the Save gadget of the animation window. Note: The View window displays the contents of the disk file image always in horizontal direction; if the window shape is different from the image file shape, the vertical contents may be different. For example, if your View window has the shape of the monitor display and its width is greater than its height, and you define an image file of 800*800 pixels with the aspect ratio 1, then the file image is a square, and therefore a wider vertical area of the scene is included in the rendered file image. @endnode @node "T5.12" @title "Chapter 5 RENDERING" 5.12 CONTINUING A CANCEELLED RENDERING PROCESS When you start rendering an animation it is a good idea to save the whole project just before pressing the play gadget of the animation window. If you have to cancel the rendering, it is then easy to continue again by reloading the project if necessary. If you have cancelled rendering an animation, but you want to continue rendering: 1. Load the animation (Project/Project/Replace) 2. Open the animation window. 3. If you are using particle animation methods, set the "Play to/Jump to" cycle gadget to "Play to". This is necessary because particle animations must be regenerated frame by frame in order to get a certain state back; you cannot jump directly in time. In other types of animations you can select "Jump to" to go to the desired point in time. 4. Select "Wireframe" shading instead of "Ray trace". 5. Make sure that the "Save" gadget is not selected. 6. Check the index of the last frame that has already been rendered; enter the next index value to the "Frame" field and hit . The animation is played to that frame. Using the wireframe shading, it will get to the desired point quickly. 7. Change "Wireframe" to "Ray trace", activate the Save gadget (unless you are rendering to file, see the example 5.11) and press the play button. You can also save the project at the time the rendering was cancelled, and then reload the project back later and just press the play button to continue rendering. It is usually best to keep a copy of the project in its initial state (particle animations cannot be "rewound" back to the beginning). @endnode @node "T5.13" @title "Chapter 5 RENDERING" 5.13 RENDERING TO AN EXTERNAL SCREEN REAL 3D contains a well designed interface for easy access to frame buffers and other custom display devices directly from REAL 3D. To use custom display devices, you need a special interface library for the particular device. REAL 3D software package contains a collection of such libraries included in the "Accessories" directory. There are more available in Public Domain and from hardware manufacturers. Note: That REAL 3D interface libraries are not the libraries which are written for the display devices themselves: for example, there exist a "harlequin.library", but the correct REAL 3D interface library is called "hr_r3d. library". In the REAL 3D user interface, display devices are accessed using a so called "External screen". When using the external screen, the first step is to install the correct library: 1. Copy the desired REAL 3D interface library from "r3d2:Accessories" drawer to your libs: directory. Of course, the display device itself must first be installed properly. For example, when using Harlequin, install the board into the machine according to the manufacturers directions and copy "harlequin.library" to "libs: directory". Then copy "accessories/hr_r3d.library" to "libs:". 2. Select Project/External Screen/Settings menu in REAL 3D. 3. Type the name of the interface library, e.g. "hr_r3d.library". Note: The library name may be case sensitive! Therefore, use capital letters only if the original name was written in capital letters. 4. Select a suitable saving format. This format is used when you select Project/External Screen/Save or when you render animations with the save option. The default format, IFF 24, is a good choice. Then select OK. 5. Select Projects/External Screen/Open. Something visible may or may not happen, depending on how the display device works. 6. You may try to use Project/External Screen/Set Modes function. If the device supports multiple modes, you should get some kind of mode selector. If something has gone wrong and the external display opening was not successful, you will get an error message telling you that the external screen is not opened. If the opening failed, check the following: - Is the device hardware properly installed - Are all the necessary libraries copied to libs: - Read the readme file of the interface library (check "Accessories" drawer) - Check that you typed the library name correctly, try typing in lowercase letters only. If the opening was successful, you can render to the external screen in the following way: 7. Choose one of the view windows to be used as a handle to the external screen. Open the render settings requester of the view. 8. Set Output cycle gadget to External. Width and Height Gadgets should automatically change to the new dimensions which correspond to the full external screen size. You may change them to smaller numbers if you do not want to get a full screen rendering. 9. Select other rendering settings and select OK. 10. Find a good viewing angle (or camera position) in the view and start rendering by hitting r. The shaded image in eternal screen will contain the same image as the wireframe representation shows in the handle view. If the width to height proportion of the view is different from that of the external screen, both images will show the same horizontal width but the vertical height will differ. To get an exact representation in the View window of the image to be rendered to the external screen, you must have the same width to height ratio. After rendering, you can save the image using Project/External Screen/Save function; this displays the file requester with which you can define a suitable file name for saving. Before saving, you can also choose the image format to be used using External Screen/Settings menu; currently IFF 24, True colour Targa 24, and 32 (alpha included) are supported. The fourth format, Custom, is device dependent. Check the interface library specific docs for more information. Note: That the Save function always saves the full external screen regardless of its contents (partial screen rendering, box rendering, etc.). You can use External Screen/Close function to close the screen when other programs need to access the display device. REAL 3D closes the screen automatically when you exit the program. The Eternal screen library name and other settings can be saved as a part of your real-startup environment. @endnode @node "T5.13.1" @title "Chapter 5 RENDERING" 5.13.1 Rendering an Animation Using External Screen When you want to render an animation to hard-disk using an eternal screen, do the following: 1. Create/load the animation project. 2. Open the external screen as presented in the previous example. 3. To maximize the rendering speed, leave only one view window open and use View/Render/Settings to choose suitable rendering options. Set the Output cycle gadget to External screen. 4. Use External Screen/Settings to select the desired saving format (default IFF 24 is probably OK). 5. Open the animation window. Set the time to 0.0 (default). 6. "Screens" selector of the animation window should contain "External". Click "External" or type the name to the "Saved" string gadget below the screen name list. 7. Activate the Save gadget (unless you are going to single frame record the images directly using a frame command). 8. Verify that the drawing method is Ray trace, not wire frame. 9. Type the full name for file saving (including path) to "Screen file" gadget. 10. Adjust other animation settings (e.g. frame resolution). 11. Press the play animation gadget "..>|". Each frame is rendered first to the external screen, then it is saved to a disk file. The advantage is that you can monitor how the rendering proceeds and cancel the rendering if the result is not expected (we recommend a low resolution HAM preview before final rendering) The disadvantage is that the data transfer to and from the external screen may require extra time where as direct-to-disk file rendering will be a little faster. @endnode @node "T5.13.2" @title "Chapter 5 RENDERING" 5.13.2 External Screen Aspect Ratio The latest interface library versions (v.40) includes automatic aspect ratio support. When you render to the external screen, the pixel aspect is automatically set to the correct value if the render settings aspect ratio field is set to zero. You can overrule this auto-configured value by typing any non-zero value to the aspect ratio field "Pixel h/w". In older libraries (v.36), the default aspect was 1.0. 5.13.3 Other Information The external screen interface is quite general and different interface libraries can work in various ways. Some devices require another monitor, some use the same as the Amiga OS. Usually, one monitor systems work so that when you start rendering the external screen pops up and disappears again when you click it or cancel the rendering. For example, the implementation of a mode query (Set Modes function) and custom format saving can vary; both can be no-operation-at-all functions. These details are usually specified in the interface library documents. At the time of the initial release of REAL 3D V2 there are libraries planned for the following devices: Devices: - Harlequin - VD2001 - DCTV - Impact Vision - EGS - Visiona - Domino - Merlin - SAGE boards - Opal Vision - A-Video - Horizon Note: Most libraries are developed by other programmers. The external screen can be used to also implement the standard Amiga based rendering facilities. For example, it may be a disk file rendering interface with multiple file format support, or just an Amiga screen with desired properties (for example: EXTRA HALFBRITE screen or 5 bit colour LORES screen with custom dithering algorithms). A nice setup using two monitors and an external screen: 1. Change the output target of one of your view windows to External, using Render settings requester. The rendering mode can be Environment. 2. Select View/Drawing Set and set "Ray trc." gadget to activate automatic ray traced shading for the view. Now you can continue using your interface as before and REAL 3D keeps on rendering a new shaded image on the second monitor display, using idle processor time available to do something useful. @endnode @node "T5.14" @title "Chapter 5 RENDERING" 5.14 BOXES With the box functions you can define a specific part of the display to be rendered. The purpose is to allow you to quickly test render only critical parts of the image without having to perform a full page render. It is also possible to first quickly render the picture using a lower resolution, define the boxes, and then render only the boxes using a higher resolution. For example: 1. Create an object. 2. Select View/Render/Settings and set X-Resolution = 4, Y-Resolution = 4, Anti-aliasing = 0, then select OK. 3. Hit r to get a quick render in the view window. 4. Select View/Boxes/Define and shape a rectangle defining a "critical" part of the scene. 5. Select View/Render/Settings, set X-Resolution = 1 , Y-Resolution = 1, Anti-aliasing = 2 and select OK. 6. Select View/Render/Boxes. Only the box area is re-rendered and it is rendered with the higher resolution and anti-aliasing. It is possible to have multiple boxes at the same time. You can modify and delete the boxes individually; REAL 3D automatically names the boxes using their creation order. Boxes/Delete All removes all the box definitions. Box definitions are window-specific: each View may has its own box list. You can also use box function to divide the rendering of an image into smaller sub-images which can be assembled later. This is useful for long rendering times where the process must be cancelled. For example, to render 4 sub-images of a 1024*1024 pixel 24-bit image to disk files: 1. Create the scene and define the render settings for the View window to be used (Output = IFF file, file name etc.) Set image Width and Height to the full 1024*1024 size. Then save the project. 2. Use View/Boxes/Define to define a box on the View. The size and location of the box do not matter. 3. Select View/Boxes/Modify, select the box (there should be only one box) and enter Left edge = 0, Top edge = 0, Width = 512, Height = 512. Then select OK. 4. Render the first quarter of the image using the View/Render/Boxes function. 5. When the image is rendered, select View/Render/Settings and change the file name (for example, add "tr" postfix to it), so that the new image is not written over the first one. 6. Select View/Boxes/Modify, select the box and enter Left edge = 512, Top edge = 0, Width = 512, Height = 512. Then select OK. 7. Render the second quarter (use View/Render/Boxes). 8. Repeat the previous steps for the two last quarters. @endnode @node "T5.15" @title "Chapter 5 RENDERING" 5.15 OBJECT ATTRIBUTES AND RENDERING The object attributes include several features for controlling the rendering of objects. Some of the flags are intended for speed optimizations and some are for special rendering effects. You can set these flags using the Modify/Properties/Attributes function. 5.15.1 Scene gadget The "Scene" gadget of the Attributes requester makes selected objects. Invisible in the first phase ray tracing. This means that you cannot see the object directly, but you can see its shadows, reflections, etc. This may sound a bit strange but consider the following problem: a shiny, golden logo moving in a black space looks good but unfortunately black space produces no reflections! The solution is to create an environment which creates rich reflections for the logo, and then make the environment invisible using the Scene-function. 5.15.2 Backdrop and Matte Objects The "Matte" gadget of the object attributes requester controls "matte" shading of objects. An object having this attribute set is shaded using the background colours. This may sound strange, but actually this feature is very useful when combining 3D computer graphics with video graphics or other 2D graphics. It allows you to create "backdrop layers", as demonstrated in the next example in which a "UfO" is flying around your house: 1. Digitize a picture of your house (use a scanner, video digitizer, or a paint program). 2. Open a suitable rendering screen with a borderless View and a Select window; for example a 16 colour HIRES-Lace screen is suitable. 3. Select View/Observer/Create Camera. Position the camera approximately so that it corresponds to the camera position where the original picture was taken. You may use exact 3D coordinates for this purpose or a cube shape representing roughly the shape of the house so that you can visually adjust the camera position. When the camera is set, delete the cube. The scale should be adjusted carefully to match the camera lens angle. The purpose of this step is get roughly equal perspective in the backdrop image and the true 3D scene. 4. Open the render settings requester for the View and select for example Environment mode. Activate the Backdrop image gadget and enter the name of the picture of the house to the backdrop image field. Then select OK. 5. Hit r to render the view. The backdrop image should fill the display. 6. When the View is rendered, select Create/Visibles/Polygon and draw a polygon along the profile of the house; the polygon should match the shape of the house as accurately as possible. 7. Select Modify/Properties/Attributes and activate the "Scene" gadget for the polygon. Then press OK button to close the requester. 8. Create the "UfO"; a flat sphere is suitable. 9. Hit z to get the top view and use Animate/Create/Rotation to make the UfO rotate around the polygon. 10. Use View/Observer/Observer->View function to get the camera view back. 11. Render the animation. The UfO flies around the house disappearing behind it and then re-appearing from the opposite side. As you see, you can cleverly blur the boundary between true 3D animation and digitized images. It is even possible to synchronize a series of backdrop images with a camera flight, providing that more accurate matte shapes are used. Note: That the Matte object feature is designed to work well with the Alpha channel support: matte objects have a full Alpha transparency. This means that you can use video systems instead of digitized images to get such effects as demonstrated above. @endnode @node "T5.16" @title "Chapter 5 RENDERING" 5.16 OPTIMIZATIONS Rendering time plays a major role in animation production. Time limitations should be considered when you are designing the scene. By default, REAL 3D can simulate reality accurately without compromise. For example, the user does not have to specify that an object casts a shadow onto another object. Normal mode rendering calculates all the shadows automatically and it is up to the user to eliminate objects from shadow calculations to speed up rendering if desired. In general, it is easy to create scenes which require very long ray tracing times. The trick is to adjust your scene so that you take advantage of the time saving features and that you realise the situations that will increase or decrease your rendering time. For example, create one thousand wooden objects and render them, the rendering time may be 15 minutes. Then with one single adjustment in the material editor, make the wood transparent, the scene could take 15 hours. There is nothing mysterious in this, you just asked REAL 3D to do something 100 times more complex. Knowing what is practical and possible and what is not in terms of rendering time is an interesting question and will depend on your hardware and your understanding of the software. Fortunately, it is always possible to manipulate the scene to achieve remarkable time savings. Some 3D animation programs only produce a "scanline" render which is not a full ray trace. This mode is sometimes useful because it can be rendered fairly quickly. In REAL 3D V2, you are able to perform "scanline" rendering if you wish but you are also able to freely adjust the intensity of the rendering to fully suit your needs. 5.16.1 Rendering Mode The most immediate control over rendering time is provided by rendering mode selection as described in the chapter 5.5 "Rendering Modes". Environment mode always renders the scene relatively quickly, rendering time being typically less than 15 minutes per frame. Starting from Normal mode, then trying Shadowless, Lampless and finally Environment mode, you will see the different speeds involved. It is possible to use tricks to obtain extra realism with simple rendering modes. For example, you can use shadow maps to create artificial shadows and texture/environment maps to create artificial but fast reflections; ultimately you can re-create a "Normal mode" using tricks but then the "manual" work required to obtain the extra level of realism may take more time (and especially more effort) than when letting the program render the image with a full level of realism. @endnode @node "T5.16.2" @title "Chapter 5 RENDERING" 5.16.2 Resolution Image resolution is another significant factor affecting the rendering time. If you use PAL resolution of 736*584, the rendered time is guaranteed to be at least 5 times longer than when using a 320*256 HAM screen. Unfortunately it is difficult to reduce the resolution without losing quality. Typically, the maximum time savings obtained this way is of a of magnitude 2. Note: That colour resolution (6 bit HAM instead of 24 bit quality) does not affect the rendering time that much except that a smaller amount of data is faster to save. 5.16.3 Recursion The recursion depth value of the render settings requester affects the rendering time significantly when large areas of the image are covered by transparent objects. When light hits a boundary between two materials it is divided into components, which are studied individually. This results in an exponential growth in rendering time. 5. 16.4 Re-interpreting B-splines If the scene contains B-Spline surfaces, rendering can be accelerated using the B-Spline->Phong function of the render settings requester. This affects the rendering quality, but when the object is simple, an adequate quality can be obtained using a higher Subdivision value. Secondly, you can lower the Subdivision setting for B-Spline shading; often the value 1 is quite sufficient. If the quality requirements or memory limitations do not allow the previous methods, you may try applying Modify/Freeform/Reparametrize to the B-Spline meshes and then rendering the scene with 1 lower Subdivision value. The quality is reasonably maintained but rendering is faster. 5.16.5 Reflections & Not Reflected. The "Not reflected" object attribute is an accurate and efficient way to improve rendering time. You can set this attribute using the Modify/ Properties/Attributes function. "Not reflected" property specifies that an object is not considered in reflection/refraction calculations. You can see the object, but you cannot see it in a mirror or through a glass window. The most typical application for the feature is a scene including one large and complex transparent/mirror-like object. When you set the attribute for the object itself, you can see the rest of the scene in reflections and refractions, but the object does not reflect itself, which can be hard to notice anyway. For example: if you have a large B-Spline modelled statue, say, a human head made of glass, standing on a simple checker floor surface, activating "Not reflected" attribute of the head may accelerate the rendering up to 20 times! This is because the reflection computations consider only the simple floor object instead of hundreds of complex B-Spline patches of the head. Usually every scene contains numerous minor details which are not necessary to be seen in reflections. Making them "not reflected" can accelerate rendering very significantly. It is even possible to add simpler "Scene" objects for creating the reflections and make the actual complex visible objects "Not reflected". @endnode @node "T5.16.6" @title "Chapter 5 RENDERING" 5.16.6 Shadows The "Cast shadows" object attribute makes it possible to define for each individual object or light-source its shadow casting property. Rendering time can be shortened significantly using this feature. You can access the feature using Modify/Properties/Attributes function; Note: That "Cast Shadows" property is set by default and you can unset it to obtain the optimization. If a visible object has this attribute unset, it does not cast a shadow at all. You can eliminate the shadows from small details of a scene and achieve remarkable time savings that way. For example: if you have a detailed model of a house, it may be enough that the walls cast shadows, it may not be necessary that doors, windows and other smaller parts cast shadows, too. This simplification may reduce the number of objects considered in shadow calculations to a small fraction. Also, sometimes the user may know that an objects shadow does not fall within the scene and therefore it is not necessary to cast the shadow. The program cannot understand the contents of the scene and do the optimization automatically. For example, if you create a relatively smooth and low fractal landscape surface and the light falls from above, the ground surface cannot cast any shadows on any object, although trees and other objects may cast shadows on it. In this case, the only consequence of clearing the "Cast shadows" attribute of the ground is much faster rendering, no shadows are lost. Secondly, if a light source has the attribute unset, no shadows are generated from that light source. You can use this feature to add numerous light sources to a scene to get complicated lighting effects, and still have reasonable rendering times. Non-pointwise light sources, which produce smooth shadows, usually slow down rendering. The basic rule is that generating smooth shadows with the "Lightsamples" value of 1 will triple the rendering time. Therefore, be careful in your application of this effect which admittedly increases the photorealism, and use the lowest possible value producing sufficient quality. 5.16.7 Other Optimizations - Use quadric primitives and compound tools instead of free-forms whenever possible. - Motion blur is a nice effect, but it is one of the most time-consuming rendering features. - Anti-aliasing level 3 is usually sufficient. Textures with strong colour variations combined with a high anti-aliasing level may slow rendering. @endnode @node "T5.17" @title "Chapter 5 RENDERING" 5.17 USING ALPHA CHANNEL When you want to render images using the Alpha channel support features of REAL 3D, do the following: 1. Create the scene. If the scene includes transparent objects, you may define a non-zero alpha level for them using the Modify/Properties/ Alpha Channel function. For example, a glass object may have an Alpha value 128. The higher the Alpha value, the more you see through the object when the image is combined with another images (e.g. live video background). 2. Prepare a View window for the rendering (camera position etc...) 3. Open the render settings requester and select Targa file output. Specify the file name. Then activate the "Alpha output and "No bar. initial" gadgets. Use any rendering mode except Outline or Draft. Using background gradients and backdrop images do not make much sense because the background will have full Alpha transparency. 4. Start rendering. Alternatively, you can render to the External screen; REAL 3D can write the Alpha information to the output target. Of course, the External screen device must have the Alpha channel feature. Remember to select "Targa+A" saving mode (Project/External Screen/Settings) before saving the image from the External screen. 32-bit true colour Targa format uses four bytes to store each pixel of which one byte is for Alpha information. This means that the Alpha transparency can be expressed using 256 levels. Note: That the anti-aliasing algorithms anti-aliase the Alpha information as well. This means that when you combine computer graphics with a live video background, the edges of objects in computer generated images are smoothly blended to video images. Also motion blur and depth of field blur work correctly: blur against background is partly Alpha transparent. It is usually important to select "No bgr. antial." gadget when using Alpha channel. That gadget instructs REAL 3D not to anti-aliase with the background colour. Otherwise the edges of objects get influenced by the background colour. For those users who do not have a frame buffer with the Alpha channel support, there is another method available for using Alpha transparency information. This method is based on 1-bit mask images. To use this technique: 1. Create the scene. This time mediumlevel alpha transparency does not have much significance (any non-zero value will be fully transparent). 2. Prepare a View window for the rendering (camera position etc...) 3. Use the render settings requester to select the IFF file output. Specify the file name. Then activate the "Alpha output" and "No bgr. antial" gadgets. Use any rendering mode except Outline or Draft. 4. Start rendering. REAL 3D renders two images of each frame, one 24-bit image and one 1-bit mask image. Both images have identical resolutions. @endnode @node "T5.18" @title "Chapter 5 RENDERING" 5.18 RENDERING FIELDS When very smooth animation is required, 25 frames (or even 30 fps) may not be enough. The extra smoothness of motions can be achieved by showing a new image in each video field. The PAL system, for example, shows 50 individual fields per second. Nevertheless, because of the interlaced nature of the PAL system, each field includes only one half of the vertical picture lines. Therefore, rendering full video resolution images for field-rate recording means wasting one half of the rendering time and picture information. REAL 3D includes a special function for more efficient field rendering. For example, if you want to render an animation using a HIRES-Interlaced Amiga screen mode: 1. Create the animation. 2. Select Project/Environment/Open Screen and select a suitable HIRES screen mode. Do NOT select an Interlaced screen mode. After opening the screen, open a borderless View on it. 3. Open the render settings requester for the View window, and define normal settings as you wish. 4. Activate the "Field rendering" gadget. 5. Render the animation. If you want to render fields using the External screen, its library must support non-interlaced (or vertically halved) resolutions. When rendering fields to disk files, do the following: 1. Create the animation. 2. Open the render settings requester for the View window, which you are going to use in rendering. Set the output to a file and define other settings as you wish. 3. Activate the "Field rendering" gadget. 4. Define the image resolution and use the halved vertical resolution. For example Width = 736, Height = 282. 5. Define the aspect ratio. It should be twice the normal ratio: for PAL, Pixel h/w = 2.0 is quite suitable. 6. Render the animation. @endnode @node "T5.19" @title "Chapter 5 RENDERING" 5.19 MOTION BLUR The following example shows how to use the motion blur effect in your animations. 1. Create the animation as normal. The effect is visible (and necessary) only when the animation contains objects moving quite fast. As a general rule, an object should move at least 10-20 pixels between two frames before the blur produces noticeable results. 2. Select the objects to which you want to apply motion blur, select the function Modify/Properties/Attributes and activate the "Motion blur" gadget. Then select OK. Use the effect only to the objects which are moving the fastest because motion blur calculations require significant amounts of extra rendering time and ram memory. 3. Define the render settings as usual, but set the anti-aliasing to level 2 or higher. The anti-aliasing factor affects the motion blur calculations. Note: That Draft and Outline modes do not support motion blur. 4. Open the animation window and define its settings. Adjust the "Smpl." gadget (temporal sampling) to the value 1 instead of 0. 5. Render the animation. You may have to increase the temporal sampling value and the anti-aliasing factor (try 3 or 4) if a blurred object is moving very fast. @endnode @node "T5.20.1" @title "Chapter 5 RENDERING" 5.20 TROUBLESHOOTING The following list shows some possible problem situations and how to recover from them. 5.20.1 Not Enough Memory The rendering engine of REAL 3D uses ram memory to speed up rendering. This means that rendering of complex scenes uses all the memory available. When multiple windows are ray-traced simultaneously (e.g. when rendering an animation), some rendering tasks may run out of memory. Suggestions: 1. Close other programs. 2. Close unused windows and screens in your REAL 3D environment. If you render an animation, leave only one screen with one View window open. 3. Check Render settings - Try using simpler rendering mode, e.g Lampless instead of Normal. - If you use mesh surfaces, check that B-spline->Phong gadget is not selected, or use lower Subdivision value. - Check Memory usage menu function. If your environment has been created in another workstation and fixed memory usage is specified, the rendering engine will make the wrong assumptions of the amount of total memory. Select "Relative" memory handling with 100% usage (sometimes lowering the memory percentage may help because the renderer may end up using low memory algorithms instead of fastest possible ones). - Use a lower light sampling value if you are using line/wall light sources. 4. Simplify the model: - Use B-Splines meshes instead of dense Phong shaded meshes. - Use less dense meshes. - Use quadric primitives instead of meshes. - Use smaller texture maps files with materials 5. Do not use motion blur, or use lower "smpl" value. 6. Switch Undo feature off before rendering. 5.20.2 Disappearing objects If an object, whose wireframe you can see, does not exist in shaded images, check the following points: 1. Use Modify/Properties/Attributes to check the object attributes. Deselect the RT-invisible, Light-source and Mapping gadgets. Also, check the object attributes of parent objects. 2. Make sure that none of the objects outside Boolean operation levels has the "Inverted" attribute set. An inverted, finite object in the beginning of the hierarchy tree may fill the whole space and replace other objects with its volume. 3. If you are using transparent, overlapping objects, check the hierarchy order. For example, a planet inside a gas cloud should be ordered so that the planet is above the gas cloud in hierarchy. 4. Make sure that you are not using the "View/Render/Selected" option. @endnode @node "T6.1" @title "Chapter 6 ANIMATION SYSTEM" Chapter 6 ANIMATION SYSTEM -------------------------- In this chapter you will be acquainted with basic features of the animation system of REAL 3D. The approach is very example oriented and after a few pages, you will be able to create animations of swimming fishes, walking robots, flying birds and so on. This section is not meant to be a tutorial for freeform modelling or any other object construction techniques, so all objects we will use are very easy and fast to create. The animation examples can be found from the software package. It might be a good idea to take a look at them before you go any further, just to verify that you know where to find them while following the tutorial. All the scene files are included, so if you cannot create any of these examples, you can compare your objects to those found from the "Examples/ Animation" directory and find out the reason for the failure. Right, it is time to pop into the first example. Start REAL 3D with one View and one Select window. Because we are going to render our animations using only wireframes, use a four color screen (depth = 2) to keep window refreshing rates high. 6.1 PATH One common way to create animations is to move objects along a path. A path can be a straight line, a smooth curve, an ellipse, a perfect circle or whichever three dimensional path you might like to create. The method called PATH is designed for that purpose and can be used for defining all kinds of motions for objects. 6.1.1 Move Object along a Path Let's create a simple logo text which moves along a path. 1. Create one level object called "Logo" by selecting the menu Create/ Structure/Level and renaming it with the function Modify/Properties/ Name. 2. Create four 3D characters under "Logo" level using the function Create/ Visibles/Polyhedron. 3. Create one method object at the same level with "Logo" object: select the menu Create/Structure/Method, select PATH and click OK. Rename your object as "Mover" so you can easily recognize it later. 4. Create one closed curve (e.g. Controls/B-Spline Closed) under the method object. This curve defines the path for the logo. Your animation is now ready, as far as REAL 3D is concerned. In order to play it, select the menu Animate/Control/Play_Forwards and you will see how your 3D logo text follows the path. Figure @{"T6-1:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-1"} 3D Logo Following a B-Spline Path. (PICTURE: T6-1) Lets go through the terminology used in this example. Make sure you fully understand the following description because we will use these terms throughout this section. - Objects to be animated are called "target" objects. They can be all kinds of objects like primitives, light sources, textures or perhaps other animated hierarchical objects. - A "Method" object modifies "target" objects so that the result is an animation. - The curve inside the method object is called a "parameter" object. Method objects use "parameter" objects to decide how to animate targets (in this case, what kind of path the logo text should follow). A parameter object can be any "evaluable" object like a polygonal line, circle or even a freeform mesh. In other words, "method" objects modify "target" objects according to the "parameters" of "methods". @endnode @node "T6.1.2" @title "Chapter 6 ANIMATION SYSTEM" 6.1.2 Move Objects along a Path Like a Snake In the previous example, all 3D characters were created inside one level object called "Logo" so there was only one target object for "Mover". If we created all characters at the same level with "Mover", the result would be quite different. Lets try this: 1. Delete the current project with Project/Project/New and create four 3D characters under the root object. 2. Create PATH method object at the same hierarchy level with the characters. 3. Create a B-Spline curve under the method object so the curve passes through all the characters. Figure @{"T6-2:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-2"} "Move along a Path like a Snake" Animation. (PICTURE: T6-2) Animate/Control/Play_Forwards the animation and the PATH method object moves the target objects individually. 6.1.3 Bouncing Sphere As you have probably already noticed, the PATH method can produce accelerations and decelerations according to distances between subsequent knot points of the parameter curve used longer the distance for defining the motion. The between subsequent knots, the higher the speed and vice versa. This example shows one advantage of the Real's animation system: all information needed for animating objects is a natural part of the object itself. When duplicating an object (e.g. bouncing sphere), all animation data will be duplicated as well, ie. the result will be two bouncing spheres. Bouncing spheres (or any other animated objects) can be saved and loaded back and they still continue "bouncing". To create a bouncing sphere: 1. Create one sphere to the top left edge of the window. 2. Now we define a motion for the sphere, as shown in the following picture. Select the function Animate/Create/Path and draw a B-Spline control polygon curve, which defines the motion for the sphere. By creating triple points, it is possible to define zero speeds; therefore, click the three first control points to the center point of the sphere so the speed of the sphere in the beginning will be zero. The deeper the sphere falls, the higher the speed ie. longer the distance between the control points should be. Finish the curve by click. 3. REAL 3D creates a level under which it puts the sphere and the method with its parameter path. Rename the new level object as "Boing". Figure @{"T6-3:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-3"} Bouncing Sphere. The higher the distance between the knots the higher the speed. (PICTURE: T6-3) 4. Now your have created a bouncing sphere which consists of a actual sphere primitive and one PATH method. Play it and it bounces. 5. Animate/Control/Play_Backwards the animation. 6. Now, duplicate the "Boing" object, move it a bit and play the animation. The result is two bouncing spheres. 7. When you played the animation, both spheres started to move immediately and they reached the end points of their paths at the end of the animation. However , this can be changed by defining start and end times for methods. Select the method moving the first sphere, select Modify/Properties/Animation and activate Start and End gadgets. Change end time from its default (1) to 0.7. This means that the method starts to work immediately but stops when the time reaches 0.7. Do the same for the method of the second sphere, but now use values Start=0.4, End=1.0. Play the animation and the spheres bounce. @endnode @node "T6.1.4" @title "Chapter 6 ANIMATION SYSTEM" 6.1.4 Hierarchical Animations and Bouncing Sphere In this example we will learn how to create hierarchical animations. In other words, how to animate objects which are already animated. Let's consider the following situation: a sphere bounces up and down by following a circular path while another method moves the whole system along another path. 1. Create one sphere and select the menu Animate/Create/Path. Define a nice path which moves the sphere only up and down. Use key to close the curve. Then rename the level object "ellipsoid" to "UpDown". 2. Select the method object (you find it under "UpDown") and redefine the Frequency of it to 10 using the Modify/Properties/Animation requester. 3. Animate/Control/Play_Forwards the animation; the sphere bounces up and down 10 times during the animation. 4. Select Animate/Control/Goto Beginning to reset the time back to zero. 5. Select the object "UpDown" and define a new horizontal motion for it using the function Animate/Create/Path. Play the animation and the sphere bounces up and down while it follows another path. Figure @{"T6-4:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-4"} A hierarchical animation. An object moves along a path while they both follow another path. (PICTURE: T6-4) 6.1.5 Move Elastic B-Spline Mesh along a Path This example shows how a B-Spline can be subdivided using groups, and how these groups can be animated so the mesh moves along a path; a bit like a flying carpet. 1. Create a mesh using the function Create/Freeform/Mesh. The default size of 8x8 is fine. 2. Select the function View/Drawing_Set and set the C.Polyg gadget and deselect the Curve gadget. This allows you manipulate B-Spline mesh through its control polygon. 3. Make the mesh the current level by double clicking it on the Select window. Make sure it is still selected. 4. Subdivide the mesh horizontally to subgroups (create "columns", not "rows") by dragging while holding the and keys. 5. Select the menu Create/Structure/Method, choose the PATH method and click OK, to create a path method to the same level with the groups. 6. Make the PATH method object the current level and create a path using the function Create/Control/B-Spline_Ctrlp. Close the path with and end it with . Play the animation and your mesh will follow the path looking very elastic. Figure @{"T6-5:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-5"} Elastic Mesh Following a Path. (PICTURE: T6-5) @endnode @node "T6.1.6" @title "Chapter 6 ANIMATION SYSTEM" 6.1.6 Talking Head This example demonstrates how path and groups can be used for creating animated freeform objects like talking heads. The idea is very simple: a group refers to desired points of the head and follows a path. 1. Because a good 3D head would take some minutes to create, let's use just one B-Spline curve representing the profile of a face. That can be done in seconds. Make the curve the current level. 2. Select desired points by dragging and holding down the key, or use the Extras/Vectors/Lasso function. 3. Create a group object by selecting the menu Create/Structure/Group. 4. Select the menu Animate/Create/Path and define a motion for the mouth. Play the animation and your head talks. Figure @{"T6-6:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-6"} Freeform Morphing Implemented by Moving a Group along a Path. (PICTURE: T6-6) 6.1.7 Moving Objects along a B-Spline Mesh The idea of using B-Spline meshes for defining motions for objects is simple and obvious: you don't have to define separate motion for an object in order to make it climb over a mountain. Instead, the mountain itself can be used for that purpose. 1. Create three spheres to be moved along a mesh. 2. Create a PATH method object at the same level with spheres by selecting the menu Create/Structure/Method. 3. Create a B-Spline mesh inside the method object by selecting the menu Create/Freeform/Mesh. 4. Play the animation and your spheres will move along the mesh. Note that it can take some time before spheres start to move. Be patient, next play starts immediately once all necessary data is defined. You can modify the mesh freely and the spheres will still move along it. Make it look like a mountain and your spheres will climb over it. Figure @{"T6-7:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-7"} Move Objects along a Mesh. (PICTURE: T6-7) @endnode @node "T6.1.8" @title "Chapter 6 ANIMATION SYSTEM" 6.1.8 Customized Paths The PATH method requires one parameter which is simply used for defining how target objects should be moved. The type of the parameter can be any "evaluable" primitive like a circle, a polygonal line, a B-Spline curve or even a mesh. Almost all kind of motions can be defined using these paths. Furthermore, motions can be accumulated by creating hierarchical animations as we did in the example 6.1.4 "Hierarchical Animations and Bouncing Sphere". Before we get into the point, remember that the following description shows you how you can create new "evaluable" primitives. In other words, you can use them with all methods, not only with PATH. For this example, you have to create one sphere and animate it using the function Animate/Create/Path. We will use the B-Spline curve to define a path for the sphere, and a formula to fine-tune the path so the sphere vibrates while it moves along the path. 1. Select the B-Spline curve and select the menu Modify/Properties/Tags. Add the following TAG to the curve: SFOR x+=0.2*sin(t*20*PI), y+=0.2*cos(t*20*PI) 2. Play the animation and sphere vibrates while it moves along the curve. The variable "t" is a time, and "x", "y" and "z" define points in the curve corresponding the time. See the reference section for full description of variables for evaluable parameters. Now you can save this customized curve and whenever you need this kind of vibrating curve, just load it in. If formulas cannot be used for solving your problem, you can write a RPL function where you can use conditional expressions like IF ELSE ENDIF, loops like DO LOOP, variables, etc. to define desired motions for your objects. Lets consider the following situation: a sphere follows a B-Spline path and when animation reaches the middle point, the sphere starts to vibrate. In order to do this, you have to create a RPL program which uses IF ENDIF structure: 1. Start you favorite text editor, write the following RPL program and save it as "vibrapath.rpl": : VibratePath t F@ 0.5 F> (if t > 0.5) IF "x+=0.2*sin(t*20*PI), y+=0.2*cos(t*20*PI)" EVAL DROP ENDIF ; 2. Create another sphere following another path and attach the following tag to the B-Spline curve: SRPL VibratePath 3. Execute your RPL program by selecting the menu Project/Macros/Execute Named and by selecting the file "vibrapath.rpl". Play the animation and the sphere starts to vibrate as soon as the time reaches the value 0.5. It is about time to leave PATH method now (there is still 23 other methods to go through). Examples we have gone th rough so far should give you some ideas about how to solve all possible and impossible "move along" problems. @endnode @node "T6.2" @title "Chapter 6 ANIMATION SYSTEM" 6.2 ROTATION Where PATH method can be used for moving objects along parameter objects, ROTATION method allows you to rotate objects around parameters. As a default, target objects are rotated one revolution with a constant speed. Use Perspective projection in the following examples so it easier to see how objects are rotated. 6.2. 1 Rotating Objects Around an Axis 1. Create a Cube 2. Create a ROTATION method: select the menu Create/Structure/Method, choose ROTATION from the method list and press OK. 3. Create an axis inside the method object by selecting the menu Create/ Controls/Axis. Play the animation and your cube will rotate around the axis. Figure @{"T6-8:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-8"} A Cube Rotates around an Axis with a Constant Spegd. (PICTURE: T6-8) The only non-obvious thing here is the direction of the rotation. It is defined using so called Right Hand Rule: if the thumb of your right hand points along the axis, your fingers show the direction of rotation. In other words, if you change the direction of the axis by mirroring it, the rotation direction will be reversed, too. 6.2.2 Rotating with Different Speeds and Directions In this example, we are going to create several objects rotating with different speeds and directions. 1. Create one cube, one polyhedron and one pyramid 2. Select the cube and the menu Animate/Create/Rotation. This function allows you to define rotations by defining a "coordsys" primitive. Play the animation and you cube will be rotated around the "x" axis of the coordsys primitive. Then select Animate/Control/Goto Beginning. Figure @{"T6-9:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-9"} Modifying Rotation Attributes. (PICTURE: T6-9) 3. Select the method object which makes your cube to rotate and select the menu Modify/Properties/Animation. Activate Start, End and Frequency gadgets and define following values for them: Start = 0.0 End = 0.3 Frequency = 0.33 This makes your cube to rotate only one third of the full cycle during the time interval 0 ... 0.3. Then it will stop. 4. Now select the polyhedron and apply Animate/Create/Rotation to it. Then select the new method and define following values for Start, End and Frequency. Start = 0.3 End = 0.6 Frequency = 0.5 This will freeze the polyhedron until the time reaches the value 0.3. Then the polyhedron rotates 180 degrees and stops when the time reaches the value 0.6. 5. Select the pyramid, apply the function Animate/Create/Rotate to it and define following values for its ROTATION method: Start = 0.6 End = 1.0 Frequency = -1 This will make the pyramid rotate -360 degrees when the time reaches the value 0.6. Play the animation and see how the objects perform their rotations one after another. @endnode @node "T6.2.3" @title "Chapter 6 ANIMATION SYSTEM" 6.2.3 Hierarchical Rotations Rotations can be hierarchically nested just like paths can. 1. Create a rectangle 2. Make it rotate around its left edge by selecting the menu Animate/ Create/Rotation. 3. Select the function Modify/Structure/Copy; this copies the rotating rectangle to the clip buffer.Then make the level containing the original rectangle and the rotation method the current level. 4. Paste the rotating rectangle from the clip buffer using Modify/ Structure/Paste. Move the pasted copy to the left a bit and make it the current level. 5. Paste and move once more and play your animation. It will behave very nicely. Figure @{"T6-10:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-10"} Hierarchically Animated Rectangles. (PICTURE: T6-10) 6.2.4 Tornado Before trying the following example, select the menu View/Drawing Set and switch off the Curve gadget and turn on the C.Polyg gadget. This allows you to handle your B-Spline mesh through control polygon and speeds up screen refreshing. 1. Create a B-Spline tornado (do it by rotating a profile curve around an axis using the function Create/Freeform/Rotate). 2. Make the tornado mesh the current level and subdivide it vertically to subgroups using the functions Vector/Lasso and Create/Structure/ Group. Create one group for each horizontal isoparametric curve of the mesh. Figure @{"T6-11:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-11"} Tornado Mesh Subdivided to sub-groups. (PICTURE: T6-11) 3. Switch the orientation of the view window so you can see the tornado from the top and apply Animate/Create/Rotate to all groups so that they will rotate around their center points. 4. Now define different speeds for different levels of the tornado (the upmost circle should rotate once, the second circle twice etc.). As you can remember, this can be accomplished just by modifying the frequency of methods. 5. Change the orientation of the View window so that you can see the tornado from the side. Open the View/Drawing Set requester, turn on the Curve drawing, turn off the Ctrl Polyg. drawing and set Surface Subdivision to 5. Then play your animation. Wow, just like a tornado! @endnode @node "T6.3" @title "Chapter 6 ANIMATION SYSTEM" 6.3 SWEEP Sweep method is designed for rotating objects with arbitrary accelerations and decelerations. Actually, the sweep is one of the most powerful tools when creating "character animations", such as walking human beings and robots. The sweep method requires two parameters: the first one defining a center point for the rotation and the second one defining how the object is rotated. Rotation is executed exactly the same way as when the user rotates objects using the mouse and the function Modify/Linear/Rotate. Thus the first parameter is usually just an offset primitive, and the second some kind of curve defining a route for some point of the object. The method tries to move that point along the defined path while keeping the point defined by the first parameter fixed, making the object rotate. 6.3.1 Walking Legs 1. Draw a thigh-bone profile using a B-spline curve. 2. Select the function Animate/Create/Sweep and define the center point for rotation. Because your thigh-bone usually rotates about hip-bone, click over the upper end of the bone. 3. Draw a closed path for the knee (lower end of the thigh-bone); use and to close and end the path definition. 4. Make the new level created by the Sweep function the current level and create the shin-bone at the same hierarchy level with the thigh-bone. 5. Apply the function Animate/Create/Sweep to the shin-bone so the shin- bone will be rotated about the knee-cap. Figure @{"T6-12:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-12"} Structure of a Leg. (PICTURE: T6-12) The upper end of the thigh-bone is fixed to the hip while the knee follows a B-Spline curve. The upper end of the shin-bone is fixed to the knee while a route for the ankle is defined by a B-Spline. Because of hierarchical construction, the parameters used for rotating shin-bone are rotated with the thigh-bone. Play the animation and your leg should behave a bit like a real leg. However, in order to make it work perfectly, we have to analyze how a real leg works. The first observation is that the shin-bone and the thigh-bone comprise a straight line until the leg starts to return back from its back position. In other words, our shin-bone should not be rotated until the time reaches the value 0.5. So, define the Start time value of the hip-bone sweep method to that value, set the End time value to 1.0 and play the animation. Now the shin-bone should not be rotated until the leg starts to rotate back to its starting position. How to create another leg? 1. Duplicate the leg. Now you have two equally functioning legs. 2. Select the method rotating the thigh-bone of the duplicated leg and define the Phase = 0.5 using the function Modify/Properties/Animation. Play the animation and ... you have walking legs. @endnode @node "T6.3.2" @title "Chapter 6 ANIMATION SYSTEM" 6.3.2 Tracking Guns In this example, we will show you how to use "Links" to use same objects to define motions for different methods. Any parameter object of a method can be replaced by a link object which points to the actual parameter. The parameter can be everywhere in the object hierarchy and more than one link can point to it. Lets consider the following situation: a sphere follows a path and no matter where it goes, gun always points towards it. To do this: 1. Create a sphere and define a path for it using Animate/Create/Path. 2. Create a level object and name it as "Gun", at the same level with the moving sphere object. Make it the current level. 3. Create a gun object under the level, pointing to the sphere. 4. Select Create/Structure/Method and create a SWEEP method. Create it at the same level where the gun shape is; the purpose is to animate the gun. Make the method level the current level. 5. Define a center of rotation for the gun by creating an offset primitive under the method level; this is the first sweep parameter. 6. Select the B-Spline curve used for defining a motion for the sphere and select the function Create/Structure/Link. Select the "link" and Modify/Structure/Cut it. Then make the gun sweep method the current level and Modify/Structure/Paste the link under the method. The link will act as the second sweep parameter. Play the animation, and your gun is rotated so it always points to the sphere. Create another gun by duplicating the original gun (the whole sweeping gun), move it to another place and rotate it so it still points to the sphere, and when you play the animation, both guns follow the sphere. Figure @{"T6-13:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-13"} Four Guns Pointing to a Sphere. (PICTURE: T6-13) The rotations for all guns as well as the motion for the sphere are all defined by the same curve. Now, modify the sphere path using Modify/Freeform/Move Knotpoint function and play the animation. All guns have automatically changed their behavior so they still keep pointing to the sphere! @endnode @node "T6.4" @title "Chapter 6 ANIMATION SYSTEM" 6.4 SIZE The size method can be used for sizing objects during animations. It takes two parameters: the first one (usually the offset primitive) is used for defining the center point of sizing and the second (usually some sort of curve) defines how target objects are sized about the center point. Whenever you have to change the size of an object in your animation, this method can be used for that purpose. 6.4.1 Beating Spheres 1. Create a sphere 2. Select the menu Animate/Create/Size and click the mouse once over the center point of the sphere. Then define a long, arbitrary curve which starts from the surface of the sphere. To create a cyclic animation, close the path with key. Play the animation and your sphere "beats". Figure @{"T6-14:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-14"} A Beating Sphere (PICTURE: T6-14) Just to raise our enthusiasm a bit, let's create some more beating spheres: 1. Create ten beating spheres by duplicating and moving the copies so the spheres form a circular path (use a duplicate+rotate macro, if you have mastered macros). 2. Change the Phase (Modify/Properties/Animation) of each size method so the phase of the first method is 0, the second is 0.1 etc. Play the animation and you have ten nicely beating spheres, producing a kind of wave effect. 6.4.2 Bubbles Let's create an animation, where a bubble gets bigger and bigger until it becomes unfastened and starts to move up, like a steam bubble in a boiling water. 1. Create a sphere representing a bubble near the bottom edge of the View window. 2. Select the function Animate/Create/Size while the sphere is selected and click the mouse in the point where the sphere is fastened (to a hypothetical pot). 3. Draw an open path defining a growing size for the bubble; remember to start the path from the surface of the sphere. As usual, REAL 3D creates a level an puts the sphere and the new method under it. 4. Find the size method under the new level, select the method and set Start time to 0 and End time to 0.5 using the function Modify/ Properties/Animation. This prevents the bubble from growing after the animation has reached its middle point. 5. Select the whole growing bubble level and define a path for it as shown in the picture below. 6. Select the path method object created by the previous action, select the function Modify/Properties/Animation and change Start time to 0.5 so the method starts to move the bubble as soon as the bubble has become big enough. Figure @{"T6-15:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-15"} Bubble gets bigger and bigger until it is starts to move up. (PICTURE: T6-15) @endnode @node "T6.5" @title "Chapter 6 ANIMATION SYSTEM" 6.5 STRETCH This method can be used for stretching objects in three directions separately. Stretch method requires two parameters: a coordsys primitive which defines the three directions for stretching, and one curve which defines how the object is stretched. 6.5.1 Elastic Cube This example is the simplest possible. One cube is stretched in three dimensions by using B-Spline curve. 1. Create one cube 2. Select the menu Create/Structure/Method and Create a stretch method. 3. Create a coordsys primitive under the method level so its origin matches one corner of the cube and the axes match three edges of the cube. 4. Create a B-Spline curve under the method so it begins from the corner of the cube opposite to the corner where the origin of the coordsys is. Note: That you can draw a three dimensional curve by swapping the orientation of your View window while outlining the curve. Figure @{"T6-16:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-16"} Elastic Cube (PICTURE: T6-16) Play the animation. One corner of the cube follows the curve while another corner is fixed to the origin of the coordsys. 6.5.2 Bouncing Elastic Sphere We have already created one bouncing sphere. However, it did not act like an elastic sphere. We can use the stretch method to add the elasticity effect to sphere bouncing: 1. Create a sphere near the top left edge of the window. 2. Select the menu Animate/Create/Stretch and create a closed curve which stretches the sphere nicely. 3. Select the stretch method and modify its start/end times so stretching starts when the time reaches the value 0.4 and stops when the time reaches 0.6. 4. Select the level which contains both the sphere and the stretch method and apply Animate/Create/Path function to it. Define a path similar to one we defined in our earlier bouncing sphere example. Figure @{"T6-17:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-17"} A Bouncing Sphere with Collision Deformation. (PICTURE: T6-17) Play the animation and the sphere starts to fall until it hits the floor at the time of 0.4 and rebounds back nicely. @endnode @node "T6.6" @title "Chapter 6 ANIMATION SYSTEM" 6.6 DIRECTION Welcome to the world of swimming fishes and wriggling snakes! The DIRECTION method works like the path method, except that it also rotates target objects so that their orientation changes according to the curvature of the parameter path. 6.6.1 Move a Logo Text along a Direction Path In order to make the difference clear to the path method, we will create exactly the same object as we did in the example 6.1.2 "Move objects along a path like a snake", except that now we use the direction method. 1. Create some 3D characters. 2. Create a DIRECTION method to the same hierarchy level with the characters. 3. Create a closed B-Spline curve under the direction method level (see the figure below). Play the animation and all the characters move along the path while they are rotated according to the curvature of the path. Figure @{"T6-18:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-18"} Logo Text Following a Directed Path. (PICTURE: T6-18) It is this rotation feature which makes this method very valuable when animating freeform objects. 6.6.2 Swimming Fish Let's create a fish: 1. Create a freeform fish (or a snake or any other creature whose length it greater than its thickness). 2. Make the fish the current level and subdivide it to groups from the tail to the head. 3. Create a DIRECTION method to the same level with the groups. 4. Create a closed B-Spline path representing the route the fish swims, at the same level with the fish primitive (one level upwards from the groups). 5. Select the B-Spline curve representing the path for the fish, select the menu Create/Structure/Link and Cut and Paste it under the method object. Play the animation to make the fish swim along the path. Figure @{"T6-19:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-19"} Swimming B-Spline Fish (PICTURE: T6-19) Note: That a curved path makes your fish swim like a fish. If the curve contains no small bends, your creature acts like a slug: it does not wriggle. It may take some time to fully learn to know the nature of this method, but the results are worth the effort! @endnode @node "T6.7" @title "Chapter 6 ANIMATION SYSTEM" 6.7 MOVE & DIR As you probably have already realized, the direction method is a very powerful way to create many kinds of nice animations. However, there are situations where you have to control the direction of the object independently from the motion; that is not possible with the direction method, because it uses the same curve to define both the direction and the motion. MOVE & DIR method is designed for these situations. The move & dir method uses two parameters: the first one defines a motion for target objects just as the path method parameter does, and the second parameter defines the direction for the targets just as the direction method parameter does. This means that if both parameter curves are equal, the method will work exactly the same way as the direction method does and if the parameter defining the direction is a straight line, the method works similar to the path method (because the direction of the object remains constant). 6.7.1 Rocking Logo Moving along a straight Line In this example we will create a logo which consists of characters. Each character follows a perfectly straight path (an axis). A B-Spline curve is used for defining the direction information so that the logo will move very nicely. 1. Create four small 3D characters as shown in the picture below. 2. Create a MOVE & DIR method to the same level with the characters. 3. Use Create/Controls/Axis to create a Straight line under the method level, so it passes through the characters. 4. Create a B-Spline curve under the method level. In the beginning, the curve should follow the axis accurately but then starts to oscillate. Figure @{"T6-20:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-20"} Rocking Logo Following a Straight Line. (PICTURE: T6-20) Play the animation, and if you are not happy with the way the characters are rotated while they follow the straight line, just modify the second curve. If you don't like the straight line, use any other curve type or even a mesh (just like we did in the "Move Along a Mesh" example). Note that you can use the second curve to define rotations in all three dimensions! The direction curve does not have to be planar as it was in this example. Naturally, the curve can define rotations which are perpendicular to the motion direction (rocking boat...). 6.7.2 The Rally Driver In this example we will show you how "Move & Dir" method can be used for creating "driving car like crazy" effects. 1. Create a car 2. Create a MOVE & DIR method object to the same hierarchy level. 3. Create a B-Spline curve representing the road under the method level. 4. Duplicate the "road" curve. If you now played the animation, the result would be just "driving car like a reasonable person". 5. Modify the second curve so the car starts to behave more aggressively as shown in the following picture. Figure @{"T6-21:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-21"} "Driving like crazy". (PICTURE: T6-21) The first curve represents the road and another curve the direction of the car in the corresponding road positions. Note that without showing knotpoints it is difficult to solve which points of the motion and the direction curves correspond to each other, because the speed of the object is defined by the distance of the knots. @endnode @node "T6.8" @title "Chapter 6 ANIMATION SYSTEM" 6.8 CONTROL CURVES This method can be used for defining paths for objects by using two curves. Target objects are moved, rotated, and stretched according to the curves. This method is very suitable for defining motions for cameras, aeroplanes, etc. where accurate control over banking angle is needed. Just as in the PATH, DIRECTION and MOVE & DIR methods, the distance between knot points determines the speed of target objects. Naturally, control curves can be any evaluable objects, like circles, ellipses or just straight lines. The ability to define whether or not the second control curve should be used also for scaling target objects make the number of possible applications for this method huge. 6.8. 1 Beating and Moving Slime Ball In this example, we will create a simplest possible example demonstrating control curves: one object moving between control curves. The distance between control curves varies causing object to pulsate like a "slime ball". 1. Create a sphere representing a slime ball. 2. Create a CONTROL CURVE method object at the same level. 3. Create two closed B-Spline curves by drawing one, duplicating it, and modifying the duplicated curve so the distance between the curves varies. Then Animation/Control/Play Forwards the animation, and after that, select Animation/Control/Goto Beginning. Figure @{"T6-22:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-22"} A Slime Ball Stretched and Moved by Control Curves. (PICTURE: T6-22) Now, lets create more slime balls. This is exactly what you should do: 1. Create two new spheres to different positions and make sure they fit perfectly between the control curves (see the figure above). 2. Select the method object. Select the menu Modify/Properties/Tag, click the "ISKE" tag string (one should exist after playing the animation) and click DEL button to delete the tag; then select OK. This asks Real to define "VPHS" tags automatically when you play the animation next time. Play the animation and you have three elastic slime balls. 6.8.2 Elastic Flying Carpet In this example we will show you how to create freeform mesh, which moves along control curves like an elastic rubber carpet (if you have not seen rubber carpets before, don't worry. I'm sure there are such things as rubber carpets). We also demonstrate the use of links just to make sure that you get familiar with them. 1. Create a mesh using the function Create/Freeform/Mesh. 2. Make the mesh the current level by double-clicking it on the Select window; as usual, we will put sub-groups under the freeform level itself. 3. Subdivide the mesh horizontally to groups, so each group consists of a column of control points. Note that you have to turn Drawing Set/C. Polyg. representation on (deselect "Curve" gadget at the same time) in order to get access to the control points of the mesh. 4. Create a CONTROL CURVES method object. 5. Create two control curves to the same level with the the mesh. 6. Create two links pointing to the control curves (multi-select the control curves and use the menu Create/Structure/Link). 7. Modify/Structure/Cut the links, make the CONTROL CURVES method the current level and Modify/Structure/Paste the links back. Figure @{"T6-23:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-23"} Flying Elastic Carpet. (PICTURE: T6-23) Now, use the function View/Drawing_Set to switch the "Curve" representation on and "C. Polyg." off and play the animation. The carpet should fly very nicely. 6.8.3 Flying Viewpoint In this example, we will show you how to define motions for objects without stretching them. For example, when creating motions for view- points, aeroplanes etc., the possibility to fully control banking is a valuable feature. This example also demonstrates how to use viewpoint and aimpoint primitives to define the orientation for the camera. 1. Create one cube in the middle of the View window so that we have something to watch in the animation. 2. Select the perspective projection (View/Type/Perspective) and find a good viewing angle by using the cursor keys. 3. Create aimpoint and viewpoint primitives by selecting the menu View/ Create Camera. REAL 3D creates the camera representing the current orientation of the View window. The camera object consist of two sub- objects: an aimpoint and a viewpoint. We are going to animate only the viewpoint, so delete the aimpoint primitive. This makes the camera always point to the origin point of the space. 4. Create a CONTROL CURVES method at the same level with the viewpoint (Under the "camera" object). 5. Create two control curves under the method so that they show the route for both "eyes" of the viewpoint. 6. Select the method object and add the following tag to it: FOR I=1 which tells to the method not to use stretching (for full description of "I" variable, see the reference section). 7. Activate the View/Observer/Camera View function. You may also use Modify/Properties/Attributes/WF-Invisible to make the camera wireframe invisible during the animation play. Play the animation and the eyes of the viewpoint will follow the control curves. However, because the aimpoint does not exist, the camera is aiming at the origin (at the cube) all the time. Figure @{"T6-24:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-24"} Motion for a Viewpoint Defined by Two Control Curves. (PICTURE: T6-24) Note: That there are easier ways to create camera flight animations (for example key framing), but the ability to control banking accurately may sometimes make this method more suitable. Lets enter the following section, which leads us into the world of Character Animations. @endnode @node "T6.9" @title "Chapter 6 ANIMATION SYSTEM" 6.9 SIMPLE SKELETON The idea behind skeletons is quite straight forward: a skeleton is a simple object which is somehow connected to more complex object(s). When the skeleton is modified, the target object is modified accordingly. The fact that it is much easier to modify these skeletons than actual (often very complex) target objects, makes the skeletons a very powerful animation tool. REAL 3D contains two skeleton types which differ from each other in the way they manipulate target objects to make them match the skeleton object. So, lets first create a SIMPLE SKELETON example and then have a look how it works. 6.9.1 A SIMPLE SKELETON and a Logo Text In this example, we will create a logo text and a skeleton which works as an elastic baseline for the text. 1. Create four 3D characters. 2. Create a SIMPLE SKELETON method to the same level with the characters. 3. Create a B-Spline curve (a skeleton curve) under the method level. The curve should match roughly the baseline of the text. 4. Select the menu Animate/Control/Refresh. Our first skeleton object example is now complete. When you selected the menu Animate/Control/Refresh, REAL 3D calculated all information needed to keep target objects on the skeleton from now on. So, lets try to modify the skeleton curve in order to test how the skeleton works. 5. Select the skeleton curve and move it. Now the skeleton is dislocated from its targets. Select the menu Animate/Control/Refresh and you logo text is pulled to the skeleton. 6. Modify/Linear/Stretch the skeleton curve and Animate/Control/Refresh. The distance between the characters is stretched, too. 7. Bend the skeleton curve, refresh the animation system and your logo is bent, too. Figure @{"T6-25:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-25"} An Object after Bending the Skeleton. (PICTURE: T6-25) As you noticed, the SIMPLE SKELETON method does not rotate or stretch target objects in any way. They are just moved back to their original positions on the skeleton. In other words, the SIMPLE SKELETON uses only "move" transformation to manipulate its targets. This makes this skeleton type suitable for animating objects whose direction should not be changed during the animation. Another observation was that the SIMPLE SKELETON requires one parameter which describes the shape of the skeleton. This parameter can be any evaluable object like a polygonal line, a B-Spline curve, a circle, a point or even a freeform mesh. Furthermore, it is even possible to create customized skeletons by creating a new evaluable object, just like we did in the PATH example 6.1.8 "Customized Paths". The SIMPLE SKELETON method pulls all target objects to the skeleton, so that the COG of the target object in question is pulled to the skeleton, and the position on the skeleton is defined by the VPHS tag associated with the target. For example, if the VPHS value for a target object is 0, then the object is pulled to the beginning point of the skeleton curve. If VPHS is 1.0, then the target is pulled to the end point of the skeleton. The value 0.5 pulls the target to the middle point of the skeleton. These values are called "parameter values" of the parameter object. The skeleton object also redefines the COG for target objects so that it lies exactly on the skeleton curve. When you selected the menu Animate/Control/Refresh the first time, the method automatically defined these tags for each target object by finding the parameter value of the skeleton curve where the distance between curve and target object was shortest. This was done only once. The method created and associated the "ISKE" tag with itself to indicate that all necessary tags are now updated and need not be refreshed any more. This is the whole theory behind the simple skeleton. As you have already noticed, you don't have to know anything about these tags as long as you are not going to define positions for target objects manually. Just create all necessary objects and let REAL 3D do the rest. Lets play with this example a bit more. Select any of the target objects and move it apart from the skeleton. Refresh the animation system and the object is pulled back to the skeleton! Now, suppose that the first target object was positioned improperly and you have to change it to a different position in the skeleton. How to move targets so that the skeleton method will not pull them back to their original positions? The answer is: just delete the tag ISKE associated with the method object (or set its value to zero), move target objects to the desired positions and refresh the animation system. So far, we have actually only tested how the skeletonally controlled objects can be manipulated interactively. Now it is time to create our first skeleton animation. @endnode @node "T6.9.2" @title "Chapter 6 ANIMATION SYSTEM" 6.9.2 Rotate a Simple Skeleton around an Axis Because skeleton objects are just ordinary objects, they can be animated just like any other objects. So, lets create such an animation: 1. Create simple logo text consisting of some characters. 2. Create a SIMPLE SKELETON method to the same hierarchy level. 3. Create a B-Spline curve, passing through the logo characters, under the method. 4. Create a ROTATION method to the same level with the skeleton so that the skeleton curve is target for it. 5. Create an axis primitive under the path method to define the rotation axis. Figure @{"T6-26:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-26"} A B-Spline curve rotating around an axis while skeletonal control keeps the logo characters attached to the curve. (PICTURE: T6-26) Play the animation. The ROTATION method moves the skeleton, while the skeleton method keeps the target objects on its parameter curve. 6.9.3 Elastic Skeleton and Logo Text In this example we are going to add some elasticity to skeletons by moving points using groups. 1. Create a logo consisting of four characters. 2. Create a SIMPLE SKELETON method to the same level with the characters. 3. Create a skeleton curve (B-Spline) under the method. 4. Make the skeleton curve the current level and create a point group object, consisting of some points of the skeleton. 5. Create a PATH method object to the same level with the group. 6. Define a motion for the group by creating a B-Spline curve under the path method. Figure @{"T6-27:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-27"} A Skeleton Modified by a Group. (PICTURE: T6-27) 6.9.4 Moving Objects along a Skeleton As you already know, the VPHS tag associated to a target object defines where the target lies on the skeleton . However , it is possible to define this value dynamically using the tag SFOR. This means you can change the position of the target during the animation just by writing the formula which refers to the time! So, let's test this by creating "Move along a Path" animation based on the skeleton method. 1. Create a sphere (a target object). 2. Create a SIMPLE SKELETON method object at the same level. 3. Create a B-Spline curve under the method object. 4. Selecting the sphere, then select the menu Modify/Properties/Tags. Click ADD gadget and then enter the following tag string: SFOR x=t Hit return and select OK. Play the animation and your target object will move along the skeleton, because its position on the skeleton is directly defined by the time. Figure @{"T6-28:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-28"} A Sphere Moving along a Skeleton. (PICTURE: T6-28) Well, we could do this simply by using a PATH method, too. However, there is a big difference between these two implementations. The PATH defines relative motion for targets whereas SKELETON defines absolute position. This means that you can move the curve used with the PATH method without changing the motion of the targets (because it still defines equal relative motion), but if you move the skeleton curve, targets follow a different route because they are always pulled back to to the skeleton. So, lets analyze what made the sphere actually move along the skeleton. The formula "x=t" assigned the current time to the variable "x". The skeleton method uses this variable to redefine the value of VPHS tag. Actually, the parameter space is three dimensional and also variables "y" and "z" are defined, but because we used a B-Spline curve, only the first dimension is relevant. A bit later we will show you how to use freeform meshes as skeletons, and then we need two dimensions (variables x and y) to define a position for the target (for full description of variables and methods, see the Reference section). All right, lets practice a bit more, by creating a formula which is bit more complex and produces a more interesting motion. @endnode @node "T6.9.5" @title "Chapter 6 ANIMATION SYSTEM" 6.9.5 Rocking Spheres The following example demonstrates how to create accelerations by using "cos()" function in a formula. 1. Create two spheres, one white and one black. 2. Add the following tags to the spheres: White sphere: SFOR x=t*0.5+(t)*(0.5+0.5*cos(8*PI*t)) Black sphere: SFOR x=t*0.5+(1-t)*(0.50.5*cos(6*PI*t)) 3. Create a SIMPLE SKELETON method to the same level with the spheres. 4. Create a B-Spline curve under the method level as shown in the picture below. Figure @{"T6-29:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-29"} Spheres Rocking along a Skeleton Curve. (PICTURE: T6-29) Play the animation and the spheres will behave in a very natural way. Lets analyze the formulas we attached to the target objects. The time (t) goes from 0 to 1 in our example when the animation is played. Thus, in the beginning, the first part of the formula, "t*0.5", has no effect at all. When the animation proceeds, the term "t*0.5" approaches 0.5. On the other hand, the rest of the formula "(1-t)*(0.5+0.5*cos(8*PI*t))" gets weaker and weaker because "(1-t)" approaches 0. So, in the beginning, the function "cos()" causes the sphere to roll up and down in its full power but in the end, it does not affect the position of the sphere at all. If math is not one of your strong points, don't worry, there will be lot of nice ready-made formulas available very soon! 6.9.6 A Hydrogen Atom and its Electron Orbit When creating atom simulations, it is necessary to understand the theory involved. If you don't know that theory, don't worry, this example can still give you some ideas. Some theory first. A hydrogen atom consists of one proton and one electron. The way how an electron "rotates" around the proton can be described by using a formula which is well known by scientists. Nobody knows where the atom is at a certain time value, but a formula can be used for calculating probability for that. There are only a few possible states the electron can represent. So, lets try to implement this. 1. First we need an electron. I don't know what a real electron looks like, but I assume it looks a bit like a sphere. So, create a sphere. 2. Then we have to define the formula describing the so called probability distribution for the sphere. For simplicity, we use just a random value for that. The variable "rnd" can be used for that purpose. Therefore, select the sphere, select the menu Modify/Properties/Tags and add the following tag to it: SFOR x=rnd This generates random values between 0 and 1. 3. Create a SIMPLE SKELETON method to the same level with the electron. 4. Then we need a new evaluable primitive which represents possible states of the electron. For hydrogen (if I remember correctly) it is a sphere whose radius represents these possible states of electron. However, let us use a circle, whose mathematical formula is very similar to the formula of the sphere, but is shorter and faster to write. The mathematical formula defining a circle is: x = r*sin(2*PI*t) y = r*cos(2*PI*t) where "r" is radius of the circle and "t" is the parametrization of it. When t goes from 0 to 1, x and y coordinates define a perfect circle. Use Create/Controls/Offset to create an offset primitive under the method, representing the center point of the circle. Assuming that the radius remains the same during the animation, say 0.5, add the following tag to the offset: SFOR x+=0.5*sin(2*PI*t),y+=0.5*cos(2*PI*t) This way, we can manipulate the offset so that instead of a single point, the result is an orbit for the electron (in this case, a circle). The animation is now ready. When you play it, the time goes from 0 to 1 and the formula attached to the electron object returns random parameter values. The skeleton method object uses these values to evaluate a point from its parameter, describing possible positions for the electron, and then moves the electron to that point. @endnode @node "T6.10" @title "Chapter 6 ANIMATION SYSTEM" 6.10 SKELETON The SKELETON method is somewhat similar to the SIMPLE SKELETON; it pulls the target objects to its skeleton parameter. However, SKELETON can also rotate objects, so that their directions match the curvature of the skeleton, thus opening new possibilities for exciting new animation effects. Because of this rotation feature, the SKELETON method requires two parameters instead of one. They are called as "primary" and "secondary" skeletons. The primary skeleton defines the actual direction and position for target objects, while the second skeleton is used for defining how target objects are oriented around the primary skeleton (the "torsion"). For example, if the secondary skeleton object is just a static object defining a fixed direction, the targets are just bent according to the primary skeleton. If the secondary skeleton is animated so that the direction it defines changes during the animation, target objects are rotated around the primary skeleton accordingly. 6.10.1 Another Logo Text Animation Lets re-create the logo text animation of the example 6.8.3 "Elastic Skeleton and Logo Text", but now using general skeleton. This example demonstrates the difference between the two methods well. 1. Create a logo text 2. Create a SKELETON method to the same level with the characters, using Create/Structure/Method. 3. Create a B-Spline curve under the method. for example using Create/ Controls/ B-Spline Ctrlp, so that the curve passes through all the target characters. 4. Make the B-Spline skeleton curve the current level and create a group referring to some points of the curve. 5. Apply Animate/Create/Path to the group. 6. Create the second parameter for the skeleton method, to the same level with the primary skeleton curve. Note that the direction of the secondary skeleton should be somewhat perpendicular to the primary skeleton. You can use an axis primitive (Create/Controls/Axis). Figure @{"T6-30:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-30"} Logo Text Controlled by the General SKELETON Method. (PICTURE: T6-30) Play the animation and compare it to the corresponding SIMPLE SKELETON animation. Your logo is bent along the primary skeleton curve and individual characters of it are rotated to match the curvature of the skeleton. 6.10.2 Rotating Skin wound Bones The purpose of this example is to demonstrate and clarify the purpose of the secondary skeleton required by the general skeleton method, and how it can be used for rotating target objects around the primary skeleton. 1. Create a freeform tube by rotating a curve around a horizontal axis (Create/Freeform/Rotate). Stretch the tube so that the cross-section of it is ellipse. This helps you to visualize the animation when it will be played. 2. Make the freeform tube mesh the current level and subdivide its control polygon to sub-groups horizontally (each sub-group should be an ellipse around the axis of the tube). 3. Create a SKELETON method to control the sub-groups (so put it to the same hierarchy level with them). 4. Create the primary skeleton curve, following the axis of the tube, under the method. 5. Create the secondary skeleton by using the function Create/Controls/ Axis; draw the axis perpendicular to the primary skeleton. 6. Select the menu Animate/Control/Refresh so REAL 3D matches the targets with the skeletons. 7. Now, bend the primary skeleton curve and refresh the animation system. The freeform tube is bent accordingly. 8. Swap the orientation of the View window so you look along the primary skeleton, select the secondary skeleton and apply the function Animate/ Create/Rotate to it. This makes the secondary skeleton rotate around the primary skeleton, making the "skin" (= the tube surface) also rotate accordingly around the "bones" (= the primary skeleton). Figure @{"T6-31:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-31"} Secondary Skeleton Rotates a Freeform Tube around its Primary Skeleton. (PICTURE: T6-31) Play the animation; try rotating the View window so you can see how the freeform tube rotates around its "elastic axis". Let us leave the SKELETON method now and enter the next example section which demonstrates the use of INVERSE KINEMATICS. @endnode @node "T6.11" @title "Chapter 6 ANIMATION SYSTEM" 6.11 INVERSE KINEMATICS Whenever you decide to switch you computer on, you just push the power switch with your finger-tip. Let's analyze from animator's point of view, what happens when you switch your computer on. All kinds of muscles in your shoulder rotate your upper arm around your shoulder. Also your biceps rotate your forearm around the elbow. Finally muscles in the forearm bend your finger around its joints so that your finger-tip eventually pushes the button, This means that the position of your finger-tip is determined by the positions of the bones between the finger-tip and the shoulder. In other words, the way your muscles modify the bones makes the finger-tip hit the power-switch. This is not how Inverse Kinematics works. When using Inverse Kinematics, you don't have to define how the bones should be rotated in order to produce a desired route for the finger-tip. You just define the position or route for the finger-tip and Inverse Kinematics solves the problem, how the bones should be positioned. 6.11.1 Curl a Finger In this example we will create a simple finger by using a conical tube tool and control it by using the INVERSE KINEMATIC and SKELETON methods. If you are already familiar with the conical tube tool, you know it creates its objects by combining quadrics, such as cones, cylinders and spheres. Because this tool is suitable for modelling robots, the question "how to keep joints stuck to each other" is quite an interesting one. The idea of this example is the following: an object created by a tube tool represents one finger. A SKELETON method is used for controlling many finger objects and the skeleton curve is animated by defining the path of its end point using INVERSE KINEMATICS. This is quite a common way to use inverse kinematics with skeletons. 1. Create a polygonal line using the function Create/Controls/Open Line. This line represents the bones of your finger, hence it consists of four points. It will be used as a primary skeleton curve. 2. Create a tube representing your finger by selecting the menu Create/ Compound Tools/Conical. Because you use quadrics, the skeleton must perfectly match the tube. So, use dragging when you define center points for conical tube joints. Because inverse kinematics allows you to define the position for the END point, make sure that the direction of your tube is the same as the direction of your skeleton. Otherwise you would define the position for a finger-root, not for a fingertip. 3. Make the tube object the current level and create a SKELETON method to the same level with the component primitives of the tube. 4. Use Cut and Paste to move the skeleton curve under the method object in the hierarchy. 5. Create the secondary skeleton by creating an axis primitive perpendicular to the primary skeleton. Now the skeleton is ready, so select the menu Animate/ Control/Refresh. This instructs REAL 3D to fix the target objects to their current positions on the skeleton. 6. Now, select the primary skeleton curve and the function Modify/Special/ Inverse Kinematics and modify the end point of the skeleton. Then refresh the animation system and, as you can see, the finger is pulled to the skeleton and all the joints of the finger remain connected. 7. Create an INVERSE KINEMATICS method at the same level with the skeleton curves; the skeletons will be targets for the INVERSE KINEMATICS method. 8. The INVERSE KINEMATICS method requires only one parameter, which defines the end point of the target curve. So, create a B-Spline curve defining the route for the end Figure @{"T6-32:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-32"} T6-32: INVERSE KINEMATICS moves the end point of the skeleton while the skeleton determines the position of the finger. (PICTURE: T6-32) Play the animation, and the finger tip follows the defined curve (unless the curve is too far so that the finger cannot follow it; then the finger just reaches out as much as possible). Okay, let's improve this animation a bit. So, jump to the next example but don't delete this one. @endnode @node "T6.11.2" @title "Chapter 6 ANIMATION SYSTEM" 6.11.2 Push a Button with the Finger-tip Lets create an animation where a finger pushes a button. This can be accomplished by using the same object to define motions for the button and the finger-tip. To do this: 1. Create a level object called "button" under the root level and a cube representing a button under the button level. 2. Create a PATH method object under the button level. 3. Create a motion for the button by using a stretched circle: create a circle under the path method and use Modify/Linear/Extend to stretch it horizontally so that it becomes just a straight line. 4. Create a link pointing to the stretched circle (select the circle and use the menu Create/Structure/Link). 5. Modify/Structure/Cut the link. Modify/Structure/Delete the original path under the INVERSE KINEMATICS method and Modify/Structure/Paste the link to replace it. The INVERSE KINEMATICS method now uses the circle to define the end point of the skeleton . Figure @{"T6-33:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-33"} The Button and the Finger use the same Path. (PICTURE: T6-33) Make sure that the finger is close enough to the button and play the animation. Because the same primitive is used for defining the motion for the both objects, the result gives an impression that the finger pushes the button. 6.11.3 Interactively Controlled Hierarchical Skeletons This example demonstrates how to create a hierarchical skeleton, and how to control it interactively using inverse kinematics. It is not difficult to find examples of hierarchical skeletons. Just look at your hand and you can see one example. The ability to fork one skeleton to several sub-skeletons is often needed, especially when creating character animations. Actually, great deal of power provided by skeletons is based on this feature. So, how to create hand-like hierarchical skeletons? The answer is simple: skeletons can be targets to another skeletons. So, lets examine how to create such a hierarchical skeleton object and how it can be controlled and modified. 1. Create a polygonal line (Create/Controls/Open Line) consisting of three points representing your arm: shoulder, elbow, wrist. 2. Create an arm using the Conical Tube tool. Snap the joints of the tube to the points of the polygon using dragging, to get perfect matching. 3. Create a SKELETON method under the tube object so that all primitives of the tube will be targets for the method. Use Cut and Paste to move the skeleton line under the method. Also create the secondary skeleton (Controls/Axis). Later, we will rotate the secondary skeleton to make the robot rotate its wrist. 4. Select Animate/Control/Refresh and now the arm is fixed to the skeleton. Select the skeleton curve and use Modify/Special/Inverse Kinematic to modify it. Refresh the animation system again, just to make sure that the skeleton really works. Note that if you have installed the default key-bindings, you can use hot keys to do that. This makes the interactive handling of skeletons much more convenient compared to corresponding menu selections. 5. Select Modify/Structure/Copy while the entire arm object is selected. We are going to create all fingers by duplicating and scaling the arm. 6. Create a new level object at the same level with the SKELETON method and rename it as "fingers". Make it the current level. 7. Select the menu Modify/Structure/Paste. Modify the pasted arm smaller so that it represents a finger. 8. Create the second and third fingers by duplicating and rotating the first one. 9. Now, set the value of tag ISKE associated with the SKELETON method controlling the arm to 0. This tells REAL 3D that the situation is changed, and the information of the relationship between the targets and the skeleton should be redefined. Select the menu Animate/Control/ Refresh and your "Robot Arm" is complete. Figure @{"T6-34:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-34"} A simple robot arm. Skeletonally controlled fingers are sub-objects of skeletonally controlled arm. (PICTURE: T6-34) After practising this a couple of times, it should not take more than a minute or two to build up this kind of hierarchical robot arm. So, let's have a look how this arm can be controlled by using inverse kinematics (naturally you can use all normal modify/animation functions to manipulate it, too). In order to move its wrist to another place, just select the skeleton line used for controlling the upper arm and the forearm and move its end-point with the Modify/Special/Inverse Kinematic modification, then select Animate/Control/Refresh and the arm, including all fingers, is pulled back to the skeleton. If you want to define a new position for a finger-tip, just select the skeleton line used for controlling the finger in question, use Modify/ Special/Inverse Kinematics and refresh the animation system. In order to define the same position for all finger-tips, select the "fingers" object (in other words, the object containing all the fingers), and use Modify/Inverse Kinematics etc. But how to rotate the wrist of the arm? Select the secondary skeleton curve of the skeleton method controlling the arm and rotate it using any suitable function . Refresh the animation system and fingers are rotated accordingly. As you already noticed, the inverse kinematics function always modifies the end point of the skeleton. So how to define a position for the other end? Just swap the direction of the skeleton using the function Modify/ Freeform/Swap Direction, use inverse kinematics and swap the direction back. We will need this arm in the next example, so don't delete it yet. 6.11.4 An Animated Robot Arm In this example we will define fixed positions for all the finger-tips and a motion for the wrist. 1. Create three offset primitives under the root level. We will use these offsets for defining fixed positions for the finger-tips. The reason why we create the offsets above the arm level is that when we animate the arm, it should not animate these offsets (because we want that they stay fixed). 2. Create an INVERSE KINEMATICS method under the skeleton method of each finger. 3. Create a link to each offset and Cut&Paste it under the corresponding INVERSE KINEMATICS method. 4. Create an INVERSE KINEMATICS method under the skeleton method used for controlling the entire arm, and create a B-Spline curve defining a motion for the wrist, under the new method. Figure @{"T6-35:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-35"} A Skeletonally controlled arm. The wrist is moving, while the finger-tips and the shoulder remain fixed. (PICTURE: T6-35) Before we leave these Inverse Kinematics examples, it should be noted that examples we have gone through so far could only scratch the surface of all the possibilities which inverse kinematics and skeletonal control offer. For example, they are very important tools when animating mechanical devices, such as engines of cars and especially when building up mechanical connections. @endnode @node "T6.12 @title "Chapter 6 ANIMATION SYSTEM" 6.12 MORPHING Actually, we have already created some morphing examples. However, it is time to acquaint you with two methods which are designed especially for morphing. They allow you to morph objects as well as materials. Morphing methods are based on key framing. This means that you can determine the shape of an object by defining two or more key-frames for it. When the animation is played, the shape of the object is modified from the first key frame towards the last. REAL 3D automatically interpolates intermediate frames for you, using extremely "smooth" B-Spline interpolation. This means that the objects and points do not move along a straight line between corresponding key frame positions but along a B-Spline curve. This feature is very valuable, especially when morphing camera positions. Morphing methods can also be applied to texture maps and materials. 6.12.1 Second Talking Head Let's create the example presented in the Path example 6.1.6, a talking head, but now using morphing. 1. Create a head; just a profile curve will do, to make modelling simple. 2. Create MORPHING OPEN method to the same level so the profile curve will be target of the method. 3. Copy the profile curve using Modify/Structure/Copy and paste it under the method object four times and modify the copies (actually the mouth; the purpose was to make the head talk) so they all look different. These are the key frame objects. Figure @{"T6-36:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-36"} Morphing Applied to a Freeform Shape. (PICTURE: T6-36) Play the animation and you see the head talking. As you have already figured out, morphing defines the shape of the target object by using its parameters, in other words, key frame objects. Just like any other method, the morphing method can have more than one target. In other words, you can use one morphing method to morph more than one object. 6.12.2 Singing Heads Lets create two heads singing the same song. This means that the only difference between heads is that they are in different positions, but the song is the same for both of them. 1. Create a talking head as described in the previous section. 2. Duplicate the target object so the morphing method has two targets instead of one. Note: That the order between the targets and the method is irrelevant. 3. Add the following tag to the second head: VOFF 1.5 0 0 This shifts the second head from the position defined by the key frames. Figure @{"T6-37:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-37"} Two Heads are Morphed by the Same Information. (PICTURE: T6-37) Play the animation and the result is two singing heads. 6.12.3 Sing the Same Song Ten Times Because we used MORPHING OPEN method in all the previous morphing examples, the head started from the first key shape and stopped to the last shape. However, in order to create a head singing the same song more than once, the MORPHING CLOSED method should be used so all motions repeat smoothly and continuously. So, lets create a head which sings the same song ten times. 1 . Create one singing head as described in the first morphing example, but use MORPHING CLOSED method instead of MORPHING. 2. Modify the method by using the function Modify/Properties/Animation: set the frequency to 10. Play the animation and your head sings the song ten times. Figure @{"T6-38:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-38"} Closed Morphing (PICTURE: T6-38) 6.12.4 Morphing Hierarchical Objects In this example, we will show you how to morph hierarchical objects and objects containing other than freeform objects. When applying morphing to hierarchical objects, the hierarchy is used for detecting what parts of the targets and the key objects correspond each other. This means that the hierarchical structure should be the same (otherwise the result may be unpredictable). As an example, we create a morphed hierarchical candlestick created with the Lathe tool. 1. Use Create/Compound Tools/Lathe to create a nice candlestick. This tool uses cylinders, cones, ellipsoids, spheres and hyperbolics to construct the shape defined and automatically creates a new hierarchy level, placing all primitives under it. 2. Create a MORPHING CLOSED method to the same level with the candlestick. 3. Copy the candlestick and paste it inside the method object as many times as you wish. Modify all key candlestick shapes so they look different. Note: That there are no restrictions for the number of keys or the depth of the key object hierarchy. 4. Because it probably is not desirable to see the key objects, select the method object, select the function Modify/Properties/Attributes and set the gadgets WF-Invisible and RT-Invisible so only the result object will be visible. Of course, it is possible to create an animation where the key objects as well as the result are visible too! Figure @{"T6-39:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-39"} Morphing A Hierarchical Candlestick (PICTURE: T6-39) 5. Play the animation. @endnode @node "T6.12.5" @title "Chapter 6 ANIMATION SYSTEM" 6.12.5 Morphing Texture Maps and Materials If you are already familiar with REAL 3D texture mapping, you know that textures are mapped on objects by using mapping primitives like rectangles and cylinders. Because the mappings are just ordinary primitives in the object hierarchy, they can be animated just like any other objects. You can define all kinds of transformations for mappings using all available methods, and morphing is not an exception. However, there is one difference between morphing and other methods. Morphing does not only change the shapes of mapping primitives, but properties of materials referred by the mappings too! In other words, if a target object for a morphing method is a mapping, also the material associated with the target mapping is morphed, using materials associated with the corresponding key frame mappings as "key materials". Let s practice this a bit by creating an animation where some material properties are morphed. 1. Create three materials named as "result", "color" and "bump", each having for example a wooden texture map. We are going to use the last two as keys for defining the material properties for the "result". Set Bump height to zero for the "color" and to maximum for the "bump" so you can see the difference when result material is interpolated through the key materials. Set the Color and Bump gadgets for the "result". 2. Create a sphere. 3. Create a level at the same level with the sphere and rename it as "mappings". Use the function Modify/Properties/Attributes and set the "Mapping" gadget. The object now consists of one sphere and one level which will be used for defining materials for the sphere. (Remember the philosophy: a moving car consist of a car shape and the motion; a wooden sphere consists of a sphere and wood). By setting the Mapping flag for the level, you instruct REAL 3D to look inside the level to seek possible material references. 4. Make the level object the current level and create one mapping primitive inside it by selecting the function Create/Mapping/Parallel; use the material "result". This means that the texture associated with the result material will be projected over the sphere using parallel mapping. 5. Create a MORPHING method to the same level with the previous mapping. 6. Create two parallel mappings under the MORPHING method. Use the material "color" with the first mapping and "bump" with the second. Figure @{"T6-40:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-40"} Morphing Applied to Materials (PICTURE: T6-40) Your material morphing animation is now complete and ready to be played. Before you play it, open a Material window and load the material "result" so you can see how properties will change during the animation. 6.12.6 Camera Flight Animation This example demonstrates how camera flights can be easily created with the MORPHING method. 1. Create a cube, just to have something to look at in the animation. 2. Create a level object called "camera_here" 3. Set the perspective projection type (View/Type/Perspective) and select the menu View/Observer/Create Camera. This creates a level object consisting of the aimpoint and the viewpoint primitives. 4. Create a MORPHING OPEN method to the same level with the camera and make it the current level. 5. Find a suitable viewing angle using the cursor keys. When found, create the first key object by selecting the menu View/Observer/Create_Camera. 6. Modify the viewing angle and create a new key object, using View/ Observer/Create_Camera. Repeat this until the desired key positions are included. 7. Activate the menu View/Observer/Camera_View. This instructs the View window in question to use orientation defined by the camera objects. Play the animation; the orientation of the View window is fetched from the first viewpoint and aimpoint, which in turn are modified by the MORPHING method. The result is a camera flight animation. @endnode @node "T6.13" @title "Chapter 6 ANIMATION SYSTEM" 6.13 TRANSFORM The TRANSFORM method is different from other methods: it is used for modifying the time. In other words, it is a sort of time machine capable of modifying time so that it becomes non-linear; it can even make the time to go backwards. All objects after the method in the hierarchy will see the modified time. 6.13.1 Piston 1. Create a level object called "up&down". 2. Create a cylinder representing a piston under "up&down" level. 3. Create a PATH method to the same level with the piston. 4. Create a vertical axis under the method level. Play the animation and the piston will move along the axis with constant speed ... no good. 5. Create a TRANSFORM method at the same level with the "up&down" object. Multi-select the TRANSFORM method and "up&down" and select Modify/ Structure/Swap to change their order in hierarchy; the method should be above "up&down". 6. Create an axis and a circle inside the transform method as shown in the picture below. Figure @{"T6-41:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-41"} TRANSFORM Method Modifies the Time. (PICTURE: T6-41) Play the animation and the piston will act like a real piston. 7. Use Modify/Properties/Animation to change the frequency of the TRANSFORM method to 4 and the piston will run up and down four times. Let's try to understand why the piston started to go up and down just like any real piston. The transform objects requires two parameters; in this example an axis and a circle. The method evaluates a point from the circle corresponding the current time. Then it projects the point to the axis and the parameter value corresponding the projected point on the axis is the new time. For example, if the projection of the evaluated point hits the beginning point of the axis, the new time would be 0.0. If the point hits the end point of the axis, the new time would be 1.0. In this example we used a circle, but it is possible to use any other evaluable object as well. @endnode @node "T6.13.2" @title "Chapter 6 ANIMATION SYSTEM" 6.13.2 Hesitating Piston The purpose of this example is to show in an intuitive manner how the TRANSFORM method actually works. We will use a small sphere and a horizontal axis to show how the point is evaluated from the transformation curve and projected to the axis. This is done simply by using the transformation curve to also define a motion for the sphere object. 1. Create one level object called "piston" and create the piston example presented in the previous example section under that level; use a B-Spline curve instead of the circle to define a time transformation (see the picture below). 2. Create a new level to the same level with the "piston" object. 3. Create a sphere, a horizontal axis and a PATH method under the new level. Place the sphere and the horizontal axis at the beginning of the B-Spline curve. 4. Create a link which points to the B-Spline curve of the transform method and move (Cut/Paste) it under the PATH method. This makes the PATH method move the small sphere and horizontal axis along the same curve which is used for time transformation. Figure @{"T6-42:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-42"} A Time Transformation (PICTURE: T6-42) When you play the animation, by following the sphere you can see how the time transformation works: the current position of the sphere shows the current point evaluated from the transformation curve. The point is projected to the vertical time transformation axis - you can "read" the projection value by checking where the horizontal line hits the axis. The distance from the crossing point to the beginning of the time axis in proportion to the whole time axis length defines the new local time for the objects affected by the TRANSFORM method. When the B-Spline curve turns downwards, the crossing points move downwards, too; this means the time starts to run backwards. @endnode @node "T6.13.3" @title "Chapter 6 ANIMATION SYSTEM" 6.13.3 Three Dimensional Time Multi-dimensional time ... sounds terrible, but it is true. It is possible to fork one dimensional time to three dimensional time. This example demonstrates how to do it and how to use this possibility. In order to understand three dimensional time, we have to understand how the animation system of REAL 3D works. Curves, such as B-Splines and circles, can be defined using so called parametric representation: each point on the curve is represented by a parameter value between 0 and 1. The value 0 corresponds the start point of the curve, and the value of 1 corresponds the end point of the curve. In other words, when the parameter value runs from zero up to one, the corresponding point moves from the beginning of the curve to the end point. When an animation is played, the time runs from 0 to 1. Methods use this time for evaluating points on their parameter(s). If a new time value is given, the method knows that it should do something to make the target objects match the new situation. For example, the PATH method knows that it should move its target objects as much as the evaluated point has moved from the previous frame. As long as the parameter object can be fully parametrized by using only one value, we need only one dimensional time. But, there are lot of objects which cannot be represented by one parameter. For example, a B-Spline mesh is such an object. To clarify this further, we compare a B-Spline curve and a B-Spline mesh and illustrate how the parametrization works for them. A B-Spline curve can be parametrized using only one value. We could use the term "length" for that value. The reason why only one dimensional parameter value is enough is that any position on the curve can simply be specified by mentioning the distance from the beginning point of the curve to the point along the curve. This is not possible with a B-Spline mesh. Instead, we need two values for describing all possible points on the surface. These values could be called as "width" and "height". For example, if the value pair 0,0 corresponds the top left edge of the surface, then the value pair 1,1 corresponds the bottom right corner of it. 0.5,0.5 corresponds the middle point of the surface etc. The time can be forked to three dimensions using a coordsys primitive as a parameter for the TRANSFORM object instead of an axis. A Coordsys includes 3 axes to project the evaluated point to, instead of one. It is possible to move objects along a B-Spline mesh by defining the motion using dimensional time and the mesh as a method parameter. Let's stop the theoretic discussion now and demonstrate this in practice. 1. Create a TRANSFORM method. 2. Create a coordsys primitive under it. 3. Create a B-Spline curve under the method so that it begins from the origin of the coordsys and wriggles between X and Y axes of the coordsys, as shown in the picture below. 4. Create a level object, at the same level with the transformation object, and make the level the current level. 5. Create a small sphere 6. Create a PATH method, animating the sphere. 7. Create a B-Spline mesh under the PATH method level. Figure @{"T6-43:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-43"} Sphere Moves along a B-Spline Mesh. (PICTURE: T6-43) The route of the sphere is defined in the parameter space of the mesh using the transform method. Play the animation and the sphere moves along a mesh. The path of the sphere is similar to the shape of the B-Spline curve, which is used as a parameter for the TRANSFORM method. 8. Bend the mesh so that it is not planar. The consequence is that the route of the sphere is bent accordingly: the sphere still moves along the mesh, no matter how much you stretched or bent it. If you have read the presented transform examples carefully, you have probably already invented some new ideas how to use the method. However, if you are familiar with some other high-end animation systems, you might ask a question: why is this "transform thing" an object, not a separate nice window? Here is the answer: because it is an object, it can be animated by using all possible animation methods. This allows you to even create animations with "feed-back". Well, it is time to go to the next chapter. And I promise, the following examples are worth reading. @endnode @node "T6.14" @title "Chapter 6 ANIMATION SYSTEM" 6.14 RADIAL FORCE Welcome to the world of force fields and particles. We could write a separate book of all possibilities and possible applications for this subject. But while waiting for that book, and before explaining any of the theory behind particles and those sorts of things, lets get started by creating the first particle system oriented animation. 6.14.1 Gravity The RADIAL FORCE method generates a force field which affects the target objects, so that the direction of the force field is defined by the line between the "center point" of the method and the particle. If the radial force field is positive, it pulls all targets towards it. If it is negative, it pushes targets away from it. This makes this method very suitable for simulating effects like electrical forces, magnetism and gravity. So, let's create a particle system which uses the RADIAL. FORCE method for generating a gravity field. Our example consists of some particles, a RADIAL FORCE method and a PROCESSOR method. 1. Create one circle, activate macro recording, duplicate the circle, move the circle a bit, end macro recording and repeat the current macro 10 times. The circles are the particles. 2. Create a RADIAL FORCE method at the same level with the circles. 3. The RADIAL FORCE method requires one parameter, which is the position of the force "source". Use Create/Controls/Offset to create the parameter under the method. 4. Create a PROCESSOR method to the same level with the force method. Figure @{"T6-44:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-44"} A simple particle system. The gravity field pulls particles towards it. (PICTURE: T6-44) Play the animation and all particles start to fall down towards the gravity point. First, what is a "particle system"? Traditional particle systems consist of a large number of particles (usually just points represented by their velocity, color etc.) acting under the influence of external force fields, such as gravity or wind. However , the particle system of REAL 3D is not what could be described as "a traditional particle system". The biggest differences are that force fields in REAL 3D are properties of objects themselves, and any object can be used as a particle. One could almost say that there is no particle system at all in REAL 3D. There are just objects which interact with each other and the animation is the result of such interaction process. But that is the situation in the Real world, too! Because the particle system is implemented using methods, it is fully integrated to the animation system. This allows you to mix particle system oriented methods with all other methods. For example, if you have a walking robot, you can move it forwards using a force method. Because of historical reasons, we use the term "particle" in the following examples instead of "target object". Anyway, a particle is just a target object of a particle oriented method. So, how then do the "particle oriented" methods of REAL 3D work? Particle oriented methods, such as RADIAL FORCE, generate a force field. This force field affects the "velocity" attribute of the object. The longer the force field affects the object, the more the velocity of the target is changed. This all happens according to Newton's laws of motion. If you recognize the formula F=m*a this all should be very clear to you. The term "F" in the formula describes, how strong the force field affecting the particle is. The term "m" is the mass of the particle and the term "a" is the resuming acceleration. In other words, if the force "F" affects the particle whose mass is "m", the acceleration for that particle will be "a". What exactly is "acceleration"? Acceleration describes how much the velocity of the particle changes ("dv") during one second and can be solved from the following formula: dv a = ---- dt By combining these two formulas, we can solve how much the velocity of a particle is changed during the time "dt". F * dt F*dt=m*dv=>dv= ------ m So, if the strength of the force field generated by a force method is 1000 N, if the mass of the particle is 100 kg and if the time between subsequent frame is 0.1 s, the velocity of the object is changed 1000 kgm/s*0.1s dv= --------------- =1.0m/s 100 kg So, the purpose of the RADIAL FORCE method is just to change the velocity of target objects in very natural manner. By default, the method generates a force field which behaves like gravity. The formula used for that is: m1*m2 F=g* ----- s where m1 is the mass of the particle, m2 is the mass of the gravity point and "s" is the distance between them. "g" is the so called gravity factor whose value is 1.0. However, you can define the strength of the force field by associating custom formulas with the method object, as we will see later. Attributes, such as mass, acceleration and velocity itself, do not move objects. To change the attributes to real motions, the PROCESSOR method is needed. This method reads all relevant attributes of target objects and moves (and rotates) the targets accordingly. So, in order to create a particle animation, we need some particles, perhaps one particle system oriented method which modifies velocities and other properties of particles, simulating the Newtons laws of motion, and finally we need a PROCESSOR method which transforms the attributes of target objects to real motions. If you have read all text above, you recognize the term "dt" and know that it means the time in seconds. So, how many seconds is the entire animation? Open the animation window. The Seconds field describes the length of the animation in seconds. If the Resolution (number of frames) is 40 and Seconds is 1.0, this means that the "dt" between two subsequent frames is 1.0s / 40 = 0.025s. Lets demonstrate the purpose of the Seconds field with an example. @endnode @node "T6.14.2" @title "Chapter 6 ANIMATION SYSTEM" 6.14.2 The Simplest Possible Particle Animation Next we create an animation without any force fields. The question is, how to generate motions if there are no force field methods present? The answer is: we define the velocity attribute for particles manually. 1. Create a sphere (a particle) 2. Select the sphere and select the function Modify/Properties/Velocity. This function allows you to define a line which represents the velocity vector of the particle. In other words, the particle will move that much in one second. 3. Create a PROCESSOR method. 4. Play the animation, and the particle moves. Now, double the value of the Seconds field of the animation window. Play the animation again and the particle will move twice as far, in other words, twice as fast. You can also modify the velocity attribute by selecting the particle and selecting the function Modify/Properties/TAGs. There should be a tag WEL associated with the particle describing its velocity. If it does not exist, the particle's velocity is zero (in other words, the particle is static). Now, select the sphere and the function Modify/Properties/Spin. This function allows you to define three values in radians, representing three component spins. The value 3.14 makes the particle rotate 180 degrees around the corresponding axis in one second. Note that the rotation is defined in "object space". This means that if you rotate an object using, for example, the Modify/Linear/Rotate function, the spin axes are also rotated accordingly. Define some spin values and play the animation. Now your sphere moves and rotates. 6.14.3 Customized Radial Force As we have already mentioned, it is possible to define a custom formula which defines the strength of force fields produced by particle methods. In this example, we will create a particle "flock" which acts under the influence of such a customized force field. 1. Create a particle flock consisting of circles. 2. Create a RADIAL FORCE method to the same level with the circles and add the following tag to it: SFOR f=100000*(s-2) 3. Create an offset under the RADIAL FORCE method so that the distance between the particles and the offset is greater than 2 m. 4. Create a PROCESSOR method to the same level with the RADIAL FORCE method. 5. Open the animation window and set the Resolution to 200 frames (this gives you more time to analyze what will happen). Play the animation. Because in the beginning, the distance between the particles and the force source is greater than 2.0, s-2 is positive and the method pulls particles towards it. As soon as the distance to any particle gets shorter than this value, the method starts to push it away. For more information about all possible variables for RADIAL FORCE see the Reference section. @endnode @node "T6.15" @title "Chapter 6 ANIMATION SYSTEM" 6.15 DIRECTED FORCE The DIRECTED FORCE method can be used for generating force fields with arbitrary and variable directions. Thus, it can be used for simulating wind, turbulence etc. The DIRECTED FORCE requires only one parameter, which describes the direction of the force field during the animation. When the animation is played, the method evaluates a point and a corresponding direction from the parameter curve. The distance between the evaluated point and the particles is used for determining the strength for the force. Thus, the closer the particle is the parameter object, the stronger the force. 6.15.1 Turbulence The purpose of this example is to demonstrate how the direction and the strength of the force is defined. 1. Create a particle flock. One very easy way to do it is to use Create/ Compound Tools/Object-Pixel Tool. 2. Create a DIRECTED FORCE method. 3. Create a B-Spline curve under the method. The direction of the force is the direction of the curve corresponding the current time. When the animation is played, the time runs from 0 up to 1 and the direction of the force varies according to the curvature of the method parameter. If the parameter is just a straight line, it generates a force field with constant direction, because the direction of the curve is the same everywhere. A Circle makes the force field rotate etc. 4. Create a PROCESSOR method at the same level with the force method. Figure @{"T6-45:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-45"} A Directed Force Field Defined by a B -Spline Curve. (PICTURE: T6-45) 5. Set the Seconds field of the Animation window to 2.0. Play the animation. The shorter the distance between the particle and the parameter object, the stronger the force field. @endnode @node "T6.15.2" @title "Chapter 6 ANIMATION SYSTEM" 6.15.2 Snow in the Wind The purpose of this example is to demonstrate use of multiple methods at the same hierarchy level. This means that more than one force field affects the particles and the result force is the sum of several forces. First we need a force field which pulls the snow down (the gravity). This can be implemented using a straight line as a parameter for the DIRECTED FORCE method. Then we need a force field representing the wind. One way to create wind is to use several force methods at the same level so that different parts of the particle mass are affected by different methods; the closer a particle is to a method, the more that method affects it. This naturally causes some turbulence to the particle mass. However, in this example we will create a customized force field. The direction of the wind depends on the position of the particle causing the particle mass behave like snow in a storm. 1. Create particles representing snow flakes. The more memory you have, the more snow you can have. 2. Create a DIRECTED FORCE method and rename it as "gravity". 3. Add the following tag to the method: SFOR f=9.81 This means that the strength of the gravity is always 9.81. In other words, the distance between the parameter object and particles does not determine the strength of the force. The value 9.81 is very close the force field generated by the earth. 4. Create a straight line under the method object, representing the direction of the gravity (it should point downwards). 5. Create another DIRECTED FORCE method to the same hierarchy level with the first one and add the following tag to it: SFOR f=10, fx=sin((y+t)*10), fy=cos((x+t)*10), fz=0 Variables fx, fy and fz are used for defining the direction of the force and they are initialized to reflect the direction defined by the parameter of the method. Here we override the original values by using sin() and cos() functions. 6. Create an offset primitive under the method. We can use any evaluable object here, because our custom formula overrides the direction anyway. 7. Create a PROCESSOR method to the same hierarchy level with the other methods. Figure @{"T6-4:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-46"} Snow particles are affected by two separate force fields: one simulating the gravity and one simulating the wind. (PICTURE: T6-46) Open the animation window, set Resolution to 100 and Seconds to 10, and play the animation. If the result is not what you expected, cancel it and use Undo feature to restore the situation. Note that you cannot play the animation backwards to restore the situation; particle methods are such by their nature that running the time backwards does not produce the same events in reversed order, but results in a new situation. If things do not happen fast enough in the animation, increment the "Seconds" value. If too much is happening, decrement Seconds and/or increment frame resolution. You may also save the project before you play the animation; it is safer than using Undo, whose depth may not be sufficient if you make too many mistakes. For more information about the variables for the DIRECTED FORCE, see the Reference manual. @endnode @node "T6.16" @title "Chapter 6 ANIMATION SYSTEM" 6.16 TANGENT FORCE The third force type is the TANGENT FORCE. The direction of the force field is always perpendicular to the parameter object and the line between the target object and the center point of the force. The right hand rule can be used for visualizing the direction, so that if the thumb of your right hand represents the parameter object direction and your first finger points to the particle, your second finger shows the direction of the force. Figure @{"T6-47:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-47"} Tangent Force (PICTURE: T6-47) This method can be used for simulating rotating force fields like those found from electrical equipment, generators etc. Because the generated force field rotates target objects around the parameter object, the centrifugal force tries to explode the particle mass just like in the real world. 6.16.1 Centrifugal Force The purpose of this example is not just to demonstrate how to create a tangential force field, but also to demonstrate how hierarchical animated objects can be used as targets for particle oriented methods, and how these traditional and particle oriented methods can be mixed with each other. In this example we will use a "mechanically" animated object as a particle and let a tangential force field rotate such particles. Because of the centrifugal force, particles will disappear quite soon, but who cares. 1. Create a level and rename it as "particle". 2. Create animated legs (just as in the example 6.3.1 Walking Legs), under the "particle" object. 3. Duplicate "particle" so that you have several walking legs. 4. Create a TANGENTIAL FORCE method to the same level with the particles. 5. Create an axis primitive under the force method. 6. Create a PROCESSOR method to the same level with the TANGENTIAL FORCE method and the particles. Figure @{"T6-48:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-48"} Walking Legs as Particles Acting under the Influence of a Rotating Force Field. (PICTURE: T6-48) Set Resolution=100 frames, Seconds=10 and play the animation. Tangential force starts to rotate walking legs; because of the centrifugal force, all the walking legs go away. Now we have gone through all three force methods by studying just one or two simple examples of each of them. The reason for this is not that there are no more things to tell you about these methods, but these kind of force simulations require some basic knowledge of mathematics and physics, and it would require an entire book to go through all different features and possible applications. So, it is time to leave these force methods now and enter the next section. @endnode @node "T6.17" @title "Chapter 6 ANIMATION SYSTEM" 6.17 INTERACTIVE COLLISION DETECTION The collision detection methods allow you to create extremely impressive animations. For example, throw a football down the stairs and it bounces down just like it does in the real world. Put a sphere on a table, tilt the table and the sphere rolls along the table, falls down and rebounds from the floor. The list of possible examples is infinite. Interactive collision detection means that collisions are detected between all particles (objects). 6.17.1 Colliding Spheres 1. Create two spheres 2. Select the second sphere and define a velocity for it: select Modify/ Properties/Velocity and draw a line starting from the sphere, passing through the second sphere. This will make the spheres collide. 3. Create one INT COLLISION to the same level with the spheres. 4. Create a PROCESSOR method (you should already know to which level...). Figure @{"T6-49:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-49"} Collision Detection Applied to Two Spheres. (PICTURE: T6-49) Play the animation (if you continue from the previous example, first reset Seconds to 1.0). The second sphere moves towards the first one until they collide. After the collision, the first sphere also moves. This all happens according to Newton's laws of motion. 6.17.2 Multiple Collisons This example is very similar to the previous one except that now we use a chain consisting of several spheres and a cube. The first sphere collides to the second, the second to the third and so on. The purpose of the cube is to show how collisions change the velocity as well as the spin of objects. 1. Create several spheres and one cube so that the first sphere will hit the cube, after colliding with other spheres. If the sphere-cube collision point is not on the line between the centers of gravity of the objects, the collision makes the cube spin, too. 2. Define a velocity for the first sphere towards the other spheres. Make sure that the velocity is high enough (the velocity vector is long enough). 3. Add a tag "FMAS 500" to the first sphere. This redefines the mass of the sphere so that it is heavier than other spheres. If there is no FMAS tag associated with an object, the default mass, 100 kg, is used. 4. Create INT. COLLISION and PROCESSOR methods. Figure @{"T6-50:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-50"} A Heavy Sphere Producing Multiple Collision. (PICTURE: T6-50) Save the whole collision object and play the animation. If the velocity was not high enough, select Project/Project/New and reload the collision object. Again, remember that if you play the animation backwards, you won't get back the original situation. So, the best way to test particle animations and collision detection is to save the original situation and load it back when necessary (or use Undo). 6.17.3 Bowling Alley In this example we will create a complete bowling alley. When you play it, the bowling ball moves towards the pins while gravity makes it collide with the bowling alley . The bowling ball starts to rotate along the bowling alley due to the friction between the ball and the alley. Finally the ball collides with the pins, the pins collide with each other and all you have to do yourself is to write down the scores. After some practising, it should take only a couple of minutes to construct this kind of animation. 1. Create the bowling alley floor (e.g. a cube) and redefine the mass of it to be extremely high by adding "FMAS 100000000" tag to it. It must be very heavy because we don't want the bowling ball and the pins to affect the floor too much. 2. Set the "Modify/Properties/Attributes/Protected" flag of the bowling alley. We have to do this, because we don't want the gravity which pulls the pins and the ball against the alley to affect the alley itself. By setting this protected field, we can fix the position of the alley. 3. Create the pins on the bowling alley by using Create/Compound/Lathe and duplicate functions. 4. Create a bowling ball about 0.5 meter above the bowling alley, as if it has just been thrown towards the pins. 5. Use the function Modify/Properties/Velocity to define the horizontal velocity for the ball. The velocity vector should be almost twice as long as the alley. 6. Create an INT COLLISION method. 7. Create a DIRECTED FORCE method and use an axis primitive to define the direction for the gravity (downwards!). Add the following tag to the force method: SFOR f=10 This makes the strength of the force constant, just as real gravity is in bowling alley scale. The gravity force on the earth is actually not constant, it varies e.g. according to the distance from the centerpoint of the planet. Nevertheless, the gravity variations on the bowling alley surface are so small that they can be ignored in the bowling simulation. Now your bowling alley is ready. Save it and then play it, using e.g. 100 frames, because this complicated simulation requires quite an accurate temporal resolution. After playback, replace the scene with the original one (load or undo). Figure @{"T6-52:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-52"} Bowling (PICTURE: T6-51) By default, the friction between the ball and the alley is very low. This means that when the ball collides with the alley, it does not start rotating much. So, let's redefine the friction for the ball and the alley so as soon as the ball hits the alley, it starts to roll. 7. Select the ball and the alley and add following tags to them: FFRI 0.5 FFRI stands for FRIction, which depends on the type and the quality of the surface of the object. Note that you can define different friction factors for different objects, in which case the collision is processed using their average. To be physically correct, the value of this tag should be between 0 and 1. However, you can use higher values (or even negative ones), but the result of such unusual friction no longer corresponds real world. If your sphere collided improperly with the alley, you can increase the collision detection accuracy. There are several ways to do this. The first one is to increase the "Smpl" value in the animation window. This makes the animation system use higher internal resolution when playing the animation. The value of Smpl affects the quality of motion blur and the accuracy to which particle animations represent the laws of physics. The second way is to increase the Resolution value of the animation window. The more frames you specify, the shorter the time sampling interval between two consecutive frames becomes, and the better the accuracy which can be obtained. The third way is to add the tag ICSM to those objects between which higher accuracy of collision handling is needed. The value of the tag can be 0, 1 or 2 (default is 0). If the value of this tag is different between the objects under consideration, the minimum is used. For example, by adding this tag to the alley and the ball, the collision between them is processed in high accuracy, but collisions between the ball and the pins are processed using the default accuracy (because there is no ICSM tag associated with pins). The third way is usually suitable because you can use it selectively. 8. So, add the tag ICSM 2 to the alley and the ball. Now your animation should work perfectly. Save it, play it and enjoy. @endnode @node "T6.17.4" @title "Chapter 6 ANIMATION SYSTEM" 6.17.4 Drop a Ball to a Tube In this example, we will throw a sphere through a long curved tube. 1. Create a curved tube using the function Create/Compound_Tools/Circular_ Subdivided. 2. Multi-select all cylinders, select Modify/Properties/Attributes, and activate Hollow, No 1 st BP and No 2nd BP gadgets to make the tube hollow. 3. Define very high mass for the tube by adding the FMAS 1000000 tag to the tube object. 4. Create INT COLLISION and PROCESSOR methods to the same level with the tube. Figure @{"T6-52:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-52"} A Sphere is Guided through the Tube by Collision Detection. (PICTURE: T6-52) 5. Create a sphere and "throw" it to the tube by defining a suitable velocity towards the beginning of the tube with the function Modify/ Properties/Velocity. 6. Add the tag ICSM 2 to the tube and the ball. 7. Play the animation (1 Seconds, Resolution 100 frames). One important fact related to collision animations (and other particle oriented animations, too) should be noted: the result of such animations depend essentially on the detection accuracy adjustments, for example on the amount of frames specified when playing the animation. Therefore, it may be wise to use the final resolution all the time. The reason for this is that even minor changes result in an accumulative sequence of further chances. In fact, this is the situation in the real world, too: even the simplest collision systems are "chaotic" by their nature. 6.17.5 A Rolling Ball In this example, we will create a table and some spheres on it. When the table is tilted, spheres start to roll and fall down rebounding from the floor. We will use the SWEEP method to tilt the table. DIRECTED FORCE (gravity) and collision detection take care of the rest. 1. Create an object consisting of a floor and a table cover. Make the object very heavy by adding the tag FMAS 1000000 (one million kilograms!) to it and nail it to the universe by setting its Protected flag (use Modify/Properties/Attributes). Rename the object consisting of the table and the floor as "table&floor". 2. Create table tilting mechanism using Animate/Create/Sweep. Set the Start time of the sweep method (Modify/Properties/Animation) to 0.05 so that it starts to tilt when the time reaches that value. This gives you time to see how collision detection keeps the spheres on the table. Set the End time of the method to 0.5. 3. Create some spheres on the table. Put them to the same hierarchy level with the "table&floor" object. 4. Create a gravity field by using a DIRECTED FORCE method and an axis parameter. 5. Create INT COLLISION and PROCESSOR methods. Figure @{"T6-53:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-53"} Tilt the Table and the Spheres Fall Down. (PICTURE: T6-53) 6. Add the tag FFRI 1.0 to the table and the spheres. This makes the spheres also rotate (they don't just slide along the table). 7. Before we play the example, let us take a look at a tag called FREB. It allows you to define so called "rebounding factor" which defines how much a colliding object loses kinetic energy in the collision. The default is 1.0, which means that it does not lose kinetic energy at all. The value 0 causes object to lose all its kinetic energy making particles to stick to each other. So, save the animation now and play it. Then reset the time to 0, replace the object with the original one, add FREB 0.5 tags to the spheres and play the animation again. @endnode @node "T6.18" @title "Chapter 6 ANIMATION SYSTEM" 6.18 NON-INTERACTIVE COLLISION DETECTION As was already mentioned in the previous section, in interactive collision detection, collisions are detected between all objects. However, sometimes this is not necessary or even desirable especially when animating particle flocks consisting of thousands of particles. For example, when a man walks in snow, collisions between the man and individual snow particles should be detected and processed but snow particles need not collide with each other. Non-interactive collision detection method is designed for these kind of applications. It processes collisions which occur between target objects and parameter objects of it. However, collisions between target objects or collisions between parameter objects are not processed. So, let's practise this. 6.18.1 A Planet and Meteorites In this example we will create a planet and several meteorites. The gravity of the planet causes meteorites to collide with the planet. However, collisions between meteorites are not detected. 1. Model meteorites using small spheres 2. Create a COLLISION method to the same level with them. 3. Create a planet under the COLLISION method. Add the tag FMAS 10000000 to the sphere to make it very massive. 4. Create a RADIAL FORCE method to the same level with the meteorites. Create an offset primitive under it defining the position for the force. Create it in the middle of the planet. 5. Create a PROCESSOR method. Figure @{"T6-54:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-54"} Collisions only Between the Planet and the Meteorites. (PICTURE: T6-54) 6. Play the animation. Depending on the size of the objects, you may have to adjust the frame count; if meteorites move so fast that they get through the planet surface, just increment animation Resolution value. @endnode @node "T6.19" @title "Chapter 6 ANIMATION SYSTEM" 6.19 FRICTION Let's imagine a situation where a force affects an object. The force accelerates the object according to the Newton's law of motion: F=ma. This means that the longer the force affects to the object, the faster the object moves. However, this is not what appears to happen in the real world. The reason for this is that usually there are some other forces involved, making it very difficult to generate very fast motions. For example, the air is a such a resisting element. These resistive forces are called friction forces. The FRICTION method can be used for adding these "resistive" forces to the virtual reality of REAL 3D. If the velocity of an object is 0, the friction method does not affect it at all. The higher the velocity of the object, the more the friction affects it, direction of the friction force being always opposite to the velocity of the object. The strength of the resisting force is proportional to the velocity squared. The strength of the force depends on the size of the object, too. The bigger the object, the higher the friction force. However, the size has less dramatic effect to the force than the velocity attribute; the strength of the force is increased only linearly proportionally to the size. The mass of the object naturally determines how much the friction force can affect its velocity. The higher the mass, the less sensitive the object is to the friction force. The strength of the force generated by the friction method is defined using the following formula: d * e² f = Fmax * --------- d * e²+ 1 where d is the diameter and e is a total energy (kinetic+spin) of the object. The Fmax is the force needed to stop the object during the time interval between two subsequent frames. The formula can never produce bigger forces than this maximum force. The friction method does not require parameters. 6.19.1 Friction and Spheres with Different Sizes 1. Create three spheres with different sizes and define equal velocities for them by using the function Modify/Properties/Velocity. 2. Create two spheres with an equal size and add the tag FMAS 10 to the second one. 3. Create a FRICTION method to the same level with the spheres. 4. Create a PROCESSOR method. Figure @{"T6-55:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-55"} The Effect of the FRICTION Method on Different Objects. (PICTURE: T6-55) Play the animation and "air resistance" slows down the spheres. The bigger the sphere, the higher the friction . The higher the velocity, the higher the friction. The bigger the mass, the less the friction can change its velocity. 6.19.2 Customized Friction The FRICTION method can be customized, just like any other method, by adding a custom formula or procedure defining the strength of the friction force to it. This way it is easy to create some nice effects, like friction whose strength depends on the position (non-homogenous friction fields). So, let's create simple particle animation where radial force moves a number of particles while one customized friction method resists their motions. 1. Create a set of spheres. 2. Create a RADIAL FORCE method. Create an offset primitive, defining the center of the force field, under the method. 3. Create a FRICTION method and add the following tag to it: SFOR if(x<0,f=f*2,f=0) The variable "x" reflects the current position of the particle in question. So, the formula uses a conditional expression where f is either duplicated or set to zero, depending on the position of the particle. 4. Create a PROCESSOR method and play the animation. All particles on the left side (where the x coordinate values are less than zero) are affected by the friction, but particles on the right are not. Figure @{"T6-56:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-56"} A Non-homogeneous Friction Field. (PICTURE: T6-56) @endnode @node "T6.20" @title "Chapter 6 ANIMATION SYSTEM" 6.20 CREATION The CREATION method is a "procedural" object creation tool. This means that it can create new objects during animations. As a matter of fact, it can control the whole process of "birth and death". For example, phenomena like boiling water or fireworks are perfect applications for this method. The CREATION method accepts any number of parameter objects. The method uses the parameter objects as a samples for creating new copies. The copies are inserted to the same hierarchy level with the method itself so that they will be targets of it. The method can also delete target objects. The rules controlling this process are mainly defined using two tags associated with parameters and/or target objects: SCRE and SDEL. Whenever the tag SCRE is found from a parameter object, it is evaluated and the value of the "I" variable is used for determining whether or not a copy of the object should be created. If the value is zero (or if there is no SCRE tag associated with the parameter object), the copy is not created. If the tag SDEL is included in the target object and if the value of the variable "I" is other than zero, the target object is deleted. 6.20.1 A Sphere Tube This is perhaps the simplest possible example of using the CREATION method: a sphere which follows a path leaving copies of itself behind. 1. Create a CREATION method. 2. Create a sphere under it. 3. Add the following tag to the sphere: SCRE I=1 4. Create a PATH method to the same level with the sphere (under the CREATION method) and a B-Spline curve under the PATH method. Figure @{"T1-1:" system "display dh9:docs/r3ddoc/r3dv2pics/T1-1"} T6-57: A Moving Sphere as a Parameter for the CREATION method. (PICTURE: T6-57) Play the animation and the PATH method moves the "sample" object along the path while the CREATION method creates one new sphere in each animation frame. The target objects created by the method have all the properties of the sample object. 6.20.2 Boiling Water Another good example of procedural creation is boiling water. When the temperature reaches a certain level, bubbles begin to appear randomly inside the water and start to go up until they reach the surface of the water and disappear. Right, let's do this. 1. Create a CREATION method. 2. Create a bubble under the method and add the following tags to it: SCRE I=1 SDEL I=y>0.0 Because the value of the "I" variable in the SCRE tag is always 1, a new bubble is created in each frame. The SDEL tag defines that the bubble will be deleted as soon as its y coordinate reaches the value 0. 3. Use the function Modify/Properties/Velocity to define a velocity for the bubble. The idea is that as soon as the bubble is created, it will start to go upwards. 4. Create a PATH method to the same level with the bubble. Set the Frequency of the method to 5, and draw a strongly oscillating curve under the PATH method. The way we define the original position for the bubbles is quite "deterministic", but if the path is very curved and complicated, it will look as if the bubbles were created randomly all over the water (We will demonstrate you later how to use a real random function to define the position for the bubbles using RPL). 5. Create the PROCESSOR method to the same level with the CREATION method. As mentioned earlier, an attribute itself (such as mass, velocity etc.) does not move the object anywhere. The PROCESSOR method is needed for converting the attributes to real motions. Because we did not create a PROCESSOR method at the same level with the sample bubble, the sample won't go up (the velocity is there, but it is not converted to a motion). 6. Create a pot and a circle inside it representing the surface of the water in the pot. Note that we used the conditional expression "y>0" to define when bubbles should disappear, so the circle representing the level of the water should be placed to that height. 7. Make the CREATION method object invisible, to make the bubbles appear out of nothing. Figure @{"T6-58:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-58"} Boiling Water (PICTURE: T6-58) Now our boiling water example is ready. I strongly suggest that you save this project now and spend some time to render it photo-realistically. Use an animated bumpmap on the water surface and with these bubbles, the boiling water should look pretty good. 6.20.3 A Wriggling Snake This example demonstrates how the age of the object can be used for determining the time when the object should "die". As soon as the object gets old enough, it disappears. The sample object is moved along a B-Spline curve just like we did in our first CREATION example, but now we will also delete target objects so that the earlier an object is born, the earlier it dies. 1. Create the objects described in the example 6.19.3 but now add also the SDEL tag to the sample sphere: SDEL I=t-fx>0.1 The variable "fx" defines the time when the object was created. The variable "t" represents the Current time. So, the age of the object is t-fx and when the age gets greater than 0.1, the object is old enough for the deletion. Save and play the animation and in the beginning, it resembles our first CREATION example. However, soon the oldest spheres start to die and the number of spheres comprising the tube no longer rises. Figure @{"T6-59:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-59"} CREATION Method Animation (PICTURE: T6-59) Let's experiment with this animation a bit more. Reload it and try the following formula with SDEL tag: SDEL I=t-fx>0.2*sin(12*t)*0.1 Play the animation and the length of the "snake" varies while it moves along the path. @endnode @node "T6.21" @title "Chapter 6 ANIMATION SYSTEM" 6.21 PROCESSOR If you have gone through all animation examples so far, you are already familiar with this method. It is used for converting particle system oriented object attributes like the "velocity" to real motions. Let's consider a particle system which consists of a sphere, a radial force and a processor method and take a look at what actually happens when the animation is played. 1. The global time is increased by a value depending on the frame resolution and all methods are to be informed about the new time. 2. The RADIAL FORCE manipulates the velocity attribute of the sphere. Because the radial force knows how strongly (F) it affects the sphere and how long the time (dt) has affected the sphere since the last frame, it can calculate how much (dv) the velocity of the sphere having a certain mass (m) should be changed. This all happens according to the Newtons laws of motion: dv F * dt F=m*a=>F=m*--=>dv=------ dt m ======== If the formula "F=m*a" tells you nothing, you probably didn't understand everything presented above. However, the formula can be described in a more understandable form: if we know how long a certain force affects an object with a certain mass, we can solve how much the velocity of the object changes. 3. Then the PROCESSOR method reads the current velocity of the sphere and calculates how far (ds) the sphere has travelled since the last frame (dt) with its current velocity: ds v=---- => ds=v*dt dt ======= In a human readable form, this could be something like: if you drive your car and you know how long you have driven and how fast, you can calculate how far you will get. @endnode @node "T6.22" @title "Chapter 6 ANIMATION SYSTEM" 6.22 RPL The RPL method allows you to create your own RPL procedures and associate them with objects. When the animation is played, your procedure is executed in each frame and it is totally up to your procedure to decide what to do when this happens. Because RPL is a full featured programming language, there is not much you could NOT do with it. In a way, this method is one of the most powerful ones found in the program, but naturally, in order to take full advantage of it, you have to know how to write RPL programs. All built-in methods, such as PATH, SIZE, RADIAL FORCE etc. can be easily implemented using the RPL method. Because this subject is huge, we will go through only a basic example here. For more information about how to write new animation methods using RPL, see the RPL tutorial and the Reference manual. 6.22.1 An Easy Way to Write a RPL Procedure The easiest way to write such a procedure is to use the Macro function. So, let's try this: 1. Create a sphere. 2. Record a macro in which you move the object a bit. 3. Create a RPL method to the same level with the sphere. 4. Add the following tag to the method: SRPL "t:macro.rpl" LOAD Play the animation and the sphere moves. The RPL function LOAD loads the current macro "t:macro.rpl" and executes it. Whenever you use this method, there must be the tag SRPL associated with it. The contents of this tag is executed in each frame and it must be a RPL program. Usually the tag contains a function call to the actual procedure, which is a speed-efficient way. @endnode @node "T6.23" @title "Chapter 6 ANIMATION SYSTEM" 6.23 WAVE The WAVE method can be used for creating waves. If the first parameter of it is an axis primitive, then the method creates "radial" waves. If the first parameter is a coordsys, then the waves can be defined separately in each direction. The second primitive can be any evaluable object defining the shape of the waves. For example, a circle creates sine waves. 6.23.1 Waving Sea This example demonstrates the effect when the wave method is applied to freeform objects. 1. Create a mesh representing the surface of water. 2. Create a WAVE method to the same level with the mesh. 3. Create an axis under the method so that it is perpendicular to the mesh. 4. Create a circle under the method so that the axis splits it to two halves. Figure @{"T6-60:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-60"} Waving Sea (PICTURE: T6-60) Play the animation and waves are created over the entire mesh. Because the first parameter is an axis, the height of the wave depends on the distance between the point of the wave and the axis. 6.23.2 A Water Drop This example demonstrates radial waves, too, but now we use the surface which is constructed by rotating a curve around an axis, The radial nature of the generated waves can be more clearly seen in this kind of surface. 1. Create a "disk" mesh by using the function Create/Freeform/Rotate: just rotate a straight line of 10 points around an axis. 2. Create a WAVE method object with an axis and a circle. Note that you can use the same axis which you used for creating the mesh. Figure @{"T6-61:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-61"} Radial Waves (PICTURE: T6-61) Play the animation, Now the radial waves can be seen clearly. 6.23.3 Parallel Waves If the first parameter is a coordsys, then the profile of the wave remains the same when moving along an "y" axis. The shape of the wave depends on the distance between a point and the origin of the coordsys in "x" direction. The length of the "x" axis defines the wave-length and the length of the "z" axis defines the wave-height. 1. Create a mesh. 2. Create a method with a coordsys and a circle as shown in the following figure. Figure @{"T6-62:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-62"} Parallel Waves (PICTURE: T6-62) Play the animation and the method generates waves in "x" direction. 6.23.4 Waves and Ripples Of course, it is possible to create more than one WAVE method at the same level, in which case the generated waves will interfere with each other. In other words, the result wave is the sum of the component waves. Because the size of the parameters for wave methods defines the wave-length and -height, this feature can be used for example for generating "ripples" on waves. So, let's create two wave methods generating parallel waves perpendicular to each other. 1. Create parallel waves as described in the previous example. 2. Duplicate the method object, rotate it and make it much smaller. Figure @{"T6-63:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-63"} Interfering Waves (PICTURE: T6-63) Play the animation and there will be small waves in the big waves. 6.23.5 Waving Particles This example demonstrates how the wave method can be used for waving a set of primitives instead of a mesh. If the target object is not a freeform object, then it is treated as a "point" of a freeform object. Instead of using one freeform target for the method, we can use hundreds of primitives. So, let' s create an example where the wave method is applied to a number of spheres: 1. Create a line consisting of small spheres. 2. Create a WAVE method to the same level with the spheres. 3. Create a coordsys and a circle under the method. 4. Play the animation. Figure @{"T6-64:" system "display dh9:docs/r3ddoc/r3dv2pics/T6-64"} Waving Particles (PICTURE: T6-64) @endnode @node "T7.1" @title "Chapter 7 RPL" Chapter 7 RPL ------------- 7.1 INTRODUCTION RPL stands for REAL 3D Programming Language. It is a FORTH-like language integrated into the REAL 3D environment. It is a full featured programming language which provides you with power, flexibility and total control over all the features of REAL 3D. The language has three main uses: as a method for storing macros, as a file format for importing and exporting all the information needed to describe the scenes and animations you create, and as a programming interface to allow you to expand the functions of REAL 3D to fulfill any requirements you might have. Because RPL is meant to be used for expanding the REAL 3D program, it has been designed to be as fast in its execution as possible. It is also capable of making direct access to the Operating System. For these reasons, it is quite a low level language. However, considerable effort has been devoted to make it easy to learn with the intention of all users being able to make use of it. This section is intended to introduce you to RPL programming as easily as possible; but some understanding of basic computer programming principles has been assumed. If after reading through the introduction and working through the tutorial section you do not feel you have a full understanding of how to use RPL then there are many good books on introductory programming. Any that directly relate to FORTH will provide the best assistance, and most if not all the examples will work in RPL. 7.1.1 Basic Concepts First some RPL terminology to get started: Word A word is a collection of constants and references to previously defined words that are to be executed when the word is run; like a procedure or function in the languages "C" or Pascal. Vocabulary This is the collection of all defined words, variables and named constants. Stack This is an area of memory used by the RPL system for storing the information it needs to process the words you want to execute and the operands those words need for their execution. RPL, like FORTH, is a threaded language. Threaded languages grow incrementally; you define new words using existing words that are either predefined (standard RPL words) or words that you have defined earlier. RPL is interactive, it executes or compiles words the instant they are entered. New words become a part of the RPL vocabulary as soon as their definitions are completed. They can then be executed just by typing in their names and pressing , or they can be included in the definitions of new words. Words must be entered exactly as they appear in the vocabulary, upper-case letters must be upper-case and lower-case must be entered as lower-case. They must also be entered in full, they cannot be abbreviated in any way. @endnode @node "T7.2" @title "Chapter 7 RPL" 7.2 TUTORIAL 7.2.1 Getting Started To start your introduction to RPL the first step you must take is to open an RPL Window. Select PROJECT/Windows/RPL and a window very similar to an OS shell window will open. Through this window you will pass information to the RPL system and it can pass information back to you. To examine the interactive nature of RPL and for you to get started try the following simple examples. Remember to enter the words EXACTLY as they appear in the examples! Example 1: Print a number. Type the following text exactly as it is shown: 2. When you press RPL will respond: 2 Note: You just asked RPL to print out the number "2". The character "." is a predefined command or word in RPL's vocabulary which prints out an integer value. Example 2: Print some text. Now enter the following line: "hello world" PUTS RPL responds: hello world Note: The word "PUTS" (Put String) is another predefined word which printed the text "hello world". Before you test any further examples some explanation of how RPL operates is necessary. 7.2.2 Stacks RPL is a stack oriented language. This means that RPL uses stacks to store operands, intermediate results and return addresses. RPL uses four stacks. The Parameter Stack holds arguments for RPL words as well as results after executing those words. The Return Stack holds addresses of locations from where other RPL words were called, so that program execution can return to the location from where the calls were made. The other two stacks are only used internally. The Control Stack is used to check that the structure of the word is correct and all flow control structures are balanced while compiling a new word. The Vocabulary Stack stores the references to the compiled words that form the RPL vocabulary. These stacks work in Last In First Out (LIFO) manner, which is explained below in "Parameter Stack". 7.2.3 Reverse Polish Notation RPL uses postfix-notation, also known as Reverse Polish Notation (RPN). In RPN the arguments, or operands, are pushed onto stack first and then an operation is applied to them. The result is left on top of the stack, and can be used in consecutive operations. The conversion from algebraic notation (the way you write mathematical expressions on paper) to RPN is quite natural. You start with the operands you would start with if you were doing the calculation manually, and then append an operator. Then you take other operands and apply other operations until all the operands and operations are used. That may sound difficult but a couple of examples should clarify the point. Example 3: Convert 12 + 5 + 2 to RPN. 1. Manually you would first add 5 to 12. Therefore you write: 12 5 + Remember, the operands come first and then the operator. 2. Then you would add 2 to the result of the previous addition. 2 + Note: Both "+" operators require two operands. The first addition uses 12 and 5 but the second "+" seem to have only one operand, the number 2. The second addition takes the result of the first addition as its second operand. How the result of the first operation is preserved will be explained in the section about the Parameter Stack. So the whole expression in RPN is: 12 5 + 2 + 3. Finally you will use the "." word to print the result; so that the RPL text becomes: 12 5 + 2 + . And RPL responds by printing the result: 19 Example 4: Convert 2 + 5 * 7 to RPN. 1. First you multiply 5 with 7 and then add 2 to the result. So in RPL you enter: 5 7 * 2 + . 7.2.4 Parameter Stack When RPL scans input, whether it comes from the keyboard or from a file, it uses the Parameter Stack to store all operands it detects. This will be just called "the stack" for brevity, when there's no risk of confusing it with the Return stack. There are three kinds of operands in the RPL system: integer , floating- point, and address. The address operands can be addresses of RPL words, or addresses of variables (integer or floating-point) or generic addresses, addresses to any kind of value you want. All the addresses are handled in the same way. That is to say that RPL makes no distinction between addresses of different types of items. The stack operates on the basis of the last operand in will be the first out. This is the LIFO principle as mentioned. If you picture the stack as a pile of bricks (or any other neatly stackable material), you put new bricks on the top of the pile and also take them off from the top. So how are operands put onto the stack? Just enter them, and they are "pushed" onto the stack so that the last entered number will be the top- most one. In Example 1, you pushed one operand onto the stack (number 2). Then the command "." pulled it off and printed it in your RPL window. Now push several operands onto the stack, Try the following: 1 2 3 You pushed three numbers onto the stack. Print them all out by entering three "." commands and RPL responds: 3 2 1 Try to enter "." command once more time and RPL will respond: STACK EMPTY There were no more operands left on the stack for RPL to print. You get the same error message if you, for whatever reason, try to pull a value from the stack when none are available. This would occur if you had two integers on the stack and entered the "+" word twice. The second "+" has only one stack item and the error message is given. Now examine what happened to the stack for Example 3. Diagrams will be used to illustrate what is happening with the stack as each step is interpreted. 1. Suppose you start with an empty stack. 2. The RPL statement "12 5 + 2 + ." was scanned by the RPL interpreter. 3. First, 12 was pushed to stack. +----+ <- top of stack | 12 | +----+ 4. Then 5 was pushed on stack +----+<- top of stack | 5 | +----+ | 12 | +----+ 5. The "+" was scanned, which, because it is a executable word not an operand, is executed. The word "+" pops (takes off) the first two operands from the stack, then adds them and pushes the result back onto the stack. +----+ | 17 | +----+ 6. Then 2 was pushed on stack +----+ | 2 | +----+ | 17 | +----+ 7. The last "+" was scanned, the top two stack items are added, resulting in the following stack situation: +----+ | 19 | +----+ 8. Finally the "." was scanned and interpreted and the value is printed leaving the stack in its initial empty state. Note: RPL words must be separated from each other and their operands by either a or , but using also passes the current line to the RPL system and it will be interpreted immediately. So the example above could also have been entered as: 12 5 + 2 + . @endnode @node "T7.2.5" @title "Chapter 7 RPL" 7.2.5 DataTypes There are three kinds of data types in the RPL system: integer, floating- point and string. These are often refered to as literals. In order to enter values on the operand stack, you type in literals separated by or just as you have done in the examples above. Integers can contain only integral values, such as -3, 0 and 12, while floating-point numbers can be used for representing decimal numbers like -1.2, 0.12 and 1243.1. 7.2.5.1 integers Integer literals begin with a optional sign (+ or -) and contain only decimal digits. So far you have only used integer arithmetic, with integer literals and their corresponding integer operator words. 7.2.5.2 Floating-points Floating-point literals are similar to integer literals but they contain a decimal point or a exponent separator or both. The exponent separator can be either "e" or "E". The exponant can then contain an optional sign. As you would expect, arithmetic operations can also be carried out with floating-point values. There are separate words to carry out these operations: F+ - add two floating-point values F- - subtract F* - multiply F/ - divide F. - print Fxx - etc. Example 5: Enter the following text: 100.0 0.5 F* F. RPL replies: 50.0000 It did that because you pushed two floating-point values onto the stack then multiplied them as floating-points and finally printed out the return value from the "F*" word, as a floating-point. Example 6: Now try the following: 123 F. and RPL responds with: 123.0000 This demonstrates an important principle of RPL. RPL uses Object- Orientation Theory to handle the operands on the stack. This means that it knows the data type of each stack value and the data type it requires for each operand of a word and handles them accordingly. In Example 6 above, when the command "F." pulled the integer value 123 off the stack, it converted the value to the required type before it tried to use it. This also works if words requiring integer operands receive floating-point values. Example 7: When you enter: 6.8 . RPL will respond with: 7 The RPL word "." works with integers, it had to convert the floating- point value it pulled from the stack to an integer before it printed it; because integers cannot contain any fractional part the value was rounded to the nearest integer value. 7.2.5.3 STRINGS String literals begin and end with a double quote character. If a double-quote is wanted in a string literal, it should be preceded by a back-slash. For example: "This string contains a \"." Will be interpreted as: This string contains a ". If a back-slash is required then two must be entered consecutively. For example: "This string contains a \\." Will be interpreted as: This string contains a \. RPL handles strings slightly differently from the way the integers and floating-points are treated. With integer and floating-point literals the numerical value is pushed on stack, and with string literals the address of the first character of the string is placed on the stack. You have already encountered the string printing word "PUTS". Let's look at how it actually operates. Consider the RPL text: "Hello, this is a string" PUTS 1. When the string "Hello, this is a string" was typed, RPL did NOT push the entire string onto the stack. Instead the address of the string was pushed. The memory for the string itself was allocated from elsewhere. 2. The word "PUTS" then pulls the address out off the stack and copies the string from that address to the window. Every character has a corresponding value, which is used for representing the character, this is called the ASCII code. For example, the ASCII code for the character "!" is 33. So, when RPL stores the character "!", it actually stores the value 33. The RPL word "EMIT" can be used for printing out characters by supplying ASCII code for them as operands. Example 8: Enter the following: 33 EMIT and RPL replies: ! So, you can store a simple string onto the stack and print it out using the EMIT function. Example 9: Enter: 76 80 82 EMIT EMIT EMIT and RPL replies: RPL Finally , you can investigate one property of string literals that might not be immediately obvious. As you just learned, entering a string caused RPL to allocate the memory for the string and push the address of it onto the stack. To be precise, the address of the first character is pushed onto the stack. This means that it is possible to use arithmetic operations to select part of a string. Example 10: 1. Type the following string: "Hello again!" Note: The first character of "again!" is the 6th in the whole string 2. Enter: 6 + Note: You have now added 6 to the address of the first character ("H") of the string. 3.Finally, type: PUTS and RPL replies again! Some care is needed when using this "address arithmetic"; if you make an error and change the address so that it is outside of the original string data structure, then the results are quite unpredictable. In the worst case you could crash the system if you read from certain hardware registers by mistake. @endnode @node "T7.2.6" @title "Chapter 7 RPL" 7.2.6 Stack Manipulation Words There are a number of words that change the order of the stack items. The "SWAP" word, as it's name implies, takes two values off the stack top and puts them back in reverse order. Example 11: 1 5 SWAP after 1 after 5 after SWAP +-------+-------+----------+ | 1 | 5 | 1 | +-------+-------+----------+ | 1 | 5 | +-------+----------+ "SWAP" is only needed if the order of the operands affects the result. It is unnecessary when using words such as "+" and "*" among others. Quite often there is more than one way to enter an algebraic expression in RPL: Example 12: Calculate the value of 28 / (2 + 4 * 3) 1. You start from within the parentheses as you would when calculating manually: 4 3 * 2 + 28 SWAP / after 4 after 3 after * after 2 +-------+-------+-------+-------+ | 4 | 3 | 12 | 2 | +-------+-------+-------+-------+ | 4 | | 12 | +-------+ +-------+ after + after 28 after SWAP after / +-------+--------+----------+-------+ | 14 | 28 | 14 | 2 | +-------+--------+----------+-------+ | 14 | 28 | +--------+----------+ 2. Or, start from the left: 28 2 4 3 * + / after 28 2 4 3 after * after + after / +--------------+-------+-------+-------+ | 3 | 12 | 14 | 2 | +--------------+-------+-------+-------+ | 4 | 2 | 28 | +--------------+-------+-------+ | 2 | 28 | +--------------+-------+ | 28 | +--------------+ This illustrates that although you can usually manage without "SWAP", it can quite often make it easier to enter your expressions in an understandable way. The next useful word for manipulating the stack, is "DUP"; which, as its name suggests, duplicates the top stack value. This is useful when you need an entered value or intermediate result more than once. Example 13: Calculate (3 + 7 * 2) / 3 + (3 + 7 * 2) * 4. You can convert it to RPL and get: 3 7 2 * + 3/ 3 7 2 * + 4 * + . or you can use DUP and get 3 7 2 * + DUP 3 / SWAP 4 * + . You can try these out and see for yourself that they give the same result. To get a copy of the second stack item you use the word OVER. Example 14: To calculate 3 + 3 * 7 you can enter: 3 7 OVER * + . If you need get a copy of a value deeper in the stack you use the PICK word. Example 15: To get a copy of the fourth value on the stack you enter: 4 PICK Note: The count of stack items (i.e. 4) does not include the count itself although it will be on the stack top when "PICK" is applied. In the previous example 4 PICK will copy to the stack top the value which was the fourth stack item before 4 was entered. "ROT" rotates the three topmost stack values so that the third item will become the top item, and the first and the second item (counting from the stack top) will be the second and the third stack item respectively. Example 16: Push 3, 5 and 7 onto the stack and then apply ROT and see how it changes the stack. 3 5 7 ROT after 3 after 5 after 7 after ROT +-------+-------+-------+---------+ | 3 | 5 | 7 | 3 | +-------+-------+-------+---------+ | 3 | 5 | 7 | +-------+-------+---------+ | 3 | 5 | +-------+---------+ Note: You can use the .S" word toprint the contents of the whole stack without removing any values to see how this example progresses. The word ROLL is used to rotate a given number (n) of stack items so that the n'th stack item becomes the stack top item and all the items between the first and the n'th item are moved one position deeper in the stack. Finally there is also a word for popping a value off the stack without printing it. The word is "DROP". You will need it later when you examine conditional execution. @endnode @node "T7.2.7" @title "Chapter 7 RPL" 7.2.7 Compiling New Words The examples so far have only demonstrated that RPL can be used as a slightly peculiar calculator. If it is to be used as a programming language, RPL needs to be able to store a sequences of operations for repeated use or which need to be executed by another part of the program. Many programming languages call these sequences functions or subroutines. The term "word" from the FORTH programming language is adopted for RPL. A word is a collection of RPL code which can be recognised by its name. This code can consist of literals, references to variables and constants, and references to other words. A definition of a word begins with a colon ":" continues with the name of the new word, and ends with a semicolon ";". When the RPL interpreter scans the colon word, a new entry in the vocabulary is started. The name of the word and the type of entry (in this case a "word definition") are stored. Everything between the name and the ending semicolon is compiled as the word's definition. When a previously defined word is given as part of the definition, a reference to it is stored. When a literal is given, its type (integer, float or string) and its value are stored in the entry. When a named constant or a variable (See: Constants and Variables) is given, a reference to its own entry is stored. In summary, the vocabulary entry for a word is made of a name, the word type and a set of literal values and references to previously defined words, The following examples should help to explain: Example 17: Define a word that prints out a specific string. Enter: :Prompt "PROMPT TEXT>" PUTS ; Remember, there has to be at least one space between ":" and the name for the new word, because the ":" is itself a word. User-defined words are used just like any pre-defined word. To use them you just need to enter their name. Example 17b: Use the word "Prompt" defined above. Enter: Prompt RPL will print: PROMPT_TEXT> User defined words would be quite useless if you couldn't pass information to them to control their operation. However, as mentioned above, user- defined words are indistinguishable from the built-in words. This means that passing operands to them is carried out using the Parameter Stack in exactly the same way as you have passed operands to words since Example 1! Now test this by defining your own interger printing word. Example 18: New integer printing word. : MyPrint . ; Call it: 10 MyPrint and RPL responds: 10 Or call it as follows: 10 20 100 MyPrint MyPrint MyPrint and the reply will be: 100 20 10 Now create a function which prints numbers out twice. To do this, you have to use the "DUP" word mentioned previously. Example 19: Print number twice as an integer. : My2Print DUP . . ; Now call it: 10 My2Print and it will reply: 10 10 or if you call it as follows: 10 My2Print 20 My2Print 100 My2Print RPL responds with: 10 10 20 20 100 100 Before the final example in this section you should learn how to use "comments" so you can add notes to your program to inform others how it works (or remind yourself at a later date). The word "(" tells RPL to skip all following text up to the next ")" command or until the end of the current line. Because "(" is a word, you have to separate it from the text that follows with a space. Comment Examples: 1. ( this is a comment ) 2. ( these are also ( legal comments 3. (this produces syntax error) 4. ( this is an illegal comment too ) Finally create a function, which takes three numbers as an input and returns the integer average of them, Example 20: Calculate the average of three numbers. : MyAver ( add 3 numbers and divide result by 3 ) + + 3/ ; If you call it as follows: 10 20 30 MyAver . RPL returns: 20 or try: 10 20 120 MyAver . and the response will be: 50 @endnode @node "T7.2.8" @title "Chapter 7 RPL" 7.2.8 Constants and Variables RPL has a mechanism to store and fetch values not only from the stack but also in "constants" and "variables". A "constant" is a named entity whose value is set when it is defined, and the value can be referenced but not changed. A "variable" is a named entity whose value can be referenced and used for either input or output. Constants and variables must be defined outside word definitions. When a constant is defined, its value is taken from the stack top. When you later want to reference a constant you enter its name. 7.2.8.1 Constants Constants are used for storing values that won't change. Although this might seem to be the same as using literals, it is good programming practice to use constants instead of literal values. Constants should be descriptive, and this makes your code much easier to read by others as well as yourself. When a constant is referrenced by its name, the value is placed on the stack. Example 21 : Define integer constant "DaysInAWeek" with the value 7. Enter: 7 CONSTANT DayslnAWeek Then entering: DaysInAWeek . prints out: 7 Example 22: Define the value for the floating-point constant "PI". 3.14159 FCONSTANT PI 7.2.8.2 Variables When a numeric variable is defined, its initial value is set to zero. For each numeric type (integer and floating-point) there are two words that are used to access this value. For integer variables these words are: @ (fetch) - takes the address of an integer variable and returns the value of that variable on the stack. ! (store) - takes two operands: the address of the integer variable and the new value for the variable, and changes the value of the variable. The address must be the top item on the stack and the new value the second. The address of a variable is pushed onto the stack when it is referred to, not the value as with constants. Example 23: Define integer variable COUNTER and store 17 into it, then check its value. VARIABLE counter 17 counter ! counter @ . Examine what happened during this example step by step: "VARIABLE counter" 1. Space was reserved for one integer value, to be accessed by the name "counter". "17 counter !" 2. The number 17 was pushed onto the stack. 3. The address of the variable was fetched and pushed onto the stack. 4. The word "!" was executed, which takes the address of a variable off the stack and assigns the second operand to the value at that address. In a way, the name of a variable is the address of its value. "counter @ ." 5. The address of the "counter" variable was again pushed onto the stack. 6. The word "@" was executed, which moves the contents from the given address onto the stack. 7. The "." word was executed, which printed the value from the stack to your window. There are corresponding words for floating-point variables; which are "FVARIABLE", "F!" and "F@". Variables and constants can be used inside or outside of a word definition. When used inside a word definition, only a reference to the constant or variable is compiled in the word's dictionary entry. The value of the constant or the address of the variable is fetched only when the word is executed, not when it is defined. Although the stack is object oriented and can automatically convert between numeric types, the internal storage of integer and floating- point variables is different. This means that words that operate on floating-point variables, i.e. F! and F@ should not be used to access integer variables. The same applies to floating-point variables and the words for integer variable access (! and @). @endnode @node "T7.2.9" @title "Chapter 7 RPL" 7.2.9 Flow Control Every programming language has to be able to alter the program flow when certain conditions are met. It is also necessary to be able to repeatably execute a section of code. RPL has addressed these needs by including a versatile set of words into its basic vocabulary for controlling program flow. The flow control words can only be used from within word definitions. 7.2.10 Conditional Execution It is often necessary to decide whether a section of code should be executed or not. This is called conditional execution . The most basic conditional execution structure is "IF..ENDIF". The "IF" word takes the stack top value and uses it to make a decision about how the execution is to proceed; this decision value is called a "flag". In RPL a flag value is said to be "FALSE" if it is equal to zero and "TRUE" if it has any other value. If the flag is TRUE, the words between IF and the corresponding ENDIF are executed, otherwise execution skips to the word that is immediately after the ENDIF. 7.2.10.1 Comparisons To put a flag on the stack ready for IF, it is useful to use words that compare stack items and as a result push a flag on the stack. Built into RPL are the following comparison words: Integer Float ---------------------------- = F= - is equal < F< - is less > F< - is greater >= F>= - greater or equal <= F<= - less or equal <> F<> - not equal Each of these takes two stack values, compares them, and places a flag onto the stack whose value depends upon the result of the comparison. Example 24: Compare 2 and 3 to see which is less. 2 3 < The second stack item is compared to the first stack item; the flag pushed on the stack indicates whether 2 is less than 3. A value of 1 means "TRUE", and a 0 means "FALSE". after 2 after 3 after < +-------+-------+-------+ | 2 | 3 | 1 | +-------+-------+-------+ | 2 | +-------+ The flag states that two is less than three (as you may have guessed). 7.2.10.2 IF..ENDIF Structure This is the simplest form of conditional execution structure. Example 25: Unpredictable program execution : Maybe RANDOM 0.5 F< IF "Yes," PUTS ENDIF "Thats it" PUTS ; Try executing "Maybe" several times and examine its response. Note: This introduces the word "RANDOM" which returns a random floating- point number between 0.0 and 1.0 when executed. The previous example tests whether the return value from "RANDOM" is less than 0.5. If it is, it prints out the text "Yes, Thats it" otherwise it just prints "Thats it". This is the explanation of the previous example. When the "Maybe" is executed: 1. Executing "RANDOM" pushes a floating-point value onto the stack 2. 0.5 is pushed onto the stack 3. The "F<" word takes two (floating-point) operands, compares "random<0.5" and pushes the flag back onto the stack. 4. The "IF" function takes the flag off the stack and if it is non-zero, then the ""Yes," PUTS"" text is executed; otherwise execution skips to ""Thats it" PUTS"" after the "ENDIF". Note: That "IF" and "ENDIF" words must be contained within a word definition; also that every "IF" needs one corresponding "ENDIF". 7.2.10.3 IF..ELSE..ENDIF Structure Now you can define a word that prints only positive values, negative values are just disposed of. Example 26: Word to print only positive values. : .Pos DUP 0> ( compare operand to zero ) IF . ( print it if greater ) ENDIF ; If you enter: 4 .Pos RPL returns: 4 So that seems to work. But what happens if you enter: -2 4 3 -1 .Pos .Pos .Pos .Pos It doesn't produce: 3 4 but nothing at all. The problem is that the word does not get rid of the negative values, so you called .Pos four times with the same value of -1 on the stack. You need to take some action if the value on the stack is not greater than zero. This is handled using an "ELSE" branch where the negative value will be dropped off the stack. Example 26b: Correct way to print only positive values. : .Pos DUP 0 > IF . ELSE DROP ENDIF ; This demonstrates another form of the IF structure, the IF. .ELSE..ENDIF structure. If you now enter -2 4 3 -1 .Pos .Pos .Pos .Pos you get 3 4 as originally intended. 7.2.10.4 Inverting Flags As well as the integer and floating-point comparison words, there is one other useful word for use in conditional structures.The "NOT" word can be used for reversing the result of a comparison. For example: 1 0 20 <> . and: 10 20 = NOT . Both print out the same value of "1" because the condition is TRUE. 7.2.10.5 Nesting Conditionals Conditional structures can also be nested. This means that they can be stacked inside each other providing that for each "IF" of "IF..ELSE" there is a corresponding "ENDIF". Example 27: Use of nested IF..ELSE..ENDIF structure. : CheckIt DUP ( duplicate the operand so that you don't lose it 0 = ( compare it against to zero ) IF "Zero" PUTS DROP ( dispose of duplicate because it won't be needed ELSE 0 > ( make comparison "is greater than" with duplicate IF "Greater" PUTS ELSE "Less " PUTS ENDIF ENDIF ; Now call it as follows: -2 CheckIt 3.7 CheckIt 0 CheckIt you should get the following response: Less Greater Zero @endnode @node "T7.2.11" @title "Chapter 7 RPL" 7.2.11 Loops In this section, the RPL words for branching back to repeat sections of code several times will be explained. This type of control structure is called a "loop". There are two basic kinds of loop: definite loops, which execute a specific number of times unless interupted, and indefinite loops, whose repeated execution is controlled conditionally in much the same way as the IF..ENDIF structure. 7.2.11.1 Definite Loops The basic RPL control structure for executing definite loops is "DO..LOOP". You specify beginning and ending values, called the limits, for a "loop variable". The ending value is first pushed onto the stack, then the beginning value, before the word "DO". Then you put the words to be repeated, and the structure ends with the word "LOOP". Example 28: Printing a string 1 00 times. : DoLoop 100 0 DO "RPL loops in style!" PUTS LOOP ; DoLoop The "loop variable", or index, starts with the starting value, and is incremented by 1 at the end of each iteration of the loop. When it reaches the ending value the loop is exited. There is a word for retrieving the value of the index. Its name is "I", and it should only be used between "DO" and "LOOP". It puts the current value of the loop variables on the stack. Example 29: Count up from 1 to 9 and print the index. : OneToNine 10 1 DO I. LOOP ; OneToNine Prints: 1 2 3 4 5 6 7 8 9 The "DO..LOOP" always starts at a value and counts up by one until it reaches the ending value. If you want to increment the index by a value other than 1 , you can use another form of the definite loop: the "DO..+LOOP". The "+LOOP" word takes an operand from the stack and adds it to the index. If the ending value is greater than the beginning value, then the loop is exited if the loop variable becomes greater than or equal to the ending value. Example 30: Count from 0 to 1 0 in twos, printing the index. : UpInTwos 10 0 DO I. 2+LOOP ; UpInTwos Prints: 0 2 4 6 8 If the ending value is less than the beginning value, then the "DO..+LOOP" is exited when the loop variable becomes less than or equal to the ending value. Example 31: Count down by one and print the index. : DownByOnes 10 0 DO I. -1 +LOOP ; 0 5 DownByOnes Prints: 5 4 3 2 1 Note: In this example the word "DownByOnes" takes its operands from the stack, so you must supply them when you call the word. Both forms of the "DO" loop execute at least once since the conditional check is made when "LOOP" or "+LOOP" is executed. It is possible to terminate a definite loop prematurely. The execution of word "LEAVE" causes the loop to terminate at the next "LOOP" or "+LOOP". Example 32: Print the squares of numbers until the square > 50. : SquareLoop 10 0 DO I DUP * ( square index ) DUP 50 > IF ( compare the square to 50 ) DROP LEAVE ELSE . ENDIF LOOP ; When execute "SquareLoop" will print the squares of I until they exceed 50. 7.2.11.2 Indefinite Loops Unlike definite loops, an indefinite loop does not terminate after a specified number of iterations. It terminates when a condition is met, if ever. All indefinite loops, just like definite loops, must lie entirely within a single definition. The structure of the indefinite loops are: BEGIN..UNTIL BEGIN..WHILE..REPEAT BEGIN..AGAIN In each of these loops, "BEGIN" marks the beginning of the loop body, which extends to the terminating word "UNTIL" , "REPEAT", or "AGAIN". In the "BEGIN. .UNTIL" loop a flag is tested and removed from the stack at the end of each repetition of the loop. If the flag is TRUE, the loop terminates. Otherwise the loop repeats from the first word following "BEGIN". Since the test is made at the end of the loop, the loop will always be executed at least once. Example 33: : CountDown 1 BEGIN DUP . ( print it out ) 1 - ( decrement by one ) DUP 0 <= ( if TRUE, terminate loop ) UNTIL DROP "PANG" PUTS ; 10 CountDown1 The "BEGIN..WHILE..REPEAT" form of indefinite loop first executes the code between "BEGIN" and "WHILE", and then a flag is tested, If the flag is TRUE, the words between "WHILE" and "REPEAT" are executed; then execution returns to "WHILE". If the flag is FALSE, then execution skips to after the "REPEAT". Example 34: : CountDown2 BEGIN 1 - ( decrement by one ) DUP ( if 0, terminates the loop ) WHILE DUP . REPEAT "Bang" PUTS DROP ; 10 CountDown2 The third form of indefinite loop has the form "BEGIN..AGAIN". Which executes forever unless either the word "QUIT" or "EXIT" is executed. "QUIT" terminates execution, empties all stacks and returns control to the interpreter, while "EXIT" exits the current word. Example 35: : CountDown3 BEGIN DUP . 1 - DUP NOT IF EXIT ENDIF AGAIN ; 10 CountDown3 7.2.11.3 Nested Loops As with conditional structures, all the loop forms can be nested, In Examples 29 to 32 you used the RPL word "I" to obtain the value of the loop variable; when you nest "DO. .LOOP" structures the words "J" and "K" can be used to copy the indices of the second and third outer loops, respectively. Example 36: Print a multiplication table. ( print carriage return and line feed: ) : CR 13 EMIT 10 EMIT . : multTable 6 1 DO 11 1 DO I J * ( multiply indices . ( and print the product LOOP CR LOOP ; multTable Will print: 1 2 3 4 5 6 7 8 9 10 2 4 6 8 10 12 14 16 18 20 3 6 9 12 15 18 21 24 27 30 4 8 12 16 20 24 28 32 36 40 5 10 15 20 25 30 35 40 45 50 This looks a little untidy so you can tidy it up by adding a conditional to print a space. Example 36b: Print a neat multiplication table. : multTable 6 1 DO 11 1 DO I J * ( multiply indices DUP ( duplicate product for testing 10 < IF ( if<10 then print a space first "" PUTS . ( now print product ELSE ( two digits in product . ( so just print it ENDIF LOOP CR LOOP ; multTable Note: It is a convention to indent flow control structures as shown in the previous two examples. This does not make any difference to the RPL system but, like comments, makes your programs easier to read and understand. @endnode @node "T7.2.12" @title "Chapter 7 RPL" 7.2.12 Words and the Vocabulary The last example, as well as being your most comprehensive RPL program to date also demonstrates an important feature of the RPL language. If you define a word with the same name as a previously defined word then the latest definition is used. You can list the whole vocabulary of your current RPL window by entering the word "VLIST". Before you do this use the size gadget of the window to make it a decent size, the vocabulary is quite long. The whole vocabulary, including the built-in words, will be printed to the RPL window in chronological order with the latest words printed first. You should see that the last two words are both "mult_table". It is possible to remove word definitions from the vocabulary using the word "FORGET". Example 37 : Remove neat "multTable" from vocabulary. FORGET mult_table If you now execute "multTable" you will get the original untidy version. "FORGET" actually removes ALL the words after the specified word. So, assuming you have worked through all the examples, if you enter: FORGET Prompt Then all the words you have defined during this tutorial will be deleted. It is important to note that the RPL system makes NO DISTINCTION between the built-in words and words defined interactively or by loading a file (see next section). This means that if you create a word definition using the name of one of the built-in words then your new definition will replace the original. This can be quite significant if you replace an important or frequently used word. You can of course recover the situation using "FORGET"; which raises another important point: you can delete built-in words just as easily as your own. This makes it possible to create a situation where RPL does not have the vocabulary to do anything! Closing the window and opening a new one enables you to start with a fresh RPL environment. @endnode @node "T7.2.13" @title "Chapter 7 RPL" 7.2.13 Loading a File Entering RPL definitions directly to the window is acceptable for the short examples so far in this tutorial, but it is hard to recover from mistakes without having to completely re-enter a definition. Using a text editor you can write any RPL code to a file and then load that file into your RPL window. Example 38: Write the following RPL program using your favourite text editor and save it as "ram:test.rpl" "loading..." PUTS : CR 13 EMIT 10 EMIT ; : Hello "Hello world" PUTS CR ; "Done" CR Now type the following program: "ram:test.rpl" LOAD RPL responds: loading ... Done Now the words CR and Hello are defined and you can call them. Type: Hello and RPL responds Hello world @endnode @node "T7.2.14" @title "Chapter 7 RPL" 7.2.14 Using RPL windows You open a RPL window by selecting PROJECT/Windows/RPL. You can have many RPL windows if you want. RPL windows are similar to OS "Shell" windows. You can use C and V to cut and paste text to and from the "clipboard" and the cursor keys can be used to edit your text and even fetch previously entered text from the window "history" buffer. Each window is separate so that whatever words are defined in one window, cannot be used in other windows. Of course you can define identical words in different windows. The stacks are also specific to each window. It is possible though to use words defined in another window by establishing a parent-child link between two windows. This is done using the word INHERIT . The syntax for this word is: "name_of_RPL_window" INHERIT Example 39: 1. Define a word "HiThere" in your current RPL window : HiThere "Hi There" PUTS ; 2. Open a new RPL window and try to execute the word "HiThere": HiThere RPL responds HiThere ? because it didn't recognize the word. 3. Now enter the following line: "RPL" INHERIT 4. Try HiThere again and RPL responds "Hi There" From now on interactive commands, as well as new definitions entered in the "RPL.1" window search the vocabulary of "RPL.1", and then, if the word is not found, the vocabulary of "RPL". So if you have defined identical words in both windows the definition in "RPL.1" will take priority. Note: The INHERIT word actually takes an address as its operand, and this address points to the string containing the name of the RPL window whose vocabulary you wish to INHERIT Remember by entering the string between the double-quote marks its address was pushed onto the stack as an operand. @endnode @node "T7.3" @title "Chapter 7 RPL" 7.3 USING RPL FOR CUSTOMIZING EDITOR In this section we will show you how to use RPL to customize and expand the user interface and functionality of REAL 3D. The real power behind the customization is based on the fact that customization allows persons to develop working environments which suit as well as possible their different modelling needs, styles, and tools. Other people can take advantage of these additional tools etc developed by somebody else. 7.3.1 Communicating with RPL Programs Before we can go any further, let's take a look how RPL programs can interact with the user and vice versa. RPL contains sets of words which can be used for requesting information from the user. Open one View window and write the following program: : AreYouSure "YeslNo" "Are You Sure?" GET_ KEY IF "You are sure" PUTS ELSE "You are not sure" PUTS ENDIF ; AreYouSure When you call the word by typing its name, REAL 3D opens a requester with the header text "Are You Sure". Depending on which gadget you click RPL prints out either the text "You are sure" or "You are not sure". So, the word GET KEY takes two parameters: a string defining gadgets to be created and the header text for the requester. It returns a value corresponding to the selected gadget. Gadgets are separated with the character "l" and it is possible to create any number of them (well, there should be at least one). Write the following program: : GetKeyTest "FirstlSecondlThirdlCancel" "Select One of These" GET_KEY . ; Now call the word GetKeyTest several times and see what values it returns. The value corresponding to the rightmost gadget is always 0 (right selection is used for negative choice, hence the value 0). The value corresponding to the leftmost gadget corresponds to the value of 1 and is incremented gadget by gadget from left to right. The word GET STR can be used for requesting strings from the user, such as object names. It takes three parameters: the address of the buffer to hold the string, the maximum length for the string and the header text for the requester. Write the following program: 16 STRING ObjName : ObjCreate ObjName 1 5 "Create Object" GET _STR IF wOT_OR ObjName "CEND" C_LEVEL DROP ENDIF ; ObjCreate /* Get string from the user */ This word opens a requester which allows you to enter the name for the object. If you select the gadget OK, the word creates a level object with the name you defined. The word GET_FLT allows you to request numerical data from the user. It takes two parameters: the address of the buffer (variable) to hold the defined value and a title for the requester. For example: FVARIABLE Length : GetLen Length "Define Length" GET_FLT IF Length F@ F. ENDIF ; GetLen This program asks user to define "Length" and prints it out. Its time to leave these "user interface" words now. There are also words available for requesting file names and vectors etc. These words can be used in a pretty similar way to those we have already discussed. Consult the "Reference Manual" whenever you need to use them. 7.3.2 "Master" ENVIRONMENT When R3D2 is first started one RPL environment is created. Unlike RPL windows this has no window associated with it. "Master" environment is responsible for taking care of the following things: 1. Processing of AREXX commands. All ARexx commands arriving to ARexx port of REAL 3D are directly passed to RPL interpreter. 2. Executing MACROS. For example, whenever you select the menu Project/ Macros/Execute_Current, the following program is passed to Masters RPL environment: "t:macro.rpl" LOAD 3. Processing key bindings. When you press any key, that key with the prefix "KEY_" is passed to Masters RPL interpreter. For example, when you press the key "k", then the RPL word "KEY_k" attempts to execute. If such a word cannot be found, the display is flashed as an error indicator. 4. Processing RPL programs bound to icons in the Tool windows. 7.3.3 Binding Macros to Keys Any RPL program can be bound to any key by defining a word which has the same name as the key in question with the prefix KEY_. The word must be defined in Master's RPL Environment and it must return information with which windows should be refreshed. This return value consists of flags corresponding to each window type. Constants for these are defined in the file "editor.rpl". IWR_SELECT IWR_VIEW IWR_MAT IWR_ANIM IWR_COL IWR_ALL How to define words to "Masters" environment? There are three possible ways to do it: 1. Write a RPL program using any text editor, save it to a file and execute that file as a Macro. 2. Insert your RPL program to the file "s:rpl-startup". 3. Send your RPL program to ARexx port of REAL 3D. Let's write a simple RPL program and bind it to a key. 1. Add the following RPL program to the end of the file "s:rpl-startup". : KEY + 1 O_LOCK ( lock object data exclusively ( fetch selected objects on the stack: O_GETSEL 0.1 0 0 0 M_MOVE 0 O_LOCK (free lock IWR_VIEW ( only View must be refreshed ; 2. Start REAL 3D and create some objects. 3. Select one of the created objects and press the key "+". This causes "Master" to call your KEY + word which moves the selected objects to the positive direction of "x" axis. Of course this is very stupid thing to do. So, let's improve it by asking the user how much the selected objects should be moved. 1. Exit the Real and load s:rpl-startup file to your text editor. 2. Modify the KEY + word so that it looks like the following one: "vectors. rpl" LOAD VVARIABLE vMovement : KEY + vMovement "Move Selected Object" GET_VECT IF 1 O_LOCK O_GETSEL V@ vMovement 0 M_MOVE 0 O_LOCK ENDIF IWR_VIEW ; Now, start Real, create some objects, and press the key "+". REAL 3D opens a requester which allows you to enter three values defining how much to move selected objects. If you exit the requester with OK, all selected objects will be moved. Note: As a matter of fact, this is very handy macro because the requester allows you to define the formulas which are then automaticaly evaluated. 1. Press the key "+". 2. Type the following formula to the first gadget: 10*3.14/100 and press the enter key. Your formula is evaluated and replaced with the result: 0.314 3. Click OK and the macro moves all selected objects 0.314 units along the "x" axis. One very powerful feature provided by REAL 3D is ability to open several screens. For example, you can use one HAM screen for rendering images and another four color hires screen for modelling. The following macro tries to bring the "Palette" window to the front, and if there are no Palette windows, it opens one. This kind of macro can be very useful when you have a lot of screens open. ( Bring window to front or ) ( open it if it doesn't exist ) : KEY_8 0 "Palette" iWM_ACTIVATE WND_SENDMSG IF iWT_PALETTE "Palette" 200 0 60 640 WND_OPEN ENDIF 0 ; When you press the key "8" the WND_SENDMSG word sends iWM_ACTIVATE message to all "Palette" windows. If none was found, it uses the word WND_OPEN to open one, This prevents you from accidentally opening more than one "Palette" window. The RPL "MENU" allows you to execute whatever menu through RPL. The word takes three parameters which describes the menu to be executed. For example, in order to execute the menu Create/Visible/Polygon enter the following string in any RPL window: 1 0 0 MENU then click the mouse on any View window and you can create a polygon. The reason for this is that the "Create" menu is the second menu. Because numbering starts from 0, the second menu corresponds the number 1. The second parameter (0) defines the first menu item of "Create", which is "Visibles". The last parameter (0) defines the first sub-menu, which is "Polygon". Naturally, you can create a word in to the rpl-startup file and call the MENU word to activate any menu. For example, by adding the following word to your rpl-startup file, you can activate the Lathe tool by pressing the key "l". : KEY_l 1 7 0 MENU ( Create/Compound_Tools/Lathe 0 ; Note: If the menu is "Ghosted" you cannot execute it using the mouse or a word. Because the MENU word does the same as if you selected the actual menu, you don't have to worry about the return value. For example, the following key binding works only if the active window is a View window. : KEY_q 3 0 1 MENU ( View/Type/Perspective ) 0 ; The standard "rpl-startup" file contains a lot of examples of how to bind RPL programs to keys. Take a look at it for more examples and our attempt at a form of standardization. 7.3.4 Binding Macros to Icons REAL 3D allows you to create your own icons on Tool windows and bind RPL programs to them, When the icon is clicked, the corresponding RPL program is executed. There are two kind of bindings: RPL word bindings and RPL file bindings. In other words, the name of the icon can correspond either to the name of the RPL word or the name of the RPL file. In order to create an icon which is bound to a RPL word called HI THERE: 1. Write the program containing the word HI_THERE and save it as "Ram:test". : HI THERE "YeslNo" "Are You Sure" GET_KEY IF "You are Sure" PUTS ELSE "You are not sure" PUTS ENDIF 0 ; 2. Select the function Project/Macros/Execute Named and execute the macro "Ram:test" (or insert it to your rpl-startup file and restart Real). 3. Open one Tool window. 4. Select the menu Tools/Create Icons which contains one string gadget and two radio-buttons. Enter the string HI THERE to the string gadget and make sure that the radio-button "Word" is selected. Click OK and one icon is created on the Tool window with the text HI_THERE. 5. Click the icon and your HI_THERE word is called causing Real to open a requester with the title "Are You Sure". In order to bind an icon to a file, just select the "File" radio-button for the icon to be created and then REAL 3D attempts to load the file whose name is the name of the gadget. REAL 3D tries to find that file from the directory defined by Settings/Paths. One very fast way to write a RPL program is to let the REAL 3D do it for you, in other words, to record a macro: 1. Create one sphere 2. Activate macro recording by selecting a menu Project/Macro/Record and move the sphere a bit to the right. 3. End macro. 4. Select the menu Project/Macro/Current_To_Named. REAL 3D opens a file requester and allows you to define a file name for the named macro. Type "ram:test". 5. Now create one icon on the Tool window with the name "test". 6. With the sphere selected, click the icon and your sphere is moved to the right. Note: REAL 3D standard configuration contains the directory named "r3d2:macros". If you put your macros there, the RPL interpreter can always find them. Now we have gone through some basic concepts how to customize REAL 3D by writing RPL procedures and binding them to keys and icons. This chapter only scratches the surface of possibilities for this customization ability which can offer users a good basis for learning new things and get new ideas about how to increase your productivity. The fact is that usually you have to spent a little time to build up a new function, but once you get it done, it can speed up your modelling in incredible ways. @endnode @node "T7.4" @title "Chapter 7 RPL" 7.4 CREATING ANIMATIONS USING RPL 7.4.1 Modifying Objects Directly The animation system of REAL 3D is very sophisticated. However, there might be some animations which cannot be created with it, simply because they are absolutely crazy. In this section, we will learn more about RPL by showing basic concepts about how to create these absolutely crazy animations which cannot be created in any other way. The principle is that we don't use the animation system of REAL 3D at all. Instead we will create animations by following the procedure described below: 1. Create your scene 2. Render it 3. Save the rendered image (if not rendered to a file) 4. Test if all frames are rendered, if they are, exit 5. Do something 6. Go back to the line 2. The line 5 (Do something) really means what it says. Because the RPL is a full featured programming language, there is not much you can't do with it. As a matter of fact, this is the way professional animators have created many of their really impressive animations. So, lets create an animation where the object just moves with a constant speed and direction. In order to do this, you need one View, one Select and one RPL window. Create one rectangle, select it and enter the following lines on your RPL window: O_GETSEL 0.1 0.2 0.0 0 M_MOVE REFRESH This program first fetches the addresses of selected objects on the stack, then moves the objects, and finally refreshes all windows. By the way, you can enter as many commands and operands in a single line as you wish (as long as their order is correct). For example, it is possible to enter the previous program as follows: O_GETSEL 0.1 0.2 0.0 0 M_MOVE REFRESH or as follows: O_GETSEL 0.1 0.2 0.0 0 M_MOVE REFRESH As you can see, moving objects are not very difficult to create. However, they can be made even easier: Write the following function: : Up O_GETSEL 0 0.1 0 0 M_MOVE REFRESH ; Now, make sure that the rectangle is selected and enter the following command: Up RPL moves selected primitive up and refreshes your windows. Lets create another function which moves object down. It will look much like the first one. : Down 0 -0.1 0 0 M_MOVE REFRESH ; In order to move objects up and down several times enter: Up Down Up Down Up Down Up Down And all objects moved up and down several times. To make up and down stuff easier to carry out, enter the following function: : UpDown Up Down Up Down Up Down Up Down ; Type UpDown and you rectangle will move up and down several times. This way you can define useful functions and group them together. Now you know enough to create a simple animation. Create the following program: : AnimLeft 10 0 DO O_GETSEL -0.1 0 0 0 M_MOVE REFRESH LOOP ; Play it and you will see that it animates all selected objects by moving them to the left. : AnimRight 10 0 DO O_GETSEL 0.1 0 0 0 M_MOVE REFRESH LOOP ; Call this function and it moves your objects to the right. Lets create a function which moves objects first to the right, and then back to the left: : AnimRL AnimRight AnimLeft ; Call this function and you will see your objects moving as you expected. Then let's create an animation where objects this several times: : AnimRL10 10 0 DO AnimRL LOOP ; Call the "Anim10" and your objects goes back and forth ten times. Lets create a function, which allows you to define how many times to move forwards and backwards: : AnimN 0 DO AnimRL LOOP ; You didn't enter the upper limit for the DO function inside the "AnimM" function. So you have to pass it to the function when you call it. Call the "AnimN" as follows: 10 AnimN and it goes 10 times. Call it as follows: 20 AnimN and your objects goes 20 times. You can use the function "I" to get the current value of the "loop index" each time around. Let's consider the following: : LoopTest 5 -5 DO I. LOOP ; When you call this function, the result will be: -5 -4 -3 -2 -1 0 1 2 3 4 You can use this index as a operand for something. For example, it can be used as a "frame counter" or parameter to trigonometric functions for defining nice motions. So, lets create an animation where all selected objects move along a sin curve: : SinMotion 100 0 DO O_GETSEL I 50 F/ ( x = I / 5 ) I 10 F/ SIN F* ( y = sin 1/10 ) 0 ( z=0 ) 0 M_MOVE REFRESH LOOP ; Call the word "SinMotion" and all selected objects will move along a sin curve to the positive direction of the "x" axis. Loops can be nested. Write the following program: : LoopLoop 10 0 DO O_GETSEL -0.1 0 0 0 M_MOVE REFRESH 10 0 DO O_GETSEL 0 0.2 0 0 M_MOVE REFRESH LOOP LOOP ; and call it. Selected objects move ten frames to the left, then one frame downwards and this cycle is repeated ten times. Sometimes a programmer wants to create a loop which terminates when some condition or event occurs. BEGIN UNTIL loop can be used for this purpose. It repeats until a condition is TRUE. : MyLoopTest BEGIN O_GETSEL 0.1 0.1 0 0 M_MOVE REFRESH RANDOM 0.9 F> UNTIL ; Previous function loops until the RANDOM function returns the value which is greater than 0.9. So the function UNTIL pushes one operand off the stack and if it is non zero, the loop is terminated. There are several other loops in RPL, but let's leave them for now. In the next section you will see how to use variables in RPL. A programming language is not a full featured programming language if it does not support variables. So, here you go! FVARIABLE t : Rotate 0 t F! ( t = 0 ) BEGIN O_GETSEL t F@ SIN t F@ COS 0.0 0 M_MOVETO REFRESH t F@ 0.1 F+t F! ( t=t+0.1 ) t F@ 3.14 F> UNTIL ( exit if t> 3.14 ) ; Now call this function and it moves all the selected objects along a circular route with a radius of 1. Let's improve this function a bit so that it moves the selected objects along a circular path where the radius is passed to the function as a operand. FVARIABLE rad : Rot2 ( radius ) rad F! ( store user defined radius to variable "rad" ) 0 t F! BEGIN t F@ SIN rad F@ F* ( rad * sin t ) t F@ COS rad F@ F* ( rad * cos t ) 0.0 ( z = 0 ) 0 M_MOVETO REFRESH t F@ 0.1 F+ t F! (t=t+0.1 ) t F@ 3.14 F> UNTIL ( exit if t > 3.14 ) ; Call this function as follows: 0.1 Rot2 and it will rotate all selected objects along the circular path with radius 0.1. Lets go through some lines of the previous function. The line t F@ SIN rad F@ F* does the following: 1. The address of the variable "t" is pushed onto the stack. 2. The function "F@" pulls the address of floating-point variable from the stack, fetches the value from that address and pushes the value onto the stack. 3. The function "SIN" takes one number off the stack and pushes the corresponding sin-value onto the stack. 4. The address of "rad" variable is fetched onto the stack 5. The function "F@" pushes the value from that address onto the stack 6. The function "F*" takes two numbers off the stack, multiplies them and pushes the result back onto the stack. Later this value is passed to function M_MOVE, which moves selected objects in x direction accordingly. Thats all for variables now. Just remember, when you type the name of any variable the pointer to the variable is returned onto the stack. If you type the string, the pointer to the string is returned onto the stack. So far we have created just wire frame animations. Lets create a complete ray traced animation: Write the following word: : RayTrace 10 0 DO ( ten frames ) O_GETSEL 0.1 0 0 0 M_MOVE RENDER LOOP ; Now we use the word RENDER instead of REFRESH causing REAL 3D to use ray tracing instead of wire frame rendering. However, this animation does not yet save the rendered images. The word SCR_SAVE can be used for saving the screen containing rendered image. The following shows the complete program for creating an animation. Note that this example assumes that your View window is opened on REAL 3D custom screen whose name is "Real.1". 100 STRING FileName : RayTraceSave 10 0 DO RENDER I "Ram:test%d" FileName SPRINTF "Real.1" FileName SCR_SAVE O_GETSEL 0.1 0 0 0 M_MOVE LOOP ; The previous program uses the word SPRINT for building up the file names for rendered images so that the name of the first image is ram:test0 and so on. The SCR_SAVE word takes two parameters: the name of the screen to be saved and the file name. Right, now we have created one complete animation. Although, it is very simple (objects just moved with constant speed along an "x" axis), it demonstrates the basic concepts needed for creating animations using this technique. However , there is one strange thing in this example: the result of the animation depends on the selected objects because we used the word O GETSEL to fetch the target objects for the M MOVE word. Although this might give your some good ideas, it is propably not what you wanted. So, lets create such an example where all cubes move to the right, and all rectangles move to the left. Create some cubes and rectangles and write the following program: 100 STRING FileName : RayTraceSave 10 0 DO RENDER I "Ram:test%d" FileName SPRINTF "Real.1" FileName SCR_SAVE "Root/cube*" O_FINDWILD 0.1 0 0 0 M_MOVE "Root/rect*" O_FINDWILD -0.1 0 0 0 M_MOVE LOOP ; Right, lets leave this section now and take a look at how to create animations using the actual Animation system of REAL 3D. @endnode @node "T7.4.2" @title "Chapter 7 RPL" 7.4.2 Creating New Methods In this section, we will demonstrate how to expand the animation system of the REAL 3D by writing new animation methods. As you already know, the animation system of REAL 3D is based on so called methods. A method is a procedure which can be associated with objects and which makes the object "intelligent enough to know what to do when the user plays with the time controlling gadgets. So, when do you have to create a new method? Only if there are no suitable methods available. It is so easy to create new animation methods, it is possible that somebody else has already created a method that solves your problem (Check the REAL 3D Support BBS for files 519-436-0140 Canada 1200 to 38400 Baud 24 hrs). Sometimes it is also possible to get the desired result by "customizing" existing methods. So, if there is no suitable method available and you cannot create such by customizing existing ones, then you probably have to write your own. Let's try it. 7.4.2.1 Do Nothing Method In this example we will learn how to create a new a method which actually does just nothing. The purpose of this kind of silly example is just to demonstrate the entire concept of how to attach procedures to objects in order to make them intelligent. So, start your favourite text editor program, type in the following RPL program and save it as RAM:test.rpl. : DoNothing 1 ; & DoNothing "DO NOTHING" MTH_CREATE DROP Then select the menu Project/Macros/Execute Named and execute the file RAM:test.rpl. This installs the new method to the method list of Real. Select the menu Create/Structure/Method. Real opens a requester which allows you to define the type of the method to be created. The last method in the list should be DO NOTHING method. So, select it, click OK and you have just created one intelligent level object. Now create one target object for the method and play the animation. As you can see, it really does nothing. There is only one requirement for the object procedure: it must return either 1 or 0 (TRUE or FALSE). The return value 1 indicates that the method in question succeeded in its mission. The return value 0 indicates that something went wrong and the animation should be cancelled. Our procedure "DoNothing" always returns 1 because nothing really can go wrong. The last line of the program & DoNothing "DO_NOTHING" MTH_CREATE DROP then installs our method to the method list of Real. The MTH_CREATE takes two parameters: the address of the RPL word and the address of the name for the method. So, the first command "&" just pushes the address of the "DoNothing" word onto the stack. If the creation succeeded, the MTH_CREATE word returns the address of the created method. We are not interested in this adress so it is discarded with the word DROP. Because the DoNothing procedure is really stupid, it is easy to make it smarter. Add the following line to your "s: rpl-startup" "ram:test.rpl" LOAD This installs your method automatically when you start Real. Now modify the contents of the ram:test.rpl file so that the word DoNothing actually does something: : DoNothing "YeslNo" "Continue" GET_KEY ; Restart Real, create one DO_NOTHING method and play the animation. Requester is opened with the header text "Continue" and two gadgets "Yes" and "No". If you select "No" gadget, the GET_KEY returns 0 and the animation is terminated. If you select "Yes" gadget, the GET_KEY returns 1 and Real proceeds to the next frame asking you the same question again. Before we leave this DO_NOTHING example, let's do something useful. Let's create one real animation method which moves the target objects randomly. So, modify the "ram:test.rpl" file so that the DoNothing word looks like the following. : DoNothing 0 o2 @ RANDOM RANDOM RANDOM 0 M_MOVETO 1 ; Now, restart Real, create one DO_NOTHING method with some targets and play the animation. Now we have finally managed to get something which looks like an animation. The reason why we first showed these silly "do nothing" examples was that it is important to realize that it is totally up to the user to decide what his/her object procedures (methods) should do. They can be simple or complex and tailored to address specific needs of the user. @endnode @node "T7.4.2.2" @title "Chapter 7 RPL" 7.4.2.2 Move Absolutely Along a Path In this example, we will demonstrate how to create a method which moves target objects along a path so that if the target is dislocated from the path, it is immediately pulled back to it. This is very good example, because it demonstrates how powerful a tool RPL is and how user created methods expand the functionality of the program. The first thing to do is to decide what kind of properties our custom methods should have and what kind of parameteres it requires. In this case our method strongly resembles the PATH methods. So, the syntax diagram of the method looks like the following: +--------+ | Parent | +--------+ / \ +--------+ +----------+ | target | | Level(M) | +--------+ +----------+ \ +------+ | Path | +------+ Next we have to work out what the procedure to be created should do. In this case, it should do the following things: - Read the current time - Evaluate one point from the parameter object corresponding to the current time. - Move target object(s) to the evaluated point. So, when the time runs from 0 up to 1, the evaluated points move along the parameter object from its beginning point towards its end point accordingly pulling all target objects with it. The following program defines AbsPath method procedure and adds a new animation method to the Animation System. ( Load definitions for object data structure "objects. rpl" LOAD ( One general usage support word : GetTargets 0 ( 0 terminates the list o2 @ O_GETSUB ( first subobject BEGIN ( test if the object address is not zero DUP IF ( fetch the contents of wMETHOD field: DUP O.wMETHOD W@ NOT IF ( if zero, valid target DUP ENDIF ELSE ( object address was zero, so EXIT ( no more targets, exit the word ENDIF ( fetch the address of the next object: O_GETNEXT AGAIN ; ( Actual object procedure : AbsPath GetTargets ( fetch target objects on the stack o1 @ O_GETSUB ( find the parameter object DUP NOT IF ( if no parameter, syntax error "Parameter Object Missing" PUTS 0 ( cancel animation EXIT ( exit word ENDIF t F@ u F@ v F@ O_EVAL 0 M_MOVECOG 1 ( return 1, everything is okay ; ( Install new method to the animation system & AbsPath "ABS_PATH" MTH_CREATE DROP As you can see, it takes only some lines of RPL code to define a completely new animation method. After executing the program, one new method called ABS_PATH can be seen in the Create/Structure/Method requester. The word GetTargets is a general usage word which can be used by all your custom methods. It just fetches the addresses of all target objects on the stack and terminates the list with 0 as required by M_XXXX words. The variables "o1", "o2" and "t", "u", and "v" are automatically defined by the animation system. "o1" contains the address of the method object, "o2" contains the address of the parent object of method and t, u and v variables reflects the new time for the method. So, let's take a look at what the actual method procedure does. Whenever the time is changed, the animation system calls our procedure AbsPath. As already mentioned, the word: GetTargets just pushes the addresses of all target objects on the stack. Then the line o1 @ O_GETSUB fetches the address of the parameter object on the stack (parameter object is sub object of the method object). The code: DUP NOT IF "ERROR: Parameter Object Missing" PUTS 0 EXIT ENDIF then tests the return value of O_GETSUB and if 0, proper error message is printed out and 0 returned indicating that the method failed. The return value of 0 causes animation system to stop. Otherwise the code after ENDIF is executed: t F@ u F@ v F@ O_EVAL 0 M_MOVECOG 1 which evaluates a point from the parameter curve and moves all targets to that point. Finally the value 1 is pushed on the stack, which indicates that method succeeded in its task. @endnode @node "T7.4.2.3" @title "Chapter 7 RPL" 7.4.2.3 Chain In this example, we will create a method which attempts to keep the distance between subsequent target objects constant. The distance between targets can be defined by associating a tag with the method object. If the tag does not exists, then our method uses default value, say 0.5. This method can be very powerful with some particle system oriented methods like radial force etc. Our methods should do the following things: 1. Find the tag value of "FDIS" tag associated with the method object. 2. Loop through all targets and move them so that the distance between COGs of subsequent targets equals the fetched tag value. Note: That we use vector operations here. Note: That this requires some basic knowledges of vector operations like how to add and subtract vectors. ( Useful support function Distribute FVARIABLE fLen VVARIABLE vTmp : Distribute ( 0 aObjects .... fDist ) fLen F! iOP_COG O_PROP vTmp V! BEGIN DUP WHILE DUP iOP_COG O_PROP vTmp V@ VSUB VNORM fLen F@ VMUL vTmp V@ VSUB vTmp V! 0 SWAP vTmp V@ 0 M_MOVECOG REPEAT DROP ; ( Actual Object Procedure : OP_Chain GetTargets o1 @ "FDIS" O_FINDTAG DUP ( find tag FDIS IF ( if found, fetch its value on the stack: 4 + @ F@ ELSE DROP 0.5 ( else push 0.5 on the stack ENDIF ( call distribute with objects and distance: Distribute 1 ; & OP_Chain "CHAIN" MTH_CREATE DROP - TUTORIAL 7.32 - Again, we divided our method into two different words: Distribute and the actual object procedure OP_Chain. The reason for this is that "Distribute" is in general usage a useful word and it is a good programming practice to write modular programs by subdividing bigger tasks to smaller ones. For example, your can apply the "Distribute" now interactively to selected objects by defining just a core word which uses the GET_FLT and O_GETSEL words for fetching the required parameters for it instead of using O_FINTAG and GetTargets as we did here. The Distribute words take the following parameters: - object list terminated with 0 - distance The first line fLen F! Just assigns the passed distance parameter to the variable "fLen". This makes it easy to use all over because we don't have to remember where it is in the stack. The next line starts the actual job: iOP_COG O_PROP vTmp V! O_PROP word is first used for fetching the COG of the first object on the stack and assigns it to the vector variable vTmp. Then in the beginning of the loop: DUP iOP_COG O_PROP fetches the COG of the second object on the stack. The line vTmp V@ VSUB VNORM fetches the COG of the first object on the stack, subtracts the COG of the second object from the COG of the first object and finally normalizes the result vector so that the lenght of it will be 1. The line fLen F@ VMUL then multiplies the unit vector by given distance. Now the length of the vector is given distance and it points from the second object towards the first one. Then we have to subtract it from the COG of the first object and we get the position for the second object. The following line subtracts the vector from the COG of the first object and saves the result back to the vTmp. vTmp V@ VSUB vTmp V! Then we just move the second target object to the defined point. 0 SWAP vTmp V@ 0 M_MOVECOG There is not much to tell about the actual object procedure OP Chain. It uses the word "GetTargets" to fetch the addresses of target objects on the stack, the distance to be used from the tag FDIS (or uses the value 0.5 if the tag does not exists) and then calls the word Distribute which does the actual job. Because the method cannot fail, it always returns 1. Before we leave this method example, let's take a look at how the Distribute word can be used interactively. 1. Open one RPL window and define the word Distribute. 2. Create 10 spheres resembling pearl necklace. 3. Write the following program: FVARIABLE fDistance : Distr fDistance "Define Distance" GET_FLT IF O_GETSEL fDistance f@ Distribute ENDIF ; 4. Select all spheres and call the word "Distr". @endnode @node "T7.4.2.4" @title "Chapter 7 RPL" 7.4.2.4 Strange Force In this example we will create a method object which applies a very strange force field over targets causing the velocity and the spin of target objects to be changed . This is an absolutely crazy method, because the way we modify the velocity is absolutely random and it might be quite a difficult job to find such a force field in the real world. However, it demonstrates well the concept of designing new physical based methods and how to create and update object tags. First we need a word which defines a direction and the strength of the force field. : GetStrangeForce RANDOM RANDOM RANDOM ; Because we separate the word which defines the strength and direction for the force, it is very easy to change this method just by modifying this word. Then we need a word which attemps to read the value of velocity tag. If the VVEL tag does not exist, then it creates it. If the velocity tag exists, then the method modifies its value according to Newtons Laws of Motion. So, how much should the velocity of the object be changed if the force affects the object for "dt" seconds? According to Mr Newton, the strength of the force equals the mass of the object multiplied by the acceleration. Mathematically the problem can be solved as follows: F=ma => F=m*dv/dt => dv = F*dt/m ----------- Because our force is not sensitive to the mass of the target object, we can forget the mass (m). Hence, the new velocity can be solved from the equation: dv = F*dt --------- The following word does all this: ( Word modifying the velocity ) ( of a given object ) : DoStrangeVEL ( aObj ) "VVEL" O_FINDTAG DUP ( try to find VVEL tag IF ( if found: 4 + @ ( fetch the address of tag value DUP V@ ( fetch the velocity on the stack ( fetch the force vector on the stack: GetStrangeForce dt F@ VMUL ( dv = F* dt ( add "dv" vector to original velocity: VADD ( assign result back to the velocity tag: 4 ROLL V! ELSE DROP DUP "CEND" 0 0 0 "VVEL" O_CREATAG DROP ENDIF ; In order to get the new particle method perfect, also the spin must be affected somehow. The only difference between this and the DoStrangeSPI words is that the result vector for the VSPI tag is multiplied by 2*PI. This is because the spin is represented in radians and 2*PI radians corresponds to a full circle (360 deg). ( A word modifying the spin of the object ) : DoStrangeSPI ( aObj ) "VSPI" O_FINDTAG DUP IF 4 + @ DUP V@ ( original spin GetStrangeForce dt F@ 2 PI F* F* VMUL ( delta VADD ( new spin 4 ROLL V ( assign result to VSPI ELSE DROP DUP "CEND" 0 0 0 "VSPI" O_CREATAG DROP ENDIF ; The actual object procedure then just scans through all targets and calls DoStrangeVEL and DoStrangeSPI words for each object. : OP StrangeForce GetTargets BEGIN DUP WHILE DUP DoStrangeVEL DoStrangeSPI REPEAT DROP 1 ; & OP StrangeForce "STRANGE_FORCE" MTH_CREATE DROP @endnode @node "T7.5" @title "Chapter 7 RPL" 7.5 USING EVAL The EVAL word provides the user with an easy way to access data structures of Real, such as materials and objects. In this chapter we will show you some basic ways to use EVAL. Create one material with all properties set to default. How to set the brilliancy of the created material "mymat to 100? Type the following line: "data(mymat->spec)=100" EVAL DROP You just set the specularity of "mymat" to 100. To make sure that this really happened, open the material requester with the material and see. If you don't like Reverse Polish Notation, you can use eval to evaluate your formulas like this: "2*3+5" EVAL . which is the same as the phrase "2 3 * 5 + ." and RPL will reply: 11 or like this: "2*3*sin(3*cos(123)+3)" EVAL F. or like this: "data(mymat->spec)=(data(mymat->bril) +data(mymat->tran))/2" EVAL. and RPL calculates an average of the brilliancy and transparency and assigns these results into a specularity field. So, let's create a material morphing animation. Create one sphere and add material "mymat" to it by creating one texture at the same level. Ensure that the rendering settings for the current View window are correct (don't use the Fast-mode because it ignores all material properties). Then write the following program: VARIABLE rg : MyAnim 10 0 DO ( ten frames ) I 10 * rg! ( rg=I*10 ) "data(mymat->roug)=rg" EVAL DROP RENDER LOOP ; and everything is ready for the show. Call the previous function and you'll see how the roughness of your rectangle is morphed during the animation. Right, how about objects. Assume that the full name (including the path) for you rectangle is "/Root/rectangle". Then you could print out the color of you rectangle as follows: "data(/Root/rectangle->R)" EVAL. "data(/Root/rectangle->G)" EVAL. "data(/Root/rectangle->B)" EVAL. or you can change the red signal of the color as follows: "data(/Root/rectangle->R)=120" EVAL. or you can print out the name of your object as follows: "data(/Root/rectangle->name)" EVAL PUTS or you can change the line pattern of your rectangle as follows: "data(/Root/rectangle->ptrn)=255" EVAL. REFRESH or you can change the register color for wire frame rendering: data(/Root/rectangle-> reg)= 3" EVAL. REFRESH For more about EVAL, see the reference manual. @endnode @node "T7.6" @title "Chapter 7 RPL" 7.6 OBJECTS In this section, we will demonstrate how RPL can be used for creating and manipulating objects. 7.6.1 Object Creation So, let's get started by creating a simple RPL program which just creates one primitive and renders it using default rendering settings. ( A minimal program for rendering a sphere 0.0 0.0 0.0 ( center ) 0.5 0.0 0.0 ( a ) 0.0 0.5 0.0 ( b ) 0.0 0.0 0.5 ( c ) 255 0 0 0 ( RGBA ) "ellipsoid" ( name ) 0 ( flags ) "CEND" ( tags ) C_ELLIPSOID DROP RENDER When passed to REAL 3D's stand-alone renderer, it should produce an image representing one red sphere. Lets go through what this program actually does. The first word C_ELLIPSOID creates an ellipsoid. The general form of all creation words is as follows: Geometry Color Attributes C_nnnn Address Geometric data is described first (in the example it consists of four vectors: center, a, b, and c). The form of geom. data depends on the type of the object to be created. Not all objects have geometric description. In this example, the geom. data defines a sphere, because the length of all three axes are the same. ( Geometric data for ellipsoid ) 0.0 0.0 0.0 ( center ) 0.5 0.0 0.0 ( a ) 0.0 0.5 0.0 ( b ) 0.0 0.0 0.5 ( c ) The second data section is a color for the object. Color is defined by 32 bits (RGB+A). Like geom. description, not all objects have color section. ( Color is defined by 32 bits R,G,B+A ) 255 0 0 0 ( RGBA ) The third data section defines so called "Attributes" for objects. Attributes can be divided into three different parts: name, flags and tag list. The name field defines a symbolic name for the object. This name can be used in many ways. For example, it can be used for finding the address of the object in order to create new objects, more on this later. The flags field is a 32 bit wide integer value. It is used for defining on/off kinds of attributes like whether or not this object should be "motion blurred" or "invisible". In the REAL 3D Editor, these flags can be defined using Modify/Properties/Attributes function. For more information about possible attribute flags, see the reference manual. The tag list can be used for defining custom attributes for objects needed by procedural textures, animation methods etc. The tag list consists of a number of tag identifier-value pairs. The tag value is a string whose length is four characters which identifies the value. The type of the tag value then depends on the tag identifier. The tag list is always terminated by "CEND" string. ( Attributes ) "ellipsoid" ( name ) 0 ( flags ) "CEND" ( tags ) C_ELLIPSOID creates an ellipsoid and returns the address. This address can be used in many ways as we will later see. In this example, it is not needed, so it is discarded by using the word DROP. The last word "RENDER" then asks REAL 3D to render the defined scene which in this example consists of only one sphere. One basic idea of RPL is that at the lowest level all data needed for defining objects must be passed to the RPL interface! There are no graphical environments used for defining parts of the data needed as in Renderman. However , this does not mean that in the case where a scene consists of a large number of almost identical objects the program would have to redefine the same data again for each object. Because RPL is a full featured programming language, there are many ways to solve this problem. For instance, let us imagine a scene consisting of 10 spheres. Would it take ten times more space to create such a scene as a scene which consists of only one sphere? Only if all the objects are totally different. Usually they are not, in which case identical data could be defined using, for example, a separate RPL word instead of redefining it for all primitives. Lets demonstrate this by creating an RPL program. The program would create two identical spheres to different position. ( A simple program implementing graphics ) ( environment using different RPL words ) : MY ELLIPSOID ( center addr ) 0.5 0.0 0.0 ( a ) 0.0 0.5 0.0 ( b ) 0.0 0.0 0.5 ( c ) 255 0 0 0 ( RGBA ) "ellipsoid" ( name ) 0 ( flags ) "CEND" ( tags ) C_ELLIPSOID ; 0 0 0 ( center ) MY_ELLIPSOID DROP 1 0 0 ( center ) MY_ELLIPSOID DROP RENDER To make this clear, let's create another program. The program creates a small "Renderman" style graphical environment used for defining "Attribute" data section for objects to be created. ( data for simple graphics environment ) VARIABLE R VARIABLE G VARIABLE B VARIABLE FLAGS 16 STRING NAME ( words for manipulating ) ( graphics environment ) : RiName ( name - ) NAME CPY ; : RiColor ( R G B - ) B!G!R! ; : RiFlags ( Flags - ) FLAGS ! ; ( Ri style interface for creating ) ( an ellipsoid ) : RiEllipsoid ( center, a, b, c - ) ( fetch color from graphics environment ) R @ G @ B @ 0 ( A=0 ) NAME ( fetch the address of the name ) FLAGS @ ( fetch flags ) "CEND" ( no tags ) C_ELLIPSOID DROP ; ( create 3 blue spheres ) 0 0 255 0 RiColor 0 0 0 1 0 0 0 1 0 0 0 1 RiEllipsoid 1 0 0 1 0 0 0 1 0 0 0 1 RiEllipsoid 2 0 0 1 0 0 0 1 0 0 0 1 RiEllipsoid ( create 2 red ellipsoids ) 255 0 0 RiColor 0 1 0 0.5 0 0 0 1 0 0 0 1 RiEllipsoid 0 2 0 0.5 0 0 0 1 0 0 0 1 RiEllipsoid ( create one green ellipsoid, "blue" ) 0 255 0 RiColor "blue" RiName 0 -1 0 0.5 0 0 0.8 0 0 0 1.2 RiEllipsoid This listing defines a custom interface where geometric data is defined by the caller and the attributes are fetched from the graphics environment. @endnode @node "T7.6.2" @title "Chapter 7 RPL" 7.6.2 Object Instances RPL allows creation of "object instances". This is a useful feature whenever it takes less space to define geometric transformations and modify new objects out of existing ones than defining object data itself. The following example creates a number of spheres using this technique. FVARIABLE Rad VARIABLE Obj ( create first object ) : MY SPHERE ( center rad - addr ) Rad F! ( assign radius to variable "rad" ) Rad F@ 0 0 ( a ) 0 Rad F@ 0 ( b ) 0 0 Rad F@ ( c ) 255 0 0 0 ( RGBA ) "ellipsoid" ( name ) 0 ( flags ) "CEND" ( tags ) C_ELLIPSOID ; 0 0 0 0.5 MY_SPHERE Obj ! ( create two object instances ) ( from the first one ) Obj @ M DUPLICATE 0 SWAP 1.5 0.2 0.2 0 M_MOVE ( the second one: ) Obj @ M_DUPLICATE 0 SWAP 255 255 0 0 1 0 M_COLOR The word MY SPHERE takes two parameters which are center and radius and returns an address of the created sphere. The line 0 0 0 0.5 MY_SPHERE Obj ! creates one sphere whose center is 0,0,0 and radius 0.5. The return value from the C_ELLIPSOID is not discarded using DROP but returned so that it can be stored into the variable "Obj". The last two lines contain the big idea so lets go through them line by line: Obj @ ( fetch the address of the sphere M_DUPLICATE ( duplicate it and leave ( its address on to the stack For the sake of efficiency, more than one object can be modified by RPL modify words at one call. The address 0 means that there are no more object addresses in the stack. So the following expression: 0 SWAP just terminates the object pointer list by 0. 1.5 0.2 0.2 0 M_MOVE then moves object instance 1 .5 along x axis and 0.2 along y and z axes. The second instance is created by changing the color of the sphere from red to yellow. 7.6.3 Grouping Objects Together Objects can be grouped together to create hierarchical object trees. This hierarchical construction of object conforms the basis for a large number of other features of RPL. The word C_LEVEL can be used for creating new levels into the object hierarchy and its syntax is as follows: Type Attributes C_LEVEL Addr The following example creates one simple object tree using the word MY_SPHERE created in the previous example. The structure of the tree to be represented is as follows: +------+ | Root | +------+ / \ +--------+ +-----+ | Sphere | | Sub | +--------+ +-----+ / \ +--------+ +--------+ | Sphere | | Sphere | +--------+ +--------+ The following program builds up the hierarchy. ( Creating a simple hierarchical object ) wOT_OR "Root" 0 "CEND" C_LEVEL O_CURRENT DROP 0 0 0 0.5 MY_SPHERE DROP wOT OR "Sub" 0 "CEND" C_LEVEL O_CURRENT 0 0 0 0.5 MY_SPHERE DROP 0 0 0 0.5 MY_SPHERE DROP O_GETCURR O_GETPAR O_CURRENT DROP The first two lines wOT_OR "Root" 0 "CEND" C_LEVEL O_CURRENT DROP create one object of the type wOT_OR. The constant named "wOT_OR" is defined "objects.rpl" in file and the actual value of it is 2. By using constants makes the type of the level more easy to understand for human beings. It is strongly recommended to use these kind of definitions instead of direct values. The first parameter "wOT_OR" defines how volumes of all sub objects are interpreted. In this example, they are "OR" read with each other. The following fields "Root" 0 "CEND" defines attributes for the object and are identical with those we have already seen in previous examples. The word O_CURRENT takes one parameter, which is an address of an object and makes it the current level so that all latter objects will be created inside it. The word returns the address of the previous current level and we get rid of it using the DROP word. The creation of the second level is similar to the first one except for two things: the name of the level to be created is now "Sub" and we don't delete the return value from the O_CURRENT. We leave it on the stack so that we can use it later to pop back to the previous level using O_GETPAR and O_CURRENT words. O_GETPAR takes the address of an object and returns the address of its parent object. Then O_CURRENT makes it the new current level. Althought all previous words are pretty simple and clear, our example itself is not perhaps as clear as it could be. The reason for this is that it shows how to built up a hierarchy at the lowest level. Again, it is not necessary to define all parameters for C_LEVEL every time a new level is created. We can create our own core word, which takes only the name of the level to be created. In the following example we will create some useful words which reduce the size of the program and make it much more understandable. ( create level ) : ObjBegin ( name ) wOT_OR SWAP 0 "CEND" C_LEVEL O_CURRENT DROP ; ( close level ) : ObjEnd O_GETCURR O_GETPAR O_CURRENT DROP ; "Root" ObjBegin 0 0 0 0.5 MY_SPHERE DROP "Sub" ObjBegin 0 0 0 0.5 MY_SPHERE DROP 0 0 0 0.5 MY_SPHERE DROP ObjEnd ( Now words ObjBegin and ObjEnd ) ( can be used for defining hierarchy ) It is very easy to close the hierarchy levels by leaving the return address of each created level on the stack and pull it out when it is needed. To get the parent object of it in order to pop up one hierarchy level. However, sometimes it is easier to build up the hierarchy first and then create the actual primitives. For example, let's build up a hierarchical tree which contains no primitives. The structure of the tree should be as follows: +------+ | Root | +------+ / | \ / | \ +------+ +------+ +------+ | Sub1 | | Sub2 | | Sub3 | +------+ +------+ +------+ / \ / \ +-------+ +-------+ | Sub21 | | Sub22 | +-------+ +-------+ / \ / \ +--------+ +--------+ | Sub221 | | Sub222 | +--------+ +--------+ Using the words ObjBegin/ObjEnd defined in previous example a program would look as follows: ( Building up an empty hierarchy ) "Root" ObjBegin "Sub1" ObjBegin ObjEnd "Sub2" ObjBegin "Sub21" ObjBegin ObjEnd "Sub22" ObjBegin "Sub221 ObjBegin ObjEnd "Sub222 ObjBegin ObjEnd ObjEnd ObjEnd Because we discarded all addresses of created objects using the DROP word in the ObjBegin word, we don't remember any addresses of any objects. So, how do we create something inside the desired hierarchy level? The address of any object can be found by its name. For example, we could create a sphere inside the object named "sub222" as follows: ( find the address of object ) "/Root/Sub2/Sub22/Sub221" O_FIND O_CURRENT DROP ( make it current ) ( create one sphere ) 0 0 0 0.5 MY_SPHERE DROP Another possibility is to use variables to store object addresses instead of fetching addresses using the O_FIND word. @endnode @node "T7.6.4" @title "Chapter 7 RPL" 7.6.4 SphereMan As a final example for this RPL tutorial, we will go through how to create "freeform objects" consisting of thousands of particles. For example, a body of the human being can be created using thousands of spheres distributed evenly over the body instead of using freeform meshes. This kind of task where we have to deal with thousands of objects would be almost impossible task to do without programming language. In this example we will use a SIMPLE SKELETON method to pull the sphere mass on the freeform mesh representing a head. RPL is used for creating all spheres as well as defining positions for each sphere so that they will be scattered all over the head. Clear the Settings/Creation/Auto_Index menu. This dramatically speeds up the creation process. It might be a good idea to switch the Undo feature off. Write the following program using your favourite text editor and save it: : CrSpheres ( iHowmany ) 1 O_LOCK 0 DO 0 0 0 ( center ) 0.05 0 0 ( a ) 0 0.05 0 ( b ) 0 0 0.05 ( c ) 255 255 255 0 ( RGBA ) "ell" ( name ) 0 ( flags ) "CEND" C_ELLIPSOID NOT IF "Not Enough Memory" PUTS 0 O_LOCK EXIT ENDIF I. LOOP 0 O_LOCK "Done" PUTS ; Now open one RPL window and load the program in. This just defines the word CrSpheres. As you can see the word CrSpheres takes one parameter which is the number of spheres to be created. Depending on the memory available, your can call this word with a different amount of spheres. If you have six megabytes of RAM memory installed, you should be able to create about 1000 spheres. So call the CrSphere as follows: 1000 CrSphere This creates 1000 spheres. Then we have to define the positions of the spheres on the skeleton mesh. If you are familiar with the skeleton methods, you know that the tag VPHS is used for defining at which position of the skeleton the target object in question is pulled. Because we are going to use a freeform mesh (a head) as a skeleton object, we have to define the first two components of the VPHS tag. For example, if the value 0,0 corresponds to the left top edge of the mesh, then the value 1,1 corresponds to the right bottom edge. The value 0.5 0.5 corresponds to the middle point of the mesh etc. So, write the following program (or just load it in from the rpl directory): ( A program scattering spheres evenly ) ( over a skeleton mesh ) VARIABLE iWidth VARIABLE iHeight : DefPhs ( aParent iWidth iHeight ) iHeight! iWidth ! O_GETSUB DUP NOT IF "No subobjects" PUTS EXIT ENDIF iHeight @ 0 DO iWidth @ 0 DO DUP "CEND" I iWidth @ F/J iHeight @ F/ 0.0 "VPHS" O_CREATAG NOT IF "Cannot create tag" PUTS EXIT ENDIF "." PUTS O_GETNEXT DUP NOT IF "AII Done" PUTS EXIT ENDIF LOOP LOOP ; The word DefPhs takes three parameters: the address of the object containing all spheres, the number of spheres in "u" direction and the number of spheres in "v" direction. For example, if the Width parameter is 100, there will be 100 spheres in the "u" direction of the mesh. Now, make the object containing all created spheres the current level and enter the following command: O_GETCUR 35 35 DefPhs This defines the VPHS tag for each sphere in the current level so that each cross-section curve of the head will consist of 35 spheres. Create one SIMPLE SKELETON method beside all the spheres and add the following tag to it: ISKE 3 This tells the skeleton method that the VPHS tags are already created and are up to date. If you forget to add this tag, the method will automatically define tags according to the current positions of the target objects. Load your freeform mesh representing a head inside the method object. Now the hierarchical structure of your object should be as follows: +------+ | Root | +------+ / \ +--------+ +-------------+ | o1..oN | | Skeleton(M) | +--------+ +-------------+ \ +---------------+ | B-Spline_Head | +---------------+ So, spheres (o1 ... oN) are pulled on the B-Spline_Head object by the skeleton method. Your "SphereMan" is now ready. Select the menu Animate/Control/Refresh and all the spheres are pulled on the head. Make the skeleton object invisible if you don't want to see the mesh itself. We will stop here, but you can carry on by animating the skeleton mesh. This also causes the spheres to be animated (because whatever you do to the head object, the spheres are always pulled on its surface). For example, you can add one WAVE method beside the B-Spline_Head and the sphere head will wave. +------+ | Root | +------+ / \ +--------+ +-------------+ | o1..oN | | Skeleton(M) | +--------+ +-------------+ / \ +---------------+ +---------+ | B-Spline_Head | | Wave(M) | +---------------+ +---------+ / \ +------+ +-------+ | axis | | curve | +------+ +-------+ Now the spheres (o1 ... oN) are pulled on the B-Spline_Head which is morphed by the Wave method. Or you can use this technique just as a creation tool and delete the skeleton after all spheres are pulled on it. Then you can use the sphere as a beginning situation in particle animations. The possibilities are infinite and the only existing limit is your imagination. @endnode @node "R1.1" @title "Chapter 1 MENU FUNCTIONS" REFERENCE --------- Chapter 1 MENU FUNCTIONS ------------------------ The following syntax is used to describe all the functions available by menu selection: / - SUB-MENU ITEMS FOLLOW * - TOGGLE GADGET 1.1 PROJECT The REAL 3D binary file format follows the IFF standard. The various data-structures necessary to define a complete REAL 3D project are each saved in a different data-section. Each data-structure can be saved and loaded independently. For each major data-structure type, there is a specific function. In addition, under the Project/ sub-menu are functions for loading and saving each individual section. There are two variants of loading for each data-section: "Insert" which loads the new data and adds it to the existing data-structure; and "Replace" which clears the existing data-structure if or when it loads the new data. The loader is intelligent, and can cope with loading files which contain some or all data-sections, but each loading function will only try to load those sections it is specified to load. The "Replace" variant of the loading functions do NOT clear the existing data-structure if the specified file does not contain the appropriate data-section. The different "Save" functions only save those sections they are specified to save. All the functions open a file-requester to allow the user to select the REAL 3D IFF file to load from. Changing the DOS path updates path- settings, so it is remembered by the requester the next time it is used. If "Confirm Save" gadget is set by using Settings/General requester, the user is asked to confirm the operation before the old file is overwritten. When working on a Workbench(TM) screen, Real-IFF files can also be loaded by moving their icons onto a View window. Objects/ Insert Load new objects from specified file into the current level of hierarchy. Save Save selected objects to the specified file, Replace Clears the hierarchy if/when it loads the object section of the specified file. Project/ The user is presented with a requester to define the new name for the root object. New This does the following: 1. Hierarchy cleared 2. Material Library deleted 3. Named Colors Library deleted 4. Grid Definitions removed 5. Vector stack is cleared 6. Undo Buffer cleared 7. Time and Frame Count are reset to zero Insert Load all the available sections of a project definition from the specified file. Save Saves all sections of the current project definition to specified file. Replace Load all available sections from the IFF file and delete any corresponding data structures in memory. Insert Sections A requester is opened to allow only those sections of a REAL 3D file the user selects to be loaded. After the selection has been confirmed, the file requester will be opened. Save Sections Opens requester to select data sections for saving, then the file requester. Replace Sections Opens data sections requester for selecting the sections to replace from a file. Materials/ Material definitions are stored in the material library. They are created and modified using a material window. Window Open a Material editor window. This allows materials to be created and modified while other actions, in particular rendering, are taking place. The material definitions are stored in a material data structure, called the material library, complete with their material name, The material definitions are created and modified using a material editor window. Figure @{"R1-1:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-1"} Material Editor Window (PICTURE: R1-1) Local Menu: DEFINE/ Texture D Select name of image file using file requester. Show Texture S Display image file. If the image is 24 bit and the External screen is open, then a requester will be produced asking for confirmation, as displaying the image may overwrite the contents of the External screen. Trans. Color C Select Transparent color from current color. TagsT Open the Tag requester to modify or define the tags associated with the current material. Gadgets of the Material window: Name Name of material in the Material library. Texture The path and name of an image file to use for defining various material properties like color or transparency. Each pixel in the bit-map relates to a point on the surface of the object, depending upon the type of mapping control object associated with the material and its position relative to the physical object, An index format string can be included as part of the name. This means that the value of the index variable "i" will be formatted to this specification and included as part of the file name. Spline When this gadget is set, and the target object for the material is a B-spline mesh, then the object itself is used for the mapping definition. Any coordinate transformations defined by mappings associated with the material are ignored. This means that the mapping of the texture file follows any modifications to the shape of the mesh. S-map uvwh These four numeric gadgets control the position and size of the image file when it is mapped onto a spline. The u and v values determine the position of the top left corner of the image and w and h control what proportion of the spline is covered. Each of these can be between 0.0 and 1,0, Color map Texture is to be used for material color definition. Bump map Red component of texture is used for bump map evaluation. The brighter the red component, the higher the bump. Transparency map Green component is used for transparency evaluation. The brighter the green component, the more transparent the material. Brilliance map Blue component is used for evaluating brilliance. The brighter the blue component, the more mirrorlike the material. Shadow map The RGB values of each pixel of the texture file are used to modify the current color values for the corresponding point of the objects surface, The modification formula is: R*r/255, G*g/255 & B*b/255 Where: r, g, b are the color values of the pixel and R, G, B are the current color values of the surface point It is intended for this function to be used with grayscale texture files to artificially produce shadow effects as an alternative to using Render Settings/Normal mode or , when it is necessary, to create artificial shadows in addition to rendered ones. Note: If shadow mapping is used with a pure white object, it produces the same results as color mapping. Clip map The surface of the object is clipped by the texture file. The object surface is removed wherever it is not covered by the texture file. This includes any areas not covered by the mapping or tiling, or any areas selected as transparent. Scope mask If this gadget is set, the material effect is modified by using the texture as a mask, which defines where the material is applied. Only the points which are affected by the texture, included in the material, get non-zero scope. The application test is equivalent to the one used for clip mapping. Transparent Color (Transp. col) The color to use as the transparent color is taken from the numeric gadgets: Trans.R, Trans.G, and Trans.B. This affects the application of a texture for clip mapping and scope mask. Transparent color is defined in 24-bit color space, so all values vary between 0 and 255. You can translate a color in original Amiga color system, values ranging from 0 to 15, to 24-bit system by multiplying each color component value by 16. For example, pure white R=15,G=15,B=15 corresponds R=240, G=240, B=240. Unshaded Light sources and shadows do not affect the shading of this material. Smooth Removes specular reflections on the boundaries of transparent materials. Exclusive When the rendering engine evaluates the material properties for each point on a surface, it mixes all the properties for each material defined by the mappings at the same hierarchical level. If only one mapping is present, then the material properties are mixed with the default material properties. Setting the Exclusive property means that other material definitions are ignored for any points on the surfaces covered by that specific material. See Also: "Effect" and "Scope" in this sub-chapter. Tiling Gadgets Tile Selects whether texture file is to be tiled in X, Y or both directions. Flip Selects whether tiled texture file is to be mirrored in X, Y or both directions. If set, then every second tile is flipped, making texture map edges match better. X-Freq. & Y-Freq. These numeric gadgets specify the number of tiling repetitions over the surface of the texture. If the frequency is set to 0, the texture is tiled infinitely for all mapping types, except spherical mapping. For parallel, both X & Y can be infinitely tiled; and for cylindrical and disk mapping, only Y = 0 is treated as infinite tiling. When infinite tiling is used, each tile is the size of the texture along that axis. Grade Selects whether color gradients are calculated for X, Y or both directions of the texture file. Color gradients produce smooth transitions from the color of one pixel to the color of the adjacent pixels. Specularity Controls how sharply defined are the high-lights reflected from the surface of the material by light sources. The higher the specularity, the smaller the high-light and the harder its edges. Specular brightness (Spec. bright.) This affects how intense the specular high-lights are. Brilliance The degree to which light is reflected directly from the material surface ("mirror-like" property), Transparency The degree to which light passes through the material surface. Turbidity Controls the degree to which light is affected as it passes through the material. The higher the setting the denser the "fog". Turbidity saturation (Turbid. sat.) Defines how the distance which light travels in a turbid material affects the light. The default value 25 gives a linear result; so if the distance is doubled, then the effect is doubled. If this value is zero, then the distance has no effect at all. The actual equation is: "turbidity effect" = Turbidity * (distance^Turbid. sat.), ^ = to the power of Refraction This determines the degree to which light is bent as it passes through the material. It represents the speed of light in the material as a percentage of its maximum speed through empty space. The higher this value the less the light is bent. Roughness This controls the degree of "molecular texture" applied by the material. This "molecular" texture is a random bump-map which is independent of the magnification of the material. Dither This enables dithering of material color to be applied to individual objects and the precise amount of dithering to be selected. The actual amount of color deviation applied is given by: R = R + rnd, G = G + rnd, B = B + rnd where -di/2 < rnd < di/2 where: di is the dither setting. Bump height Relative scale of bumps produced by bump-mapping texture file and procedural bump handler. Effect All materials at the same hierarchical level are mixed together. This controls how strongly the properties of the current material will affect the objects to which it is applied. Effect level is combined with the Scope material variable "s" to determine the final strength of the material properties at any point on the surface of the targets. APPLY Apply the current settings to the library under the name specified in the "Name" text-gadget. If a material under the name already exists, the old definition is overwritten. Otherwise a new material is created and appended to the material library. LOAD Open a requester to allow one of the materials in the current material library to be selected and loaded into the editor window. RESET Reset the material editor to display default material properties. Procedural Handlers In addition to being defined by a slider value or an IFF file, certain material properties can be defined using mathematical equations. These handlers are modifiers to the properties defined by the other settings. The equations to control these properties can come from several sources: Default No procedural handler. Formula An equation with an assignment to a system variable is entered in the expression box. This expression is evaluated using the RPL word EVAL. RPL RPL text is used to define the handler. This can either take the form of direct RPL words and operands, or an external RPL file to be loaded. The RPL text is interpreted, so the fastest way to implement any handler is to define an RPL word which accesses the material variables directly. The name of this word is then entered into the expression box as the RPL text. The text is interpreted by the RPL "Master" environment, so if the word was defined in an RPL window, then it is necessary for "Master" to INHERIT the other environment. For more details of this see RPL documentation. Built-in Handlers Each procedural handler has several built-in formulas to produce particular effects more rapidly than using the equivalent as a Formula or RPL handler. These handlers use the a and b variables as control parameters for various aspects of their formulas. The default value for both a and b is usually 1.0, but Scope and Color/Waves are exceptions. For the Scope handlers, the default for a is Material Variable sz, the texture size, which is used if a = 0.0. In the Color/Waves handler, the default for b is 128. Descriptions The equivalent formula for each of these handlers are given under the heading for the handler type to which they apply. The formulas use w for the texture map width and h for texture map height, but these are not material variables. Material Variables a,b - User definable variables, initially assigned the value of the numeric gadgets to the right of the expression gadget. x - Horizontal texture coordinate. Type: FLOAT y - Vertical texture coordinate. Type: FLOAT z - Depth texture coordinate. Type: FLOAT sz - Size of texture geometry. Type: FLOAT r - Distance from the origin of the texture. Type: FLOAT s - Scope output variable. Type: FLOAT sp - specularity Type: FLOAT sb - specular brightness Type: FLOAT br - brilliance Type: FLOAT tr - transparency Type: FLOAT tu - turbidity Type: FLOAT ts - turbid saturation Type: FLOAT ri - refraction index Type: FLOAT ro - roughness Type: FLOAT di - dithering scale Type: FLOAT bh - bump height Type: FLOAT bx - Bump-map horizontal coefficient Type: FLOAT by - Bump-map vertiCal coefficient Type: FLOAT R - Red color component Type: INTEGER G - Green color component Type: INTEGER B - Blue color component Type: INTEGER t - Local animation time Type: FLOAT i - Material texture index Type: INTEGER The following variables are available as a part of EVAL's function: Frm - Current Frame index Type: INTEGER Res - Frame Resolution Type: INTEGER T - Global animation time Type: FLOAT The ranges of x & y are either between 0,0 and 1,0 if no texture mapping type is being used, or between zero and the number of pixels along the x or y dimension of the texture file. z, sz & r are distances expressed in spatial coordinates and can have any positive value, If the mapping used is type Default, then x, y & z are the absolute spatial coordinates, and any mathematical handlers will effectively use Parallel mapping along z-axis. The value sz depends on the texture geometry in the following way: parallel - length of the shorter texture rectangle edge cylinder - radius of the cylinder (average if elliptic) sphere - radius of the sphere (average if elliptic) disk - radius of the disk (average if elliptic) The values for R,G & B are from 0 to 255. If a user defined formula assigns a value greater than 255, then it will be limited to 255. Negative values become zero. The range for T & t is between 0.0 and 1.0. The value of i is assigned by the user and can have any integer value. Frm & Res are a positive integer values between 0 and MAX_INT All the others should be between 0,0 and 100.0. If a formula takes a variable outside this range, then the effects are unpredictable. The order of the handlers indicates the order in which they are evaluated; Mapping first and Index last. Although the material variables can be assigned values at any time, assigning them values before the handler in which they are properly assessed has no practical effect, e.g. The color components are assigned their values from the texture file after the evaluation of the mapping and scope. The material variables x,y & z can be modified in any of the expressions, Handler Types: Mapping Material Variables: x, y & z. The Mapping handler is evaluated after the initial coordinate transformation calculations that use the mapping geometry have evaluated the values of x,y & z. Using an equation to modify one of these variables changes the way in which a texture file is mapped onto the surface. The following diagram shows how the mapping axes relate to the geometry of each mapping type. The x, y, z coordinates in the diagram relate directly to the material variables. Figure @{"R1-2:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-2"} Mappings (PICTURE: R1-2) Built-in Handlers Tilt y = y + x*a*h/w Waves y = y + sin(x*a*PI/w)*b*h SwapXY tmp = x, x = y, y = tmp Scope Material Variables: s, sp, sb, br, tr, tu, ts, ro, ri The primary variable for the scope handler is "s" which, along with Effect level, determines how much of the material properties are mixed with the material properties already applied to the objects. If no other materials are applied, then the material is mixed with the default properties. Built-in Handlers Sphere if r < a s=100, else s=0 InvLin s = 100/(1 + r^2/a) InvExp s = 100*exp(-r/a) Local s = max(100*a/(a-r),0) Temporal s = s*(a*(1 - T) + b*T) Where a = sz by default, except in Temporal, where a = 1 by default. Bump Material Variables: bh, bx & by. Bump-mapping is a process whereby the surface normal produced by the ray hit routines of the rendering engine are modified to make the surface appear to have "ripples" or "bumps". This modification is carried out by using vector addition between the true normal and two other vectors. The variables bx & by define the vectors used to deviate the normal and produce the bump-mapping effect. If a texture file is being used as a bump map, then bx and by are first evaluated from the red component of the texture. The bump-mapping vectors and their relationship to the normal (denoted by n) are illustrated in the following diagram: Figure @{"R1-3:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-3"} Bump Variables in Mappings (PICTURE: R1-3) Built-in Handlers Waves bx = bx + sin(x*a*PI/w)*b Bumps bx = bx + sin(x*a*PI/w)*b, by = by + sin(y*a*PI/h)*b Color Material Variables: R, G & B. The color components of the material can also be mathematically modified. The initial values for R,G & B are evaluated from the texture file if used. Mathematical formulas can then be used to modify or replace these initial values, as with the other Material Variables. The size variable (sz) can be used for to bind a formula to the size of a texture. Built-in Handlers Bright R = R*b/(r*a + 1.0) ( G,B similar ) Waves R = R + sin(x*a*w/h)*b ( G,B similar ) Index Material Variable: i The material variable i is evaluated by any index format string used in the texture file name. Using a mathematical formula based upon either T, t or Frm makes it possible to control the indexes of texture files in very flexible ways to create moving material textures. Built-in Handlers Default i = a, a+1, ..., b-1, 0, 1, ..., b-1, ... PingPong i = a, a+1, ..., b-1, b-1, b-2, ..., 0, 1, ... Index handler default values are a = 0.0, b = 0.0 (zero offset and no modulo cycle). Non-homogeneous Material Properties By using the procedural handlers, or mixing multiple materials, certain material properties can be evaluated non-uniformly, so the properties vary with their depth in the material. The number of times the material properties are sampled is dependent upon Render Settings/Mat. samples. The following properties, and their corresponding Material Variables are evaluated in this way: specularity specular brightness turbidity turbid saturation These non-homogeneous materials enable atmospheric gasses and sun-glow effects to be created. Delete Open a requester allowing the user to select a material from the library for deletion. If mappings still refer to deleted materials, then default material is used, If a new material with the same name is created or loaded, then the mappings will use the new definition. Delete All Delete all material definitions from the material library, Insert Load previously saved material definitions into material library. Save Save all material definitions in material library to the specified file. Replace Material library is cleared if the specified file contains a material section and new materials are loaded. Macros/ Macros are files containing the ASCII text of the operands and RPL words which recreate the actions of the user. Hierarchical selection is not recorded, so the macro executes using the selected objects as operands. The current macro is saved in the file t:macro.rpl. Only those actions which modify objects or the hierarchy structure are recorded. As well as being executed by the functions below, macros can be executed from an RPL window using the "LOAD" word. The RPL system saves and executes macro files on a line by line basis. This means the only limit to the size of a macro is the OS maximum file size. * Record Macro Record all user selected functions and input data as the current macro. When macro recording is started, the previous current macro is deleted. Execute Current Execute current macro upon the selected objects. This is equivalent to executing the RPL command t:macro.rpl LOAD. Execute Named Produces file requester for user to select name of stored RPL text file. This is usually a macro, but it could be any executable file. The selected file is then executed in the "Master" RPL environment. Repeat Current Execute current macro specified number of times. This is implemented internally using following RPL code: : Repeat_Current n 0 DO t:macro.rpl LOAD LOOP ; where n is the number of repetitions requested by the user. Spread Current Executes the current macro upon selected objects increasing execution count by one for each consecutive object. The execution count starts from zero, so it is not executed at all for the first object, then once for the second and twice for the third. Current to Named Opens a File Requester to the Macro Directory allowing user to define a new name for the current macro. This does not affect the operation of the current macro. This is the equivalent to copying the macro file using the OS. Named to Current Opens file requester allowing the user to select the macro file to be copied to the current macro file. This can also be accomplished using OS file copying. Named Colors/ Named colors are a way of storing special colors which need to be used repeatedly and on different projects. The color values of these colors are saved in a library which can be saved to a file, then re-loaded at a later date. Select A color is selected from the named colors library using a requester. The value of the current color will assume the value of the named color selected. Create The RGB values of the current color are saved in the named colors library under the name specified. Modify A named-color is selected from the library and its RGB values are changed to those of the current color. Delete The selected color is deleted from the library. Insert Load the file specified into the Named colors library. The existing named colors are not replaced. Save Save the Named colors library as the file specified, Replace Replace the Named colors library if the file specified contains appropriate data section. Windows/ Most windows are opened on the default public screen unless they are too large, when they will be opened on another public screen which is large enough. The animation window and palette window each open on their own private screens, which take their Interlace/Non-Interlace properties from the default public screen. Select Open window for selecting objects and moving through the hierarchy. Clicking on individual names selects a single object. Using over the Select window multi-selects objects. To de-select objects use or . The Select window uses the following text styles to indicate which types of objects are in the hierarchy: - Normal style used for primitives. - Bold style used for levels. - Italic used for controls and mappings. The current level is shown at the top left of the select window. All the objects in that level are indented and arranged in their order in the hierarchy from first to last. - Methods are shown with "(M)" after their name, unless they are the current level, when their method type will be shown in full. - A level with the boolean operator "AND" is shown with "(A)" after its name. - In addition to being printed in italics, mappings have "(T)" as a postfix to their name. The purpose of the select window is to show the logical structure of the object and to make it possible to point objects through their names. View Open a general purpose View which is the window into the REAL 3D universe. Individual Views can be configured using the functions in the View menu. Each View stores all its own settings, including both the sizes and positions selectable with the "zoom-gadget" to the right of the "depth- gadget". When the Select window shows the logical structure of objects, the View window is used for showing the physical structure of objects. The operation of View windows is part of the asynchronous design of REAL 3D. This means that they take full advantage of the Amiga multi-tasking environment by executing time consuming functions, like rendering, as a separate "task". This task will continue to run in the background, leaving the View free to respond to all user actions promptly. View Superbitmap Open superbitmap View, This means the window can be moved over a much larger "virtual" View using the scroll-bars at the bottom and right side. Objects can be created and modified, even rendered on any part of the superbitmap. View Borderless Open View covering the full screen. This has no visible borders and obscures the menu-strip. This window type is usually needed for rendering final images or animations where window borders are not desirable. View DBuffered Opens a double-buffered borderless View on a new screen. This enables wire-frame motion to be observed without seeing the intermediate drawing steps, so the image does not flicker. The new screen is always 4 color, 640 wide, maximum height and interlaced. This screen is a special private screen and no other windows can be opened on it. By default the View projection type is perspective. RPL Open RPL Shell window for programming RPL words. This is an OS Shell window with support for all the editing, text history and clipboard hot-keys (c and v). It has no menu strip associated with it. RPL window is designed for interactive use. Henceforth each RPL window has its own environment where all RPL definitions are private to the window in question and cannot be accessed by other windows unless parent/child relationship is established using inheritance. All defined words, variables etc. also disappear when the window is closed. When more permanent definitions are desired, the Master environment can be used for that purpose and, when necessary, RPL windows can inherit Master's RPL context by executing the command Master INHERIT RPL words, variables etc. can be defined to the master's RPL environment by loading them as macros, sending them through the ARexx port or defining them in the "rpl-startup" file. The Master RPL environment is allocated when REAL 3D is started and it is used for executing macros, ARexx commands and requester formula evaluation. Tool Open Tool window for loading with tool icons. There are a number of pre- defined tool icons in the REAL 3D system, and these provide single-click short-cuts to selecting the most frequently used creation and modification functions. The user can also create his own icons using Tool/Create Icon. These icons can invoke any executable RPL file or RPL word. The purpose of Tool window is to provide the user with ability to expand and customize the user interface of the program to suit different kinds of projects. Tool windows have no separate RPL environment, so in order to bind icons to RPL words, the word must be defined in Master's RPL environment. If the icon is bind to a file, the RPL file must be found from the macros directory specified in Settings/Paths. Animation Open Animation window on its own private Hires screen. The animation window is used for controlling the animation system, for defining animation settings such as the number of frames to be used for rendering an animation and the name of the result file. Figure @{"R1-4:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-4"} Animation Window (PICTURE: R1-4) Gadgets of Animation Window: Time The slider gadget and its associated numeric gadget provide the user with an interactive way of altering the global time. The affect of changing the time, with either the slider or by entering it numerically, depends on the state of the Play To/Jump To gadget. Play Controls These "video recorder" style controls have the following functions: |<... - Play backwards from current time to time 0.0 ..>| - Play forwards to time 1.0 |<- - Go to time 0.0 ->| - Go to time 1.0 <. - Single step one interval backwards .> - Single step one interval forwards CANCEL - Cancel all animation processing including rendering Play To/Jump To This gadget alters the way the Animation System reacts to changes to the time gadgets. If "Play To" is selected, then changing the time causes the animation to play from the current time to the new time. If "Jump To" is selected, then the display is just updated for the new time. Screens & Saved The list selector enables the one of the open REAL 3D screens to be selected for saving to an IFF file after each animation frame. The name can also be typed directly into the Saved text gadget. If an External screen has been opened, then it can be selected and will be saved using the file settings selected with Project/External_Screen/Settings. Resolution & Smpl (Samples) Resolution controls how many intervals time is divided into when it is evaluated from 0.0 to 1.0. Each step is evaluated internally with additional intervals set by Samples. Increasing Samples improves the quality of particle method evaluation. Samples is also used to determine the number of intervals over which to evaluate Motion Blur. Frame The current frame number. This value increase by one for every interval into which Time is divided by Resolution as the animation is saved. You can also use the gadget to move in time by entering the corresponding time value. Seconds The value in this field is only used by the Particle animation system to determine the amount of real time to evaluate particle movement properties over. This means that a particle with a velocity of 1.0 will travel 1.0 ASCs in 1.0 real time seconds; the evaluation of spin is treated in a similar way. Increasing "Seconds" increases the amount of motion for each particle during the whole animation. Format This is an index format string which is used to format the current Frame number before appending it to the end of Screen file text, Individual Views, which are also handles to files, use the formatted index for their file saving. Save If set, then the selected screen is saved to file and Frame is incremented, after rendering of the current frame is completed. Screen File The name and path for the screen image files saved by the Animation system. Frame Cmd This can contain RPL text which is interpreted by the "Master" RPL environment every time Frame is incremented. By using the RPL word "SYSTEM", commands can be passed to the CLI to control, for example, a single-frame video recorder system. Or alternatively, the frame command can for example convert IFF images the renderer produces to the JPEG format. Palette Open Palette window. This is opened on its own private HAM screen. The Palette is used to control the R,G,B values of the current color and the 16 register color values. The current color is used whenever REAL 3D requires a color value for a function e.g. Modify/Properties/Color. Figure @{"R1-5:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-5"} Palette Window (PICTURE: R1-15) The register colors give the user fast access to 16 different color definitions. Selecting one of the register color buttons makes the current color the same as the current value of the register color. The value of the register color is then changed using either the sliders or selecting from the color spectrum with the left mouse button. Holding the left button down while moving over the color spectrum changes the current color and the slider values continuously. There is no need to confirm these changes. The effects take place when the "OK" gadget is pressed. It is also necessary to select the settings required BEFORE using a function which uses the current color. If a Palette window is not currently open, then the last setting for the current color will be used. Measuring This opens the Measuring system window. The Measuring system can be used for replacing the mouse when accurate input is needed. It also allows the user to define coordinates using natural units, such as meters and feet, instead of just plain absolute space coordinates. Figure @{"R1-6:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-6"} Measuring Window (PICTURE) Measuring window gadgets: X, Y, Z These gadgets show the current position of the mouse in current units. The user can also enter coordinates through these gadgets, in which case the effect is the same as if the user moved the mouse to the corresponding point in View window. Formula evaluation is also supported, making it possible to enter formulas instead of coordinate values. The purpose of these gadgets depends on the measuring type used. If "Normal" method is used, these fields define 3D coordinate values relative to input-plane/absolute space and origin/hotpoint depending on the state of other gadgets on the window. If "Polar" is used, X and Y fields define the direction (horizontal and vertical angle) and Z field is used for distance. Polar coordinates can also be relative to hot-point/origin and input-plane/absolute space. The direction is always defined in degrees. N The purpose of this gadget varies from one function to another. It can be used for defining angles for sector primitives, depths for primitives etc. Absolute/I-plane (Input-plane) This radio button defines whether the coordinates are relative to the Input Plane or Absolute Space. Normal/Polar This radio button defines whether to use normal 3D coordinate system or polar (angle&radius) coordinates. Origin/Hot-point This radio button defines whether to use coordinates relative to origin of absolute space or to hot-point. Unit The cycle gadget defines the unit to be used. The absolute space units corresponds to meters. Possible choices are: Symbol Description Abs. Space Units m meters 1.0 mm millimeters 0.0001 cm centimeters 0.01 in inches 0.02548 ft feet 0.3048 Screen This opens a small window which enables control of the public screens used by REAL 3D. It is opened automatically when a new screen is created to provide a "handle" to the REAL 3D menus, until other windows have been opened. Gadgets of the screen window: Default Make active screen the default public screen. Jump Jump to next public screen. The control window will follow. Close Close all REAL 3D windows on the current screen then attempt to close the screen. If other windows prevent the closure, then a warning requester will be opened Hijack When enabled, windows and requesters opened for public screens will be hijacked and opened on the default public screen. This allows other applications which use public screens to be integrated into the REAL 3D system. One possibility for this is to integrate a text editor for creating and editing the text for RPL. Pop-to-front When windows and requesters are opened on the default public screen, it will be brought to the front. Close Close the currenCy selected window. Some windows, for example a borderless-View, do not have a close gadget. This function enables all windows to be closed. * No Gadgets This function removes all the gadgets for controlling the View window to leave a window with a narrow surrounding border. This window cannot be moved or re-sized until this function is selected again. Environment/ "Environment consists of the following data sections: - screens - windows (including Measuring system) - global settings: - frame buffer library name - save format for frame buffer (tga, iff, ...) - RPL initial configuration - current tool name for modify system - current register and RGB color - operation level - settings for modify subsystem - default directory paths for projects, objects, textures etc. - aspect ratio - hot-point - undo settings - load/save sections - sections - vector/float format strings - file name for current macro - minimum dragging time - default settings for fractal generators Open Screen Open new REAL 3D screen using Screen-settings requester. Make Def.Pub. Make currenCy selected screen the default public screen. Close Screen Close selected REAL 3D screen. Close Current Close any windows currently open on active screen and then attempt to close the screen. If other programs have opened windows on the REAL 3D screen, then the screen cannot be closed and the user will be warned. Insert Load a new environment definition from the file specified. This will create a set of windows and screens in addition to the existing ones. Save Save the complete environment definition to the file specified. Replace Delete existing environment definition before loading the specified environment file. Save Screen Open a File Requester and then save the active-screen as the specified IFF file. Screen Palette Figure @{"R1-7:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-7"} Screen Palette Requester (PICTURE: R1-7) Open a requester enabling the active screen colors to be changed. The screen register color to modify is selected from the color spectrum, then it can be adjusted using the RGB sliders. Two pre-defined palette definitions can be loaded by selecting either of the two button-gadgets. The "COLOR SCALE" definition is used with Render Settings/"Color Shading". Screen palettes are saved as part of the screens data section. External Screen/ These functions enable a library for controlling an External screen, like a frame buffer, to be used. Open Open an External screen with its specified External screen library. Close Close External screen and its library. Set Modes This function allows settings of an External screen to be modified. Not all libraries need this function, and so will not produce a requester. Settings Opens External screen requester allowing the user to select External screen library and file format. Figure @{"R1-8:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-8"} External Screen Settings Requester (PICTURE: R1-8) Gadgets of the External screen requester: Library Name of External screen library. IFF24 IFF 24 file format used. TARGA Targa file format used. TARGA+A- Targa file format with alpha-information used for saving. CUSTOM External screen's own format. Save Save image from External screen using format specified by settings. Exit Real Close all REAL 3D windows and screens and return to WB. If other programs have opened windows or requesters on any of REAL 3D's public screens, then the program will warn the user and leave the screens open. @endnode @node "R1.2" @title "Chapter 1 MENU FUNCTIONS" 1.2 CREATE Creating the various primitive and compound-objects is carried out by selecting the function and then supplying the appropriate data coordinates. This is usually carried out with the mouse. The defines the View in which the operation will be carried out, selects the first coordinate and starts the operation. It also defines consecutive coordinates. The completes a phase of the function. This may either move onto the next phase, complete the creation, or cancel the whole function. The first component of each primitive is ALWAYS created on the input plane. Those components with depth are then extruded perpendicular to the input plane. The direction of extrusion is determined using the Right Hand Rule. All 2D primitives, such as rectangle, circle and polygon, contain a small stick called as "dvect", which describes the volume defined by the primitive. This information is needed when object is used in Boolean operations. 2D primitives divide the space to two different parts and the dvect describes which side is the inside of the primitive. This means that REAL 3D can handle infinite solids and they don't have to be closed (some other solid modelling packages require that the solid must be closed, so it is not possible to get inside it without passing through surfaces used for defining it). Visibles/ This sub-menu contains all the creation functions for the basic visible primitives. Polygon PRIMITIVE: polygon Create polygonal plane. DEFINE: three or more points on a polygon. Terminating the function before creating 3rd point cancels the creation. Polyhedron PRIMITIVE: polyhedron Create polygonal prism. DEFINE: polygonal cross-section. The cross-section is extruded to defined depth. Polymid PRIMITIVE: polymid Create polygonal based pyramid. DEFINE: polygonal base and apex. Cut polymid PRIMITIVE: cut-polymid Create polygonal based pyramid with truncated apex. Figure @{"R1-9:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-9"} Polygon-based Visibles (PICTURE: R1-9) DEFINE: polygonal base, center of truncating surface and radial size of truncating surface. Figure @{"R1-10:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-10"} Rectangle-based Visibles (PICTURE: R1-10) Rectangle PRIMITIVE: rectangle Create rectangular plane. DEFINE: two coordinates of diagonally opposite corners of rectangle. Cube PRIMITIVE: cube Create rectangular prism. DEFINE: rectangular cross-section. The cross-section is defined as for rectangle. On completion, the rectangle is extruded to depth. Pyramid PRIMITIVE: pyramid Create rectangular based prism. DEFINE: rectangular base and apex. Cut pyramid PRIMITIVE: cut-pyramid Create rectangular based prism with truncated apex. DEFINE: two separate rectangles. The two rectangles form the two parallel surfaces with additional planes created automatically for the sides. Figure @{"R1-11:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-11"} Regular Polygon-based Visibles (PICTURE: R1-11) Reg.polygon PRIMITIVE: polygon Create regular polygonal plane. NUMERIC: number of sides of a regular polygon DEFINE: center and radial size. Reg.polyhedr. PRIMITIVE: polyhedron Create regular polygonal cross-section prism. NUMERIC: number of sides of a regular polygon DEFINE: center and radial size of polygonal cross-section, The polygonal cross-section is extruded to the defined depth. Reg.polymid PRIMITIVE: polymid Create regular polygonal based pyramid. NUMERIC: number of sides of a regular polygon DEFINE: center and radial size of regular polygon base and then apex. Reg.cut.plmd PRIMITIVE: cut-polymid Create regular polygonal cross-section prism. NUMERIC: number of sides of a regular polygon DEFINE: center and radial size of regular polygon base and then center and radial size of truncating surface. Circle PRIMITIVE: ellipse Create circular plane. DEFINE: center and radius. 3P Circle PRIMITIVE: ellipse Create circular plane. DEFINE: three points on the circumference of a circle to create a circular plane. Cylinder PRIMITIVE: cylinder Create cylindrical prism. DEFINE: circular cross-section to be extruded to defined depth. Cone PRIMITIVE: cone Create conical surface. DEFINE: circular base and apex. Cutcone. PRIMITIVE: cut-cone Create conical surface with truncated apex. DEFINE: circular base and center of truncating surface. Figure @{"R1-12:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-12"} Circle-based Visibles (PICTURE: R1-12) Figure @{"R1-13:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-13"} Ellipsoid Visibles (PICTURE: R1-13) Sphere PRIMITIVE: ellipsoid Create regular spherical surface. DEFINE: center and radius. Ellipsoid PRIMITIVE: ellipsoid Create ellipsoid surface with elliptical axes in two directions. DEFINE: center and then the size of the two axis of an ellipse. This ellipse defines the major circumference of the ellipsoid parallel to the input plane. The depth is pre-defined. Ellipsegment PRIMITIVE: ellipse-segment Create ellipsoid with two cutting planes equidistant from the defined circular circumference. DEFINE: center and size of a circle about the major axis of the ellipsoid parallel to the input plane. Then define center and size of the cutting planes. The depth is pre-defined. Cut ellipseg PRIMITIVE: ellipse-segment Create ellipsoid with two cutting planes, one positioned on the defined circumference. DEFINE: center and size of two circular planes. The larger one becomes the major circumference of the ellipsoid parallel to the input plane. Figure @{"R1-14:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-14"} Hyperboloid Visibles (PICTURE: R1-14) Hyperbol PRIMITIVE: hyperboloid Create hyperbolic surface with two cutting planes equidistant from a "waist". DEFINE: center and radius of two circular cross-sections. The larger of the two circular sections defines the 1 st & 2nd cutting planes and the smaller defines the waist. Cut hyperb. PRIMITIVE: hyperboloid Create hyperbolic surface with two cutting planes, one positioned at the "waist" of the surface. DEFINE: center and size of two circular cross-sections. The smaller one defines the circumference of the waist. Sectors/ The creation functions in this sub-menu enable various visibles to be constructed with cross-sections which are a sector of a circle. The first coordinate describes the center of the circular cross-section, then the start-point of the segment is defined by the next coordinate, finally the third coordinate defines the angle of the segment and the radius of the cross-section. Figure @{"R1-15:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-15"} Sector Visibles (PICTURE: R1-15) Circle PRIMITIVE: ellipse SECTOR Create sectored circular plane. DEFINE: sector cross-section only. Cylinder PRIMITIVE: cylinder SECTOR Create sectored cylinder. DEFINE: sector cross-section only. Cone PRIMITIVE: cone SECTOR Create sectored cone. DEFINE: cross-section and apex. Cut cone PRIMITIVE: cut-cone SECTOR Create sectored cone with truncated apex. DEFINE: cross-section then center and radial size of cross-section at the apex. Ellipsegment PRIMITIVE: ellipse-segment SECTOR Create sectored ellipsoid with equidistant cutting planes. DEFINE: cross-section then center and size of second cross-section. Larger will be circumference. Cut ellipseg. PRIMITIVE: ellipse-segment SECTOR Create sectored ellipsoid with cutting planes at circumference and end. DEFINE: cross-section then center and size of second cross-section. Larger cross- section will be the circumference. Hyperbol PRIMITIVE: hyperboloid SECTOR Create sectored hyperbolic surface with waist. DEFINE: cross-section then center and size of second cross-section. Smaller cross- section will be the waist. Cut hyperbol PRIMITIVE: hyperboloid SECTOR Create sectored hyperbolic surface truncated at waist. DEFINE: cross-section then center and size of second cross-section. Smaller cross- section will be the waist. Structure/ Level PRIMITIVE: level OR Create a structure which can be used to contain objects at a new level of the hierarchy. The arrangement of objects in levels is key feature used by many of the functions and systems of REAL 3D. Levels are used for defining a logical structure of the object and they can be compared to directories (Drawers) of Disk Operating Systems. +-------+ /| brace | / +-------+ +------+/ +--------+ | base |---| stand2 | /+------+\ +--------+ +-------+/ \ +--------+ +------+ /| table |\ +-------+ \| stand1 | | Root |/ +-------+ \| Cover | +--------+ +------+ +-------+ Figure @{"R1-16:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-16"} Hierarchy Levels (PICTURE: R1-16) Link PRIMITIVE: link This creates structures each of which references the selected objects. This "symbolic-link" can then be cut and pasted to another part of the hierarchy to provide access to the original object. A link can only be used to read the data from a target object. Modifications are not passed to the object through a link. The most common situation which requires the use of links is for using one object to define the parameters for several methods. They are also necessary sometimes when defining texture morphing using the MORPH methods. Links can also be used for jumping from one level to another by double clicking the desired link on Select window. If link points to a level object, that level becomes the current level. If it points to a primitive, probably nothing happens, because most primitives cannot be the current level, in other words, they cannot have sub-structure. Group PRIMITIVE: group Create a structure called a "group" which refers to the points on a freeform. Unlike links, groups can pass data in both directions. Hence modifying a group modifies the points on the original freeform. The points to form the group are taken from the vector-stack, so they must be selected from the freeform first by using or Lasso selector. If several objects are selected, then a new level will be created containing all the new groups. Groups are usually created inside the freeform they refer to, so unexpected cumulative modification results are avoided (same points are modified first through freeform itself and again through groups referring to freeform). HOT-KEYS: There are also two hot-key combinations: and which will automatically create a group with the name "group tmp", or a level with the name "level tmp". When is used, then only points from the selected freeforms are used. Method PRIMITIVE: level OR SMTH Creates a new level and opens the animation-properties requester to allow a method typed to be selected. This will then be assigned to the new level, which becomes the current-level to allow the parameters for the method to be defined easily. Note: That the same result can be achieved by creating a level object using the function Create/Structure/Level, and changing the method type using the function Modify/Properties/Animation. Methods are "intelligent objects used for creating animations. In other words, method objects cause target objects to be animated according to parameter objects placed under them. Light-sources/ Point PRIMITIVE: offset LIGHT-SOURCE Create point light source. DEFINE: single coordinate. This is rendered as a single infinite point of light. Because the point light has no dimension, it can produce only sharp edged shadows. In real world the intensity is inversely proportional to square of distance, but in REAL 3D, a formula which produces less radical result is used and intensity drops only inversely proportionally to distance. DIFFUSE LIGHT SOURCES These use Render-Settings/"Lightsamples" to determine the quality of the soft-shadow they cast. The higher the Render settings/Lightsamples, the better the quality of shadows generated. If Lightsamples is zero, the light source is treated as a point light. Intensity is dropped the same way as the Point light. Line PRIMITIVE: line LIGHT-SOURCE Creates a diffuse linear light source. DEFINE: two points of a line. This casts soft-shadows from a linear source the length of the line created. Wall PRIMITIVE: rectangle LIGHT-SOURCE Creates a diffuse rectangular light-source. DEFINE: rectangular plane. The soft-shadows are cast from an area light- source the size of the rectangle created. Controls/ The objects created in this menu do not appear when a scene is rendered. They are used to create other objects or control various aspects of functions and methods. The wire-frames for all controls are drawn with a broken line of long dashes by default. Attribute PRIMITIVE: attribute This creates an attribute primitive. It does not require any spatial coordinates, so no pointer input is required. This primitive can, for example, be used as a parameter for methods when object attributes, such as motion blur must be animated. Offset PRIMITIVE: offset Create a primitive for the specified coordinate. Offsets are most commonly used with animation Methods to define centers of rotations etc. DEFINE: coordinate. Axis PRIMITIVE: line Create a line with two points. DEFINE: start and end coordinates of axis. Axes can be used, for example, as parameters for animation methods for defining rotations and straight motions. Coordsys PRIMITIVE: coordsys Create a set of x,y,z axes. DEFINE: origin and size. Coordsys primitive is used as a parameter to animation Methods. It is also very handy for defining the orientation of input plane of View windows. Figure @{"R1-17:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-17"} Lines and Curves (PICTURE: R1-17) Open Line PRIMITIVE: line "polygon" Create one or more linked lines. DEFINE: start coordinate and at least one other coordinate. Multiple points on the line are defined by supplying multiple coordinates. The function is terminated with . The line can be closed/opened with key. In animations, polygonal lines can be used for producing "sharp edged" motions. For example, mechanical devices often require motions which are not smoothly curved. When used as a parameter for freeform surface construction tools, polygonal lines produce polygonal surfaces. Closed Line PRIMITIVE: line "polygon" Create three or more lines linked as a polygonal loop. DEFINE: start coordinate and at least two other coordinates. The function is terminated with . The curve can be opened/closed using key. Circular Line PRIMITIVE: line "polygon" Create three or more lines linked as a regular polygonal loop. NUMERIC: Number of sides to regular polygon. DEFINE: center and radial size. B-Spline Ctrlp PRIMITIVE: line "B-spline" Create B-spline by defining control-polygon. DEFINE: at least 4 coordinates of points on open ended control-polygon of B-spline. This is one of the basic tools when creating B-spline curves. It allows the user to define a control polygon which defines the actual smooth B-spline curve of third degree. The curve tends to automatically be very smooth when using this curve definition method, but the fact that the curve itself is dislocated from the control points makes it tricky to use for the novice user. B-spline curves can be used for defining smooth motions for animation methods, and as parameters for B-spline freeform surface construction tools. B-Spline Knot PRIMITIVE: line "B-spline" Create B-spline by defining knot-points. DEFINE: 2 or more coordinates of knot-points on B-spline. Figure @{"R1-18:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-18"} A B-spline Curve Produced from Knot Points (PICTURE: R1-18) This tool allows the user to define a B-spline curve by defining the curve's knot points. Because the curve passes through knot points, the user has more accurate control over the curve. However , the curve may not always interpolate knot points in expected way. B-Spline Curve PRIMITIVE: line "B-spline" Create B-spline by defining control-polygon. End points are fixed with triple-points and curve is drawn interactively. DEFINE: start-point coordinate, then consecutive points on the control- polygon. As the cursor is moved, the resultant B-spline curve is drawn. When terminated, the last coordinate supplied becomes a fixed end-point. The start and end points of the B-spline polygon are fixed by defining three points on the control-polygon at the same coordinates (triple- point). B-Spline Closed PRIMITIVE: line "B-spline" Create B-spline by defining closed control-polygon. DEFINE: four or more points of a polygon with closed ends. B-Spline Cir. PRIMITIVE: line "B-spline" Create circular B-spline by defining closed regular polygon. NUMERIC: sides of regular polygon. Entry must be 4 or greater. DEFINE: center and radial size. B-Spline Helix PRIMITIVE: line "B-spline" Create helical B-spline. NUMERIC: number of points on control-polygon and total angular distance of helix in radians. DEFINE: center and radial size. Mappings/ All the objects created in this sub-menu have a material definition attached to them when created. They define the type of mapping used to apply the material properties to the physical objects in the hierarchy. The type of the mapping primitive defines how the absolute space, where objects are defined, is mapped to material space where material properties are defined. For example, when using rectangle primitive, the absolute space is mapped to material space using parallel projection which is fully defined by the size and the orientation of the rectangle used. See also Material window/Mapping handler description. The material to be mapped to absolute space is referred by a tag "SMAT". The wire-frames for all mapping objects are drawn with a broken line of short dashes. Default PRIMITIVE: attribute MAPPING Creates attribute with attached material properties. This enables material properties not requiring any special mapping to be placed in the hierarchy. This saves on memory and avoids cluttering the screen with unnecessary wire-frames. No transformations are applied between material/absolute spaces (in other words, the space where materials and objects are defined is the same). When using textures with this mapping, parallel projection along z-axis is used. Parallel PRIMITIVE: rectangle MAPPING Create rectangular mapping. The basic mapping type of the attached material properties will be parallel. The size and position of the rectangle determines how material space is moved, rotated and stretched to absolute space where objects are defined. Cylinder PRIMITIVE: cylinder MAPPING Create cylindrical mapping. DEFINE: center and radial size of circular cross-section. Depth is pre- defined. This mapping method can be used for wrapping textures cylindrically around objects. The axis of the cylinder corresponds the vertical direction of the texture. The horizontal direction is bent along the cross-section circle. Sphere PRIMITIVE: ellipsoid MAPPING Creates spherical texture. DEFINE: center and radial size. Disk PRIMITIVE: ellipse MAPPING Creates circular texture. DEFINE: center and radial size. Observers/ Viewpoint PRIMITIVE: viewpoint Create a viewpoint. DEFINE: two coordinates defining the centers of stereo viewpoint pair. Viewpoint can be used for defining orientation for View windows. If the menu View/Camera/Camera_View is checked, the orientation for the corresponding View window is fetched from the viewpoint object, if found. If the object contains more than one viewpoint, the first one found is used, unless the viewpoint contains a tag SWND, in which case it is used only if the contents of the tag matches the name of the View window in question. This makes it possible to associate different viewpoints with different View windows. Because viewpoint is just a primitive, it can be animated like any other object. It is possible to create animations where the screen contains more than one View window and where each View window shows the animation from different point of view. The viewpoint primitive can be used with the aimpoint primitive for fully define the orientation for the camera. In other words, camera consists of a viewpoint and an aimpoint. Aimpoint PRIMITIVE: aimpoint Create an aimpoint. DEFINE: center. The aimpoint primitive can be used for defining camera direction. The reason why the camera is divided into two different part is that it makes it possible to insert aimpoint to any object, and if the object is animated, the camera always tracks it. This is true for viewpoint too. Of course, it is possible to place both primitives inside one level object, in which case, it can be treated just like a single camera. The tag SWND can be associated with aimpoints as well. Compound Tools/ The functions in this section all create multiple visibles all placed within a new level. All the necessary boolean-operations and other modifications are carried out on the original visibles to create the expected composite visible shape. Lathe Create compound-object from various visibles by defining an axis and a profile. DEFINE: two end points of axis. Then define a sequence of "curve" directions and shapes to create the profile. A new direction for the profile curve is started by cancelling the curve shaping with the . This makes it possible to create sharp joints between object segments. The function is terminated by using the twice. Circular Subdivided Create compound-object from cylinders along subdivided line. The polygonal line is subdivided using quadric Bezier curves. NUMERIC: subdivisions per line segment. DEFINE: circular cross-section, open polygonal line. Rounded Circ. Subd. Create compound-object from cylinders along subdivided line with spheres at junctions. NUMERIC: subdivisions per line segment. DEFINE: circular cross-section, open polygonal line. Sharp Circular Create compound-object from cylinders along line. DEFINE: circular cross-section, open polygonal line. Rounded Circular Create compound-object from cylinders along line, with spheres at junctions. DEFINE: circular cross-section, open polygonal line. Conical Create compound-object by joining defined spheres with cones. DEFINE: two or more spheres. Conical Subdivided Create compound-object by joining defined spheres with cones, subdividing between sphere centers. Position and radius for intermediate spheres is interpolated using quadric Bezier curves. NUMERIC: subdivisions between centers of spheres. DEFINE: two or more spheres. Rectangular Create compound-object from rectangular prisms along line, with cylinders at junctions. DEFINE: circular cross-section, open polygonal line. Rectangular Subdiv. Create compound-object from rectangular prisms along subdivided line, with cylinders at junctions. NUMERIC: subdivisions per line segment. DEFINE: circular cross-section, open polygonal line. Rectangular Conical Create compound-object by joining defined cylinders with rectangular based pyramids. DEFINE: two or more cylinders. Rect.Conical Subd. Create compound-object by joining defined cylinders with pyramids, subdividing between cylinder centers. NUMERIC: subdivisions between centers of cylinders. DEFINE: two or more cylinders. Rounded Polygon Creates a compound plane from a polygon and circle segments. DEFINE: polygon. The created compound plane is bounded by this polygon. A polygon is created which forms the outer controlling boundary polygonal plane whose "corners" are rounded with segments from circular planes. While this bounding polygon is being defined, the resultant polygon and circle segments which will compose the final plane are shown. The following key bindings are defined during creation: TICK - define new radius for the current corner. BACKSPACE - define new radius for arbitrary corner. - new radius for all corners. Rounded Polyhedron Create a compound solid from polyhedron and cylinder segments. DEFINE: bounding polygon. The bounding polygon defines the rounded polygonal cross-section which is extruded to a defined depth to form a solid. The level created contains a polyhedron and the cylindrical segments of the compound solid. Hot keys are similar to Rounded polygon tool. Ellipsed Polygon Create a round edged compound plane from a polygon and ellipse segments. DEFINE: bounding polygon. The level created contains a polygon visible and several ellipse segments which boarder all the edges of the polygon. This forms a compound plane with continuous curved edges. Ellipsed Polyhedron Create a round edged compound solid from a polyhedron and cylinder segments. DEFINE: bounding polygon. A polyhedron and the cylindrical segments which border its edges are created. This is the extruded solid of the ellipsed polygon defined by the bounding polygon. Join Primitives This creates a set of cut-cones or cut-pyramids to join multi-selected spheres or cylinders together. Only the new visibles form the compound- object; the original visibles remain at their original level. If non- spherical ellipsoids or cylinders of dissimilar depth are used, then the cut-cones or cutpyramids will use the minimum dimensions of the operands as a default. Using any visible other than ellipsoids or cylinders will be ignored by this function. Object-Pixel Tool Create multiple copies of selected objects using pixels from image file. SELECT: image file DEFINE: rectangle. The compound-object is created from multiple copies of the selected objects. The offsets for each of these new objects is taken by mapping the image file onto the rectangle and taking the coordinates of each active pixel. Their color is taken from the pixel color. For register color IFF files pixels of register color 0 do not create objects. With 24-bit image files all pixels create objects. Freeform/ The free-form construction functions take two or more lines selected as operands by multi-selection. These operands are used to produce a mesh. If all operands are of one type, then the resultant mesh will be of the same type. With mixed types of operands, then the mesh will be polygonal by default. If B-spline operands are used, then there must be four or more to produce a B-spline mesh. Note that when creating B-Spline surfaces, a large amount of points are not needed for making objects "smooth", which is the case when creating objects using polygonal models. Instead, points are needed for representing details. Mesh PRIMITIVE: mesh Create rectangular mesh of B-spline curves. NUMERIC: the number subdivisions of each axis of the mesh. DEFINE: size of the mesh as a rectangle. Coplanar PRIMITIVE: mesh Create a mesh from a profile displaced along a sweeping curve. OPERANDS: 1st - profile 2nd - sweeping-curve The profile is displaced along the sweeping curve and replicated at each point of the sweeping curve. The resultant profiles are joined consecutively into a mesh. The profile curves of the mesh remain parallel to the original profile operand. The displacement is relative, in other words the profile curve is not pulled to the beginning of the sweeping curve. Figure @{"R1-19:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-19"} Coplanar Sweeping (PICTURE: R1-19) Orthogonal PRIMITIVE: mesh Create a mesh from a profile displaced along a sweeping curve. OPERANDS: 1st - profile 2nd - sweeping-curve The profile is rotated to follow the direction of the sweeping-curve while being displaced. At each point of the sweeping curve, the profile is replicated. These profiles are joined to form the mesh. Figure @{"R1-20:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-20"} Orthogonal Sweeping (PICTURE: R1-20) Rotate PRIMITIVE: mesh Create a mesh by rotating a profile about an axis. OPERANDS: 1st - profile 2nd - axis of rotation NUMERIC: number of subdivisions during rotation. The new mesh is created by rotating the profile about the axis and creating a new profile for each subdivision specified. The profiles are linked into a mesh. Swing/Move PRIMITIVE: mesh Create a mesh by rotating a profile about an axis and displacing it using a third curve. OPERANDS: 1st - profile 2nd - axis of rotation 3rd - displacement-curve The profile is copied once for each point on the displacement-curve. Each copy is rotated about the axis by the angle between the original profile and a line through the axis, and the corresponding point on the displacement-curve. Each copy is also displaced by the relative distance between the axis and original profile, and the axis and the corresponding point. Swing/Size PRIMITIVE: mesh Create a mesh from a profile, an axis and a sizing curve. OPERANDS: 1st - profile 2nd - axis of rotation 3rd - sizing-curve The profile is copied once for each point on the sizing-curve. Each copy is rotated about the axis by the angle between the original profile and a line through the axis, and the corresponding point on the sizing-curve. Each copy is also scaled by the relative distance between the axis and the original profile, and the axis and the corresponding point. Figure @{"R1-21:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-21"} Swing/Size (PICTURE: R1-21) Build from Curves PRIMITIVE: mesh Multi-select a number of curves to be built into a mesh. The order of selecting the curves determines the order in which the curves are assembled. By default, the surface is not closed in "joining" direction, The function Modify/Freeform/Open&Close can be used for closing the surface in the ("v") direction. Figure @{"R1-22:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-22"} Build_From_Curves (PICTURE: R1-22) Mesh-Pixel Tool PRIMITIVE: mesh create a mesh using image file. FILE: name of image file. DEFINE: rectangle. The image file will be scaled to the rectangle. A mesh will be constructed with a point for each pixel of the image file. The height of each point above the base level is relative to the intensity of the corresponding pixel. Fractals/ Landscape Figure @{"R1-23:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-23"} Fractal Landscape Generator (PICTURE: R1-23) Create a mesh representing a fractal "landscape". REQUESTER: fractal generator information DEFINE: rectangle. Gadgets : u Direction, v Direction These fields define the resolution for the final landscape mesh. In order to get the best possible result, the value of these fields should be 2^n+1, where "n" is integer. Depth This defines the relative depth of the landscape to be created. The higher the value, the higher the profile. Random Defines how random the result is. The higher the value, the greater the randomness. Figure @{"R1-24:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-24"} Fractal Tree Generator (PICTURE: R1-24) Power Defines the shape. If the value is large, mountain peaks are sharp and valleys are flat. If small, then mountain peaks are flat and valleys deep. Seed Seed value for random factor. Using identical seeds allows identical landscapes to be created. Tree Create a fractal "tree" from spheres and cut-cones and optionally a selected object. REQUESTER: fractal generator information DEFINE: sphere for position and size of first "node", then two coordinates to define direction of growth and length of the first branches. If an object is selected, then this will be used as the "leaves" at the ends of the last branches. The basic idea for controlling all the properties of a tree is relatively simple. There are some initial settings, like depth and branch count which have several modifiers applied, like random and depth modifier, in order to get the final value for a particular property of the tree. For example, the following diagram shows how the number of sub-branches is defined for each node: Initial - This is an initial value defined by "Branch Init" | field in the Fractal tree requester. | \/ Random - Initial value is passed to random modifier, which uses the | value of the gadget "Branches_Rand" to define how much to | randomize the initial value. | \/ Depth - Depth modifier changes the value according to the value of | "Branch Depth" The lower the level of the node, the higher | the number of sub-branches. | \/ Branch - Branch modifier modifies the passed value according to the | branch in question. This makes it possible to define fewer | sub branches for outer parts of the tree. | \/ Actual - The actual number of sub branches for the node in question. level 2 \/\/\/\/ level 1 \/ \/ \ / level 0 \/ The depth of this tree is 3 and branch count is 2. Depth Fields: There are three fields used for defining the depth of each branch. The depth of a branch dictates how many times it can branch again. Init This value defines an initial depth for all branch instances in a tree. Rand Defines a random scale used for modifying initial depth value. If a value of this gadget is 0, the depth is not affected randomly. If 100, the depth of a tree can vary +/- 0.5 *depth. Branch Defines how the branch in question affects the depth, i.e. how the tree to be created is balanced. If zero, then either the central or first branch of each node has the greatest depth. If 50, all branches are treated equally and if 100, the outer or last branches of each node has the greatest depth. Branch Fields: These fields define how the number of branches is defined. This information is evaluated individually for each branch of a tree. Init This field defines the initial number of branches per node. Rand This defines how randomness affects the initial number of branches. The new branch count can vary up to +/- 0.5*initial_count. Depth This field defines how the level of the node in question determines the number of sub-branches to be created. If 0, it has no affect at all. If 100, the number of branches is reduced from level to level using the following formula: level/(level + 1)^2*f/100*count, Where: f is the value of this gadget. Thus, if level is 0, or the factor "f" is zero, the level of the node has no effect over the number of sub-branches. In other words, the higher the level, the fewer the number of branches. O O \ / Level 1: 2 sub branches O | O | O \|/ Level 0: 3 sub branches O Branch Define how the branch in question determines the number of sub-branches to be created. If 50, the tree is balanced (each branch will contain equal number of sub-branches). If 0, the central or first branch of each node has the highest number of sub-branches. Size fields: These fields define how the size of the node is defined. Depth Initial sizing factor. Defines how the size of each node is reduced for each new level. A value of 10 means the size for new nodes in the next level will be 10% of the size of the nodes in the current level. Rand Random factor. If zero, then there is no randomness. If 100, size can vary +/- size/2. Branch Define how the branch in question modifies the size of the node to be created. This field can be used for creating trees with inner or first nodes thicker than outer or last nodes. Length Fields: Depth Defines how the length of branches is reduced from level to level. Rand Random factor for length. Branch How the branch in question affects the length of the branch. Direction Fields: Direct Hor, Vert, Norm These fields define the directions for branches to be created. The direction for a new branch is calculated by using vector addition, where the three vectors are Norm, Hor and Vert. Norm is the direction of the current branch and Hor and Vert are perpendicular to this. The mathematical formula for this vector addition is: newdir = norm*current_dir+hor*sin(x)+vert*cos(x), Where: Norm, Hor and Vert are the values of the corresponding gadgets on the requester, and x is value representing the direction of the current branch. Rand Define random factor for the length of the H or, Vert and Norm vectors. Gravity Define how much "gravity" pulls down the branches for each new level. If 0, gravity is zero too. If 1 00, gravity pulls down the branches by the length of the first branch. Rotate Fields: These fields define how much branches are rotated for each new level. Level The maximum rotation is half a revolution. Random Random factor for rotation. Other Gadgets: Subdivision This field defines how many spheres and cut-cones are used for creating branches. If 1, all nodes are connected using one cut-cone. The higher the value, the smoother the the result. Branches are smoothed using a cubical B-spline curve. Branch Color Define the color for all visibles forming the body of the tree created. The contents of this string are passed to EVAL to define the color for the spheres and cut-cones of the tree. The following variables are defined during evaluation: R, G, B - Color for the object to be created. x, y, z - COG of the object to be created I - Hierarchy level (the level of the root is 0) b - Number of the branch in question. The range is 0.0 to 1.0, where the first branch in a node is 0.0 and the last is 1.0. If used, then the central branch will be -1.0 s - Subdivision index for branches. If subdivision is 1, all branches consists of only one cut-cone and the value of "s" is constant (1 ). If subdivision is 1 0, each cut-cone has a separate index, where the index for last cut-cone created for the branch in question is 10. If this gadget is empty, current color is used. Leaf Color This string is passed to EVAL in order to define a color for the leaves. If this gadget is empty, the original colors of leaf objects are used instead. R, G, B - Color for the leaf to be created. x, y, z - COG of the object to be created I - Hierarchy level (the level of the root is 0) b - Number of branch to which the leaf is attached. If this string is empty, the color of the selected objects is used. Example Formula: R=127+128*sin(b), G=127+128*cos(b), B=127+128*cos(b) Note: For both these color evaluations, the only variables which affect the visibles in question are R, G, & B. Although the other variables can be assigned new values, this only affects their use in the expressions. It does not modify the visibles. Central If set, then the various "Branch" gadgets work with the "central" branch of a node e.g. 3rd branch of a group of 5. Otherwise, they work with the first branch. Trunk If set, then a main trunk will be created and the first node will be at the top to form a "tree", otherwise it will be a "bush". Boolean/ OR AND AND NOT AND with PAINT AND NOT with PAINT Figure @{"R1-25:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-26"} R1-25: Boolean Operations (PICTURE: R1-25) These all work by creating a new object from the selected objects. At least one object must be selected using multi-selection. The first object selected is used as the target, and the rest of the selection are used as the operands. The target and operands are copied to a new level which has its AND attribute set. For AND NOT, the operands each have their INVERTED attribute set. The operands of AND with PAINT have PAINTS set, and AND NOT with PAINT sets both these attributes for the operand objects. Rethink When applied to selected booleans, this function re-calculates the wire- frame to more closely resemble the surface of the objects produced as a result of the boolean-operator. Rethink All This function also produces new wire-frame for booleans. It also scans through sub-objects of the selected-objects, and re-calculates the wire- frames for all booleans. Figure @{"R1-26:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-26"} Rethinking Boolean Wire-frame (PICTURE: R1-26) @endnode @node "R1.3" @title "Chapter 1 MENU FUNCTIONS" 1.3 MODIFY Linear/ All these functions are started and completed with or terminated with . Move DEFINE: handle coordinate, then new position A reference coordinate is defined, then the selected objects can be moved by this "handle" to a new position. Move COG DEFINE: new position for COGs When all the selected objects have their Center-off- Gravity (COG) moved to the cursor position after the first click, a new position for the COGs is then selected. If objects are multi-selected, then all their COGs are moved to the same coordinate and this causes them to overlap. If a level containing sub-objects is selected, then their COG's are averaged to find the COG of the whole group. Size 2D DEFINE: sizing-center, sizing handle then new size A center about which the sizing of the selected objects will take place is first specified, and then a reference coordinate or "handle". As the cursor is moved relative to the sizing center, the objects are re-scaled in proportion to the distance between the center and the handle, and the current cursor position and the center. The re-scaling only takes place about the coordinates axes of the Input-plane. Size 3D DEFINE: sizing-center, sizing handle then new size This works in an identical way to Size-2D, only the re-scaling is applied to all three coordinate axes of the objects. Stretch DEFINE: sizing-center, sizing handle then new sizes This works in a similar way to Size _2D, only the re-scaling parameters are evaluated independently for each of the two Inputplane axes before being applied to the objects. Extend DEFINE: extension-center and direction, then extension amount The fixed center of the extension is defined first, then the direction in which the extension of the objects is to take place. Moving the cursor relative to the fixed point determines the degree of extension. Rotate DEFINE: rotation-center and handle, then amount of rotation The center about which the objects are to be rotated is first specified, then a reference point. Moving the cursor about the rotation-center controls the amount of rotation applied to the target objects. Mirror DEFINE: fixed-point and end-point on mirroring axis, then final position of axis end point. The axis about which the objects is to be mirrored is defined in two stages. First define the fixedpoint and endpoint of the axis. The axis can then be rotated about the fixed-point until the final position is selected. Shear DEFINE: two points on shearing-axis, handle, and then degree and direction of shear. The shearing-axis determines the direction along which the shearing modification will be applied. Then select a handle coordinate. Moving the cursor relative to this coordinate defines the direction and amount of shearing to be applied to the selected objects. Rot&Ext DEFINE: rotation-center with extension fixed-point, rotation handle with extension-direction and then amount of rotation and extension to be applied. This is a combination of the rotation and extension modification functions. The first coordinate defined is used as both the center for the rotation function and the fixedpoint for the extension. The second coordinate defines the rotation handle and the direction for the extension. Moving the cursor allows the amount of each modification to be applied to the objects to be determined. Deform DEFINE: fixed-point, deformation-direction and then degree of deformation. This function works in a similar way to extend. The extension of the objects dimensions along the deformation-direction is matched by the inverse amount of extension to the objects dimensions perpendicular to this. Structure/ Cut Remove selected objects from hierarchy and place in clip-buffer. Copy Copy selected objects to clip-buffer. Paste The contents of the clip-buffer are pasted to the bottom of the current level. Delete Delete selected objects from hierarchy. This does not alter the clip- buffer. Duplicate Copy selected objects and paste to hierarchy. The copy is left in the clip-buffer. Swap Cut currently selected objects, reverse the order in which they were selected, and paste them back to the corresponding locations in the hierarchy. This function does not use nor affect the clip buffer in any way. PrOperties/ Color The color of the selected objects becomes the RGB values of the current- color. If the key is held down when this function is activated, the modal color requester is opened and the color of the first selected object is shown. Name A text requester carrying the name of the first selected object is opened. The name can then be edited. The maximum length for an object name is 16 characters. All multi-selected objects are renamed to the specified name. Attributes Open Attributes requester to modify the attributes of selected objects. Multi-selecting objects displays the attribute settings for the first object; confirming changes with OK changes the attributes of ALL multi- selected objects to the chosen settings. Gadgets of Attributes Requester: AND/OR These control whether a boolean AND or a boolean OR operation is to be used for this object. This means that all objects inside a level have this boolean operator applied. Inverted If set, then everything outside of the volume of the objects is used for boolean operations. Paints The surface properties of the objects are applied to intersecting surfaces in boolean operations when this attribute is set. WF-Invisible Objects wire-frames are invisible if set. RT-Invisible If set, then the object will not visible when rendered. Mapping Setting this allows any primitive to be used as a texture. This means that sector-visibles can be used as textures, but only rectangles, ellipsoids, cylinders and circles will have their geometry projected appropriately. If this flag is set for a level or a link, then the Rendering Engine will scan the object for mappings. Protected When set, the object is not affected by ANY modifications other than direct hierarchy modifications such as Cut and Delete. Motion-Blur Setting this attribute means that Motion Blur will be evaluated for this object during rendering, provided that Animation Settings/"Samples" is set greater than 0. Light-source When set, an object is a light. An offset becomes a light-point, an axis (two point line) becomes a light-line and a rectangle a light-wall). All other primitives are treated as lightpoints with their COG as the source. Hollow Objects will be hollow if set. No 1st BP Visible surface of 1 st bounding-plane is removed if set. No 2nd BP Visible surface of 2nd bounding-plane is removed if set. Infinite Actual bounding planes are removed if set. Scene If set, then objects only visible via reflection or refraction. Not Reflected The objects will reflect but not be reflected if this attribute set. Matte The objects will always return the background color. This effectively means they mask any objects behind them as though they were behind part of the background. Cast Shadows This attribute allows specific visibles and lights to be removed from shadow calculations. It is set by default, but if un-set, then affected lights will not cast shadows from any visibles, and any visibles affected by this attribute will not cast shadows from any lights. Alpha Channel Open a modal requester allowing user to define new value for Alpha channel property for selected objects. The Alpha channel of the first selected object is shown when the requester is opened. Tags This enables tags to be added or modified for selected objects in sequence using the Tag-requester. In REAL 3D, tags are used for expanding object and material data structures which may be necessary e.g. when creating user defined methods or procedural materials. Tag requester shows a list of the tags defined for the current object. Selecting from this list makes the Tag available in the edit box. Either the Tag-ID or its Tag-Values can be edited. Pressing updates the list. Gadgets of the Tag Requester: DEL Deletes the current tag from the list. ADD If the edit box is shaded, then this gadget makes it possible to enter text for a new gadget. When text has been entered, using this gadget adds the text to the list. The Tag ID will be checked to see if its first character is a valid type. Valid Tag Types: C, D, F, I, M, S & V Any Tag-Values follow the Tag ID and are separated from it and each other by . The length of a Tag ID is restricted to four characters, the first of which must be a valid type. Animation The animation properties of the selected objects can be changed with the Animation Properties Requester. Figure @{"R1-27:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-27"} Animation Properties Requester (PICTURE: R1-27) This has five numeric gadgets to define Start Time, End Time, Phase, Frequency and Method Time. For a method to function correctly, Start Time cannot be after End Time, but Phase can be any Time value and Frequency any positive value. "Time" defines the local Method Time for a method in its current state. Confirming new settings updates the VTIS, VTIE, VPHS and VFRQ tags. Start Time This defines the time before which the method will be inactive. End Time This defines the time after which the method will be inactive. The method will carry out the whole of its evaluation during the period from Start Time to End Time. Method Action ^ 1.0 I | ____> | / | / | / | / |____/ | 0.0 + +--------------> Time ^ ^ | | VTIS | VTIE Phase This controls the "phase relationship" between the method and parent time. In effect, it is an offset, so instead of starting from Method-Time = 0.0, it will start from the value specified by "Phase". Frequency This acts as a multiplier applied to the time passed to the method via the animation message. Increasing or decreasing Frequency increases or decreases the rate at which method carries out its actions. If it is decreased. so the resulting method time is less than 1.0, then the method will only carry out the specified fraction of its actions. Method Time The current local method time. This requester also contains a list selector to allow the method type to be attached to the selected objects. Internally, this defines the SMTH tag. If the method type is "NONE", then although the tags for the Time properties will be created or modified, this will not affect how the Animation System evaluates the objects. Animation Method Types: NONE COLLISION CONTROL CURVES CREATION DIRECTED FORCE DIRECTION FRICTION INT COLLISION INV KINEMATIC MORPHING CLOSED MORPHING OPEN MOVE & DIR PATH PROCESSOR RADIAL FORCE ROTATION RPL SIMPLE SKELETON SIZE SKELETON STRETCH SWEEP TANGENT FORCE TRANSFORM WAVE The method type is used to specify how an object is evaluated by the Animation system. Each method requires a certain hierarchical syntax in order for it to be valid. The syntax for each method is described in detail in the reference chapter 2. Replace Tags Allows the tags of selected objects to be modified collectively. The tag to be modified is selected using the requester. The Tag ID and Tag values can then be edited. All tags with identical Tag ID and Tag Value are replaced with the edited values. e.g. Material references "SMAT wood" can be changed to "SMAT marble" The following properties are evaluated by certain methods for particle animation. Some of them define new tags which override default object properties. COG DEFINE: coordinate for new COG TAG: MCOG The COGs of the selected objects are changed to the the defined coordinate. The COG is the reference point used by the Modify/Linear/Move COG function. Also Skeletonal control, particle system, Modify/About_COGs/ xxx and Modify/COGs/xxx functions use this attribute. Direction DEFINE: coordsys TAG: DDIR DDIV This changes the direction for the selected objects to those of the defined coordsys. Direction is needed for: - skeleton methods - spin becomes fully defined only when associated with direction - when using the function Obj. Space to View Velocity DEFINE: axis TAG: VVEL The new velocity of the objects are defined by the direction and length of the defined axis. Velocity means how much object is moved in one second. Velocity is used by particle system oriented methods. Spin NUMERIC: three values in radians TAG: VSPI The spin (angular velocity) of the objects are given the values specified by the user. Spin defines how fast the object is rotating. The first value defines how fast the object is rotating around VHOR axis, second around VVER and third defines the spin around the vector perpendicular to VHOR and VVER. Size NUMERIC: scalar value in Absolute-Spatial-Coordinates TAG: FSIZ The default size for the objects is redefined. This is the size value used by COLLISION, INT COLLISION and FRICTION methods. For example, the collision detection system uses the size for detecting if the collision between objects is possible or not. Bend Local/ Move_2D Move_3D Move_Radial Size_2D Size_3D Size_Radial Bend Global/ Move_2D Move_3D Move_Radial Size_2D Size_3D Size_Radial Bend Endp./ Move_2D Move_3D Move_Radial Size_2D Size_3D Size_Radial Bend Linear/ Move_2D Move_3D Move_Radial Size_2D Size_3D Size_Radial All the free form bending functions work in similar ways. They are normally used for modifying free forms. If other than free forms are modified, only COGs are affected. A bending axis is defined with two points, then a handle coordinate is defined. After the degree of effect has been decided, the function is completed. The bending function effect, defined below, determines how the bending axis is used to determine the effect interval. This selects which points of the freeforms will be affected. The effect interval is the volume bounded by two planes at each end of the bending axis and orthogonal to the axis. Bending Function Effects: Local Only those points within the interval are affected. Global All points are affected. Those within the interval are affected with the direction of transformation, those outside in the opposite direction. End_Point All the points from the plane through the first end point and beyond are affected. The degree of effect increases progressively away from this first plane. Linear All points are affected with linear shear-like functions. The bending axis determines the direction perpendicular to the effect. The actual function type determines how the selected points are transformed. Move_2D The displacement of the points is independent of the distance from the point to the bending axis and its position in the bending interval. Move_3D Although the displacement is independent of the distance from the point to the bending axis, the depth of the point within the bending interval is treated in the same way as its distance along the bending axis. Move_Radial The displacement is independent of the distance to the bending axis but increases radially away from the axis. Size_2D The displacement increases the further the point is from the bending axis but is not affected by its depth within the interval. Size_3D The displacement is affected equally by the distance of the point from the axis and its depth within the interval. Size_Radial The effect increases with the distance of the point radially from the bending axis Non-linear/ There are four different types of Non-linear spatial transformations. All of them have a radial interval of effect. Move DEFINE: end point and center point Size DEFINE: center point and end point Stretch DEFINE: center point and end point Rotate DEFINE: center-point and end-point Each of these types can use one of the following control forms: * Parabola * Linear * Circle * Sine * Curve The Non-linear transformation functions take freeforms as their operands. The function type is applied to the points in the operands non-linearly over the interval of effect. The degree of effect of the function type depends upon the distance of the target point from the center point and a scaling factor derived from a control curve. The scaling factor is calculated by taking the distance of the target point from the center point and using this to evaluate a point along the control curve from its start. This control point is then projected perpendicularly onto an axis and the scaling factor is this distance. Pre-defined Control Forms For the Linear, Circle, Sine & Parabola forms the control curve is defined internally. For example, using the Circle form of Modify/Non-linear/Move, the scaling factor for each point in the operand is the perpendicular distance from the axis to the point around the circumference of the circle which corresponds to the distance of the target point to the defined center point. The distance of the point is normalized, so that the full radius of the effect of the function is the circumference of the control circle. Curve Form The Curve form uses a TRANSFORM method defined by the user, and selected with /Set_Tool. Because the scaling factor is derived by evaluating ALONG the control- curve, the profile of the points being modified does NOT match the curve. Set Tool Select the object to be used as a tool by the Non-Linear functions Curve form. This object must be a TRANSFORM method. Special/ Project To Object DEFINE: Two points, which define the projection direction and the projection distance. This function projects the operands onto a defined object. The function takes two or more operands. The first operand is used as a target, onto which the rest of the operands are projected. The operands to be projected can be: 1. primitives; the function moves their COGs the distance defined by the given two points, unless the COGs collide to the target object (The first operand) earlier. 2. freeforms, including groups from a larger mesh. The control points of freeforms are moved independently the amount specified by the given two points, unless they collide to the target object (the first operand) earlier. Inverse Kinematic DEFINE: coordinate This function can take one or more lines as its operands and moves the end points with the pointer while applying Inverse Kinematic Evaluation. This means the line segments will behave like mechanical linkages with rotary joints at each point. The start point is fixed and never moves. COGs/ Size_2D Size_3D Stretch Extend Rotate Mirror Shear Rot&Ext The above functions work in the same way as their linear counterparts, except the COG's of the selected objects are used as the operands. About COGs/ Size_2D Size_3D Stretch Extend Rotate Mirror Shear Rot&Ext The About_COG's functions also work in a similar way to their linear equivalents, but the modification is applied to each multi-selected object individually, with their COG's being used as ether the center or fixed point for the function. For example: Using About_COGs/Size_3D causes each object to be individually sized on all three axes using their COGs as the sizing center and in proportion to the amount the cursor is moved away from the defined center relative to the defined handle coordinate. Freeform/ Reparametrize This doubles the number of knot-points on a B-spline along the directions selected, without affecting the shape of the curve. Move Knotpoint K This allows a single knotpoint on a freeform to be selected and moved. The selects the nearest knotpoint on the freeform. Concatenate This takes multi-selected freeforms as its operands and creates a new freeform by joining them together. The endpoints of each freeform are joined to the startpoint of the next in the selection. When the operands are meshes, then the start & end-points of the v direction lines are joined. The number of points in the u direction of the result mesh will be the same number of points as in the u direction of the first mesh in the selection. The functions /Swap Direction and /Exchange_u_&_v can be used to control how the freeforms are concatenated. Swap Direction Reverse the direction in which a freeform is evaluated. Open/Close The Open/Close Freeform requester has two gadgets indicating if a freeform is currently open or closed in each of the u & v directions. Selecting either of these gadgets will reverse the state. Selecting OK applies the change to the targets. Type Change how the data of a freeform is to be interpreted. Both curves and surfaces can be one of the following types: Polygon Phong B-spline Invert Treat current freeform data as knot points and convert freeforms to new control polygon. Remap Modify number of points along each dimension of a mesh. Surf. to curves Create a set of lines from the lines defining the u dimension of a mesh. To obtain the line s defining the v dimension, then use /Exchange_u_&_v first Distribute Figure @{"R1-28:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-28"} Distribute. (PICTURE: R1-28) This function redistributes the knot points along a B-spline line or over a B-spline mesh so they are spaced equidistant. Assign Figure @{"R1-29:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-29"} Modifying a Mesh with the Assign Function. (PICTURE: R1-29) Points from a mesh pushed onto the Vector stack using are assigned new coordinates. The new coordinates are taken from a selected line operand. The selected points are assigned their new coordinates consecutively i.e. first selected point from the first point on the line. If the number of selected points and points on the curve are un-equal, then extra points are ignored or un-used. Exchange u & v This exchanges the interpretation of the u and v dimensions of selected mesh(es). Snap to This function takes two or more freeforms as parameters and "snaps" the points of the rest of the operands to the first "target" operand. The "Snap" operation is based on the shortest distance from each point to the target. Usually, the operands are groups, because snapping e.g. a whole surface to another one seldom makes sense. For example, the three leftmost curves of a B-spline control polygon mesh can be snapped to another mesh, thus joining the both. Delete DEFINE: Select a freeform, a point on it, then select the function. The function deletes the selected points on a freeform. If the operand is a mesh, the "u"-direction curve on which the point lies, is deleted. To delete a "v"-direction curve, apply Exchange_u_&_v first. If the curve/ mesh contains less than 4 points in a parameter direction after applying the function, the type of the freeform is automatically converted to "Polygon". Insert DEFINE: Select a freeform, a point on it, then select the function. This function adds a new point after the first selected point of each operand curve. If the operand is a mesh, a new "u"-direction curve is inserted. The position of the new point or the shape of the new curve is obtained by interpolating linearly the selected point/curve and the next point/curve. If the selected point/curve is the last one, it is duplicated. Break DEFINE: Select a freeform, a point on it, then select the function. This function splits the target freeform. The point where a curve is broken is copied to both halves. If the target is a freeform, it is broken in "u" direction along a curve on which the selected point lies. Draw Mode/ * Accurate * Bounding_box These two complementary toggles select whether the full wire-frame or a rectangular prism enclosing the selected objects is to be used while a modify function is being executed. @endnode @node "R1.4" @title "Chapter 1 MENU FUNCTIONS" 1.4 VIEW Each view window has its own settings to define how and when it is refreshed. These are defined with the functions under this menu heading. The View to which these settings apply will be the currently selected window. Type/ * Parallel View shows the objects using parallel-projection. No account is taken of distance to the viewpoint when calculating the 2D positions of 3D coordinates. The viewing coordinate system can be altered using the keyboard controls. * Perspective The 2D positions of 3D coordinates are evaluated taking into account the perspective caused by their distance from the viewpoint. The viewing coordinate system can be altered using the keyboard controls. This form of projection is slower than parallel. * Separate IO When this is enabled the input and output planes are separated. This means that rotating the view coordinates allows object creation to be viewed from any angle. Disabling this function means the input and output planes remain connected during rotation, so the actual creation orientation is changed. Input Crd./ Set XY X Set I/O planes of view window to be x, y plane. Set YZ Y Set I/O planes to be y, z plane. Set ZXZ Set I/O planes to be z, x plane. Set Custom C Set I/O planes to last defined custom direction maintained by all other functions except Set_XY/YZ/ZX. This makes it possible to swap quickly between all four main projections. Define X Define x axis of input plane to be the same as vector defined using two coordinates. Define Y Define y axis of input plane to be the same as vector defined using two coordinates. Obj. Space to View Use a selected object to define the orientation for the view window. In other words, the direction of the selected object becomes the direction of the active View window. Camera/ Forward F Backward B These functions allow you to move forwards in the direction of the aimpoint, or backwards away from the direction of the aimpoint. Both the viewpoint and the aimpoint are moved. SETTINGS/View Resolutions/Position defines how much they are moved each time. Orientation Opens a requester which is used for defining the current viewing angle. Three values defines how much the viewing angle is rotated about x, y and z axes in degrees. If the menu View/Separate IO is not set, this function also rotates the input plane. View->Camera V This allows the current View-orientation to be saved by storing it to the selected objects. The objects must contain at least one camera, and the orientation will be copied to the first viewpoint and/or aimpoint found. Camera-> View Selected objects are searched and the first viewpoint and/or aimpoint found will be used to define the new orientation for the View. This allows a new View orientation to be selected using previously defined viewpoint and/or aimpoint. If no cameras are found, then an error will be raised. Create Camera This records the current view-orientation by creating a level at the current hierarchy level containing a viewpoint and aimpoint. The aimpoint and viewpoint data reflect the current orientation and zoom settings of the View. * Camera View When this function is enabled, then viewpoint and aimpoint primitives are used for defining the orientation for the View window when an animation is played. This means that if these primitives are modified by the user, or by a method during the animation, then the viewing position and zoom level will also change. If there are more than one viewpoint or aimpoint, the first found is used, unless the tag SWND is used for defining a particular name of a View window to be exclusively related to aim/viewpoint in question. Display/ Zoom In + Increases magnification of View using zoom setting. Zoom Out - Decrease viewing magnification using zoom setting. Custom Scale Enter zoom scale with numeric requester. Position Move view position in plane of View. A point in Absolute Coordinate Space is defined first, and this is moved to the coordinate of the View defined with the second action. Pos&Zoom In I DEFINE: center point and size of new view. The center point of the new viewing coordinates is created, then a rectangle the same proportions as the view is sized. If confirmed, then the view will be expanded so the rectangle fills the view window. Pos&Zoom Out O DEFINE: center point and size of the current view. The defined rectangle becomes the size of the current view in the view window. Reset E Reset View Orientation to the last saved settings for the View. Grid/ Select Open the grid select requester to select name of grid to use as current grid for View. Figure @{"R1-30:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-30"} The Grid Requester (PICTURE: R1-30) Create Create a new grid using the grid requester, with the following gadgets: Name Enter name of the new grid. Grids are selected using the name. Grid Enter X,Y, Z dimensions of grid. Origin Enter X,Y, Z coordinates of origin of grid. Position & Size The grid plane position and size definitions. Pattern A 16 bit value, which defines the drawing pattern for the grid. The default value 65535 defines a solid line, whereas the value 255 defines a broken line. The value 1 produces only discrete dots. Color The color of the grid. If confirmed, then the new grid will become the current grid for the window. Modify Allows a grid to be selected using the Grid select requester. Then the Grid requester is opened to allow the selected grid to be modified. If the changes are confirmed, the grid is modified and it becomes the current grid Reposition The center of the grid is redefined to the coordinate defined with the pointer. Delete Select name of grid to be removed from list of defined grids. * Visible If set, then grid is visible * Snap to Grid Entered coordinates will be rounded to nearest grid dimension. Render/ Window R Render currently selected view window. Boxes Only render defined boxes in selected view window. Grayscale The highest resolution screen with maximum bitplanes will be opened with a borderless window for rendering. The initial settings will be taken from the current View, and the render settings requester will be opened to allow the user to make changes before commencing rendering. HAM Open HAM screen with borderless view window and render to this. Initial settings are taken from the current View, and the render settings requester is opened to allow changes to be made before finally rendering. * Selected When set, only selected objects are rendered . Settings S Open Render settings requester for current View. Local Menu: IMAGES/ Backdrop image/ Define Produce file requester to select Backdrop image. Show Display Backdrop image. If the image is 24-bit, then a requester will be produced asking for confirmation, as displaying the image may overwrite the contents of the External Screen. Environment map/ Define Produce file requester to select Environment map image file. Show Display the Environment map image. As with Backdrop_image/Show, this will ask for confirmation before displaying a 24-bit file. COLOR/ Ambient Background Background_gradient Environment Environment_gradient Each of these menu selections assigns the current color to the RGB values for the corresponding numeric gadget. The current color can be changed using the Palette window. SET/ File Name Open a file requester to define the name of the output file, which is used when IFF file/Targa file/Bmp file output is selected. Memory_Usage This opens a requester to control the maximum memory the View window can use when rendering. The more memory the Rendering Engine has available, then the faster it is capable of going, and if it does not have enough, then it cannot render at all. Figure @{"R1-31:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-31"} The Memory Usage Requester (PICTURE: R1-31) Gadgets: Fixed The maximum amount of memory the View can use when rendering is calculated from the amount of free memory when the View is created. Relative The memory for rendering is determined as a percentage of the total available memory when rendering is commenced. The default for this is 20%. * Color Shading When set the Rendering Engine will use color shading. For this setting to produce the correct results, the screen palette must be set to "COLOR SCALE" using the main menu function PROJECT/Environment/Screen Palette to open the screen palette requester. Color shading works properly only if screen depth is 6 or higher. Figure @{"R1-32:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-32"} The Render Settings (PICTURE: R1-32) Gadgets: Output Select output target for rendered image: Window - Real-3D View window IFF File - File in IFF24 format Targa File - File as Targa format BMP File - File in Windows(TM) BMP format External - External Screen e.g. 24-bit frame-store Note: If a View which is a handle to an External-screen is saved, it does not automatically open the External screen when the file is re-loaded. This will produce a warning requester, and if the External-screen is not opened, then the View will default to rendering to it's window" File When one of the "File" output targets is selected, then the name of the destination file is entered here, or it can be selected with SET/File_ Name. The file name will have the current Frame number appended to it, and formatted using the Format string from the Animation system. Mode = Draft The rendering engine uses a grey-scale evaluation of the object color and ignores all material properties to render the image. This is the fastest rendering mode available. Mode = Environment All objects are treated as Not Reflected with reflections being taken from Environment color and/or map. Only a single light-source from the viewpoint is used. This is the fastest rendering mode which shows object colors and a representation of material properties. Mode = Lampless The scene is rendered using full object and material properties, but only the single viewpoint light-source is used. Mode = Shadowless All user-defined light-sources are evaluated, but no shadows are calculated. Mode = Normal Full rendering evaluation. Mode = Outline The scene is rendered as a hidden-line wire-frame image by rendering the edges of all objects. These outlines are colored according to each object's color properties and will be dithered if dithering is enabled. Dithering = Rnd RGB Separate random deviation for each color component: R = R + rnd1, G = G + rnd2, B = B + rnd3 Dithering = Rnd intensity The same random deviation is used for each component: R = R + rnd, G = G + rnd, B = B + rnd Dithering = Fixed rnd int The same random deviation for each color component and a fixed dithering pattern is used for every frame. Dithering = Row Colors dithered line by line. Dithering = Raster Use a checkered pattern for dithering. Dithering = None No dithering applied. Ambient (0,0,0) Color and level of ambient light. This affects the overall color of highlights and shadows. Background (128 128, 128) Color of image background. This does not interact with the rendering of objects and materials. Backgr. grad (RGB settings & gadget) (0, 0, 0) Using Background Gradient enables a non-uniform background to be produced. When the Background gradient gadget is enabled, then the image will have a uniform gradient from the Background color at the top of the image to the Background Gradient color at the bottom. Environment (128, 128, 128) This specifies the color which is evaluated as if an infinite sphere of this color surrounds the objects in the scene. This sphere is treated as a Scene object and only appears in reflections and via refraction. Envir. grad (RGB settings & gadget) (0, 0, 0) When the Environment Gradient gadget is enabled, then the "Environment Sphere" will have a gradient from the Environment color at the top, to the Environment Gradient color at the bottom of the image. Brightness (0 - 255) This controls the scaling of all the light sources in the scene. The ratio between the intensities of all the light sources is maintained, but re- scaled by the Brightness setting. The default setting is 50. Overlight (0 - 255) The level of this setting controls how rapidly the color intensity turns the color to pure white. While the color of each pixel is being evaluated, the internal color components can exceed 255. The excess for each component is multiplied by the Overlight factor and then added to the other two components. The default setting of 1 means that only the brightest parts of the scene become "over-exposed", and only gradually. Recursions (0 - 16) This defines to what depth light rays are evaluated as they reflect from surface to surface. At the default setting of 3, only the first three reflections of a light ray can have any effect on the current pixel. Dither scale This defines the maximal deviation of the color signals when using dithering. The default value of 64 determines that only two consecutive colors are mixed at a time. 24-bit rendering output is not affected by this setting. Backdrop image (file name & gadget) When the Backdrop image gadget is enabled, then the named file is used as a background to the rendered scene. This does not interact with the 3D objects in any way and fills the background display area completely. If a backdrop image is being used, this replaces any Background color settings. Environment map (file name & gadget) Setting the Environment map gadget maps the file specified onto the "environment sphere". If an environment map is being used, this replaces any Environment Color/Gradient settings. Width & Height These gadgets control the width & height of the rendered image in pixels when rendering to a file or an Eternal Screen. They are ghosted when a Window output target is selected, and they only display the window dimensions. Pixel h/w Controls the aspect ratio used for individual pixels when rendering. The default setting of 0. 0 means that the target Rendering Screen's automatic aspect ratio is used. DOF Scale Controls how the Absolute Spatial Distance of an object from the Aim-point affects the focus. "DOF Scale" does not relate directly to Absolute Spatial Coordinates, but the higher it's value, the more rapidly distance from the Aim-point increases blurring. If set to 0.0, then Depth of Field is infinite and all objects are sharp. DOF Strength (0.0 - 5.0) This numeric controls how much blurring occurs at a given distance. Like "DOF Scale", the effect increases with an increase in value, and if set to 0.0, then Depth of Field is infinite. Default setting is 2.0. X-resolution (1 - 8) Y-resolution (1 - 8) These two gadgets control the size of patches evaluated when rendering. Default is 1 for X & Y. Antialiasing (0---8) This controls when the color signal difference triggers the Adaptive Over-sampling of the Anti-aliasing routines. trigger level = 256/(2^aa) So: 256/(2^8) = 1 -> always over-sampled 256/(2^1) = 128 -> if csd > 128 where: csd = color signal difference aa = anti-aliasing setting It also affects motion blur quality by triggering additional temporal sampling. Lightsamples (0 - 32) This controls the amount of sampling used for diffuse light-sources. A setting of 1 will produce satisfactory results unless the diffuse-light- source is very large in relationship to the other objects in the screen. A "Lightsamples" level of 32 converts a lightwall into over 1000 internal light-sources, which will have a significant impact on rendering time. Mat. samples (0 - 32) Amount of sampling for Non-homogeneous Material Properties. Subdivisions (0 - 4) Controls how finely B-spline surfaces are evaluated when rendering, and if B-spline->Phong is set, how much each face is subdivided. A setting of 0 will be faster, but may produce some visual errors. If set to 4, B-splines are very finely subdivided during rendering. This will slow evaluation considerably, but will allow even very convoluted surfaces to render correctly. The default setting is 2, which is adequate most of the time. B-spline->Phong B-spline surfaces are converted internally to phong type freeforms before rendering. This obviously produces all the artifacts of "Phong" shading, but as it accelerates calculations considerably, it is useful for evaluating a scene before final rendering. The quality of the result is controlled by the Subdivisions setting. The conversion process consumes a significant amount of memory. Autogxp (set by default) This rescales the output from the Rendering Engine, so only the brightest parts of the scene will reach maximum display brightness when rendered. The effect of this is the same as that of automatic exposure by a camera, which is to produce the most balanced image possible under the available lighting conditions. Field rendering Every odd frame is rendered half a pixel lower. This provides the odd and even fields for 50fps PAL. No bgr. antial. Prevents anti-aliasing between the edges of objects and the background. This is useful when the image will be genlocked with video source. Alpha output Rendering calculations will be carried out using Alpha Information from visibles. This Alpha Channel information can go directly to an External Screen if the device supports this, or can be rendered to a Targa Alpha file. HL-shading Uses additive instead of proportional method to calculate consecutive shades of a color. This produces significantly better results for 6-bit HAM rendering. It can be also used for producing more "colorful" images in general. Export RPL This function outputs all the material data-structure, object data structure, animation settings data structure and the Render settings for the View in ASCII RPL format to a file specified by the user through the file requester. Drawing Set D Opens Refresh settings requester. This requester controls how each View is refreshed and what features are displayed when refreshed as wireframe. Figure @{"R1-33:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-33"} Drawing Settings (PICTURE: R1-33) Gadgets: Curve Subdiv. (2 - 9) The number of subdivisions used when drawing curves. The default is 5. Surface Subdiv (2 - 9) The number of subdivisions used when evaluating the curves of a B-spline surface. The default setting is 2. Draw v When set, the v direction of a B-spline is drawn using Surface Subdivision. If un-set, then only u direction is subdivided. Render Wire Window is always refreshed as wire-frame when refreshed by the Animation System. Morphing Routes Key-frame morphing paths are drawn when set. No Refresh The window will not be refreshed by normal refresh commands. Coordinates When enabled, the View will display the position of the pointer in absolute spatial coordinates and the "Current and "Next" items on the action list will be displayed in the active view window's title bar. Aspect R. Control the aspect ratio of the view window. C.Polyg. Draw control polygons of B-splines when set. Curve When set, the curve of a B-spline is drawn. This is the default setting. Knots If set, the knot-points of B-splines lines will be marked with a "oo" and the end-point of the curve will be marked with an arrow. The end-points of the curves for a B-spline mesh are marked with "u" or "v", depending on which dimension. This is set by default. Mappings Mapping primitives are visible if this gadget is set. This is the default. Names The names of objects will appear on or near them if this is set. Ray Trc. If this is enabled, then the default refresh mode for the window will use the rendering engine with the current Render settings. Controls When set, Controls objects are visible. This is the default. Busy Req. When set, a requester will be produced when the window is being rendered, or when a Fractal tree is being generated, to show the percentage of the task completed. Abs Grid This produces a fixed grid in the Z-X plane to make visualization of the current view orientation easier. Boxes/ Define Create rectangle to confine rendering area. An unlimited number of these rectangles can be defined, and they may overlap. Modify Select name of box to modify, then a numeric requester will allow the position and dimensions of the box to be changed. Delete Select name of box to be deleted. Delete All Remove all box definitions for selected window. Show All Shows all defined boxes with broken outline. @endnode @node "R1.5" @title "Chapter 1 MENU FUNCTIONS" 1.5 ANIMATE The Animation System refreshes all Views during play, ignoring the System Refresh Settings and any "No Refresh" gadgets for individual Views. Create/ These functions all build the necessary hierarchical structure to implement the method for selected objects. The selected objects each become the target for the method and the defined controls become the parameters for the method. For further details of the methods, see the reference chapter 2. Coplanar Path Create a PATH method using selected objects and defined B-spline. DEFINE: points on the control polygon of a B-spline. Orthogonal Path Create a DIRECTION method using selected objects and defined B-spline. DEFINE: points on the control polygon of a B-spline. Rotation Put the targets into counter clockwise rotation in the current input plane. DEFINE: coordsys Sweep Create a SWEEP method using selected objects and defined offset and B-spline. DEFINE: first offset, then points on the control polygon of a B-spline. Stretch Create a PATH method using selected objects and defined coordsys and B-spline. DEFINE: coordsys then points on the control polygon of a B-spline. Size Create a SIZE method using selected objects and defined coordsys and B-spline. DEFINE: coordsys then points on the control polygon of a B-spline. RPL Create a RPL method using targets and specified text. The text can be any valid RPL. The method is attached directly to the target(s). No additional structure is created. Control/ Play Forwards Evaluate animation for from current time to Time = 1.0 and refresh Views every 1/Resolution time intervals. Play Backwards Play Animation from current time to Time = 0.0. Go to Beginning Change Time to 0.0 and evaluate animation at Root level. Go to End Change Time to 1 .0 and evaluate Root. Step Forwards Increase Time by 1/Resolution and evaluate Root. If Samples is greater than zero, then the evaluation will be subdivided, but the Views will only be refreshed at the end of the interval. Step Backwards Decrease Time by 1/Resolution and evaluate Root with subdivision, if Samples > 0. Refresh Refresh the animation system. Some methods automatically add tags to objects when refreshed first time, "matching" the parameters and the target objects. @endnode @node "R1.6" @title "Chapter 1 MENU FUNCTIONS" 1.6 EXTRAS Vectors / The Vector stack is a place for storing and modifying Absolute Spatial Coordinates or points from freeforms. It works on a "Last In First Out (LIFO) basis. Whenever a box is formed, the points inside the box are stored or "pushed" onto the Vector stack. If no keys are used as modifiers, it performs a default action, which is to return the average of all the points inside the box. Points or coordinates can also be pushed onto the Vector-stack without any automatic action being taken. They can then be retrieved or "pulled" from the Vector stack to replace coordinate entries while using Create or Modify functions. HOT-KEYS: - Push points from all objects and return average. - Push points from selected objects and average. - Push points from all objects inside box onto Vector- stack. - Push points from selected objects onto stack. - Push ASC onto Vector stack. - Pull point to replace click in a View. Before the pints are used, it is possible to carry out various vector- arithmetic operations with them to obtain averages of different groups of points; or create new construction points relative to existing ones. Push This waits for a click or in a View, and the coordinate defined or points selected are pushed onto the stack. Pull . Pull coordinate from stack to define a coordinate instead of using a click or a action. Enter Enter value for ASC using a requester. This coordinate is then pushed onto the stack. Clear Clear Vector stack. The stack can also be cleared by using over empty space. Add Add two vectors on the top of Vector stack. The result remains on the stack. Subtract Subtract top vector from next vector, leaving the result on the stack. Average Average first two vectors on the top of the stack. Average All Find the average of all the vectors on the stack. This is the same as using , only the average point is left on the stack. Cross Product Calculate the cross-product of the top two vectors of the stack. The cross-product of two vectors is one which is perpendicular to both. The following Evaluation System functions take multi-selected objects as their operands, and if they are a valid evaluable parameter, then they will be evaluated, otherwise they will be ignored. If the selected object is a level, then the first sub-object will be used as the operand. For each evaluated parameter, a point will be entered onto the Vector stack. Eval. Current This function evaluates a pint along parameters corresponding to the current value of Time. Define & Eval. Three values between 0.0 and 1 .0 are entered. These are used as the coordinates of the Parameter Space for the evaluable parameters. Length evaluate Evaluates a point a given distance in ASCs along each parameter which is a line. Undo Recall previous hierarchy definition from undo buffer. Statistics Produces requester stating: - Number of objects in hierarchy - Memory used for hierarchy Refresh All/ Wire-frame Refresh all Views using their individual Refresh Settings. Ray Trace Renders all View windows. Each View uses its own Render Settings. Cancel All Terminates execution of all REAL 3D functions currently being executed. Evaluate/ Curve Length Display the lengths of the currency selected lines. Parameter Find the nearest point on selected parameters to the pointer when clicked. This point is entered onto the Vector-stack. Select Objects This function selects the objects in the hierarchy which currenCy have points on the Vector stack selected with . @endnode @node "R1.7" @title "Chapter 1 MENU FUNCTIONS" 1.7 SET TINGS Clip Boxes/ Figure @{"R1-34:" system "display dh9:docs/r3ddoc/r3dv2pics/R1-34"} The Effect of a Clip Box (PICTURE: R1-34) Cubes can be selected as volumes to define which portion of the scene is to be visible as a wire-frame. This does not affect rendering. * Active If set, then only those parts of the scene enclosed by the cubes currently selected a s clip boxes will be drawn as wire-frame. The wire-frames are only drawn to the nearest line endpoint inside the clip boxes. Select Enable currency selected cubes as clip boxes. Deselect Disable all current clip box definitions. General Produce requester for general system settings: Vector Format The numeric format for displaying coordinates. Float Format Numeric format to be used for general floating point number display. Macro File Where to save the current-macro definition. Aspect Ratio Default system aspect ratio. This is combined with the Refresh Settings/" Aspect-R" or Render Settings/"Pixel-h/w" of each View to produce the aspect ratio finally used for refreshing each View. Drag Delay This controls the delay before dragging produces the default average all result from the Vector stack. Confirm Save When this gadget is activated, REAL 3D gives a warning before overwriting any existing file. Refresh/ These complementary toggles define the System refresh settings which control which view windows will be refreshed when REAL 3D issues an automatic refresh command. * None - None of the Views will be refreshed. * Current - Only the currently active View. * All - All the view windows. Oper.Level/ These functions control what levels of the hierarchy to re-draw. Everything from the current level and below is re-drawn, with the depth controlling how many levels above are to be considered. * Active Enable redraw depth when set Depth Enter number of hierarchy levels above current level to redraw. Creation/ The following toggles determine various system actions during object creation. * Qry. Level Name When a compound-object creation function is used, a requester is produced to allow the user to change the name of the level created. * Qry. Prim. Name The creation of any new primitive queries its name. * Auto current Make newly created level the current level of hierarchy. * Auto active New object will be active after creation. *Auto index As new objects are created, a "." and an index number is appended to their names. This auto-indexing may slow down the creation procedure in some cases (F or example, when importing DXF files, where all primitives are created at the same level). Paths Enter the default file paths for loading and saving. The path can either be entered in the text gadget, or by clicking the gadgets on the left, a file requester is produced which enables the path to be selected. These can be separately defined for the following data sections: Objects Macros Materials Environments Projects Textures Images Alpha Channel This requester allows the current alpha information value to be set. This is stored as an object property in an the same way as the RGB color components; it acts just like a fourth color component for rendering. Alpha information is used only when the combination of non-Draft mode Render Settings with "Alpha-Channel" enabled is used. The background Alpha level is automatically set to maximum value 255. One byte of alpha information per pixel is written to the output target. Attributes Allows default attributes and names used at creation to be set for each primitive. For example, if you want all the cubes you create to be automatically hollow: 1. Choose Settings/Attributes. 2. Find the primitive "cube" from the list and select it, then press OK. 3. The REAL 3D will now create a requester which shows the current object attributes. Set the Hollow field and choose OK. From now on all new cubes you create are hollow. You can verify this using the Modify/Properties/Attributes function. RPL Produces requester to enter the depth settings for the various RPL stacks Parameter Stack This stack holds the parameters for RPL words as well as the results after execution. Returncode Stack Hold the addresses of RPL words calling another word, so execution can return to the original location. Control Stack Used internally by RPL while compiling new words. It is also used for "IF" and 'LOOP" nesting, and recursion. Vocabulary Stack Stack used for storing the references to the compiled code for RPL word definitions. The amount of memory required for each reference is not exactly quantifiable, but is approximately 12 bytes on an Amiga System. Strings Maximum number of string variables which can be used in RPL at any one time. The maximum length of a string is 255 bytes. View Resolutions/ Rotation (0.125664) Position (0.100000) Zoom (10.00000) These functions enable the increments used for view window rotation, position and zoom to be set. Rotation is specified in radians, Position in ASCs and Zoom as scaling units. The default settings are shown in parentheses. Undo/ * Active Enable operation of Undo buffer. If memory runs out, it is possible to recover the memory used for the buffer by de-activating it. Set Depth Define the depth of the Undo buffer. This defines how many previous versions of the hierarchy are stored. If the scene is complex, then a deep buffer will consume memory very quickly. The default depth is 3. Clear Clears current contents of Undo buffer This also recovers the memory used by the buffer. File Icons This function calls up a requester , enabling the user to select which REAL 3D file data sections should have an icon created for them when they are saved. @endnode @node "R1.8" @title "Chapter 1 MENU FUNCTIONS" 1.8 TOOLS This menu is only active if a Tool window is the active window. Icons/ * Visibles * Sectors * Structures * Lights * Controls * Compounds * Freef.Tools * Mod/Linear * Mod/Structure The menu toggles, listed above, select which sets of pre-defined tool icons are to be loaded into the selected tool window. It is possible to have several tool windows each containing different, or even duplicate sets of tool icons. Create Icon The user is requested to enter the text for a tool gadget. This will be created in the currently active Tool window. When this gadget is selected, an RPL file or word with the same name as the gadget text will be looked for in the MACRO directory or Master RPL environment. If found, it will be executed. The maximum length for the gadget text is 11 characters. Delete Icon This opens a requester displaying the text contents of all the user defined tool gadgets. One can then be selected for deletion. @endnode @node "R2.1" @title "Chapter 2 ANIMATION METHOD SYNTAX" Chapter 2 ANIMATION SYSTEM -------------------------- 2.1 Principles 2.1.1 General Information The basic concept of the Real 3D Animation system is that it is possible to create an object which consists of a shape, and a motion. These animation actions are created by adding an animation method to the same level of hierarchy as the object defining the shape. For example, a moving car consists of a shape and a motion object. +-----------+ | MovingCar | +-----------+ / \ +-----+ +-----------+ | Car | | Motion(M) | +-----+ +-----------+ / +------+ | Road | +------+ Figure @{"R2-1:" system "display dh9:docs/r3ddoc/r3dv2pics/R2-1"} A moving car consists of a shape and a motion. Technically a method consists of an object to which some kind of procedure has been attached. The Animation system informs each method when time has changed and each procedure then determines what actions it should carry out to the targets. For brevity the term "method" is used interchangeably with method procedure unless it is necessary to make the distinction clear. There are two possible kinds of method procedures: built-in method procedures and procedures defined via RPL by the user. 2.1.2 Built-in Methods The built-in methods, with the exception of TRANSFORM, each use the objects at the same level of hierarchy as themselves as targets (excluding other methods). Built-in methods all carry out their actions on their chosen targets depending on the difference between their current time and the new time value. The actions of the built-in methods are determined by three factors: their method type, their parameters (if specified in their syntax), and the outcome of their evaluation of time. Most of the built-in methods require additional information in order to carry out their actions. This information takes the form of either one or more parameters contained within the sub-structure of the method object, or one or more tags attached to the method object. It is also sometimes necessary to attach tags to the targets and the parameters. Since most methods require at least one parameter it is usual to use a level as the method object. It is possible, and often necessary, to arrange methods hierarchically so that one method affects the parameters of another. 2.1.3 User Defined Methods User defined methods can take whatever action they choose when informed by the Animation system that Time has changed. They do not even have to affect any target or take any account of their method time. It is quite legitimate for a method procedure to take some arbitrary action such as a call to a system function for every new frame. Since the syntax of the method procedure is decided by the user, it is possible to choose an appropriate method object to attach to the procedure; and any required parameters or tags can be specified in any way. The user can create new methods either using the RPL word MTH_CREATE, or by using the build-in method named just RPL. It is also possible to customize existing methods by associating SRPL and SFOR tags with them. Note: A method procedure is executed for every time interval. The number of time intervals during an animation is dependent on Resolution and Samples. 2.1.4 Evaluating Parameters Most methods require that certain parameters be of a type that can return certain information when processed using the Evaluation System. Evaluation System takes three floating values and one object as parameters and returns either a point or direction corresponding to the given parameter values. Currently the following primitives can be used as evaluable parameters: offset axis coordsys ellipse line mesh Other primitives can be made evaluable by attaching SFOR or SRPL tags to them and by defining relevant RPL variables. In order to make the object fully evaluable (ie. all methods can use it) proper values must be assigned to the following variables by user defined formula/procedure: x,y,z - position corresponding given parameter value i,j,k- direction corresponding given parameter Variables t, u, and v are used for parameter space and are read only. All built-in evaluable primitives are sensitive only to the first dimension (t) except for the mesh which uses the first two dimension (t and u). Tags SFOR and SRPL can be attached to evaluable primitives in order to customize them, in which case the built-in evaluation is processed first. The user has access to the Evaluation System via the RPL words "O_EVAL" and 0 DERIV which allows an evaluable parameter to be used to provide the same kind of control for a user defined method procedure as the built-in methods use. 2.1.5 Animation Oriented Tags There are five vector tags which are evaluated by the Animation-System and used to control the operation of all methods. The interaction of these tags and their affect on the operation of the methods is as follows: VTIS - This tag defines when the method becomes "active". The current time of the method in is automatically shied to start from zero. In other words, when the current time reaches the value defined by the tag VTIS, the method begins to work and its time starts from the zero. VTIE - When the current time reaches this value, the method in question becomes inactive. The local time of the method is stretched so that when the current time runs from the VTIS up to VTIE, the time of the method in question runs from 0 up to 1. VPHS - The time is shifted by this value for the method in question. VFRQ - The time of the method is multiplied by this value. be used for accessing SFOR - This tag can the RPL interface of the Animation System. The tag can be associated with methods, targets and parameters and can affect the RPL variables defined during animation. The contents of this tag is usually a formula which modifies certain variables in order to customize the object it is associated with. SRPL - The purpose of this tag is to provide the user with total control over the RPL interface of the Animation system. The tag value can be any RPL program providing the user with a more powerful way to customize the method, target, and/or parameter objects. The RPL Interface to the Animation system consists of the following variables: T - The current time. This time can be modified by the Animation Window and is always between 0 and 1. Res - Frame resolution Frm - Current frame a, b,c - Velocity i, j, k - Spin x, y, z - Center of Gravity t, u, v - Local time of the method in question or parameter value for object evaluation m1, m2 - Mass d - Diameter of the object (size of the bounding sphere) f - Strength of the Force rnd - Random value, always between 0 and 1 o - Address of the object I - General usage 32 bit integer value fx, fy, fz - General usage variables. Purpose depends on the context s - Distance dt - Time interval between subsequent animation samples e - Kinetic energy of the object 2.1.6 Particle System Principles The particle system of Real 3D is implemented through methods. These methods treat all targets as "particles" with velocity, spin, mass, and other physical particle properties. Particles then behave according to Newtons Laws of Motion when acted upon by forces. With the exception of PROCESSOR, each particle method modifies the velocity and spin by applying a force that depends upon the method type and the properties of the particles. The motion properties are stored in the tags VVEL and VSPI which describe the linear and rotational velocity along or about each axis respectively. @endnode @node "R2.1.6.1" @title "Chapter 2 MENU FUNCTIONS" 2.1.6.1 Converting Motion Properties into Real Motion The PROCESSOR method converts the motion properties into actual Move and Rotate modifications for each particle. If this method is not present on the level of the targets of other particle methods then VVEL and VSPI will be changed but the particles will not move or rotate. 2.1.6.2 Forces in the Particle System The other methods each apply some force to particles. The default formula for this force can be over-ridden by the user with the tags SFOR and SRPL. These can contain expressions which are evaluated by RPL and assigned to the force variable. If the strength of the default force is not strong enough then SFOR f*100, for example, would increase this by a factor of 100. It can also be set to a constant simply with SFOR 100, which can be desirable for certain effects. Individual methods then have certain other variables that relate to their effect. 2.1.6.3 Real Time and Particle Motion The particle methods simulate the effect of physical motions. This means they require an absolute time scale on which to operate. This time scale is called Real-Time, and is expressed in terms of seconds. A particle with a velocity of 1.0 will travel the distance of one Absolute Spatial Coordinate in one Real Time second. Spin is evaluated in the same way with one revolution (expressed as 2 * PI radians) occurring per Real Time second. The amount of Real Time evaluated during an animation is controlled by the "Seconds" field of the Animation Window, and is not related to "Resolution" or rendered frames. 2.1.6.4 Side-effects of Particle Animations The Particle System simply evaluates the velocity and spin of each particle for each time interval and then the PROCESSOR method updates the position and direction accordingly. It is often not possible to calculate what the previous motion properties of a particle were given only the current values. Imagine looking at a pool table after the player has played his shot and all the balls have come to rest. It is clearly not possible to work out how the balls came to be in their current position. They have no velocity or spin and they could have just stopped moving from some unknown direction, or been placed there by hand. This means that a particle animation CANNOT be evaluated in reverse in the same way as other methods. The only possible way that Real 3D could play particle animations backwards would be to record every frame in a buffer, and this would eat away all available memory too quickly to be of any use. The Undo buffer is the only way to recover the starting position of a particle animation to replay it. Another side effect is that the motion produced by other methods is not taken into account by the Particle System. It can only evaluate the movement and rotation described by the tags VVEL and VSPI. Often particle animation is the fastest way to produce animations where moving and colliding objects have to behave as realistically as possible. To "hand-animate" the collision between hundreds of irregular objects would be prohibitively time consuming, and would be unlikely to yield believable results. With the particle animation system all the calculational details are taken care of leaving the user free to design the actual animation. 2.1.7 Creating New Methods If it is not possible to create a desired animation effect using one of the built-in methods it is possible for the user to create their own via the Real Programming Language-RPL. There are two ways in which this can be accomplished: 1. Create some RPL text, possibly via Project/Macros/Record Macro, then create the RPL method with the text attached. 2. Define an RPL word to carry out the desired animation action; then use the MTH_CREATE word to add this new method to the "Method Type" list of the Animation Properties requester. The word must be defined in the RPL "Master" environment, or "INHERIT" must be used in the RPL Shell window where the word was defined. The new method can then be used exactly like any of the built-in methods. The method procedure attached to the method object, when this method type is selected, is the user defined RPL word; and it can be as simple or as complex as necessary. @endnode @node "R2.2" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2 Animation methods The structure of each syntax description is as follows: SYNTAX The necessary hierarchical structure is described under this heading. The syntax is generalized to show the minimum structure necessary for the method to function as a stand alone animation object. PARAMETERS Parameters required by the method in question are described under this heading. Parameter names refer to the SYNTAX. TAGS Tags which have some specific application to the method in question are included here. VARIABLES All RPL variables affected by the method in question are described here. DESCRIPTION A full explanation is given of how the method evaluates any parameters or tags to carry out its actions on the targets. EXAMPLE Simple example clarifying the usage of the method. @endnode @node "R2.2.1" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.1 Path SYNTAX Figure @{"R2-2:" system "display dh9:docs/r3ddoc/r3dv2pics/R2-2"} PARAMETERS (PICTURE: R2-2) path - evaluable parameter object defining how to move the objects. TAGS: VPHS - Automatically created for each target if the ISKE tag is not present or the value is not equal to 2. ISKE - Created and set to 2 when VPHS tags are created. VARIABLES a, b, c - relative movement during "dt" dt - time interval t, u, v - current time DESCRIPTION: Moves all targets along the given "path". The movement of the targets for each time interval is evaluated from the parameter. When the animation is played for the first time, the VPHS tag is automatically created for each target object by snapping their COGs to the parameter curve. If automatic phase definition is not desired, the user can create an ISKE tag with the value of 2 before playing the animation. RPL variables a, b and c reflect how much the target object in question will be moved during the time interval. @endnode @node "R2.2.2" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.2 Rotation PURPOSE Rotate about another object SYNTAX Figure @{"R2-3:" system "display dh9:docs/r3ddoc/r3dv2pics/R2-3"} (PICTURE: R2-3) PARAMETERS coordsys---Any geometric TAGS None VARIABLES i,j, k - Defines how fast the target object in question rotates about the object space of the parameter object. I - Modify flags. Can be used for defining what kind of rotation should be applied to the target objects. The following values are valid: 0 - target objects are rotated about the parameter object (same as Modify/Linear/Rotate). 4 - target objects are rotated about COGs of their own (same as Modify/About COGs/Rotate). 8 - target objects are not rotated, their COGs are (same as Modify/ COGs/Rotate). DESCRIPTION Rotates targets around parameter object. Each geometric has a well defined axis as part of its geometry. The ROTATION method rotates the targets about this axis. The angular step per time interval is derived from "Resolution"; but is calculated so that the method does not rotate the targets completely during its evaluation. It rotates by one angular step less than that derived, producing continuous motion for a cyclic animation. Note: The Right Hand Rule is used for defining the direction of rotation about the parameter; so the direction of rotation can be changed by mirroring the parameter object. @endnode @node "R2.2.3" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.3 Sweep PURPOSE General rotation with accelerations SYNTAX Figure @{"R2-4:" system "display dh9:docs/r3ddoc/r3dv2pics/R2-4"} (PICTURE: R2-4) PARAMETERS center- parameter for the center-point for general rotation. control- evaluable parameter defining how to rotate the target around the center-point. TAGS VPHS - Phase used for defining rotations for the target VARIABLES I - Modify Flags, see ROTATE method. DESCRIPTION General rotation with accelerations and decelerations. This rotates the targets around "center". The rotation is controlled by the evaluation of the "control" parameter. Character animations, walking robots etc. applications where arbitrary accelerations are needed can be easily created using this method. The tag VPHS can be associated with any target object but it is not defined automatically. @endnode @node "R2.2.4" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.4 Size PURPOSE Size objects during an animation SYNTAX Figure @{"R2-5:" system "display dh9:docs/r3ddoc/r3dv2pics/R2-5"} (PICTURE: R2-5) PARAMETERS center - parameter defining center-point for sizing. control - evaluable parameter defining how object is sized. TAGS None VARIABLES I - Modify flags, See ROTATE method. DESCRIPTION Changes the targets size according to the distance between the "center" parameter and the evaluated point from the "control". The variable "I" can be used for defining whether to use Modify/Linear/ Size, Modify/COGs/Size or Modify/About_COGs/Size. @endnode @node "R2.2.5" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.5 Stretch PURPOSE Stretch objects in given directions SYNTAX Figure @{"R2-6:" system "display dh9:docs/r3ddoc/r3dv2pics/R2-6"} (PICTURE: R2-6) PARAMETERS coord - coordsys defining axis for the stretch. control- evaluable parameter defining how the target dimensions are stretched. TAGS None VARIABLES I - Modify flags, see ROTATE method. DESCRIPTION The targets dimensions in relationship to the axis of the "coordsys" are changed according to the point evaluated from the "control" and projected onto the corresponding axis of the "coord". This method can be used for creating deformations needed in bouncing spheres, collision detection animations etc. @endnode @node "R2.2.6" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.6 Direction PURPOSE Move along a path with automatic direction control. SYNTAX: Figure @{"R2-7:" system "display dh9:docs/r3ddoc/r3dv2pics/R2-7"} (PICTURE: R2-7) PARAMETERS path - evaluable parameter defining move and rotate transformations. TAGS VPHS, ISKE VARIABLES None DESCRIPTION Moves targets along a given "path" rotating it to follow the curvature of the parameter. VPHS tags are automatically created by snapping the COG of each target object to the parameter curve "path". This method can be used for creating animations where objects move along a path like a car follows a road. Swimming fishes, sneaks etc. can be created by subdividing freeform meshes into subgroups and using groups as targets for this method. @endnode @node "R2.2.7" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.7 Move & Dir PURPOSE Move along a path with separate direction control SYNTAX Figure @{"R2-8:" system "display dh9:docs/r3ddoc/r3dv2pics/R2-8"} (PICTURE: R2-8) PARAMETERS move - evaluable parameter defining movement for the targets. direct - evaluable parameter defining rotation for the targets. TAGS VPHS, ISKE VARIABLES None DESCRIPTION This is a combination of methods MOVE and DIRECTION. The first parameter defines how the targets are moved. The second parameter defines how the targets are rotated using the same evaluation as DIRECTION. Thus, two identical curves produce a result the same as the DIRECTION method. If the second parameter is a straight line (axis) the method works as a MOVE method. The VPHS tag is automatically defined for each target by snapping the COG of the target in question to the parameter curve "move". @endnode @node "R2.2.8" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.8 Control curves SYNTAX Figure @{"R2-9:" system "display dh9:docs/r3ddoc/r3dv2pics/R2-9"} (PICTURE: R2-9) PARAMETERS curve1, curve2- two evaluable parameters defining how to control the stretch, rotation, and movement of the targets. TAGS VPHS, ISKE VARIABLES I - Modify flags. The first bit is used to define whether or not the method should stretch the target. If set, targets are not stretched. DESCRIPTION Two points are evaluated from each of the parameters of this method and the relationship between these points are used to control the transformations of the targets. The distance between the points controls the size, the angle between them controls the rotation, and the relative displacement since the previous evaluation controls the movement. The VPHS tag is automatically defined for each target by snapping the target to the first parameter curve. @endnode @node "R2.2.9" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.9 Simple skeleton SYNTAX Figure @{"R2-10:" system "display dh9:docs/r3ddoc/r3dv2pics/R2-10"} (PICTURE: R2-10) PARAMETERS: skel - skeleton TAGS: VOFF - Defines the offset between the skeleton and target COGs. If not present, each target COG is snapped on to the skeleton. VPHS - Parameter value defining the position on the skeleton. SFOR, SRPL - when associated with targets, can be used for redefining the position on the skeleton. ISKE - the value 2 indicates that the VPHS and MCOG tags defined for each target. VARIABLES x, y, z - Parameter space defining the position of the target object on the skeleton. DESCRIPTION This method moves the COGs of the targets to the skeleton. The position on the skeleton is defined by the tag VPHS associated with the target object in question. However, SRPL and SPHS tags allows a more powerful way to define the same thing: the position can be defined using whatever formula to define proper values for x,y and z variables. If the value changes during the animation, the position of the target object on the skeleton changes correspondingly. The VOFF tag defines the offset between the skeleton and target COGs. If not present, each target COG is snapped over the skeleton. By default the tag VPHS is automatically defined by snapping the COG of the target onto the skeleton and detecting which parameter value of the skeleton corresponds to that position. The difference between these two points are then used for defining the value for the tag MCOG. @endnode @node "R2.2.10" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.10 Skeleton PURPOSE Skeletonal control SYNTAX Figure @{"R2-11:" system "display dh9:docs/r3ddoc/r3dv2pics/R2-11"} (PICTURE: R2-11) PARAMETERS: primary - primary skeleton object defining the direction for the target objects secondary - secondary skeleton object defines how the target objects are oriented about the primary skeleton. TAGS VOFF - displacement between target COG and skeleton objects VPHS - parameter value defining the position on the skeleton. SFOR, SRPL - when these tags are associated with the targets, variables x, y and z can be used for redefining the position of the target object. ISKE - Indicates that the VPHS, VDIR, and VDIV tag definitions are executed. VARIABLES x, y, z - position of the target object. DESCRIPTION: Skeleton parameter "primary" is connected to the targets using move & rotate transformations. By modifying the skeleton objects, the targets are modified accordingly. Skeletons are typically modified using Inverse Kinematics. The second parameter is needed to fully define the direction for the target objects. By rotating this object about the skeleton, all the target objects will also rotate about the skeleton. The VOFF tag defines the offset between the skeleton and the target COGs. If not present, each target COG is snapped over the skeleton. By default the MCOG, VDIR, VDIV and VPHS tags are defined automatically for each target. Note: The hierarchical combination of SIMPLE SKELETON/SKELETON with the INV KINEMATIC method is a common way to create "Character Animations". @endnode @node "R2.2.11" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.11 Inv kinematic PURPOSE Modify skeletons by re-defining or manipulating the end point only. SYNTAX: Figure @{"R2-12:" system "display dh9:docs/r3ddoc/r3dv2pics/R2-12"} (PICTURE: R2-12) PARAMETERS: path- evaluable parameter that defines the end point for the skeletonal object TAGS VOFF - Offset vector. SRPL, SFOR - Formula/procedure for defining the end point VPHS - Phase for end point evaluation VARIABLES a, b, c - endpoint DESCRIPTION: Applies Inverse Kinematic evaluation to the targets while moving their end-points along "path". Inverse Kinematics attempts to move the end point of the skeleton to a defined point without changing the distance of points used for defining the skeleton. Variables a, b and c reflect the endpoint defined by the evaluation process and can be changed by user defined SRPL and SFOR tags. @endnode @node "R2.2.12" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.12 Morphing open & closed PURPOSE Morphing based on key-frames SYNTAX Figure @{"R2-13:" system "display dh9:docs/r3ddoc/r3dv2pics/R2-13"} (PICTURE: R2-13) PARAMETERS: key1, key2, ... two or more key-frame objects TAGS VOFF - displacement for the target object VARIABLES None DESCRIPTION: This Method can be used to apply morphing to the targets. The hierarchical structure of the target should correspond to the structure of "key" objects. At least two key objects are needed. Cubical B-Spline interpolation is used for defining intermediate situations. The targets object data structure is just used as the space in the hierarchy to store the results of the morphing. Modifying it does not affect the actual result of the animation. If the targets contain material references, morphing is also applied them too. Different materials must be created and used for the target and the "keys" as their material data structures is/are again used to store the morphing results. The following material properties are morphed: - S-map u, v, w & h - X-Freq & Y-Freq - Transparent Color - Specularity - Specular Brightness - Brilliance - Transparency - Turbidity - Turbidity Saturation - Refraction - Effect Level - Roughness - Bump height - Dither - a & b variables for each Procedural expression @endnode @node "R2.2.13" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.13 Transform PURPOSE Time transformations SYNTAX Figure @{"R2-14:" system "display dh9:docs/r3ddoc/r3dv2pics/R2-14"} (PICTURE: R2-14) PARAMETERS coord - axis or coordsys primitive to which the evaluated point from "trans" is projected. trans - time is mapped to the parameter space of this evaluable parameter. TAGS None VARIABLES None DESCRIPTION: Local time transformation. This differs from other methods in that its "target" is actually the local time being passed by the Animation System to each method. After the time has passed through the TRANSFORM method then the local time will have been changed to a new value according to the parameters. The method re-maps the parameter space of the "trans" parameter by projecting it onto the "coord" parameter. If the "coord" parameter is an axis, then the transformation affects only the first component of the time (t). If it is a a coordsys, then other dimensions can also be defined (u, v). @endnode @node "R2.2.14" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.14 Wave SYNTAX Figure @{"R2-15:" system "display dh9:docs/r3ddoc/r3dv2pics/R2-15"} (PICTURE: R2-15) PARAMETERS coordsys - coordsys or axis primitive defining wave direction wave - any evaluable object defining a shape of the wave TAGS None VARIABLES x, y, z - position of the target in the object space of "coordsys" fx, fy, fz - position corresponding x, y and z variables t, u, v - current time DESCRIPTION This method applies "wave" effect over all the target objects. If the target object is a freeform, then the wave is applied separately to each individual point. If the target object is non-freeform (hierarchical "level" object, quadric etc.) then it is treated as a whole. If the first parameter object is "coordsys", the targets are moved parallel to the "z" axis of it and the targets projections to "x" and "y" axis are used as parameters for evaluating pints from the second parameter object. These evaluated pints are projected to the "z" axis and the difference between the projected points are used for defining how much the target in question should be moved. If the second parameter object is a mesh (or any evaluable object sensitive to the first two component of the parameter space) the wave shape can be defined separately in both the "x" and "y" directions. If the first parameter object is "axis", then radial waves are created and the distance between the target and the axis is used as a parameter for evaluating the shape of the wave from the second parameter object. The user can define whatever control curve for wave generation by attaching a formula or procedure to the method object with the tags SRPL and SFOR and by defining the variables "fx", "fy" and "fz". The variables "x", "y" and "z" represent the current position of the target object in question in the object space of the first parameter object. If the first parameter object is "axis" then the "x" variable reflects the distance between the target and the axis and the "y" reflects the targets projection to the axis. EXAMPLE Symmetrical sin waves 1. Create a mesh +------+ | Root | +------+ / +------+ | mesh | +------+ 2. Create the method WAVE +------+ | Root | +------+ / \ +------++----------+ | mesh || Level(M) | +------++----------+ 3. Create axis inside the method so that it is perpendicular to the mesh +------+ | Root | +------+ / \ +------++----------+ | mesh || Level(M) | +------++----------+ / +------+ | axis | +------+ 4. Create a circle beside the axis. +------+ | Root | +------+ / \ +------++----------+ | mesh || Level(M) | +------++----------+ / \ +------++--------+ | axis || circle | +------++--------+ @endnode @node "R2.2.15" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.15 Radial force SYNTAX / FMAS 10 +--------+ +----------+/ | Object |--| particle |-- VVEL 0 0 0 +--------+\ +----------+\ \+----------+ \ VSPI 0 0 0 | Level(M) | +----------+\ \ \+--------+ | center | +--------+ Figure R2-16: PARAMETERS center - evaluable primitive defining a "center" of the force. TAGS FMAS - mass VVEL - velocity VARIABLES x, y, z - COG of target object a, b, c - velocity of target object i, j, k - spin of target object d - size (diameter) of target m1 - mass of target object m2 - mass of parameter object dt - time interval between subsequent animation samples e - kinetic energy of target f - strength of the force t, u , v - current time fx, fy, fz - direction of the force (unit vector) s - distance between parameter target objects DESCRIPTION Modifies velocity of the objects by applying a force radiating from the "center". The default formula used for defining force field is f = m1*m2/d<, which makes RADIAL FORCE act like gravity on a planetary scale. A small offset (0.05) is added to d< to prevent extreme behavior of particles. The method can be customized by associating SFOR and SRPL tags with it. The direction of the force (fx, fy, fz) and the strength of the force (f) can be freely modified/redefined. All other variables are "read only". The velocity of the object is modified according to Newtons laws of motion F = ma, where "F" is the strength of the force, "m" is a mass of the object and the "a" is the acceleration. For example, if the strength of the force field is "F", the mass of the target object is "m", the time interval between subsequent frames is "dt" then the velocity of the object is changed by "dv". dv F * dt F=m*a=>F=m*--=>dv=------ dt m SEE ALSO PROCESSOR method @endnode @node "R2.2.16" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.16 Directed force SYNTAX / FMAS 10 +--------+ +----------+/ | Object |--| particle |-- VVEL 0 0 0 +--------+\ +----------+\ \+----------+ \ VSPI 0 0 0 | Level(M) | +----------+\ \ \+--------+ | direct | +--------+ Figure R2-17 PARAMETERS direct - evaluable parameter defining the direction and center of the force field TAGS FMAS - mass (kg) VVEL - velocity (m/s) VSPI - spin (rad/s) VARIABLES x, y, z - COG a, b, c - Velocity i, j, k - Spin d - size (diameter) m1 - mass dt - duration e - kinetic energy f - strength of the force t, u, v - current time fx, fy, fz - direction of the force field (unit vector) s - distance between center of force field and the object in question DESCRIPTION Modifies the velocity of particles by applying an external force. The direction and strength are defined by evaluating the parameter object. The direction of the force field is the evaluated direction of the parameter object and the strength is defined by the distance between the object in question and the evaluated position (center of the force field) of the parameter object. Default force is defined using the formula f = 1000.0/(1+s), where "s" is the distance from the center of the force field. User defined formulas and procedures can change the variables "f" and "fx, fy, fz". All other variables are read only. The velocity of the object is modified according to the Newtons laws of motion: F = m * a. In other words, if the force affects the object for the time of "dt", then the velocity is changed by the value "dv" according to the following equation: F * dt dv=------ m @endnode @node "R2.2.1" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.17 Tangent force SYNTAX: / FMAS 10 +--------+ +----------+/ | Object |--| particle |-- VVEL 0 0 0 +--------+\ +----------+\ \+----------+ \ VSPI 0 0 0 | Level(M) | +----------+\ \ \+------+ | axis | +------+ Figure R2-18 PARAMETERS: axis - valuable parameter defining the axis of the rotating cylindrical field of force. TAGS FMAS - mass VVEL - velocity VSPI - spin VARIABLES x, y, z - COG a, b, c - velocity i, j, k - spin d - size m1 - mass dt - duration e - kinetic energy f - strength of the force t, u, v - current time fx, fy, fz - direction of the force field s - distance between center of the force and the object in question DESCRIPTION: Modifies velocity and spin of objects by applying a force that is perpendicular to the vector between the COG of the particle and the axis of the force field. The direction and strength of this rotating force is derived by evaluating the "axis" parameter for the current time. The default force is defined using the equation f = 1000/s where "s" is the distance between center of the force field and the object in question. The force affects the object according to the Newtons laws of motion. The direction of it is defined using the "right hand rule". @endnode @node "R2.2.18" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.18 Collision SYNTAX / FFRI 0.7 | ICSM 2 +--------+ +----------+ | FREB 0.5 | Object |--| target1 |--< FMAS 10.5 / FFRI 0.7 +--------+\ +----------+ | VVEL 0 0 0 | ICSM 2 \+----------+ | VSPI 0 1 0 | FREB 0.5 | Level(M) | \ FSIZ 1.5 | FMAS 10.5 +----------+\ /| VVEL 0 0 0 \ / | VSPI 0 1 0 \+--------+ / \ FSIZ 1.5 | param1 |/ +--------+ Figure R2-19 PARAMETERS Objects with which the target objects can collide. TAGS FREB - Rebound Energy FFRI - Surface Friction ICSM - Collision Surface Sampling FMAS - Mass VSPI - Spin VVEL - Velocity FSIZ - Size of the bounding sphere VARIABLES m1 - mass of the collided parameter object m2- mass of the collided target object s - distance between COGs a, b, c - relative velocity vector (v2 - v1 ) i, j, k - relative spin e - relative kinetic energy t, u, v - current time o1, o2 - addresses of collided objects I - 1 = process collision, 2 = do not process collision, 3 = fatal error p1, p2 - addresses of internal collision data structures DESCRIPTION Non-interactive collision detection. Collisions are detected only between targets and parameter objects. The COLLISION method affects the motion of the particles using principles related to natural physical laws. Each collision transfers kinetic energy between the particles involved. The velocity of each particle after a collision is dependent on their initial velocities. In addition, velocity is converted to spin and vice versa depending on the shape of the objects and where they collide. The tag FREB defines a floating-point value which describes how the energy of motion is changed by the collision. The new velocity of the objects is the product of its/their current velocity and the average of the Rebound Energy. If both tags equal 1.0, the collision is totally elastic and no motion energy is lost. If both values are 0.0, collision is totally non- elastic and the particles "stick" together. Values greater than 1.0 means that the velocity of the particles increases for each collision. The tag which affects how the spin and velocity interact as particle surfaces "rub" against each other is FFRI. This is the "surface-friction" of each particle. The higher the value of this tag the more the velocity alters spin for each collision and vice versa. Both these properties can have any positive value. If they are absent then the default value for FREB is 1.0 and for FFRI is 0.0. Values between 0.0 and 2.0 for FFRI produce results resembling normal physical friction effects, with a value of 0.5 being typical. Values greater than 2.0 will produce un-natural or extreme surface-friction behavior. The final tag for controlling collision behavior is ICSM (Integer Collision Sampling). When two particles come within initial collision range their ICSM tags are checked. If present the tag determines how finely to spatially-sample the surfaces used for the surface-collision detection. The lowest sampling value of the particle pair is used. ICSM can have the following value: 0 - Default (same as ICSM absent) 1 - Increased sampling 2 - Maximal sampling For basic collisions where the particles collide and immediately rebound the default is adequate, but if particles "slide" or "roll" over each other, or if surface-friction effects are involved, then one of the higher values may be required to produce realistic results. If the spatial- sampling is not high enough then some surface penetration can result in incorrect collision effects. The user defined SFOR and SRPL formula/procedure can be used for customizing collision processing. The variable "I" is used for defining whether the collision should be processed. If the value of this variable is 1, collision is detected and will affect the velocities/spins of the collided objects. The value 2 indicates that no collision was detected. By having the value of this variable always at 2, the user defined formula can disable all collisions. The value of 0 indicates a fatal error and animation playing is cancelled. When using an RPL word as a collision hook function, the variables o1, o2 and p1, p2 provides the user with total control over collision processing. The variables o1 and o2 contain the addresses of objects between whom the collision detection should be applied. The variables p1 and p2 points to internal data structures described below where all data used for processing collisions can be found. This interface can be used for modifying velocities and spins of objects directly. Offset Field Size Description -------------------------------- 0 aObj 4 Address of the object 4 aCOG 4 Address of the COG of the object 8 aVel 4 Address of the VVEL tag value the object. 12 aSpi 4 Address of the VSPI tag value. 16 fSiz 8 Size of the bounding sphere of the object 24 fMas 8 Mass of the object -------------------------------- @endnode @node "R2.2.19" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.19 Int collision SYNTAX / FFRI 0.7 | ICSM 2 +--------+ +----------+ | FREB 0.5 | Object |--| target1 |--< FMAS 10.5 +--------+\ +----------+ | VVEL 0 0 0 \+----------+ | VSPI 0 1 0 | Level(M) | \ FSIZ 1.5 +----------+ Figure R2-20 PARAMETERS None TAGS FREB - Rebound Energy FFRI - Surface Friction ICSM - Collision Surface Sampling FMAS - Mass VSPI - Spin VVEL - Velocity FSIZ - Size of the bounding sphere VARIABLES m1 - mass of the collided parameter object m2 - mass of the collided target object s - distance between COGs a, b, c - relative velocity vector (v2 - v1) i, j, k - relative spin e - relative kinetic energy t, u, v - current time o1, o2 - addresses of collided objects I - 1 = process collision, 2 = do not process collision, 3 = fatal error p1 , p2 - addresses of internal collision data structures DESCRIPTION Interactive collision detection. Like the non-interactive collision detection this only modifies the velocity and spin of the particles involved. However, collisions are detected between all particles at the same level as the INT COLLISION method, and the motion of all colliding particles interact. SEE ALSO COLLISION @endnode @node "R2.2.20" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.20 Friction SYNTAX / VVEL 0 0 0 +--------+ +----------+/ | Object |--| particle |-- VSPI 0 0 0 +--------+\ +----------+\ FSIZ 0.5 \+----------+ \ FMAS 100 | Level(M) | +----------+ Figure R2-21 PARAMETERS None TAGS FMAS - mass FSIZ - size VVEL - velocity VSPI - spin VARIABLES x, y, z - COG (position) of the object a, b, c - velocity . i, j, k - spin d - size (diameter) m1 - mass dt - time interval (duration) e - kinetic energy f - coefficient of friction t, u, v - current time DESCRIPTION Frictional force evaluation. This method slows down the velocity and spin of objects at the same level. The SFOR tag can be used to define custom friction formulas. The variable f contains the default "coefficient of friction", the default value for this is evaluated using the following formula: d * e² f=------ d*e²+m This coefficient is used for modifying the velocity and the spin of objects according to the following formulas: vel(new) = vel(old) * (1 - f) spi(new) = spi(old) * (1 - f) In other words, the bigger the object, the higher the coefficient and the more the friction force slows it down. If the size of the object is 0, force would'nt affect it at all. The bigger the mass, the less the friction can affect the velocity of the object. The user defined formula/procedure can change the following variables: f - coefficient a, b, c - velocity i, j, k - spin All other variables are read only. @endnode @node "R2.2.21" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.21 CREATION SYNTAX / SDEL I=t>0.5 +--------+ +----------+/ | Object |--| target |-- VCRE 0 0 0 +--------+\ +----------+ \+----------+ | Level(M) |\ +--------+ / SCRE I=t>0 +----------+ \| sample |/ +--------+ Figure R2-22 PARAMETERS sample - Sample objects for procedural creation TAGS VCRE - creation time SCRE - formula used for procedural creation SDEL - formula used for procedural deletion VARIABLES x, y, z - position of the object a, b, c - velocity i, j, k - spin d - size m1 - mass dt - time interval e - kinetic energy t, u, v - current time fx, fy, fz - birdth day I - boolean value for deletion/creation DESCRIPTION This method is one of the most unusual of the built in methods. It actually creates and deletes objects during animations. Objects are created and deleted depending on how the SCRE String CREation formula tag evaluates for each parameter and how the SDEL (String DELetion formula) tag evaluates for each target. For each parameter object that the SCRE formula evaluates to a non-zero value then the object is created at the same level as the CREATION method; effectively becoming a target for possible deletion. For each target that the SDEL formula evaluates to a non-zero value then the object is deleted. If the parameters do not contain a SDEL formula or the formula never evaluates to non-zero, then this method will continue to create without deletion until the animation ends or the available memory is exhausted. If there isn't a SCRE tag associated with the parameter object, method never creates it. This makes it possible to use other methods for animating sample objects of creation method. For example, boiling water, fireworks etc. phenomena can be easily created this way. The tag VCRE is automatically created for all created targets for saving the birthday of the object in question. This information can be used for deleting objects according to their ages. The possibIe values for the variable "I" are: 1 - Object is either created or deleted depending on the tag in question (SCRE, SDEL) 0 - Object is not created or deleted All other variables are "read only". If there are SFOR or SRPL tags associated with the method object, they are processed after the SCRE and SDEL tags. @endnode @node "R2.2.22" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.22 Processor SYNTAX / VVEL 0.64-0 +--------+ +----------+/ | Object |--| particle |-- VSPI 0 0 0 +--------+\ +----------+ \+----------+ | Level(M) | +----------+ Figure R2-23 PARAMETERS None TAGS None VARIABLES a, b, c - velocity i, j, k - spin DESCRIPTION This method processes the motion properties of each target object into Move and Rotate transformations according to the Newtons laws of motion. If a velocity tag is associated with the target object, it is read and the object is moved according to the following formula: s v- => s=v*t t where "v" is the velocity of the object (VVEL), and "t" is a time interval between subsequent frames (animation samples). If a spin tag is associated with the target object, the object is rotated according to the following formula: 2*PI Rad w * t w=--------=>RAD=------ t 2 * PI where w is a spin defined by VSPI tag, "t" is the time interval, PI is 3.14 and "Rad" is the angle in radians. @endnode @node "R2.2.23" @title "Chapter 2 ANIMATION METHOD SYNTAX" 2.2.23 RPL SYNTAX +--------+ | Object |\ +--------+ \+------------+ | Object (M) |--- SRPL Proc +------------+ Figure R2-24 PARAMETERS The number and type of parameters required for this method are entirely dependent upon the implementation of the method procedure attached to it via the SRPL tag. VARIABLES Any DESCRlPTION A method whose method procedure is defined with a single line of RPL text. This method executes the user specified RPL "text" every time the object animation time is changed. This "text" acts as the method procedure. The "text" is just passed to RPL interpreter. It can contain a short interactive program, the name of a user defined RPL word or it can contain the "LOAD" word with a file-name; which loads and executes the actual program from the named file. The RPL interpreter for executing this "text" resides in the "Master" environment so it is necessary to use "INHERIT" if the word definition was created in an RPL window. The program should not contain any variable or word definitions because they will be redefined every time the method procedure is executed (which happens at least once per frame). @endnode @node "R3.1" @title "Chapter 3 RPL SYNTAX" Chapter3 RPL SYNTAX ------------------- Following prefixes are used for variables and constans to indicate the type of the variable. a - generic address b - byte (8 bits) e - either integer or floating-point value f - floating-point value i - long integer value (32 bits) I - boolean flag. 0 deNote:s FALSE, any other value deNote:s TRUE. s - address of a sting v - vector (consist of three floating-point values) w - short integer value (16 bits) CFA - Code Field Address. The address of a defined word on the Vocabulary Stack. name - The text for an RPL token (word or variable). NULL - The integer value zero. 3.1 KERNEL WORDS This sub-chapter contains the syntax and descriptions for all the general usage words built-in to RPL's vocabulary when a RPL window is initially opened. WORD ( TEMPLATE ( DESCRIPTION This defines the start of an RPL comment. All the text after it until either ")" or EOL is ignored. Note: The two comment control words "(" and ")" are defined internally and do not appear as part of the vocabulary. EXAMPLE ( this is a comment ) VLIST ( list vocabulary WORD ) TEMPLATE ) DESCRIPTION Terminates a comment before EOL reached. Other words can then follow. EXAMPLE 0 1 . ( top stack item, then second item ). WORD . TEMPLATE i. DESCRIPTION Takes a parameter off the stack and prints it as an integer value. EXAMPLE 10 . 15.5 . 10 20 30 1.2 .... SEE ALSO F.H.O.B. WORD .S TEMPLATE .S DESCRIPTION Prints the whole contents of the Parameter Stack without removing any values. WORD ! TEMPLATE iValue aVariable ! DESCRIPTION Assigns an integer value iValue to an integer variable aVariable. Integer and floating point variables must be referenced only with words that are for the variable type in question. For example, an integer variable MUST NOT be referenced using F! or F@, but only with ! and @. This is because the internal representations for similar integer and floating-point values are different. EXAMPLE VARIABLE MyVar ( define an integer variable ) SEE ALSO @ VARIABLE WORD & TEMPLATE & Word aWordAddr DESCRIPTION Retrieves the address of the specified word and places it on the stack. The word can then be stored in a variable and executed by EXECUTE. EXAMPLE : MyWord "Hello!" PUTS ; & MyWord EXECUTE SEE ALSO ?& EXECUTE WORD + TEMPLATE i2 i1 + iResult DESCRIPTION Takes two integers off the stack, adds them, and puts the sum on the stack. EXAMPLE VARIABLE MyVar 10 20 + MyVar ! ( MyVar = 10 + 20 ) WORD - TEMPLATE i2 i1 - iResult DESCRIPTION Takes two integers off the stack, subtracts the stack top value from the second one, and puts the difference on the stack. EXAMPLE 20 10-. WORD * TEMPLATE i2 i1 * iResult DESCRIPTION Takes two integers off the stack, multiplies them, and puts the product on the stack. EXAMPLE 3 4 * . WORD / TEMPLATE i2 i1 / iResult DESCRIPTION Takes two integers off the stack, divides the second value on the stack by the stack top item, and puts the integer part of the quotient on the stack. EXAMPLE 10 5 / . WORD : TEMPLATE : DESCRIPTION Begins a word definition. . The ":" is followed by a space and the name, which can be up to 15 characters, of the RPL word to be defined. The definition ends with a ";". EXAMPLE ( define RPL word ) : MyFunction "this is RPL word" PUTS ; ( call it ) MyFunction SEE ALSO ; WORD ; TEMPLATE ; DESCRIPTION Ends a word definition. SEE ALSO : WORD < TEMPLATE i2 i1 TEMPLATE i2 i1 <> IResult DESCRIPTION Takes two integer values off the stack and compares them. If the second value is not equal to the first value, <> puts TRUE on the stack, otherwise FALSE is put on the stack. EXAMPLE : MyTest ( i1 i2 ) <> IF "not equal" PUTS ELSE "equal values" PUTS ENDlF ; 10 20 MyTest ( not equal 5 5 MyTest ( equal values WORD = TEMPLATE i2 i1 = IResult DESCRIPTION Takes two integer values off the stack and compares them. If the values are equal, = puts TRUE on the stack, otherwise FALSE is put on the stack. EXAMPLE : IsEqual ( i1 i2 ) = IF "Yes" PUTS ELSE "No" PUTS ENDIF ; 10 20 IsEqual ( no 10 10 IsEqual ( yes WORD > TEMPLATE i2 i1 > IResult DESCRIPTION Takes two integer values off the stack and compares them. If the second value is greater than the first value, > puts TRUE on the stack, otherwise FALSE is put on the stack. EXAMPLE 10 20 >.(0 10 5 >.(1 WORD >= TEMPLATE i2 i1 >=IResult DESCRIPTION Takes two integer values off the stack and compares them. If the second value is greater than or equal to the first value, >= puts TRUE on the stack, otherwise FALSE is put on the stack. EXAMPLE : IsNegative (val) 0>= IF "yes"PUTS ELSE "no"PUTS ENDIF ; 10 IsNegative (no -1 IsNegative (yes 0 IsNegative (no WORD >R TEMPLATE e>R DESCRIPTION Takes the stack top values and stores it on the Return Stack as an integer value. SEE ALSO R> WORD >RAD TEMPLATE fDeg >RAD fRad DESCRIPTION Converts a value given in degrees to radians. EXAMPLE 180.0>RAD F.(3.141593 WORD ?& TEMPLATE ?& name a DESCRIPTION Retrieves the address of a given word. If the word is not found pushes a 0 onto the stack. EXAMPLE : DO_IF_FOUND ( executes word DOIT ( if it has been defined DOIT ?& ?DUP IF EXECUTE ENDIF ; SEE ALSO & EXECUTE WORD ?DUP TEMPLATE e ?DUP e e DESCRIPTION Duplicates the stack top value if it is not zero. SEE ALSO DUP WORD ?ELSE TEMPLATE ?ELSE DESCRIPTION In an interactive conditional structure marks the beginning of the block that is to be executed when the condition fails (i.e the flag tested is FALSE). SEE ALSO ?ENDIF ?IF ELSE ENDIF IF EXAMPLE ( define constant if not yet defined ) ?& MyVar NOT ?IF 1 CONSTANT MyVar ?ENDIF WORD ?ENDIF TEMPLATE ?ENDIF DESCRIPTION Ends an interactive conditional structure, either ?IF..?ENDIF or ?IF...?ELSE. .?ENDIF. SEE ALSO ?ELSE ?IF ELSE ENDIF IF WORD ?IF TEMPLATE I ?IF DESCRIPTION Begins an interactive conditional structure, . either ?IF..?ENDIF or ?IF..?ELSE..?ENDIF. If the flag is TRUE then the words entered after ?IF will be executed immediately until either ?ELSE or ?ENDIF is encountered. If the flag is FALSE, the words between ?IF and ?ELSE/?ENDIF are ignored. Execution then resumes after ?ELSE/?ENDIF. The interactive conditional structure remains active until ?ENDIF is encountered. These interactive conditional structures may be nested. Note: Interactive conditional structures can be used to control the execution of parts of an RPL file as it is loaded. EXAMPLE ( check if the word VADD is already defined ) ?& VADD ?IF "vectors.rpl already installed" PUTS ?ELSE "vectors.rpl" LOAD ?ENDIF SEE ALSO ?ELSE ?ENDIF ELSE ENDIF IF WORD @ TEMPLATE aInteger @ iValue DESCRIPTION Fetches the value of an integer variable and puts the value on the stack top. The address of the integer variable must be on the stack top before calling this word. EXAMPLE ( MyVar = MyVar + 1 ) MyVar @ 1 + MyVar @ ! SEE ALSO ! VARIABLE WORD AGAIN TEMPLATE AGAIN DESCRIPTION Marks the end of an BEGIN..AGAIN loop. The BEGIN..AGAIN loop executes forever unless a QUIT or EXIT is executed. Note: Can only be used inside a word definition. EXAMPLE : MyLoop BEGIN "YESlNO'" "Cancel Loop ?" GET_KEY IF EXIT ENDIF AGAIN ; SEE ALSO BEGIN EXIT QUIT WORD AND TEMPLATE I2 I1 AND I DESCRIPTION Takes two boolean flags off the stack and, if they both are TRUE, puts TRUE on the stack, otherwise puts FALSE on the stack. The value is TRUE if it is not zero. SEE ALSO IF OR XOR EXAMPLE 1 1 AND . ( 1 0 1 AND . ( 0 0 0 AND . ( 0 10 20 AND . ( 1 WORD ACOS TEMPLATE fRad ACOS fAng RETURNS fAng - value from 0 to PI DESCRIPTION Arccosine function. EXAMPLE 0.5 ACOS F. SEE ALSO ASIN, ATAN, COS WORD ASIN TEMPLATE fRad ASIN fAng RETURNS fAng - value from -PI/2 to PI/2 DESCRIPTION Arcsine function. EXAMPLE 0.5 ASIN F. SEE ALSO ACOS, ATAN, COS WORD ATAN TEMPLATE fRad ATAN fAng RETURNS fAng - value from -PI/2 to PI/2 DESCRIPTION Arctangent function. SEE ALSO ASIN, ACOS, TAN WORD B. TEMPLATE iB. DESCRIPTION Takes an integer off the stack and prints it as a binary number. SEE ALSO .H.O. EXAMPLE 1 B. (00000000000000000000000000000001 2 B. (00000000000000000000000000000010 3 B. (00000000000000000000000000000011 4 B. (00000000000000000000000000000100 - WORD B! TEMPLATE b aByte B! DESCRIPTION Stores a value in a byte variable. Takes the address of the variable and the value to be stored off the stack. Note: There are no byte variables in RPL. This word is needed only when accessing 8 bit data (like R,G,B) from data structures. SEE ALSO W! W@ B@ WORD B@ TEMPLATE aByte B@ iValue DESCRIPTION Fetches the value of a byte. The address of the byte must be in the stack top before calling this word. Note: See Note: for B!. SEE ALSO W! W@ B! WORD BAND TEMPLATE i2 i1 BAND i DESCRIPTION Makes a binary AND operation on the two operands and puts the result on the stack. In a binary AND operation, the result has only those bits set whose corresponding bits are set in both the operands. SEE ALSO BNOT BOR BXOR EXAMPLE 1 1 BAND (1 2 1 BAND (0 2 3 BAND (3 WORD BEGIN TEMPLATE BEGIN DESCRIPTION BEGIN marks the beginning of an indefinite loop. An indefinite loop can be any of the following: BEGIN..UNTIL BEGIN . .AGAIN BEGIN..WHILE..REPEAT In the BEGIN..UNTIL loop a flag is tested at the end of each repetition of the loop. If the flag is TRUE, the loop terminates. Otherwise the loop repeats. Since the test is made at the end of the loop, the loop will always be executed at least once. The BEGIN..AGAIN loop executes forever unless a QUIT or EXIT is executed. In the BEGIN..WHILE..REPEAT loop the words between BEGIN and WHILE are first executed, and then a flag is tested. If the flag is TRUE, the words between WHILE and REPEAT are executed and the loop starts over. If the flag is FALSE, then execution skips to the word that comes after REPEAT. Indefinite loops can be nested. Note: Can only be used inside a word definition. SEE ALSO UNTIL AGAIN WHILE REPEAT QUIT EXIT EXAMPLE : BeginUntil BEGIN "YeslNo" "Cancel Loop ?" GET_KEY UNTIL ; : BeginAgain BEGIN "YeslNo" "Cancel Loop ?" GET_KEY IF QUIT ENDIF AGAIN ; : BegWhlRpt BEGIN "YeslNo" "Continue ?" GET_KEY WHILE "hello" PUTS REPEAT ; WORD BNOT TEMPLATE i1 BNOT i DESCRIPTION Inverts the bits of a integer value on the stack. Any bits in the integer value that are set (1) are reset, and any bits that are reset (0) are set. SEE ALSO BAND BOR BXOR WORD BOR TEMPLATE i2 i1 BOR i DESCRIPTION Makes a binary OR operation on the two operands and puts the result on the stack. In a binary OR operation the result has all those bits set that have a corresponding bit set in either or both of the operands. SEE ALSO BNOT BAND BXOR WORD BXOR TEMPLATE i2 i1 BXOR i DESCRIPTION Makes a binary XOR (exclusive or) operation on the two operands and puts the result on the stack. In a binary XOR operation the result has those bits set that have a corresponding bit set in only one of the operands. SEE ALSO BNOT BAND BOR WORD CAT TEMPLATE s2 s1 CAT DESCRIPTION Concatenates two strings. Takes two pointers s1 and s2, and joins the string pointed to by s2 to the end of string pointed to by s1. The result is stored in s1. EXAMPLE 30 STRING NAME "Mary" NAME CPY " Smith" NAME CAT NAME PUTS SEE ALSO CPY PUTS SPRINTF STRING WORD CONSTANT TEMPLATE i CONSTANT name DESCRIPTION Defines a named integer constant and initializes it to the value popped off the stack. When the constant is later referenced by entering it's name, the value of the constant is pushed onto the stack. Note: This word is usually used outside word definitions. SEE ALSO VARIABLE FVARIABLE FCONSTANT WORD COS TEMPLATE f1 COS f DESCRIPTION Calculates the cosine of the stack top item. The operand must be in radians. SEE ALSO SIN EXAMPLE 3.16 SIN F. WORD CPY TEMPLATE s2 s1 CPY DESCRIPTION Copies a string. Takes two pointers s1 and s2, and copies the string pointed to by s2 to the string pointed to by s1. SEE ALSO CAT PUTS SPRINTF STRING EXAMPLE 100 STRING sBuf "Hello world" sBuf CPY sBuf PUTS WORD DEPTH TEMPLATE DEPTH i DESCRIPTION Puts the count of the stack items onto the stack. SEE ALSO RDEPTH WORD DO TEMPLATE i2 i1 DO DESCRIPTION Begins a definite loop, either DO..LOOP or DO..+LOOP A definite loop executes the words inside the loop a specified number of times. The beginning (i1) and ending (i2) values for the loop variable are put on the stack before the word DO. The loop variable can be referenced using the words I, J or K depending on the nesting level. Note: Can only be used inside a word definition. EXAMPLE : 5Times 5 0 DO I . LOOP ; SEE ALSO LOOP +LOOP I J K WORD DROP TEMPLATE e DROP DESCRIPTION Removes the top value from the stack. WORD DUP TEMPLATE e DUP e e DESCRIPTION Duplicates the stack top value retaining its type (i.e. integer or floating-point). SEE ALSO ?DUP WORD ELSE TEMPLATE ELSE DESCRIPTION In a conditional structure, marks the beginning of the block that is to be executed when the condition fails (i.e the flag tested is FALSE). Note: Can only be used inside a word definition. EXAMPLE : ABS ( i ABS i ) DUP 0 >= IF ELSE -1 * ENDIF ; SEE ALSO IF ENDIF WORD EMIT TEMPLATE i EMIT DESCRIPTION Prints the ASCII character corresponding to the first byte of the top stack value. EXAMPLE : CR 13 EMIT 10 EMIT ; ( carriage return and line feed ) "Hello" PUTS CR "World" PUTS CR WORD ENDIF TEMPLATE ENDIF DESCRIPTION Ends a conditional structure, either IF..ENDIF or IF..ELSE..ENDIF. Note: Can only be used inside a word definition. SEE ALSO IF ELSE WORD ERROR TEMPLATE sErrorMsg ERROR PARAMETERS sErrorMsg - error message to be printed DESCRIPTION Terminates the program as if an error had occurred and prints out the given error message. RPL programs can use this word for terminating code execution in situations which are not interpreted as errors by RPL. For example, if a procedural texture handler realizes that it cannot generate required color information for the renderer, it can call this word in order to cancel rendering. If the sErrorMsg is 0, no error message is printed. EXAMPLE RX RC @ IF "Return value is not zero" ERROR ENDIF WORD EVAL TEMPLATE sExpr EVAL f DESCRIPTION Evaluates an algebraic expression contained in the string pointed to by sExpr, and pushes the result on the stack. If the string contains multiple expressions then the last one evaluated determines the return value. The following operators are supported by the EVAL word: , - separator for multiple expressions ( - parentheses for controlling evaluation precedence ) - + - add - - subtract * - multiply / - divide - - negate ^ - power % - modulo += - x+=0.1 is same as x = x + 0.1 -= - *= - /= - && - logical AND II - logical OR = - assignment == - comparison is equal > - comparison greater than < - >= - comparison greater or equal <= - != - comparison not equal =if() - =if(a>b,t,f) if a > b then return t, otherwise f abs() - absolute value, for example abs(-10) produces 10 ceil() - returns smallest integer value which is >= x data() - interface to object and material data structures. exp() - exp(x) returns e^x floor() - greatest integer value which is <= x Ig() - log to base 10 In() - natural log max() - returns the greatest from the list min() - min(a,b,c,1,2) returns the smallest from the list a,b,c etc. sgn() - sign, sgn(x) is -1 if x < 0, 0 if x = 0 and 1 if x > 0 sqrt() - square root sum() - sum(1,2,3) = 6 cos() - trigonometric functions sin() - tan() - acos() - inverse trigonometric functions asin() - atan() - ceil() & floor() examples: ceil(1.4) returns 2, floor(1.4) returns 1 and ceil(-1.4) returns -1 data() By using the data() operator of EVAL, the properties of objects and materials and some global system values can be accessed. THE APPROPRIATE DATA STRUCTURE MUST BE LOCKED USING O LOCK OR MAT LOCK BEFORE USING THE data() OPERATOR TO ACCESS THEM. Objects The syntax for accessing object attributes through EVAL is: "data(/path/name->prop)" EVAL f EVAL again returns the address of the property if used without any expression assignment. Where: "/path/name" - Objects name including full absolute path. If the first character in data() is a slash, the name is assumed to refer to an object. Otherwise it is considered to be a material reference. "prop" - One of the following: R, G, B - Red, Green, or Blue color signal (0 .. 255) A - Alpha information reg - A register color for wire frame representation ptrn - A pattern for the line. Value must be between 0 and 65535 and each bit in pattern represents one pixel in the line to be drawn. If the first bit is set, then the first pixel in the line will be set. Thus a value of 65536 produces a solid line. Materials The syntax is as follows: "data(name->prop)" EVAL f If used without any expression assignment then EVAL will return the address of the material property. Where: "name" - The name of the material in the Material Library to be accessed. "prop" - Any of the material properties listed below: name - name (string field) imag - image (string field) splu - spline mapping u/v/width/height (0.0 .. 1.0) splv splw splh frex - texture frequency x (positive integer) frey - texture frequency y (positive integer) tr.r - transparency color R, G, B (0 .. 255) tr.g tr.b spec - specularity sbri - specular brightness bril - brilliance tran - transparency turb - turbidity tbsa - turbidity saturation refr - refraction roug - roughness dith - dithering scale bump - bump height (-100 .. 100) effc - effect maph - mapping handler mapa - constants for the mapping handler (floating-point) mapb scoh - scope handler scoa scob bmph - bump handler bmpa bmpb colh - color handler cola colb indh - index handler inda indb Values for all properties can vary between 0 .. 100, unless otherwise specified above. Handlers can contain values 0,1. 2 etc. depending on the number of choices in the corresponding cycle gadget in the Material Editor window (Default = 0, etc.). Global Data Global system data can also be accessed through EVAL. The following variables are defined for this purpose: T - Current Time (floating-point value) Res - Animation Resolution for animation (integer) Frm - Current Animation Frame (integer) EXAMPLE FVARIABLE X 0.02 X F! "0.5 * sin(2 * X) + cos(X)" EVAL F. "Real:Textures/wood1" "data(wood->image)" EVAL CPY "data(/Root/rectangle->R)=255" EVAL ( print out the number of frames ) "Res" EVAL F. ( reset the frame counter and discard ) "Frm=0" EVAL DROP ( the return value ) WORD EXECUTE TEMPLATE aCFA EXECUTE DESCRIPTION Executes a word given it's CFA. SEE ALSO &?& WORD EXIT TEMPLATE EXIT DESCRIPTION Terminates the execution of the current word, and returns control to the word that executed the current word. Note: Can only be used inside a word definition. EXAMPLE : TEST DUP 5 < IF DROP EXIT ENDIF . ; : LUP 10 0 DO I TEST LOOP ; SEE ALSO QUIT WORD EXP TEMPLATE fPar EXP fRet DESCRIPTION Raises the natural logarithm base E to the fPar power. WORD F. TEMPLATE f F. DESCRIPTION Takes a floating-point value off the stack and prints it. SEE ALSO .H.O.B. WORD F! TEMPLATE f aFloat F! DESCRIPTION Stores a value in a floating-point variable. Takes the address of the variable and the value to be stored off the stack. Note: See the Note: on ! SEE ALSO F@ FVARIABLE WORD F+ TEMPLATE f2f1F+f DESCRIPTION Takes two floating-point values off the stack, adds them, and puts the sum on the stack. WORD F- TEMPLATE f2 f1 F- f DESCRIPTION Takes two integers off the stack, subtracts the stack top value from the second one, and puts the difference on the stack. WORD F* TEMPLATE f2 f1 F* f DESCRIPTION Takes two floating-point values off the stack, multiplies them, and puts the product on the stack. WORD F/ TEMPLATE f2 f1 F/ f DESCRIPTION Takes two floating point values off the stack, divides the second value on the stack by the stack top item, and puts the quotient on the stack. WORD F< TEMPLATE f2 f1 F< I DESCRIPTION Takes two floating-point values off the stack and compares them. If the second value is less than the first value, F < puts TRUE on the stack, otherwise FALSE is put on the stack. WORD F<= TEMPLATE f2 f1 F<= I DESCRIPTION Takes two floating-point values off the stack and compares them. If the second value is less than or equal to the first value, F<= puts TRUE on the stack, otherwise FALSE is put on the stack. WORD F<> TEMPLATE f2 f1 F<> I DESCRIPTION Takes two floating-point values off the stack and compares them. If the second value is not equal to the first value, F <> puts TRUE on the stack, otherwise FALSE is put on the stack. WORD F= TEMPLATE f2 f1 F= I DESCRIPTION Takes two floating-point values off the stack and compares them. If the values are equal, F= puts TRUE on the stack, otherwise FALSE is put on the stack. WORD F> TEMPLATE f2 f1 F> I DESCRIPTION Takes two floating-point values off the stack and compares them. If the second value is greater than the first value, F > puts TRUE on the stack, otherwise FALSE is put on the stack. WORD F>= TEMPLATE f2 f1 F>= I DESCRIPTION Takes two floating-point values off the stack and compares them. If the second value is greater than or equal to the first value, F>= puts TRUE on the stack, otherwise FALSE is put on the stack. WORD F>I TEMPLATE f F>I i DESCRIPTION Takes a floating point value off the stack and pushes a corresponding integer value on the stack. SEE ALSO I>F WORD F@ TEMPLATE aFloat F@ f DESCRIPTION Fetches the value of a floating-point variable and puts the value on the stack top. The address of the floating-point variable must be on the stack top before calling this word. Note: See the Note: on ! SEE ALSO F! FVARIABLE WORD FCONSTANT TEMPLATE f FCONSTANT name DESCRIPTION Defines a named floating-point constant and initializes it to the value popped off the stack. When the constant is later referenced by entering it's name, the value of the constant is pushed onto the stack. Note: This word is usually used outside word definitions. SEE ALSO FVARIABLE VARIABLE CONSTANT WORD FMOD TEMPLATE f2 f1 FMOD f DESCRIPTION Takes two floating point values off the stack, divides the second value on the stack by the stack top item, and puts the remainder of the division on the stack. WORD FORGET TEMPLATE FORGET name DESCRIPTION Removes definitions from the vocabulary. All words that have been defined after the given word, as well as the word itself, are removed from the Vocabulary Stack. WORD FVARIABLE TEMPLATE FVARIABLE name DESCRIPTION Defines a named floating-point variable. The name of the variable must follow the word FVARIABLE. The RPL interpreter allocates memory from the Vocabulary Stack for storing the variable. The variable is initialized as 0.0. When the variable is later referenced by entering it's name, the address of the memory location that stores the variable's value is pushed onto the stack. Note: This word is usually used outside word definitions. SEE ALSO F! F@ FCONSTANT VARIABLE CONSTANT WORD H. TEMPLATE i H. DESCRIPTION Takes an integer off the stack and prints it as a hexadecimal number. SEE ALSO .O.B. WORD I TEMPLATE I i DESCRIPTION Inside a definite loop copies the value of the loop variable of the innermost loop onto the stack. Note: Can only be used inside a word definition. SEE ALSO J K WORD I>F TEMPLATE i I>F f DESCRIPTION Takes an integer value off the stack and pushes a corresponding floating-point value onto the stack. SEE ALSO F>I WORD IF TEMPLATE I IF DESCRIPTION Begins a conditional structure, either IF..ENDIF or IF..ELSE..ENDIF. In the former case, if the flag is TRUE then the words between IF and ENDIF are executed, and then the words after ENDIF. If the flag is FALSE, execution skips the words between IF and ENDIF. In the latter case, if the flag is TRUE then the words between IF and ENDIF are executed and then the words after ENDIF. If the flag is FALSE, the words between ELSE and ENDIF are executed and then the words after ENDIF. Conditional structures may be nested. Note: Can only be used inside a word definition. EXAMPLE : PrintSign DUP 0 < IF DROP "-" PUTS ELSE 0 > IF "+" PUTS ENDIF ENDIF ; -2 PrintSign 3 PrintSign 0 PrintSign SEE ALSO ELSE ENDIF WORD J TEMPLATE J i DESCRIPTION Inside a definite loop copies the value of the loop variable of the second innermost loop onto the stack. Note: Can only be used inside a word definition. EXAMPLE ( line feed and carriage return ) : CR 10 EMIT 13 EMIT ; : MULT TABLE 11 1 DO 11 1 DO I J * . LOOP CR LOOP ; SEE ALSO I K WORD K TEMPLATE K i DESCRIPTION Inside a definite loop copies the value of the loop variable of the third innermost loop onto the stack. Note: Can only be used inside a word definition. SEE ALSO I J WORD LEAVE TEMPLATE LEAVE DESCRIPTION Terminates a definite loop prematurely. The word LEAVE causes the definite loop to terminate at the next LOOP or +LOOP. Note: Can only be used inside a word definition. EXAMPLE ( terminates when I squared exceeds 50 ) : LUP 10 0 DO I DUP * DUP 50 > IF LEAVE ELSE DROP ENDIF . LOOP ; SEE ALSO EXIT QUIT WORD LOAD TEMPLATE sFile LOAD DESCRIPTION Loads a file containing RPL code. The effect is the same as if the text had been entered in the RPL window. The address of the string containing the file name is taken off the stack top. WORD LOG TEMPLATE fPar LOG fRet PARAMETER fPar - positive parameter value DESCRIPTION Takes the base E logarithm. The parameter fPar must be a positive value. SEE ALSO LOG10 WORD LOG10 TEMPLATE fPar LOG10 fRet PARAMETER fPar - positive parameter value DESCRIPTION Takes the base 10 logarithm. The parameter fPar must be a positive value. SEE ALSO LOG WORD LOOP TEMPLATE LOOP DESCRIPTION Ends a definite DO..LOOP loop. Note: Can only be used inside a word definition. SEE ALSO DO +LOOP I J K WORD +LOOP TEMPLATE i +LOOP DESCRIPTION Ends a definite DO.. +LOOP loop. This word is used when the loop variable must be incremented by values other than 1. +LOOP takes the stack top value and adds it to the loop variable. If the ending value is greater than the beginning value, then the loop is exited if the loop variable becomes greater than or equal to the ending value. If the ending value is less than the beginning value, then the DO..+LOOP is exited when the loop variable becomes less than or equal to the ending value. Note: Can only be used inside a word definition. EXAMPLE ( use negative increment ) : Down DO I. -1, + LOOP; 0 5 Down SEE ALSO DO LOOP I J K WORD MOD TEMPLATE i2 i1 MOD i DESCRIPTION Takes two integers off the stack, divides the second value on the stack by the stack top item, and puts the remainder of the division on the stack. WORD NOT TEMPLATE I1 NOT I2 DESCRIPTION Inverts a boolean value on the stack. If the flag is TRUE, it is replaced by FALSE and vice versa. Any value that is not equal to zero is regarded as TRUE. A value of zero is regarded as FALSE. SEE ALSO IF WORD O. TEMPLATE iO. DESCRIPTION Takes an integer off the stack and prints it as an octal number. SEE ALSO .H.B. WORD OR TEMPLATE I2 I1 OR I DESCRIPTION Takes two boolean flags off the stack and, if either one (or both) is TRUE, puts TRUE on the stack, otherwise puts FALSE on the stack. SEE ALSO IF AND XOR WORD OVER TEMPLATE e2 e1 OVER e2 e1 e2 DESCRIPTION Copies the second stack item to the stack top. SEE ALSO ROT ROLL PICK SWAP WORD PICK TEMPLATE i PICK e DESCRIPTION Gets a copy of a value on the stack. The copied value will be the i'th value BEFORE the operand for PICK was entered. EXAMPLE 10 9 8 7 .S 4 PICK .S SEE ALSO ROLL ROT SWAP OVER WORD POW TEMPLATE fPow fVal POW fRet DESCRIPTION Raises fVal to the fPow power. EXAMPLE 2 3 POW . ( 9 3 4 POW . ( 64 WORD PUTS TEMPLATE sPUTS DESCRIPTION Prints a string pointed to by s. SEE ALSO CAT CPY SPRINTF STRING WORD QUIT TEMPLATE QUIT DESCRIPTION QUIT terminates execution of the current word, empties all stacks and returns control to the interpreter. Note: Can only be used inside a word definition. SEE ALSO EXIT WORD RO TEMPLATE RO i DESCRIPTION Puts on the stack the starting address of the return stack. This is the address where the first item (usually a return address) on return stack is stored. SEE ALSO RDEPTH WORD R> TEMPLATE R> i DESCRIPTION Takes an integer value off the return stack and pushes it onto the Operand Stack. SEE ALSO >R WORD RANDOM TEMPLATE RANDOM f DESCRIPTION Returns a floating-point value between 0.0 and 1.0 inclusive and pushes it onto the stack. WORD RDEPTH TEMPLATE RDEPTH i DESCRIPTION Puts on the stack the count of the items on the return stack. SEE ALSO DEPTH WORD REPEAT TEMPLATE REPEAT DESCRIPTION Marks the end of a BEGIN..WHILE..REPEAT loop. Note: Can only be used inside a word definition. SEE ALSO BEGIN WHILE WORD ROLL TEMPLATE described below DESCRIPTION The word ROLL is used to rotate a given number (i) of stack items so that the i'th stack item becomes the stack top item and all the items between the first and the i'th item are moved one position deeper in the stack. The count i is on the stack top before executing ROLL. EXAMPLE 10 9 8 7 .S 3 ROLL .S SEE ALSO PICK ROT SWAP OVER WORD ROT TEMPLATE e3 e2 e1 ROT e1 e3 e2 DESCRIPTION ROT rotates the three topmost stack values so that the third item becomes the top item, and the first and the second item (counting from the stack top) will be the second and the third stack item, respectively. SEE ALSO ROLL SWAP OVER PICK WORD SO TEMPLATE SO i DESCRIPTION Puts on the stack the starting address of the operand stack. This is the address where the first item on operand stack is stored. SEE ALSO DEPTH WORD SIN TEMPLATE f1 SIN f2 DESCRIPTION Calculates the sine of the stack top item. The operand must be in radians. SEE ALSO COS WORD SQRT TEMPLATE fVal SQRT fRet PARAMETER fVal - Positive value DESCRIPTION Squareroot of fVal. EXAMPLE 9 SQRT . ( 3 16 SQRT . ( 4 WORD SPRINTF TEMPLATE e .. sFormat sResult SPRINTF DESCRIPTION This formats the operand list e . . using the format string specified by sFormat and stores the result in the string whose address is sResult. The operand list must be in REVERSE order as for all RPL word operands. The format string s1 controls the output format as follows: % start conversion specification. Then any of the following: - left adjust operand in its field. m digit string specifying minimum field width. . separator from field width and next digit string. n digit string specifying maximum number of characters or floating-point precision. Then a conversion character: c Operand is taken as a single character. d Operand is converted to decimal notation. e Operand is taken as floating-point and converted to decimal. f Operand is taken a floating-point and output as [-]mm.nnn where the number of digits for nnn is specified by the precision. g Use %e or %f whichever is shorter. o Operand is converted to unsigned octal notation. s Operand must be a string, and is stored until precision specification or the end of the string is reached. u Operand is converted to unsigned decimal notation. x Operand is converted to unsigned hexadecimal notation. Note: For more information about this word refer to a "C" Language reference manual. EXAMPLE 80 STRING Buffer 31 "Hello, I am %d years old" Buffer SPRINTF Buffer PUTS SEE ALSO CPY CAT PUTS STRING WORD STRING TEMPLATE i STRING name DESCRIPTION Allocates memory for a named string variable. The size of the memory to be allocated is popped off the stack. When the string variable is later referenced by entering it's name, the address of the first character of the string is pushed onto the stack. Note: This word is usually used outside word definitions. SEE ALSO CPY CAT PUTS SPRINTF WORD SWAP TEMPLATE e2 e1 SWAP e1 e2 DESCRIPTION Changes the order of the two stack top values. SEE ALSO ROT ROLL PICK OVER WORD TAN TEMPLATE f1 TAN f2 DESCRIPTION Tangent function SEE ALSO SIN, COS WORD UNTIL TEMPLATE I UNTIL DESCRIPTION Marks the end of a BEGIN..UNTIL loop. In the BEGIN..UNTIL loop a flag is tested at the end of each repetition of the loop. If the flag is TRUE, the loop terminates. Otherwise the loop repeats. Since the test is made at the end of the loop, the loop will always be executed at least once. Note: Can only be used inside a word definition. EXAMPLE ( scan through a list terminated by zero ) : ListScan BEGIN DUP DUP = IF .H ENDIF NOT UNTIL ; SEE ALSO BEGIN WORD VARIABLE TEMPLATE VARIABLE name DESCRIPTION Defines a named integer variable. The name of the variable must follow the word VARIABLE. RPL interpreter allocates memory from the Vocabulary Stack for storing the variable. The variable is initialized as 0. When the variable is later referenced by entering it's name, the address of the memory location that stores the variable's value is pushed onto the stack. Note: This word is usually used outside word definitions. SEE ALSO ! @ CONSTANT FVARIABLE FCONSTANT WORD VLIST TEMPLATE VLIST DESCRIPTION Lists the names of all words on Vocabulary Stack. WORD W! TEMPLATE w aWord W! DESCRIPTION Stores a value in an short integer variable. Takes the address of the variable and the value to be stored off the stack. This word can be used for accessing 16 bit integer fields, such as found from Real 3D's material and object data structures. Note: There are no word variables in RPL. This word is needed only when accessing 16 bit data from external data structures. SEE ALSO W@ B@ B! WORD W@ TEMPLATE aWord W@ i DESCRIPTION Fetches the value of a short integer. The address of the integer must be on the stack top before calling this word. Note: See Note: for W!. SEE ALSO W!B@B! WORD WHILE TEMPLATE WHILE DESCRIPTION In a BEGIN..WHILE..REPEAT loop a flag is tested at the WHILE word. If the flag is TRUE, the words between WHILE and REPEAT are executed and the loop starts over. If the flag is FALSE, then execution skips to the word that comes after REPEAT. Note: Can only be used inside a word definition. EXAMPLE : TILL_TEN ( i TIL_TEN ) BEGiN DUP 1 + 10 <= WHILE . REPEAT DROP ; SEE ALSO BEGIN REPEAT WORD XOR TEMPLATE I2 I1 XOR I DESCRIPTION Takes two boolean flags off the stack and, if one and only one of them is TRUE, puts TRUE on the stack, otherwise puts FALSE on the stack. SEE ALSO IF AND OR 3.2 OBJECT CREATION WORDS The following words allow all the REAL 3D objects to be created using RPL. These creation words can be recognized easily from the prefix "C_". The general syntax for all the creation words is the following: Geometry Color Attributes Tags C_XXXXX Address RPL constants required by these words are defined in the file "creation.rpl". The object data structure must be exclusively locked before using any of these words. @endnode @node "R3.2" @title "Chapter 3 RPL SYNTAX" 3.2.1 Geometry The structure of this section depends on the object in question and some objects like "links" and "levels" don't have this section at all. The purpose of this section is to describe the geometry for the object to be created. Although the structure is this section is different for all objects, they include some common data. 3.2.1.1 fStAngle & fEnAngle These parameters describe the angle of the sector in terms of the object space of the primitive starting from fStAngle around anti-clockwise to fEnAngle. These two floating-point operands are optional. If a sector primitive is required then bit 12 of iAttr must be set and these two operands must be supplied. Only the following quadric primitives can be sectored: cone cut-cone cylinder ellipse ellipse-segment hyperboloid 3.2.1.2 wGeomFlags This parameter describes additional geometry information for freeforms. wGF_CLOSEU - u dimension periodic: 0 - open, 1 - closed wGF_CLOSEV - v dimension periodic: 0 - open, 1 - closed wGF_SECTOR - set if sector primitive wGF_PERIODIC - open/closed evaluation for animations wGF_CLOSEU and wGF_CLOSEV flags can be used for closing freeform objects. If the flag is set, the curve/surface is closed in corresponding direction. Note: That curves are only sensitive to the flag wGF_CLOSEU. The wGF_SECTOR flag is set whenever the object is sector primitive. This flag tells to the evaluation system whether or not to treat the primitive as a sector. If the flag wGF_PERIODIC is set, closed curves are evaluated so that their end point is the same as their beginning point. In order to use closed loops for generating continous motions for loop-animations, set this flag. 3.2.1.3 wFreeType This specifies how the point data of a freeform is evaluated: wFT_POLYGON - polygonal line or surface wFT_PHONG - phong shaded surface (treated as polygonal for lines) wFT_BSPLINE - Cubic B-Spline curve/surface All other types are RESERVED. These freeform types correspond the radio-button gadgets in the Modify/ Freeform/Type requester. @endnode @node "R3.2.2" @title "Chapter 3 RPL SYNTAX" 3.2.2 iColor This section consists of four integer values defining a color for the object to be created. Whether or not this section should exists, depends on the object in question. The RPL format of this section is the following: bR bG bB bA ( Red Green Blue Alpha ) 3.2.3 Attributes This section is required by all creation words. The attributes data section consists of two different parameters: 3.2.3.1 Name The name of the object to be created can be up to 16 characters long. If a longer string is supplied, it will be truncated. 3.2.3.2 Object Flags The flags field is an integer value containing "yes/no" (on/off) kind of information for the object to be created. The bits in this parameter correspond the gadgets in the requester Modify/Properties/Attributes. Flag Description IOF_INVERTED Volume inverted in Boolean Operations IOF_PAINTED Surface properties affects in Booleans IOF_WFINVISIBLE Wire frame is invisible IOF_LIGHTSOURCE Object is a light source IOF_HOLLOW Represented as a surface instead of solid object IOF_INFINITE Infinite object IOF_SCENE Invisible in primary ray tracing IOF_RTINVISIBLE Ray tracing invisible IOF_NOBP1 No 1 st. bounding plane IOF_NOBP2 No 2nd bounding plane IOF_TEXTURE Primitive used for mapping textures to Absolute Space IOF SECTOR Sector Primitive IOF_PROTECTED Primitive cannot be modified IOF_SEGMENT Segment instead of sector IOF_NOTREFL Not reflected IOF_MOTION Motion Blurred object IOF_SHAdOWLESS Does not Cast Shadows IOF_MATTE Matte Object These bits correspond the toggle gadgets on the Attributes requester. However, there are additional properties which can be controlled from RPL. These are listed below: IOF_SECTOR The sector angle which is a part of the geometry definition of all quadric primitives is enabled, and the object cross-section becomes a sector of an ellipse. IOF_SEGMENT The Sector Angle is used to define the chord of an ellipse and the object cross-section of the quadric primitive becomes a segment. Any RESERVED bits must be left as zero for future compatibility. @endnode @node "R3.2.4" @title "Chapter 3 RPL SYNTAX" 3.2.4 Tags The tags section consists of a list of pairs of tag values and tag ID's in that order. The list must terminate with "CEND", which because of the RPN nature of the RPL language must be entered first. For example, possible materials and methods associated with objects are described using tags. The method can be associated with the object by using the SMTH tag whose value is any method name. This can either be a user-defined method or one of the built-in methods. If no SMTH tag is present then NONE is used as default. Built in method names: NONE PATH ROTATION SWEEP SIZE STRETCH DIRECTION MOVE & DIR TRIM CURVES SIMPLE SKELETON SKELETON INV KINEMATIC MORPHING OPEN MORPHING CLOSED TRANSFORM WAVE RADIAL FORCE DIRECTED FORCE TANGENT FORCE COLLISION INT COLLISION FRICTION CREATION RPL Materials can be associated with objects using the tag SMAT with the material name. For example, "wood1" "SMAT". 3.2.5 Return Value All the creation words return the address of the primitive created. If an illegal geometry is defined then RPL will terminate execution and raise an error. 3.2.6 Word Definitions WORD C_AIMPOINT TEMPLATE VPosition bR bG bB bA sName iAttr TagList C_AIMPOINT aObject WORD C_ATTRIB TEMPLATE iR, iG, iB, iA sName iAttr TagList C_ATTRIB aObject EXAMPLE ( create a texture with mapping type "Default" ) 255 255 255 0 ( RGBA ) "wood_texture" ( Name ) IOF_TEXTURE ( Attrib ) "CEND" ( Tags ) "wood" "SMAT" C_ATTRIB DROP WORD C_CONE TEMPLATE Vapex Va Vb Vaxis Vp Vm Vn [fStAngle fEnAngle] iR iB iG iA sName iAttr TagList C_CONE aObject EXAMPLE ( surface ) 1.50 1.50 2.00 (center) 0.50 0.00 0.00 ( a ) 0.00 0.50 0.00 ( b ) 0.00 0.00 -1.00 ( c ) ( bounding plane ) 1.50 1.50 1.00 ( p ) 0.00 0.50 0.00 ( m ) 0.50 0.00 0.00 ( n ) 255 255 255 0 ( RGBA ) "cone" ( name ) 0 ( attr ) "CEND" ( tags ) C_CONE DROP WORD C_COORDSYS TEMPLATE Vorigin Vx Vy Vz bR bG bB bA sName iAttr TagList C_COORDSYS aObject WORD C_CUBE TEMPLATE Vvertex0 Vvertex1 Vvertex2 Vdvect bR bG bB bA sName iAttr TagList C_CUBE aObject EXAMPLE ( create a cube animated by ) ( a RPL method MethodWord ) 2.00 3.01 0.00 ( first vertex ) 3.01 3.01 0.00 ( second vertex ) 2.00 2.00 0.00 ( third vertex ) 0.00 0.00 1.00 ( dvect ) 255 255 255 0 ( RGBA ) "cube" ( name ) 0 ( attr ) "CEND" "RPL" "SMTH" "MethodWord" "SRPL" ( See MTH_CREATE example ) C_CUBE DROP WORD C_CUTCONE TEMPLATE Vcentre Va Vb Vaxis Vp1 Vm1 Vn1 Vp2 Vm2 Vn2 [fStAngle fEnAngle] iR iB iG iA sName iAttr TagList C_CUTCONE aObject EXAMPLE ( create a sectored cut-cone ) ( surface ) -2.51 -0.50 2.50 (center) 0.50 0.00 0.00 ( a ) 0.00 0.50 0.00 ( b ) 0.00 0.00 -1.50 ( axis ) ( first bounding plane ) -2.51 -0.50 1.00 ( p1 ) 0.001 1.00 0.00 ( m1 ) 1.00 0.00 0.00 ( n1 ) ( second bounding plane ) -2.51 -0.50 2.00 ( p2 ) 0.00 1.00 0.00 ( m2 ) 1.00 0.00 0.00 ( n2 ) 0.00 4.71 ( angles ) 255 255 255 0 ( RGBA ) "cutcone" ( name ) IOF_SECTOR ( attr: sector ) "CEND" C_CUTCONE DROP WORD C_CUTPOLYMID TEMPLATE Vvertex0 Vvertex1 Vvertex2 Vvertex3 Vvertex4 Vvertex5 [Vvertexn ..] iCount bR bG bB bA sName iAttr TagList C_CUTPOLYMID aObject Note: iCount specifies the number of vertices on each polygonal face of the polymid, NOT the total number of vertices. There must be an equal number of vertices for both faces, or the geometry is illegal. WORD C_CUTPYRAMID TEMPLATE Vvertex0 Vvertex1 Vvertex2 Vvertex3 Vvertex4 Vvertex5 bR bG bB bA sName iAttr TagList C_CUTPYRAMID aObject WORD C_CYLINDER TEMPLATE Vcentre Va Vb Vaxis Vp1 Vm1 Vn1 Vp2 Vm2 Vn2 [fStAngle fEnAngle] iR iB iG iA sName iAttr TagList C_CYLINDER aObject WORD C_ELLIPSE TEMPLATE Vcentre Va Vb Vdvect [fStAngle fEnAngle] iR iB iG iA sName iAttr TagList C_ELLIPSE aObject WORD C_ELLIPSEG TEMPLATE Vcentre Va Vb Vaxis Vp1 Vm1 Vn1 Vp2 Vm2 Vn2 [fStAngle fEnAngle] iR iB iG iA sName iAttr TagList C_ELLIPSEG aObject WORD C_ELLIPSOID TEMPLATE Vcentre Va Vb Vaxis bR bG bB bA sName iAttr TagList C_ELLIPSOID aObject WORD C_GROUP TEMPLATE iIndx0 [iIndxn ..] iCount bR bG bB bA sName iAttr TagList C_GROUP aObject OPERANDS iIndxn - Indexes of the points of the freeform. DESCRIPTION Creates a sub-group primitive referring to the points of a freeform. One tag in must be SOBJ and its value must contain the path and name of the freeform. EXAMPLE 0.0 0.0 0.0 0.0 0.1 0.0 1.0 1.0 0.2 3 ( count ) 3 ( type ) 0 ( geometry flags ) 255 255 255 0 ( RGBA ) "line" ( name ) IOF_RTINVISIBLE ( attr: ) "CEND" ( tags ) C_LINE DROP ( point references ) 0 2 2 ( count ) 255 255 255 0 ( RGBA ) "line_group" ( name ) 0 ( attr: ) "CEND" ( tags ) "/Root/line" "SOBJ" C_GROUP DROP SEE ALSO C_LINE C_MESH WORD C_HYPERBOL TEMPLATE Vcentre Va Vb Vaxis Vp1 Vm1 Vn1 Vp2 Vm2 Vn2 [fStAngle fEnAngle] iRiBiGiA sName iAttr TagList C_HYPERBOL aObject WORD C_LEVEL TEMPLATE wBoolean sName iAttr TagList C_LEVEL aObject DESCRIPTION Creates a level with the attributes and tags supplied. The Boolean Operator type is specified by wBoolean as follows: wOT_AND wOT_OR Note: The level does not become the Current Level. EXAMPLE wOT_OR "mylevel" 0 "CEND" C_LEVEL DROP SEE ALSO: O_CURRENT WORD C_LINE TEMPLATE Vpt0 Vpt1 [Vptn ..] iCount wFreeType wGeomFIags bR bG bB bA sName iAttr TagList C_LINE aObject EXAMPLE ( points ) 1.00 -1.00 0.00 2.00 -1.00 0.00 2.00 -2.00 0.00 1.00 -2.00 0.00 4 ( count ) 3 ( type ) wGF CLOSEU ( geom. flags ) 255255 255 0 ( RGBA ) "mycurve" ( name ) 0 ( flags ) "CEND" C_LINE DROP Note: For B-spline lines there must be a minimum of four points. WORD C_LINK TEMPLATE sName iAttr TagList C_LINK aObject DESCRIPTION Create a symbolic link. One of the tags must be "SOBJ" and its value is the path and name for the object the link refers to. EXAMPLE "link" 0 "CEND" "/Root/rectangle" "SOBJ" C_ LINK WORD C_MESH TEMPLATE Vpt[0,0] Vpt[0,1] [Vpt[u,v] ..] Vpt[1,0] Vpt[1,1] [Vpt[u,v] ..] iU iV wFreeType wGeomFIags bR bG bB bA sName iAttr TagList C_MESH aObject OPERANDS iU, iV - number of points for each dimension of the mesh. Note: For a B-spline mesh there must be at least four points for each dimension. The total number of points for the mesh must be the product of iU and iV. EXAMPLE ( line 0 ) -0.50 0.50 0.00 -0.17 0.50 0.00 0.17 0.50 0.00 0.50 0.50 0.00 ( line 1 ) -0.50 0.17 0.00 -0.17 0.17 0.00 0.17 0.17 0.00 0.50 0.17 0.00 ( line 2 ) -0.50 -0.17 0.00 -0.17 -0.17 0.00 0.17 -0.17 0.00 0.50 -0.17 0.00 ( line 3 ) -0.50 -0.50 0.00 -0.17 -0.50 0.00 0.17 -0.50 0.00 0.50 -0.50 0.00 4 ( width ) 4 ( height ) 3 ( type ) 0 ( geom. flags ) 255 255 255 0 ( RGBA ) "mesh" ( name ) 0 ( attr: ) "CEND" C_MESH DROP WORD C_OFFSET TEMPLATE Vposition bR bG bB bA sName iAttr TagList C_OFFSET aObject EXAMPLE ( create blue light-point that doesn't cast shadows ) 0.0 0.0 0.0 ( position ) 35 35 255 0 ( RGBA ) "BlueLight" ( name ) IOF_LIGHTSOURCE IOF_SHADOWLESS BOR "CEND" C_OFFSET DROP WORD C_POLYGON TEMPLATE Vvertex0 Vvertex1 Vvertex2 [Vpt..] Vdvect iCount bR bG bB bA sName iAttr TagList C_POLYGON aObject WORD C_POLYHEDRON TEMPLATE Vvertex0 Vvertex1 Vvertex2 [Vvertexn ..] Vdvect iCount bR bG bB bA sName iAttr TagList C_POLYHEDRON aObject WORD C_POLYMID TEMPLATE Vvertex0 Vvertex1 Vvertex2 [Vvertexn ..] Vapex iCount bR bG bB bA sName iAttr TagList C_POLYMI D aObject WORD C_PYRAMID TEMPLATE Vvertex0 Vvertex1 Vvertex2 Vapex bR bG bB bA sName iAttr TagList C_PYRAMID aObject WORD C_RECTANGLE TEMPLATE Vvertex0 Vvertex1 Vvertex2 Vdvect bR bG bB bA sName iAttr TagList C_RECTANGLE aObject WORD C_TRISET TEMPLATE Vpt0 Vpt1 Vpt2 [Vptn ..] iCount iIndx0 iIndx1 iIndx2 [iIndxn iIndxo iIndxp ..] iF aceCount wFreeType bR bG bB bA sName iAttr TagList C_TRISET aObject OPERANDS iIndxn - Indexes of the points forming the faces iFaceCount - Number of index triplets DESCRIPTION This word is used internally for creating a mesh with a triangular face topology. There are no menu functions for this. It is possible to create RPL programs to convert the data structures of other 3D graphics programs that use triangular mesh topologies into REAL 3D meshes using this word. Note: wFreeType must specify either polygonal or phong type WORD C_VIEWPOINT TEMPLATE Vleft Vright Vdvect bR bG bB bA sName iAttr TagList C_VIEWPOINT aObject OPERANDS Vleft - position of left view for stereo vision pair Vright - right view Vdvect - direction of stereo vision pair DESCRIPTION Create a viewpoint consisting of a stereo vision pair. @endnode @node "R3.3" @title "Chapter 3 RPL SYNTAX" 3.3 MODIFICATION WORDS RPL constants for these words can be found from the file "modify.rpl". This set of words in the RPL vocabulary allow object properties to be modified. Their target objects are specified by one or more addresses on the stack. This list is terminated with NULL. Each word requires additional information to carry out its function. This information is specified with a common integer operand, whose bits are defined as follows: 3.3.1 Modify Flags FLAG DESCRIPTION IMF_ROTEXT Rotate & Extend if set IMF_NOSUB 0 - Modify sub-objects, 1 - Only modify targets IMF_NOCOG About COGs if set IMF_COGONLY With COGs if set IMF_BNDSIZE 0 - M_BEND Move, 1 - M_BEND Size IMF_PARABOL IMF_LINEAR IMF_SPHERE IMF_CURVE IMF_SIN All other bits are RESERVED and should be left as zero by the user for future compatibility. 3.3.2 Locking Object Data Before using any of the M words the data structure MUST be locked EXCLUSIVELY or conflict with other tasks may cause the system to crash. 3.3.3 Word Definitions WORD M_ALPHA TEMPLATE 0 aObject1 [...aObject] iA iFlags M_ALPHA OPERANDS iA - New alpha channel value for objects. DESCRIPTION Modifies so called "alpha channel" attribute of given objects. The value of iA must be between 0 and 255. EXAMPLE O_GETSEL ( objects ) 100 ( alpha ) 0 M_ALPHA WORD M_COLOR TEMPLATE 0 aObject1 [...aObject] iR iB iG iA iRegister iFlags M_COLOR OPERANDS iR iB iG iA - New color for objects iRegister - Register color for wire-frame DESCRIPTION Changes the color of given objects. EXAMPLE 0 "/Root/rectangle" O FIND ( objects ) 255 255 255 0 ( RGBA ) 2 ( register ) 0 M_COLOR WORD M_COPY TEMPLATE 0 aObject1 [aObjectn ..] M_COPY DESCRIPTION Copies the targets to the Clip Buffer. EXAMPLE O_GETSEL ( objects ) M_COPY WORD M_CUT TEMPLATE 0 aObject1 [aObjectn ..] M_CUT DESCRIPTION Cuts targets from the hierarchy and places them in the Clip Buffer. EXAMPLE O_GETSEL ( objects ) M_CUT WORD M_DELETE TEMPLATE 0 aObject1 [aObjectn ..] M_DELETE DESCRIPTION Deletes targets from hierarchy. EXAMPLE O_GETSEL ( objects ) M_DELETE WORD M_DUPLICATE TEMPLATE 0 aObject1 [aObjectn ..] aLevel iFlags M_DUPLICATE DESCRIPTION Duplicates given objects and inserts them in to the given object aLevel. EXAMPLE O_GETSEL ( objects ) O_GETCURR ( to ) 0 ( flags ) M_DUPLICATE WORD M_EXTEND TEMPLATE 0 aObject1 [aObjectn ..] vCentre vDirect fCoeff iFlIags M_EXTEND DESCRIPTION The targets are extended about Vcentre along the direction specified by Vdirect by the amount specified by fCoeff. EXAMPLE O_GETSEL ( objects ) 0.21 0.22 0 ( center ) 0.97 -0.25 0 ( direction ) -0.6 ( coefficient ) 0 ( flags ) M_EXTEND WORD M_MIRROR TEMPLATE 0 aObject1 [...aObjectn] vCentre iFlags M_MIRROR DESCRIPTION The targets are mirrored about a plane that passes through Vcentre, and in the direction specified by Vdirect. EXAMPLE O_GETSEL ( objects ) -0.03 0.78 0 ( center ) -0.58 -0.81 0 ( axis ) 0 ( flags ) M_MIRROR WORD M_MOVE TEMPLATE 0 aObject1 [...aObjectn] Vdelta iFlags M_MOVE OPERANDS Vdelta - vector defining direction and amount to move targets. EXAMPLE O_GETSEL ( objects ) 0.2 0.2 2 0 ( delta ) 0 ( flags ) M_MOVE WORD M_MOVECOG TEMPLATE 0 aObject1 [...aObjectn] vPosition iFlags M_MOVECOG OPERANDS vPosition - new position for targets' COGs. - REFERENCE 3.45 - EXAMPLE O_GETSEL ( objects ) -0.23 0.52 0 ( position ) 0 ( flags ) M_MOVECOG WORD M_NAME TEMPLATE 0 aObject1 [...aObjectn] sName iFlags M_NAME DESCRIPTION Renames ALL targets to the name specified by sName. EXAMPLE O_GETSEL ( objects ) "newname" ( name ) 0 ( flags ) M_NAME WORD M_PASTE TEMPLATE aLevel iFlags M_PASTE DESCRIPTION Pastes copies of the Clip Buffer into the object pointed by aLevel. EXAMPLE "/Root/rect*" O_FINDWLD M_CUT "/Root/Level" O_FIND 0 M_PASTE WORD M_ROTATE TEMPLATE 0 aObject1 [aObjectn...] vCenter vHor vVert vNorm iFlags M_ROTATE DESCRIPTION The targets are rotated and scaled to the coordinate system defined by vCenter, vHor , vVert and vNorm parameters. If the lenghts of vHor, vNorm and vVert vectors are 1, then the target objects are only rotated. For example, if the length of the vector vHor is 2, the the size of the objects is doubled in the d irection defined by vHor. The syntax of this word reflects the functions Modify/Linear/Rotate, Rot&Ext and Deform. EXAMPLE O_GETSEL ( objects ) -0.32 0.4 0 ( center ) 0.83 0.56 0 ( hor ) -0.56 0.83 0 ( vert ) 0 0 1 ( norm ) 0 ( flags ) M_ROTATE WORD M_SIZE2D TEMPLATE 0 aObject1 [aObjectn . .] vCenter vHor vVert fHCoeff fVCoef iFlags M_SIZE3D DESCRIPTION Changes the size of the targets in two dimensions about the center defined by vCenter. The directions in which the object is stretched are defined by the parameters vHor and vVert. This word reflects the internal implementation of the Modify/Linear/Size 2D function. EXAMPLE O_GETSEL ( objects ) -0.68 0.82 0 ( center ) 1 0 0 ( hor ) 0 1 0 ( vert ) 0.44 0.44 ( hf,vf ) 0 ( flags ) M_SIZE2D WORD M_SHEAR TEMPLATE 0 aObject1 [aObjectn...] vCenter vNorm vDir fCoeff iFlags M_SHEAR DESCRIPTION The targets are sheared in the direction defined by vDir parameter. The longer the distance between a point and vCenter in the direction defined by vNorm, the more it is moved along the vDir axis. The coefficient defines how much the targets are sheared. EXAMPLE O_GETSEL ( objects ) 0.28 0.36 0 ( center ) -0.92 -0.38 0 ( normal ) 0.38 -0.92 0 ( dir ) -0.83 ( coeff ) 0 ( flags ) M_SHEAR WORD M_SIZE3D TEMPLATE 0 aObject1 [aObjectn ..] Vcentre fCoeff iFlags M_SIZE3D DESCRIPTION Alter the size of the targets about the centre specified by Vcentre in all dimensions by the amount specified by fCoeff. EXAMPLE O_GETSEL ( objects ) -0.67 0.78 0 ( center ) 1.4 ( coefficient ) 0 ( flags ) M_SIZE3D WORD M_STRETCH TEMPLATE 0 aObject1 [aObjectn ..] vCentre vHor vVert vNorm vCoeff iFlags M_STRETCH DESCRIPTION Stretches objects in three dimensions. How much the object is stretched is defined independently in all three dimensions by the parameter vCoeff. For example, if the value of vCoeff is 0 1 0, then the size of object is doubled in the direction defined by vVert. EXAMPLE O_GETSEL ( objects ) 0 0.3 0 ( center ) 1 0 0 ( hor ) 0 1 0 ( vert ) 0 0 1 ( norm ) -0.02 -0.23 0 ( coeff ) 0 ( flags ) M_STRETCH WORD M_SWAP TEMPLATE iFlags M_SWAP DESCRIPTION Swaps the order of selected objects. This function corresponds the function Modify/Structure/Swap. EXAMPLE 0 ( flags ) M_SWAP @endnode @node "R3.4" @title "Chapter 3 RPL SYNTAX" 3.4 OBJECT WORDS These words are all for creating and manipulating object data structure in the hierarchy. 3.4.1 Return Value Excluding O_EVAL, O_DERIV and O_SCAN, possible return values are always addresses to the data structure the word relates to. If the word fails to execute because the operands are invalid, then it returns NULL. 3.4.2 Locking Data Structure THE OBJECT DATA STRUCTURE MUST BE LOCKED BEFORE ANY OF THE O_words IS USED. Failure to do so may cause RPL code to crash the system. Object data structure should be unlocked as early as possible, because locking prevents other tasks from accessing object data. If the user's RPL code only reads data structures, then shared access can be used. If the code modifies data (M_words, O_DELETE etc.), then exclusive access MUST be used. See: O_LOCK. 3.4.3 Word Definitions WORD O_CREATAG - Create Object Tag TEMPLATE aObject TagList O_CREATAG aTagAddr DESCRIPTION Creates and adds to the given object the given tags. The tags are defineds as pairs of a Tag Value and a Tag ID, and the list must be terminated with "CEND". The word returns the address of the last Tag ID created. Note: The address of the Tag Field is the address of the Tag ID + 4. If the tag is an integer (lxxx) then the Tag Field is the Tag Value, otherwise it is the address of the Tag Values. EXAMPLE ( create vector tag to the object "/Root/myobj" ) "/Root/myobj" O_FIND "CEND" 12.0 5.0 0.0 "VMyT" O_CREATAG DROP WORD O_CURRENT TEMPLATE aObject O_CURRENT aPrevCurr DESCRIPTION This makes the object specified by aObject the current level. It returns the address of the previous current level unless the object is a primitive with no sub-structure ( e.g. an ellipsoid ). EXAMPLE "/Car/Engine" O_FIND O_CURRENT WORD O_DELETE TEMPLATE aObject O_DELETE DESCRIPTION deletes the object whose address is aObject. Note: That NULL is a valid address for O_DELETE, in which case the word does nothing. EXAMPLE "/Root/myobj" O_FIND O_DELETE WORD O_DERIV TEMPLATE aParam VPSpace O_DERIV Vdir DESCRIPTION This returns the three floating-point values of the direction evaluated from the parameter aParam with the parameter values specified by VPSpace. The vector components of VPSpace correspond the r, s and t dimensions. Note: The operand aParam must point to an evaluable object or an error will follow. EXAMPLE ( get the address of a valid parameter ) "/Root/line" O_FIND ( specify the Parameter Space coordinates ) 0.5 0.0 0.0 O_DERIV F.F.F ( print out the direction ) WORD O_EVAL TEMPLATE aParam VPSpace O_EVAL Vpoint DESCRIPTION This returns the three floating-point values of the point evaluated from the parameter aParam with the parameter values specified by VPSpace. The vector components of VPSpace correspond to the r (Time), s and t dimensions. Note: The operand aParam must point to a valid parameter or an error will result. EXAMPLE ( get the address of a valid parameter ) "/Root/ellipse" O_FIND ( specify the Parameter Space coordinates ) 0.5 0.0 0.0 O_EVAL WORD O_FIND TEMPLATE sName O_FIND aObject DESCRIPTION Attempts to find an object by its name. If an object is found, its address is pushed onto the stack. If not found, NULL is returned. EXAMPLE : MyRename ( sNewName sOIdName ) O_FIND DUP IF bOFO_NAME + CPY ELSE DROP ENDIF ; "myrect" "/Root/Level/rectangle" MyRename WORD O_FINDTAG TEMPLATE aObject sTagID O_FNDTAG aTagAddr - REFERENCE 3.50 - DESCRIPTION Attempts to find the tag specified by sTagID from the object specified by the address aObject. It returns the address of the Tag ID if the tag is found. note: See O_CRETAG for Note: S about Tag ID, Tag Field and Tag Values. EXAMPLE : TagTest "/Root/Level" O_FIND "FMAS" O_FNDTAG IF "Yes" PUTS ELSE "FMAS not found" PUTS ENDIF ; WORD O_FINDWILD TEMPLATE sWild O_FINDWILD 0 aObject1 [aObjectn ..] DESCRIPTION Attempts to find objects whose name matches the given wild-card, and pushes the address for each match onto the stack. Zero is used for terminating this address list. The wild-card characters available are: * - any number of any characters ? - any single character . - current level .. - parent level / - level separator Note: The list of object addresses can be used directly by the M_words. EXAMPLE ( move all objects at the current level ) ( whose name ends with "le" ) "* le" O_FINDWILD 0.10 0 0 M_MOVE REFRESH WORD O_GETCUR TEMPLATE O_GETCUR aCurrent DESCRIPTION Returns the address of the current level. EXAMPLE ( pop up one level ) O_GETCUR O_GETPAR O_CURRENT WORD O_GETNEXT TEMPLATE aObject O_GETNEXT aNextObj DESCRIPTION Returns the address of the next object in the hierarchy at the same level as aObject, unless the object was the last in which case NULL is returned. EXAMPLE : PrintLevel ( aLevel ) O_GETSUB BEGIN DUP WHILE DUP bOFO_NAME + PUTS O_GETNEXT REPEAT DROP ; ( print objects inside the current level ) O_GETCUR PrintLevel WORD O_GETPAR TEMPLATE aObject O_GETPAR aParent DESCRIPTION This returns the address of the of the parent of the object pointed by aObject unless there is no parent i.e. aObject is the Root level. Note: This works only if the object is linked to the object data structure. WORD O_GETPREV TEMPLATE aObject O_GETPREV aPrevObj DESCRIPTION This takes a pointer to an object as its operand, and returns a pointer to the previous object at the same hierarchy level. If there is no previous object, NULL is returned. Note: Due to the internal implementation, it is faster to fetch the address of the next object than the previous one. This word works only if the object is linked to the object data structure. WORD O_GETSEL TEMPLATE O_GETSEL 0 aObject1 [aOjectn ..] DESCRIPTION Returns a list of obJect addresses to the selected obJects. The list is terminated with zero. EXAMPLE ( move selected obJects ) O_GETSEL 0.1 1.0 0 0 M_MOVE REFRESH WORD O_GETSUB TEMPLATE aObJect O_GETSUB aFirstSub DESCRIPTION This returns the address of the first sub-object of aObject unless it contains no sub-obJects, in which case 0 is returned. WORD O_LOCK TEMPLATE iAccess O_LOCK DESCRIPTION Locks or unlocks the obJect data structure (hierarchy) according to the value of iAccess as specified below: LOCK_REMOVE - Unlocks the obJect data LOCK_EXCLUSIVE - Tries to lock the data exclusively so that no other task can access it. If the data is already locked, the task in question goes to sleep. LOCK_SHARED - Tries to get shared access to the data structure. Several tasks can access the data structure if they all use shared access. For more details about locking and task access See: "Amiga ROM Kernel Reference Manual: Exec" EXAMPLE LOCK_EXCLUSIVE O_LOCK ( lock object data "/Root/re*" O_FIND O_DELETE ( delete object LOCK_REMOVE O_LOCK ( unlock ) SEE ALSO MAT_LOCK WORD O_PROP TEMPLATE aObject IProperty O_PROP .... PARAMETERS aObject - pointer to object IProperty - flags defining what properties the word should fetch: iOP_COG - Center of gravity iOP_ SIZE - Size of the object iOP_ DIR - direction iOP_MASS - the mass of the object. RETURNS The number of return values depends on the IProperty flags as follows: Property Return value iOP_COG A vector iOP_DIR Three vectors (coordinate system) defining the object space iOP_SIZE A float value defining the radius of the bounding sphere iOP_MASS A float value defining the mass of the object Parameters are pushed on the stack in this order. DESCRIPTION Takes the object and property flags and returns corresponding properties of the object on the stack. EXAMPLE ( Print out the size of the current level O_GETCURR iOP_SIZE O_PROP F. ( Print out the size and the mass ( of the current level O_GETCURR iOP_MASS iOP_SIZE BOR O_PROP F.F. ( word printing the distance between ( given objects : PrintDist ( aObj1 aObj2 ) iOP_COG O_PROP ( COG of the 1st object 4 ROLL iOP_COG O_PROP ( COG of the 2nd obJect VSUB ( subtract COGs VLEN ( length of the vector F. ; WORD O_SCAN TEMPLATE aObject aCFA O_SCAN e DESCRIPTION Object scan and execute. This parses the hierarchical structure of the object pointed to by aObject and executes the RPL word pointed by aCFA for each sub-object. The RPL word executed receives the address of the current obJect as a parameter on the stack and must return a non-zero value to continue the scan or zero to stop. O_SCAN returns the value from the executed word. EXAMPLE : PrintName bOFO_NAME + PUTS ( print the name ) 1 ( return 1 to continue scanning ) ; "/Root" O_FIND & PrintName O_SCAN DROP WORD O_SELECT TEMPLATE 0 aObJect1 [aObJectn ..] O_SELECT DESCRIPTION Objects whose address is supplied as an operand become selected. Note: This word is useful for creating macros which select targets for menu function modifications. EXAMPLE ( find and select all rectangles ) ( at the current level ) "rectangle*" O_FINDWILD O_SELECT REFRESH @endnode @node "R3.5" @title "Chapter 3 RPL SYNTAX" 3.5 ANIMATION WORDS WORD ASPEC TEMPLATE iFrameResol fStartTime sFileName iFlags sFormatString sScrName sFrameComm iCurrFrame iSamples fSeconds ASPEC DESCRIPTION Animation settings. The parameters of this word correspond the contents of the Animation window. iFlags parameter can contain the following bits: iAF_SAVE - save rendered frames iAF_WIRE - preview iAF_GOTO - go directly to given EndTime EXAMPLE 40 ( frame resolution ) 0 ( current time ) "ram:test" ( filename ) iAF_SAVE ( flags ) "%s%d" ( format ) "Real.1" ( screen name ) "" ( frame command ) 0 ( current frame ) 0 ( samples ) 1.0 ( seconds ) ASPEC 0 0 1.0 PLAY ( play the animation ) SEE ALSO PLAY WORD PLAY TEMPLATE aObject aMethod fEndTime PLAY PARAMETERS aObject, aMethod - Set these to NULL fEndTime - time value between 0 ... 1 DESCRIPTION Plays the animation to the given time using the current animation settings. If the given time is less than the current time, the animation is played backwards. Note: The first two parameters MUST be set to 0 for future compatibility. EXAMPLE : Forwars 0 0 1.0 PLAY ; : Backwards 0 0 0.0 PLAY ; : DoTwice Forwards Backwards ; DoTwice WORD MTH_CREATE TEMPLATE aWord sName MTH_CREATE aMthAddr DESCRIPTION Creates a custom method to REAL 3D's Method list. The new method can then be assigned to objects as if it was one of the built-in methods. The a Word operand contains the address of the RPL word to be used by the method and sName specifies the name of the custom method as it will appear on the list. This can be up to 15 characters long; if a longer string is supplied, it will be truncated. The word returns the address of the method data. When an animation is played, this word is called with the following syntax: aNewTime aMthTime aMthObj aParentObj XXXXXXX where aNewTime - the address of the vector defining the new time. aMthTime - the address of the vector describing the current method time. If aNewTime is different than aMthTime, the method should "do something". aMthObj - the address of the object to which the method procedure was associated. aParObj - the address of the parent object of aMthObj. Also the following variables are defined during the animation: o1 - method object o2 - parent object t, u, v - new time fx, fy, fz - method's current time dt - time interval EXAMPLE : ColorProc 0 o2 @ ( address of object to be modified t 255 * ( R RANDOM 255 * ( G t 6.28*SIN 127 * 128 + ( B 0 ( A 2 ( register color 0 ( iFlags M_COLOR ; & ColorProc "Color" MTH_CREATE DROP WORD MTH_DELETE TEMPLATE aMthAddr MTH_DELETE DESCRIPTION Deletes the custom method specified by aMthAddr from the Method list. WORK MTH_FIND TEMPLATE sName MTH_FIND aMthAddr DESCRIPTION Returns the address of the method given its name. Note: Do not use this word if you don't know the internal structure of the method. @endnode @node "R3.6" @title "Chapter 3 RPL SYNTAX" 3.6 I/O WORDS WORD FIL_LOAD TEMPLATE sFile iSections iReplace FIL_LOAD DESCRIPTION Loads the data sections specified by the bits of iSections from a REAL 3D Binary Format IFF file defined by the name sFile. The variable iReplace defines which sections replace the existing ones and which sections are inserted. The bits of iSections and iReplace select the Data Sections (REAL 3D IFF HUNKS) in the following way: HUNK DESCRIPTION RSCR Screens RWIN Windows RINF Measuring System RSTT Global Settings RGRI Grids RREN Render Settings RANI Animation Settings RATT Default Primitive Attributes ROBJ Objects RMTR Materials RCOL Named Colors RRPL RPL Text Note: The Version Hunk RVRS is always loaded. EXAMPLE "io.rpl" LOAD ( insert all sections found ) "MyProject" IRIO_ALL 0 FIL_LOAD ( insert all except objects ) "MyProject" IRIO_ALL IRIO_ROBJ FIL_LOAD WORD FIL_SAVE TEMPLATE sFile iSections iFlags FIL_SAVE DESCRIPTION Saves the data sections specified by the bits of iSections to the file specified in sFile using REAL 3D binary format. Note: See FIL_LOAD for the data sections bits and Note:s about iFlags. FIL_SAVE always saves the Version Hunk. @endnode @node "R3.7" @title "Chapter 3 RPL SYNTAX" 3.7 MATERIAL WORDS WORD MAT_CREATE TEMPLATE sName wSpecularity wSpecBright wBrilliance wTransparancy wTurbidity wRefraction wCurlndex wEffect wRESERVED wRoughness wFlags wTurbSatur wMapMethods wRESERVED wFreqX wFreqY fSplineU fSplineV fSplineW fSplineH wRESERVED sImage bR bG bB bA wBumpHeight wDither wScopeHandle sScopeExpr fScope_a fScope_b wMapHandle sMapExpr fMap_a fMap_b wBumpHandle sBumpExpr fBump_a fBump_b wIndexHandle sIndexExpr fIndex_a fIndex_b TagList MAT_CREATE aMaterial OPERANDS wFlags The bits of this integer specify various material properties. wMTF_TRANCOL wMTF_UNSHADED wMTF_TILEX wMTF_TILEY wMTF_FLIPX wMTF_FLIPY wMTF_GRADEX wMTF_GRADEY wMTF_SPLINEMAP wMTF_SCOPEMASK wMTF_NOREFL wMTF_EXCL wMTF_SMOOTH wMapMethods The bits of this integer specify the mapping types: wMM_COLOR wMM_BUMP wMM_BRILL wMM_TRANSP wMM_CLIP wMM_SHADOW wMM_ENVIRONM DESCRIPTION Creates a material in the material library using the name specified with sName. It returns the address of the material created. WORD MAT_DELETE TEMPLATE aMaterial MAT_DELETE DESCRIPTION Deletes the material pointed by aMaterial from the material library. WORD MAT_FIND TEMPLATE sName MAT_FIND aMaterial DESCRIPTION Searches the material specified by sName from the material library and returns its address, or zero if the search failed. WORD MAT_LOCK TEMPLATE iAccess MAT_LOCK DESCRIPTION Locks or unlocks the material data structure (material library) so that tasks can access it safely. Note: THE MATERIAL DATA STRUCTURE MUST BE LOCKED BEFORE ANY ACCESS FROM RPL CODE. Failure to do so may cause RPL code to crash the system. The material data structure should be unlocked as soon as possible, because locking prevents other tasks from accessing it. If the RPL code only reads materials then shared access can be used. If it changes materials, (MAT CREATE, MAT DELETE etc.), then exclusive access MUST be used. See: 4.4 O_LOCK for details of locking and iAccess. @endnode @node "R3.8" @title "Chapter 3 RPL SYNTAX" 3.8 MISCELLANEOUS WORDS WORD ERR_INSTALL TEMPLATE aErrHook ERR_INSTALL PARAMETERS aErrHook - address of the word to be called when an error occurs DESCRIPTION Installs a new error hook word to the RPL environment. When an error occurs the defined word is called. The number of possible hooks is not restricted in any way and they are called so that the hook installed first is called last. The called error hook word is removed by the system. This word is usually needed for error handling. If a RPL program allocates any system resources, it should also deallocate them when the program is terminated. Note: Error hooks cannot be nested. In other words, you cannot install error hook word for another error hook word. SEE ALSO ERR_REMOVE EXAMPLE VARIABLE aMem : MyErrHook "All Right" "This is my own error handler" GET_KEY DROP aMem @ 512 MEM_FREE ; : DoSomething ( allocate some memory ) 512 0 MEM_ALLOC aMem ! ( install error hook ) & MyErrHook ERR_INSTALL ( then do something which causes error ) #@!)=? ( this is the normal exit procedure ) ( when everything went OK ) & MyErrHook ERR_REMOVE aMem @ 512 MEM_FREE ; DoSomething WORD ERR_REMOVE TEMPLATE aErrHook ERR_REMOVE PARAMETERS aErrHook - address of the RPL word installed with ERR_INSTALL DESCRIPTION Removes an error hook word from the RPL environment. If the given RPL word is not installed, an error message is produced. SEE ALSO ERR_INSTALL EXAMPLE : MyErrHandler ( .... ) ; & MyErrHandler ERR_INSTALL ( .... ) & MyErrHandler ERR_REMOVE WORD MEM_ALLOC TEMPLATE iSize iFlags ALLOC aAddr PARAMETERS iSize - the amount of memory to be allocated iFlags - must be 0 RETURNS aAddr - the addres of the allocated memory DESCRIPTION Allocates given amount of memory from the system and returns the address of the allocated hunk. If allocation fails, 0 is returned. SEE ALSO MEM_FREE EXAMPLE VARIABLE aMyStr : AllocExample ( allocate 64 bytes of memory 64 0 MEM_ALLOC aMyStr ! aMyStr @ 63 "Enter any string" GET_STR IF aMyStr @ PUTS ENDIF aMyStr @ 64 MEM_FREE ; WORD MEM_FREE TEMPLATE aAddr iSize MEM_FREE PARAMETERS aAddr - the address of the memory to be freed iSize - the size of the memory to be freed DESCRIPTION Frees the memory allocated by MEM_ALLOC. SEE ALSO MEM_ALLOC WORD INHERIT TEMPLATE sName INHERIT DESCRIPTION The operand sName must be a valid RPL Environment (e.g. an existing RPL Window). The current RPL environment then inherits the vocabulary from this environment. When RPL looks for a word, the local vocabulary will be searched first, then any inherited definitions will be examined. INHERIT does not enable closed inheritance "loops". If an environment attempts to INHERIT from an environment that has already inherited the first one, then INHERIT will be ignored. There is one special RPL Environment called "Master" which is used for processing Macros and AREXX commands. This environment is created automatically by REAL 3D and does not have a window associated with it. EXAMPLE "RPL.1" INHERIT WORD MENU TEMPLATE iMenu iItem iSubItem MENU DESCRIPTION This word executes the menu function specified by the operands exactly as if it was selected using the mouse. Menus are numbered from zero starting from the top left. Menu separators are counted as menu items. All three operands must be supplied even if there is no Sub-Menu. For a listing of the menu items and their three selection operands see the appendix B. EXAMPLE 2 2 1 MENU ( MODIFY/Properties/Name ) WORD REFRESH TEMPLATE REFRESH DESCRIPTION Refreshes all windows using their individual refresh settings. WORD RENDER TEMPLATE RENDER DESCRIPTION Renders all Views using their individual render settings WORD ROT_COORD TEMPLATE fxAngle fyAngle fzAngle aCoord ROT_COORD DESCRIPTION This rotates three vectors Vx, Vy, Vz in an array pointed by aCoord, around each other by the angles (in radians) specified by fxAngle, fyAngle & fzAngle. First Vy and Vz are rotated around Vx by fxAngle, then in the resulting system Vz and Vx are rotated around Vy by fyAngle etc. Note: Used extensively by the RPL Libraries. WORD SCR_SAVE TEMPLATE sScreen sFile SCR_SAVE I DESCRIPTION Saves the screen having the name sScreen to the file whose name is defined by sFile. It returns TRUE if the screen was found and saved, otherwise it returns FALSE. EXAMPLE "Real3D" "RAM:Real3D.IFF" SCR_SAVE WORD SYSTEM TEMPLATE sCLI SYSTEM DESCRIPTION This passes the string sCLI to the OS CLI for execution. EXAMPLE "SYS:Tools/IconEdit" SYSTEM WORD WND_ADDR TEMPLATE sName WND_ADDR aWnd PARAMETERS sName - the name of any window RETURNS aWnd - the address of the window DESCRIPTION Returns the address of the window whose name is aName. If the window cannot be found, returns NULL. Note: Don't use this word if you don't know the internal structure of the window in question. WORD WND_OPEN TEMPLATE iType sName iLeft iTop Width iHeight WND_OPEN PARAMETERS iType - the type of the window to be opened. Can be one of the following: iWT_SELECT iWT_PROJECT iWT_PROJECTSB iWT_PROJECTBL iWT_SHELL iWT_TOOL iWT_ANIMCTRL iWT_COLCTRL iWT_PROJECTDB iWT_MATCTRL iWT_SCRCTRL sName - Name for the window. iLeft, iTop - Top left edge of the window wWidth, iHeight - Size of the window DESCRIPTION Opens a Real 3D window. EXAMPLE ( open the select window ) "editor.rpl" LOAD iWT_SELECT "MyWindow" 100 10 150 100 WND_OPEN WORD WND_SENDMSG TEMPLATE 0 aPn ... aP1 aWndName iMsglde WND_SENDMSG iMsgNum PARAMETERS 0 aPn ... aP1 - the addresses of parameters to be passed with the message aWndName - a string defining the target windows iMsglde - a message identifier. Can be one of the following: iWM_ACTIVATE iWM_GETDATA iWM_INTUIMSG iWM_DIE RETURNS iMsgNum - a number of messages sent. DESCRIPTION Sends a message to given windows. The parameter list maximally consists of 5 addresses of parameters. An address 0 means that there are no more parameters to be passed. The purpose and amount of parameters depends on the message in question. The window name can include wildcards so that it is possible to send the message to more than one window. The return value indicates the number of messages sent. EXAMPLES Bring the palette window to the front and activate it: 0 "Color" WM_ACTIVATE WND_SENDMSG DROP Kill the "Color" window: 0 "Color" WM_DIE WND_SENDMSG DROP MyView window to front if exists. If not, create it: 0 "MyView" iWM_ACTIVATE WND_SENDMSG NOT IF iWT_VIEW "MyView" 10 10 300 200 WND_OPEN ENDIF WORD RAY_INTERS - Ray/surface intersection TEMPLATE aHandle avPos avDir avlnters avNorm RAY_PREP iResult PARAMETERS aHandle - a handle from the RAY_PREP word avPos - the address of a vector defining the position of the ray avDir - the address of a vector defining the direction of the ray avInters - the address of a vector to contain the intersection point avNorm - the address of a vector to contain the surface normal in the intersection point RETURNS iResult - TRUE if intersection was detected, FALSE if no intersection found. DESCRIPTION Executes an intersection test between a given obJect (aHandle) and a given ray (avPos and avDir). If no intersection was found, FALSE is pushed on the stack. Otherwise the variables avPos and avDir contain the position and the normal vector of the surface where the intersection between object and ray was detected. Note: This word can be used for creating "behavioral" animations where objects observe their living environment making decisions and conclusions depending on the information they receive. For example, a flying object can try to avoid hitting other objects a RPL method using this word. EXAMPLE ( check if there is an object ) ( somewhere in front of us ) VVARIABLE vPos VVARIABLE vDir VVARIABLE vHit VVARIABLE vNrm VARIABLE iHnd 100 STRING sBuff : MyCollTest ( prepare intersection ) "/Root/Enemy" RAY_PREP iHnd ! ( shoot some rays ) 0 0 0 vPos V! ( start point of the ray ) 1 0 0 vDir V! ( direction of the 1 st ray ) iHnd vPos vDir vHit vNrm RAY_INTERS IF vHit V@ "Hit found in position %g %g %g" sBuff SPRINTF sBuff PUTS ENDIF 0 1 0 vDir V! ( direction of the 2nd ray ) iHnd vPos vDir vHit vNrm RAY_INTERS IF vHit v@ "Hit found in position %g %g %g" sBuff SPRINTF sBuff PUTS ENDIF ( free intersection handle ) iHnd @ RAY_FREE ; SEE ALSO RAY_PREP, RAY_FREE WORD RAY_FREE - Free a ray intersection handle TEMPLATE aHandle RAY_FREE PARAMETERS aHandle - pointer to a ray intersection handle DESCRIPTION Deallocates the data structures needed for ray intersection testing. EXAMPLE VARIABLE RayHandle "/Root/Tube" O_FIND RAY - PREP RayHandle ! .... RayHandle @+RAY_FREE SEE ALSO RAY_INTERS, RAY_PREP WORD RAY_PREP - prepare a ray/surface intersection handle TEMPLATE aObJect RAY_PREP aHandle PARAMETERS aObJect - a pointer to an object RETURNS aHandle - A ray intersection handle DESCRIPTION Prepares data structures needed for ray intersection testing SEE ALSO RAY_INTERS, RAY_FREE WORD LIB_CALL TEMPLATE TagList iOffset iLibBase LIB_CALL OPERANDS TagList - Tag Values are addresses of operand data and Tag IDs are register names. e.g. "A0", "D0" etc. iOffset - Function offset in the library iLibBase - Library base-pointer DESCRIPTION Calls a library function using the given operands. The tag values are addresses so that RPL variables can be used to pass the operands for the library function, and return values are passed back through the same variables. EXAMPLE VARIABLE IntuiBase VARIABLE ScrOpernd 0 "intuition.library" LIB _OPEN IntuiBase ! 0 ScrOpernd ! "CEND" ( terminate tag list ) ( See Amiga ROM Kernel Ref: AutoDocs ) ScrOpernd "D0" 96 ( See Amiga ROM Kernel Ref: Exec ) IntuiBase @ ( Intuition lib. base pointer ) LIB_CALL ( call DisplayBeep(0) ) IntuiBase @ LIB_CLOSE WORD LIB_CLOSE TEMPLATE iLibBase LIB_CLOSE OPERANDS iLibBase - Library base-pointer DESCRIPTION Closes an OS library. Note: If iLibBase does not point to an open library when the word is called, system will crash. WORD LIB_OPEN TEMPLATE Version sName LIB_OPEN iLibBase OPERANDS iVersion - The version number of the library sName - The name of the library RETURNS iLibBase - The library base-pointer DESCRIPTION Attempts to open an OS library and returns the base-pointer if succeeds in opening, otherwise returns NULL. @endnode @node "R3.9" @title "Chapter 3 RPL SYNTAX" 3.9 USER INTERFACE WORDS WORD BUSY_CANCEL TEMPLATE aHnd BUSY_CANCEL iBool PARAMETERS aHnd - a return value from the BUSY_OPEN word RETURNS iBool - TRUE or FALSE (1/0) DESCRIPTION Checks whether or not the user has pressed the CANCEL gadget of a given busy requester. If the gadget is pressed, TRUE is pushed on the stack, otherwise FALSE. SEE ALSO BUSY_OPEN, BUSY_CLOSE, BUSY_UPDATE EXAMPLE VARIABLE aBusyHnd : BusyTest 100 0 DO aBusyHnd @ "Rendering..." I BUSY_UPDATE ( Rendering ) aBusyHnd @ BUSY_CANCEL IF LEAVE ENDIF LOOP aBusyHnd @ BUSY_CLOSE ; WORD BUSY_CLOSE TEMPLATE aHnd BUSY_CLOSE PARAMETERS aHnd - a return value from the BUSY_ OPEN word DESCRIPTION Closes a given busy requester. SEE ALSO BUSY_OPEN, BUSY_UPDATE, BUSY_CANCEL EXAMPLE aBusyHnd @ BUSY_CLOSE WORD BUSY_OPEN TEMPLATE sHeader BUSY_OPEN aHnd PARAMETERS sHeader - title string RETURN aHnd - address of the busy requester. DESCRIPTION Opens a busy requester with the given header text and returns a handle which can be used for updating the busy requester and checking whether the user has requested cancelling. SEE ALSO BUSY_CANCEL, BUSY_CLOSE, BUSY_UPDATE EXAMPLE VARIABLE aHnd : MyAnimation "Rendering Animation..." BUSY_OPEN aHnd ! 100 0 DO O_GETSEL 0.1 0 0 0 M_MOVE REFRESH aHnd @ 0 I BUSY_UPDATE LOOP aHnd @ BUSY_CLOSE ; WORD BUSY_UPDATE TEMPLATE aHnd aNewHdr iPer BUSY_UPDATE PARAMETERS aHnd - a return value from the BUSY_OPEN word NewHdr - a new a header text for the requester iPer - value between 0 and 100. DESCRIPTION Updates the contents of the busy requester. If the aNewHdr parameter is not 0, then it is assumed to be the address of the new header text for the requester. If it is NULL, the header text of the requester is not changed. The iPer parameter must be between 0 and 100. SEE ALSO BUSY_OPEN, BUSY_CLOSE, BUSY_CANCEL EXAMPLE VARIABLE aBusyHnd : BusyTest "Optimizing ..." BUSY_OPEN aBusyHnd ! 100 0 aBusyHnd @+0 I BUSY_UPDATE ( Optimizing ) LOOP 100 0 DO aBusyHnd @ "Rendering..." I BUSY_UPDATE ( Rendering ) LOOP aBusyHnd @ BUSY_CLOSE ; WORD GET_KEY TEMPLATE aGadTxts aHdrTxt GET_KEY iRetVal PARAMETERS aGadTxts - string defining gadgets to be created. Gadget texts are separated by the character "I". aHdrTxt - Headline string for the requester. RETURN iRetVal - integer corresponding the selected gadget. The value corresponding the first (leftmost) gadget is 1 and the return value corresponding the rightmost gadget is 0 (cancel/negative choice should always be the rightmost one as suggested by the Amiga Style Guide). Intermediate gadgets/return values are incremented by one from left to right. DESCRIPTION Opens a requester with a given header text and gadgets, waiting the user to select one of them. The function returns a value corresponding the selected gadget. EXAMPLE "FIRSTlSECONDlTHIRDlCANCEL" "Select One of These" GET_KEY. WORD GET_FLT TEMPLATE aFIt aHdr GET_FLT iRetVal PARAMETERS aFIt - pointer to a floating point aHdr - headline text string for the requester RETURN iRetVal - TRUE of FALSE depending on the user's action EXAMPLE Opens a requester allowing the user to define a floating point value. Formula evaluation is supported. EXAMPLE ( define float variable ) FVARIABLE MyFIt : MyTest 3.14 MyFlt F! MyFlt "Define Angle" GET_FLT IF MyFlt F@ F. ENDIF ; MyTest WORD GET_STR TEMPLATE aStr iLen aHdr GET_STR iRet PARAMETERS aStr - a pointer to a buffer iLen - the maximum lenght of the string (lenght of the buffer - 1 ) aHdr - a header text for the requester RETURN iRet - 1 or 0 depending on the user's choice. DESCRIPTION Opens a requester allowing the user to define a string. - REFERENCE 3.69 - EXAMPLE ( create an object with custom name ) "creation.rpl" LOAD 16 STRING ObjNam : MyTest "Noname" ObjNam CPY ObjNam 16 "Create Object" GET_STR IF wOT_OR ObjNam 0 "CEND" C_LEVEL DROP ENDIF ; WORD GET_VECT TEMPLATE aVct aHdr GET_VECT iRet PARAMETER aVct - pointer to a vector (an array of 3 floating points) aHdr - a header text for the requester RETURN iRet - TRUE or FALSE depending on the user's choice. DESCRIPTION Opens a requester allowing the user to define three floating point values, in other words a 3D vector. Formula evaluation is supported. EXAMPLE ( move selected objects ) "vectors.rpl" LOAD VVARIABLE vDelta : MyTest 0.0 1.0 3.1 vDelta V! vDelta "Move Selected Objects" GET_VECT IF O_GETSEL vDelta F@ 0 M_MOVE ENDIF ; WORD GET_FILE TEMPLATE iType aNam aDir aHdr GET_FILE iRet PARAMETER iType - One of the follwing action qualifiers: iIO_READ - Selection is used for reading iIO_WRITE - Selection is used for writing iIO_DIR - Selection is used for defining a path aNam - pointer to an initial file name/result string aDir - pointer to an initial directory path aHdr - a header text for the requester RETURN iRet - TRUE or FALSE depending on the user's choice. DESCRIPTION Opens a file requester on a given DOS drawer (directory) allowing the user to select a file name. If the user moves in the hierarchy, the contents of the buffer pointed by "iDir" is updated accordingly. If the user selects OK, the buffer pointed by "iNam" will contain the complete file name (including the path). Note: That both buffers should be large enough to hold the result strings. EXAMPLE ( load a Real 3D IFF file ) "io.rpl" LOAD 256 STRING Name 256 STRING Path : MyLoad "myfile" Name CPY "r3d2:projects" Path CPY iIO_READ Name Path "Load something" GET_FILE IF ( replace all sections: ) Name IIO_RALL IIO_RALL FIL_LOAD ENDIF ; MyLoad @endnode @node "R3.10" @title "Chapter 3 RPL SYNTAX" 3.10 WORDS WORD RX TEMPLATE sPrg RX PARAMETER sPrg - string defining the arexx program to be executed DESCRIPTION This word sends a given ARexx program to the ARexx manager process as if it was typed in from an Amiga DOS shell using the rx command. Note: That if the RX word does not return 0, it is not automatically interpreted as an error situation. The reason for this is that some applications use the return value for indicating something else than an error. EXAMPLE "ADDRESS COMMAND dir" RX "RENDER" RX SEE ALSO RX_RC WORD RX_RC TEMPLATE RX_RC - aRetVal RETURNS aRetVal - The address of the return value DESCRIPTION This word can be used for fetching the return value from a previously executed RX word. RX_RC returns the address of an integer variable containing the result. EXAMPLE ( send ARexx command ) "ADDRESS STANDALONE RENDER" RX RX_RC @ ( fetch return value ) IF ( terminate the RPL program ) "ERROR:Cannot Execute" ERROR ENDIF Note: Although the word returns the address of the return value, currently it does not make sense to assign a return value to ARexx commands arriving to Real 3D's ARexx port. WORD RX_RESULT TEMPLATE RX_RESULT - aResStr RETURNS aResStr - Address of the result string DESCRIPTION This word can be used for accessing the result string variable of Real 3D. The word returns the address of the result string. RPL programs can read this variable after each sent ARexx message in order to detect the possible result strings returned by external applications. The word can also be used for passing a result string to an external application who have sent an ARexx message to the ARexx port of Real 3D. Note: That a result string is returned only if it is requested by the command sender application. Furthermore, all commands do not return a result string even if it is requested. If the ARexx command sent to Real 3D fails, result string is NOT returned. In other words, the result string is valid only if the return code indicates that no error occurred during command processing. EXAMPLE .... "RX ( send ARexx command ) RX_RC @ ( fetch return value ) IF "ERROR:Cannot Execute" ERROR ENDIF RX_RESULT PUTS ( process result string ) WORD RX_SETCLIP TEMPLATE sName sValue RX_SETCLIP PARAMETERS sName - Address of the name string sValue - Address of the value string DESCRIPTION This word can be used for putting new items to the Clip List or updating existing ones. Each item in the Clip List consists of a pair of strings defining a name and a value for the item. The Clip List can be used for passing information between Real 3D and ARexx and is typically used whenver two or more result strings are needed. EXAMPLE "rad" "0.5" RX_SETCLIP "position", "0.5, 0.8, 0.0" RX_SETCLIP - REFERENCE 3.72 - @endnode @node "R3.11" @title "Chapter 3 RPL SYNTAX" 3.11 VECTOR OPERATIONS These words are defined in the file "vectors.rpl". WORD VVARIABLE TEMPLATE VVARIABLE name DESCRIPTION Defines a vector variable. The name of the variable must follow the word VVARIABLE. The variable is initialized as 0 0 0. A vector variable is an array of three floating point variables. When the variable is later referenced by entering its name, the address of the first floating point is pushed onto the stack. EXAMPLE VVARIABLE myVector SEE ALSO v@ V! WORD V! TEMPLATE fX fY fZ aVariable V! PARAMETERS fX fY fZ - three values defining a vector aVariable - an address of the vector variable DESCRIPTION Store a vector in a variable. EXAMPLE VVARIABLE myVar 0 0 1.5 myVar V! WORD v@ TEMPLATE aVariable v@ fX fY fZ PARAMETERS aVariable - the address of a vector variable RETURNS fX fY fZ - contents of the variable DESCRIPTION Fetch a vector from a given address. EXAMPLE ( print the value of vMyVar ) vMyVar F@ V. WORD VADD TEMPLATE v1 v2 VADD vRes PARAMETERS v1 v2 - two vectors to be added RETURNS vRes - result vector DESCRIPTION Vector addition. Pulls two vectors off the stack and pushes the result vector back. EXAMPLE VVARIABLE v1 VVARIABLE v2 VVARIABLE vRes 1 0 0 v1 V! ( v1 = 1 0 0 ) 0 1 0 v2 V! ( v2 = 0 1 0 ) v1 V@ v2 V@ VADD vRes V! ( vRes = v1 + v2 ) WORD VSUB TEMPLATE v1 v2 VSUB vRes PARAMETERS v1 , v2 - vectors to be subtracted RESULT vRes - result DESCRIPTION Pulls two vectors off the stack, subtracts them and pushes the result back onto the stack. EXAMPLE 10 5.0 0.5 ( v1 ) 5 5.0 0.5 ( v2 ) VSUB V. WORD VMUL TEMPLATE v f VMUL vRes PARAMETERS v - a vector to be multiplied f - a scalar value RESULT vRes = v1 * f DESCRIPTION Multiplies a vector by a scalar. In other words, each component of the given vector "v" is multiplied by the given float "f" and the result is pushed onto the stack. EXAMPLE ( duplicate the length of a vector ) 1.5 3.1 8.2 2.0 VMUL V. WORD VDOT TEMPLATE v1 v2 VDOT fRes PARAMETERS v1, v2 - two vectors to be operated RESULT fRes - Dot product of given vectors DESCRIPTION Pulls two vectors off the stack, executes dot product and pushes the result (a floating point value) back onto the stack. EXAMPLE ( dot product of perpendicular vectors = 0 ) 1 0 0 0 1 0 VDOT F. WORD VCROS TEMPLATE v1 v2 VCROS vRes PARAMETERS v1, v2 - two vectors RESULT vRes - result vector DESCRIPTION Cross product. The result vector is always perpendicular to the operands v1 and v2. EXAMPLE 1 0 0 0 1 0 VCROS V. ( result = 0 0 1 ) WORD VNORM TEMPLATE v VNORM vRes PARAMETERS v - vector to be normalized RESULT vRes - unit vector DESCRIPTION Vector normalization. The given vector is divided by its length and the result is pushed back on to the stack. The lenght of the result vector is always 1. EXAMPLE 120.2 10.2 -2.1 VNORM WORD VLEN TEMPLATE v VCROS fLen PARAMETERS v - any vector RESULT fLen - the length of "v" DESCRIPTION Pulls the given vector off the stack and puts the length of it back to the stack. EXAMPLE 10 20 30 VLEN F. WORD V. TEMPLATE v V. PARAMETERS v - vector DESCRIPTION Pulls a vector ( three float values ) off the stack and prints them out. WORD VCONSTANT TEMPLATE VCONSTANT name DESCRIPTION Defines a vector constant. EXAMPLE ( some useful constants ) 1 0 0 VCONSTANT vX 0 1 0 VCONSTANT vY 0 0 1 VCONSTANT vZ vX V. @endnode @node "R4.1" @title "Chapter 4 GEOMETRIC OBJECT PROPERTIES" Chapter 4 GEOMETRIC OBJECT PROPERTIES ------------------------------------- 4.1 GEOMETRIC PROPERTIES 4.1.1 Surface Definition The vectors and points of the data structure of each visible describe the mathematical surfaces that form the basis for the final visible surfaces that are produced by rendering. The surface definition can be modified by the various modification functions and boolean operations. How the data structure describes each surface of a visible is given in the following figures and text. 4.1.2 COG The center of gravity of each primitive occupies one vector. The tag MCOG can be used for overriding the default value. 4.1.3 Direction This property is defined by two vectors perpendicular to each other. The tags DDIR and DDIV can be used to redefine the defaults. The property describes the local obJect space coordinate system. 4.1.4 Size One floating-point value is used to define the size of each object. This represents the radius of a spherical volume that can contain the entire object. For a level, this bounding sphere encloses its sub-obJects. The default can be overridden with the FSIZ tag. For more information about tags see the reference chapter 5. 4.2 DEFAULT GEOMETRIC PROPERTIES The following text and diagrams describe the default geometric properties for each primitive and how the data structure relates to the surface definition. All the calculations shown involve vector arithmetic, and the following symbols are used: ASC - Absolute Spatial Coordinate ptn - Point on a line pt[u,v] - Point from a mesh vn - Vertex of a geometric solid The other symbols relate to the data structure of the primitive. PRIMITIVE : aimpoint, offset COG : position DIR : ASC z DIV : ASC x Figure @{"R4-1:" system "display dh9:docs/r3ddoc/r3dv2pics/R4-1"} (PICTURE: R4-1) PRIMITIVE : cone COG: 0.3*center + 0.7*(intersection of the axis and the bounding plane) DIR : axis DIV : a PRIMITIVE : coordsys COG : origin DIR : z DIV : x Figure @{"R4-2:" system "display dh9:docs/r3ddoc/r3dv2pics/R4-2"} (PICTURE: R4-2) PRIMITIVE : cube COG : average of vertices DIR : dvect DIV : v1 - v0 Figure @{"R4-3:" system "display dh9:docs/r3ddoc/r3dv2pics/R4-3"} (PICTURE: R4-3) PRIMITIVE : cut-cone, cylinder, ellipse-segment, hyperboloid COG : average of p1 & p2 DIR : axis DIV : a Figure @{"R4-4:" system "display dh9:docs/r3ddoc/r3dv2pics/R4-4"} (PICTURE: R4-4) PRIMITIVE : cut-polymid COG : average of vertices DIR : vector between polygonal surface centers DIV : v1 - v0 Figure @{"R4-5:" system "display dh9:docs/r3ddoc/r3dv2pics/R4-5"} (PICTURE: R4-5) PRIMITIVE : cut-pyramid COG : average of vertices DIR : vector between the rectangular surface centers DIV : v1 - v0 Figure @{"R4-6:" system "display dh9:docs/r3ddoc/r3dv2pics/R4-6"} (PICTURE: R4-6) PRIMITIVE : ellipse COG : center DIR : dvect DIV : a Figure @{"R4-7:" system "display dh9:docs/r3ddoc/r3dv2pics/R4-7"} (PICTURE: R4-7) PRIMITIVE : ellipsoid COG : center DIR : axis DIV : a PRIMITIVE : group COG : average of indexed points DIR : vector between 1 st & 2nd indexed points DIV : ILL-DEFINED PRIMITIVE : level COG : average of all sub-obJect COGs unless empty DIR : DIR of 1 st sub-obJect unless empty DIV : DIV .. .. .. .. .. .. Figure @{"R4-8:" system "display dh9:docs/r3ddoc/r3dv2pics/R4-8"} (PICTURE: R4-8) PRIMITIVE : line COG : pt0 DIR : pt1 - pt0 DIV : ILL-DEFINED PRIMITIVE : link COG : fetched from target DIR : .. .. .. DIV : .. .. .. Figure @{"R4-9:" system "display dh9:docs/r3ddoc/r3dv2pics/R4-9"} (PICTURE: R4-9) PRIMITIVE : mesh COG : average of all points DIR : (pt[1 ,0] - pt[0,0]) x (pt[0, 1] - pt[0,0]) DIV : pt[1 ,0] - pt[0,0] Note : x - vector cross product Figure @{"R4-10:" system "display dh9:docs/r3ddoc/r3dv2pics/R4-10"} (PICTURE: R4-10) PRIMITIVE : polygon COG : average of vertices DIR : dvect DIV : v1 - v0 Figure @{"R4-11:" system "display dh9:docs/r3ddoc/r3dv2pics/R4-11"} (PICTURE: R4-11) PRIMITIVE : polyhedron COG : aver age of vertices DIR : dvect DIV : v1 - v0 Figure @{"R4-12:" system "display dh9:docs/r3ddoc/r3dv2pics/R4-12"} (PICTURE: R4-12) PRIMITIVE : polymid COG : average of vertices and apex DIR : vector between base-center and apex DIV : v1 - v0 Figure @{"R4-13:" system "display dh9:docs/r3ddoc/r3dv2pics/R4-13"} (PICTURE: R4-13) PRIMITIVE : pyramid COG : 0.3*apex + 0.7*base-center DIR : vector between base-center and apex DIV : v1 - v0 Figure @{"R4-14:" system "display dh9:docs/r3ddoc/r3dv2pics/R4-14"} (PICTURE: R4-14) PRIMITIVE : rectangle COG : average of vertices DIR : dvect DIV : v1 - v0 PRIMITIVE : triset COG : average of all points DIR : direction of 1 st face DIV : direction of 2nd face Figure @{"R4-15:" system "display dh9:docs/r3ddoc/r3dv2pics/R4-15"} (PICTURE: R4-15) PRIMITIVE : viewpoint COG : average of left & right DIR : dvect (initialized to the direction of the current aimpoint) DIV : right - left @endnode @node "R5.1" @title "Chapter 5 TAGS" Chapter 5 TAGS -------------- TAGs are used for expanding the object and the material data structures. They contain alternatives to assumed default values or additional information to describe some additional property for the object. These additional properties are often needed when creating new animation techniques (methods) and procedural materials. Internally a tag consists of two parts: the tag ID (tag identifier), and the tag field, which points to the actual tag values unless it is an integer (lxxx) tag, in which case the tag field is the actual tag value. From the user perspective, a tag consists of the tag ID and the tag value, unless RPL is being used; then it is necessary to access the tag values via the tag field. The user can utilize his/her own tags by creating a function that looks for a particular tag ID and then acts upon or modifies its values. This function takes the form of an RPL word definition which is then invoked either by executing it directly, executing it via the user interface (a macro or a tool icon), or by attaching it to a method as a method procedure. Tags provide the final degree of customization necessary to expand the features of REAL 3D For example: IAGE 32 SNAM John Houston FLEN 182.5 VPOS 1.5 1.2 0.5 5.1 Tag identifiers The tag ID consists of four ASCII characters and its structure is generally Txxx, where: - T describes the type of the tag value - xxx is the identifier used for recognizing individual tags. There are two basic kinds of tags: 1. Tags affected by Real 3D modify functions. When user modifies the object to which the tag is attached, the tag value is modified as well. There are two sub-classes of modifiable tags: "M" and "D". 2. Tags which are not affected by the modify functions. Tag type characters can be one of the following: C - Control tag, used only internally. F - Floating-point tag. The tag field is a pointer to an actual floating-point tag value. I - Integer tag, the tag field is used directly to store the value. S - String tag, the tag field points to a string which is the tag value. V - Vector tag, the tag field is a pointer to an array of three floating-points. M - Modifiable vector tag. Modified as absolute 3D point by REAL 3D modify functions. D - Modifiable vector tag. Modified as a vector, so modify functions such as rotate and mirror affects this tag, but the move function has no effect at all. 5.2 Reserved tag identifiers The following are the tag ID's reserved for use internally by REAL 3D: CEND - This ends the tag data structure. It does not appear on the tag requesters. DDIR - Primary direction vector for object. For example: "DDIR 1.0 0.0 0.0" DDIV - Secondary direction vector for object. For example: "DDIV 0.0 -1.0 0.0" DDIR defines obJect "axis" and DDIV defines how object is rotated around this axis. These tags are used where exactly defined direction for objects is needed and they override the default object direction. These tags do not have to be defined as perpendicular to each other as they are "normalized" internally so that DDIV is always perpendicular to DDIR. MCOG - Center of Gravity. This tag can be used for overriding the default center of gravity. For example: "MGOG 1.0 1.0 0.5" SCRE - Formula producing logical result to control target creation by CREATION method; the result should be assigned to the "I" variable. For example: "l=(t> 1 .0)" SDEL - Logical formula to control target deletion by CREATION method. For example: "l=(y> 1.0)" SMAT - This tag is used for defining materials associated with objects. All mapping primitives contain this tag. The tag value contains the name of the material. For example: "SMAT wood1". Note: That if the name of any material is changed, then the tag value for SMAT should also be changed to reflect the new material name. SMTH - The name of the method associated with object. For example: "SMTH SIMPLE SKELETON". SOBJ - Reference to another obJect. Links and groups refer to other objects and the information about the target object is stored using this tag. The tag value contains the full name of the target object including the path (for example: /Root/myobj/mesh). The path can be absolute or relative. SRPL - The contents of this tag can be any RPL program. The purpose of it depends on the obJect it is attached to. When associated with method or parameter object, the tag can be used for customizing built-in methods and evaluable parameter objects (see SFOR). The tag is also used for attaching RPL procedures to objects allowing user to create intelligent "thinking" objects. For example: "SRPL MyMethod". VFRQ - How much faster (or slower) a method's time runs compared to its parent time. For example "VFRQ 3.0 0.0 0.0". VOFF - Offset vector used by methods. For example "VOFF 0.5 0.5 0.5". VPHS - General usage phase tag. The tag can be used for modifying a method's local time. When associated with target objects, the purpose of the tag depends on the method in question. For example "VPHS 0.2 0 0". VTIE - Time end tag. When the time reaches this value, the method stops. For example: "VTIE 0.8". VTIM - This tag is used for defining a method's current time, i.e. the time that the method's current state corresponds to. For example: "VTIM 0.5". VTIS - Used for defining a sub-range from parent time. When the current time reaches this value, the method is activated. For example: "VTIS 0.1". FFRI - Surface friction between particles involved in collisions. This causes changes to velocity and spin. For example: "FFRI 0.5". FMAS - Mass for obJect. If this tag is absent the default mass for the object is 100.0 kg. For example: "FMAS 10000.0". FREB - Rebound energy for collision detection system. With this tag it is possible to specify the "elasticity" of collisions with the object having this tag. The default value is 1.0 (fully elastic); the value 0 results to fully non-elastic behaviour. For example: "FREB 0.8". FSIZ - Size for particle. This tag can be used for overriding the default object size. The collision detection system uses the size property to define when distance between objects is small enough for surface collision detection. The size is also needed by the FRICTION method (the bigger the object, the higher the friction force). For example: "FSIZ 2.3". ICSM - Collision sampling accuracy used by COLLISION and INT COLLISION methods. The default value 0 gives normal accuracy, the other possible values 1 and 2 give increased accuracy. For example: "ICSM 1". SFOR - String tag used for defining formulas. The contents of this tag is always evaluated when associated with method and parameter objects. Some methods also allow this tag to be associated with target objects. For example: "SFOR if(x<0, f=f*2, f=0)". VSPI - Spin for particle methods. Value defines angular velocity around direction axes in radians. The tag value can also be negative to reverse the direction of rotation. For example: "VSPI 3.14 6.28 -0.5". VVEL - Velocity of particles used by particle methods. For example: "VVEL 10.0 5.0 0.0". SIDE - Unique identifier used for linking group and link primitives with their targets. If the object referred by a SOBJ tag cannot be found, then the target is resolved using this tag. SWND - Window name. Can be added to viewpoint and aimpoint primitives to identify the window whose camera orientation they specify. @endnode @node "R6.1" @title "Chapter 6 AREXX INTERFACE OF REAL 3D" Chapter 6 AREXX INTERFACE OF REAL 3D ------------------------------------ 6.1 General ARexx is undoubtedly one of those things which make the Amiga platform something special. ARexx provides applications with a common communication protocol, this kind of versatility is difficult to find on other platforms. ARexx has quickly become a standard supported almost by all commercial products and REAL 3D is not an exception. Basically REAL 3D contains a so called "active" ARexx port, similar to many other programs. In other words, REAL 3D can send and receive ARexx commands. However, the way how the ARexx interface of REAL 3D is implemented, is somewhat unique. In REAL 3D there is no fixed set of supported ARexx commands. Instead, commands arriving at REAL 3D are passed directly to the parser of REAL 3D'S built in programming language - RPL. 6.2 ARexx vs. RPL REAL 3D uses RPL extensively. For example, it is used as a macro recording language, as a scene description method, procedural textures and animations are described using it, key and icon bindings are defined using RPL, user defined custom formulas describing mathematical textures are evaluated using RPL etc. Because of the time critical nature of some of these tasks, RPL was designed to be fast in its execution. This led to quite a low level "compiled" language. ARexx is based on the REXX programming language and is an "interpreted" language. Because of this, it is slower in its execution and cannot be used for implementing time critical tasks like procedural textures. However, the strongest point of ARexx is that it can be used for integrating different applications with each other. It is important to realize that RPL and ARexx are not two different "competitive" programming language implementations for REAL 3D. ARexx interface of REAL 3D is more than just set of ARexx commands; it is actually another programming language. Together, ARexx and RPL provide the user with a great deal of power and flexibility due to the fact that both ARexx and RPL are "interactive" languages, they fit perfectly together. This kind of ARexx interface has many advantages. One of the biggest is that the interface is not fixed; the user can expand it simply by programming new RPL words. In other words, the ARexx interface of REAL 3D is not "hard coded" to the program. Another advantage is that you can use RPL for those tasks that better suit RPL and ARexx for those tasks where ARexx appears to be a more natural choice. Thanks to the clever implementation of ARexx, you can mix RPL and ARexx programs without any problems. You don't have to know much about RPL in order to use the ARexx interface of REAL 3D. You can call existing RPL words as if they were commands implemented Just for the ARexx interface. However, no programming language contains all possible functions for all possible tasks. There are always cases where some new useful functions could help and speed up the Job. Therefore, a system where the ARexx interface is not fixed and can be quickly extended can turn out to be an extremely valuable feature. We could say that all the power provided by RPL can also be achieved through ARexx programs and vice versa. The interface is established using a set of RPL words which can be used for sending ARexx commands to other applications, for passing results back to them, accessing the ARexx Clip List and so on. In the following sections we will show you how to use the ARexx interface of REAL 3D. However, this chapter is not ment to be a tutorial for ARexx programming or the RPL programming language. For more information about the ARexx programming, see your Amiga system software manuals. @endnode @node "R6.3" @title "Chapter 6 AREXX INTERFACE OF REAL 3D" 6.3 Sending ARexx Commands to the ARexx Port of REAL 3D The name of the REAL 3D ARexx port is REAL3D0. If there are more than one REAL 3Ds running simultaneously, the postfix index is incremented by one for each new instance so that it remains unique and can be used for identifying all program instances if needed. rx "ADDRESS REAL3D0 RENDER" When entered in an AmigaDOS shell window, this command line sends a RENDER command to REAL 3D which causes REAL 3D to render all its windows. A more common way to send ARexx commands to REAL 3D is to write an ARexx program and save it to a file. This ARexx program can then be invoked from the AmigaDOS shell or any application which supports ARexx. For example, the following ARexx program can be saved as "ram:test.rexx" and executed by entering the command "rx ram:test". /* Render REAL 3D windows */ ADDRESS REAL3D0 RENDER You can execute any REAL 3D menu function by using the MENU command. As the RPL word descriptions specify, the RPL word MENU takes three parameters where the first defines the menu title, the second defines menu item and the last defines the submenu. /* Activate the function Modify/Structure/Name */ ADDRESS REAL3D0 2 2 0 MENU The MENU command allows you to execute REAL 3D functions using the highest level interface. For example, the command: /* play forwards */ ADDRESS REAL3D0 4 1 0 MENU plays the animation to the end. However, if you don't want to access functions at the highest level, you have to consult the RPL reference chapter in order to find how to access the desired function at a lower level. F or example, if you want to ask REAL 3D to load the object file "r3d2:objects/myobj", you don't want to use the highest level access to the ProJect/Objects/Load function (because it opens the file requester asking the user to select the file name). In this case the word FIL_LOAD can be used instead. /* ask Real to load file r3d2:objects/myobj" */ ADDRESS REAL3D0 "r3d2:objects/myobj" lIO_RALL 0 FIL_LOAD If you want to invoke the function Animate/Control/Goto so that REAL 3D asks the user to define the moment in time where to play, you can use MENU word. Another possibility is to use lower level access and use the PLAY word. PLAY takes one parameter which defines the moment in time to which the animation should be played: /* play animation to half way */ ADDRESS REAL3D0 0.5 PLAY For more information about all possible RPL words (REAL 3D ARexx commands), see the RPL reference chapter. Because all arriving ARexx commands are passed directly to the RPL parser, it is possible to mix ARexx and RPL freely. For example, the following ARexx program produces a simple animation. /* simple animation */ ADDRESS REAL3D0 do i = 1 to 10 /* ten frames */ 0 O_GETROOT /* objects to be moved */ 0.10 0 0 M_MOVE /* move 0.1, 0 0 units */ RENDER /* render the frame */ end As mentioned earlier, the ARexx interface of REAL 3D can be expanded simply by writing new RPL words. For example, the animation presented in the previoUs example can be implemented by defining a following RPL word in REAL 3D. ( execute this as a macro from REAL 3D ) ( or insert it to s:rpl-startup ) : MOVE_&_RENDER 0 0 GETROOT ( objects to be moved 0.1 0 0 0 M_MOVE ( move 0.1 0 0 units RENDER ( render the frame ; Then it is possible to execute the following ARexx macro: /* simple ARexx animation */ do i = 1 to 10 /* ten frames */ MOVE_&_RENDER /* call the new RPL word */ end In the previous examples, we used ARexx control structures for defining a simple animation loop. However, the same animation can be created by using the control structures of RPL. In other words, the RPL word can also contain the loop definition. Execute the following RPL program as a Macro from REAL 3D: : ANIMATE 10 0 DO ( call a word defined earlier ) MOVE_&_RENDER LOOP ; Now send the following ARexx command to REAL 3D: rx "ADDRESS REAL3D0 ANIMATE" and all obJects will be moved and rendered ten times. The third way to create the same animation is to send a small RPL program to REAL 3D which takes care of everything: /* define a new RPL word through ARexx */ ADDRESS REAL3D0 ":ANIMALL 10 0 DO 0 O_GETROOT 0.1 0 0 0 M_MOVE RENDER LOOP ;" Then send the "ANIMALL" command to REAL 3D: rx "ADDRESS REAL3D0 ANIMALL" Note that if the syntax of a RPL program is not accepted by the ARexx interpreter, it must be quoted . When the ARexx sends the string to the host application it removes double quotes making it a valid RPL program. 6.4 Return Values REAL 3D returns 0 if it succeeds in its task to execute an ARexx command. Otherwise it returns a positive value. ARexx assigns this return value to the variable "rc". You can use this variable to detect whether or not the command succeeded. /* return value testing example */ address REAL3D0 ZENDER /* send command to Real */ if(rc ~= 0) then do /* test return value */ say "Cannot ZENDER" exit rc end Note that REAL 3D uses the return value only for indicating whether or not the executed command succeeded. One of the most common errors is "syntax error" in the RPL program; the ARexx program has sent a command or program to REAL 3D which RPL cannot understand. Because the return value is only used as an error indicator, the only way to affect the return value is the RPL word ERROR. In other words, the called RPL word can cause an error itself, making REAL 3D return an error code to the ARexx program. ( Define this RPL word in REAL 3D ) : MAKE_SURE "YESlNO" "Are You Sure" GET_KEY IF QUIT ( if "YES" selected, return 0 ) ELSE ( otherwise cause error ) 0 ERROR ( without error message ) ENDIF ; Now the new RPL word can be called from any ARexx program as follows: /* test return value example */ address REAL3D0 MAKE_SURE if(rc ~= 0) then do say "The user selected NO" exit rc end say "The user selected YES" 6.5 Result String When a simple "error/no error" return value is not enough, ARexx programs can ask REAL 3D to return additional information about the executed command. So called "result string" can be used for that purpose. REAL 3D returns a result string only if it is requested by the ARexx program and if Real successfully executed the command. Therefore you always have to check the return value assigned to the variable "rc" before accessing the result string. You can request REAL 3D to pass a result string by using the ARexx instruction OPTIONS RESULTS, and the RPL word RX RESULT can be used for defining the result siring REAL 3D should return. For instance, an ARexx program could ask REAL 3D to ask the name of the user. This can be accomplished by defining the following word in REAL 3D: ( Execute me as a macro ) : WHO_ARE_YOU ( put user's name to the result string ) RX_RESULT 50 "Who Are You ?" GET_STR ( return error if user ) ( cancelled the requester ) NOT IF 0 ERROR ENDIF ; The ARexx program sending WHO_ARE_YOU command to Real looks like the following: /* request result string */ options results /* define host address */ address REAL3D0 /* send command to REAL 3D */ WHO_ARE_YOU /* check return value and exit */ /* if the user selected cancel */ if(rc ~= 0) then do say "Unknown Person" exit rc end /* otherwise "result" variable contains */ /* the name of the user */ say result Although ARexx allows you to mix RPL programs with ARexx programs (if ARexx cannot recognize a part of the program, it assumes it to be an external procedure call and sends it to the host application), a better solution is to keep RPL programs and ARexx macros separated. This can be implemented so that the ARexx macro asks REAL 3D to load the required RPL programs in as the first thing. For example, the previous WHO_ARE_YOU example could be implemented as follows: /* ask Real to load whoareyou.rpl */ /* before calling word WHO_ARE_YOU */ ADDRESS REAL3D0 "ram:whoareyou.rpl" LOAD WHO_ARE_YOU if(rc ~= 0)then do say "Unknown Person" exit rc end say result As you have propably already noticed, ARexx allows you to use apostrophes (") for passing quoted strings to host applications. Whenever you have to send a string to REAL 3D, you have to enclose it with apostrophes because of the way ARexx translates them. ARexx translates "/car/engine" 0_FIND to /car/engine O_FIND which will cause a syntax error when sent to REAL 3D. Another possiblity is to use a variable as follows: objname = "/car/engine" " II objname II " O_FIND 6.6 Clip List Multiple result strings can be passed to an ARexx program by using the Clip List feature of the ARexx. The Clip List consists of pairs of strings where each entry consists of a name and a value. REAL 3D can access the Clip List using the word RX_SETCLIP and ARexx programs using the function getclip() and setclip(). For example, REAL 3D can add one entry to the Clip List as follows: "rad" "0.5" RX_SETCLIP Then the Arexx program can read it as follows: radius = getclip("rad") Clip List is typically used whenever two or more result strings are needed. For example, the ARexx program could ask REAL 3D to assign the name of the current level and root objects to the clip list. The RPL program would look like this: ( save this program as ram:clexample.rpl ) : ASK_CURR_ROOT "root" ( Clip List item name ) ( and address of the object name: ) O_GETROOT O.sName + RX_SETCLIP "current" O_GETCURR O.sName RX_SETCLIP ; The actual ARexx macro asks REAL 3D to load clexample.rpl in and then calls the word ASK_CURR_ROOT which causes Real to assign values to "root" and "current items in the Clip List. /* ARexx macro */ ADDRESS REAL3D0 /* ask Real to load clexample.rpl in */ "ram:clexample.rpl" LOAD /* call the word defined in clexample */ ASK_CURR_ROOT say getclip("root") say getclip("current") @endnode @node "R6.7" @title "Chapter 6 AREXX INTERFACE OF REAL 3D" 6.7 Sending ARexx Commands from REAL 3D As already mentioned, REAL 3D can send and receive ARexx commands. This can be accomplished by using the RPL word RX. The RX word takes one parameter, which is a string containing the ARexx program to be executed. For example: "ADDRESS COMMAND dir" RX causes ARexx to send the "dir" command to the underlying AmigaDOS shell when entered from any RPL window. The command: "RENDER" RX causes all REAL 3D windows to be rendered as if the RENDER command was received from the external application or typed in from any RPL window. Note that ARexx allows you to use apostrophes (") for passing quoted strings to host applications. In RPL, you can use use the backspace character before the double quote character. This allows you to send strings with double quotes to the ARexx master process. For example: "\"hello world\" PUTS" RX does the same as the command "hello world" PUTS when typed in from a RPL window. Lets consider the following scenario: the user is going to render an animation which consists of 1000 frames. Because there is not enough disk space for such a big animation, the only possibility is to render the animation directly to video through a single frame recorder. Naturally the software which controls the single frame recorder supports ARexx and can therefore communicate with REAL 3D without any problems. The "frame command" in the Animation window can be used for that purpose. Lets assume that the user has written a ARexx macro which saves the rendered imagefile to video. If the name of the ARexx program is "save.rexx", then the frame command would look like the following: "save.rexx" RX Whenever the REAL 3D gets a new image ready, the frame command is executed causing ARexx to run the "save.rexx" program saving the rendered image to the video tape. 6.8 Return Values From Other Applications Just as REAL 3D can pass a return value to an ARexx program, other applications can return result values to REAL 3D. Because some applications use return values for indicating something else than just error situations, return values are not automatically interpreted as errors by RPL. The word RX_Rc word can be used for fetching the return value from an executed ARexx command. For example: ( Simple RPL program sending an ARexx ) ( command to another application ) : RC_TEST ( send ARexx command : "ADDRESS ABCD Hi There" RX RX_RC @ ( fetch return value IF ( if return value is not zero "ARexx command failed" PUTS ELSE "Arexx command succeeded" PUTS ENDIF ; In this example, the execution of the RPL program is not terminated if the ARexx command failed. However , if the error situation is fatal and the RPL program should not continue at all, the ERROR word can be used for terminating the RPL program. ( Terminate the program if ) ( ARexx command fails ) : RC_TEST ( send ARexx command: "ADDRESS ABCD Hi There" RX RX_RC @ IF "Cannot execute ARexx command" ERROR ENDIF ; Note that you can use RX RC only for checking what kind of return values the called external application returned. You cannot use it for affecting the return value REAL 3D passes to the caller application which has sent an ARexx message to REAL 3D's port. REAL 3D always returns 0 if the executed command succeeded and a positive value if it failed. In order to return more information to the caller application, use result strings or the Clip List. 6.9 Result Strings from Other Applications ARexx commands sent by REAL 3D can return information from eternal applications through "result string" much the same way as REAL 3D can return result strings to eternal applications. The result string can be accessed using the RPL word RX_RESULT. For example, lets imagine that the user starts an external application whose ARexx port name is EXTAPP and which supports the ARexx command called WEEK_DAY. This command returns the result string containing the current day of week. The RPL program could look like this: ( RPL program which asks the current day ) : DAY ( send ARexx command ) "ADDRESS EXTAPP WEEK_DAY" RX ( check the return value ) RX_RC @ IF "Cannot get day" ERROR ENDIF ( print out the result string ) RX_RESULT PUTS ; For more information about all ARexx oriented RPL words, see the RPL reference chapter 4.10 AREXX WORDS. @endnode @node "AA" @title "Appendix A PREDEFINED ICONS" Appendix A PREDEFINED ICONS. ---------------------------- Figure @{"AA-1:" system "display dh9:docs/r3ddoc/r3dv2pics/AA-1"}: (PICTURE: AA-1) Figure @{"AA-2:" system "display dh9:docs/r3ddoc/r3dv2pics/AA-2"}: (PICTURE: AA-2) @endnode @node "AB" @title "Appendix B HOT KEYS AND MENUS" Appendix B HOT KEYS AND MENUS ----------------------------- SYMBOLS USED FOR HOT-KEY DESCRIPTIONS - control key - either alt key - either shift key - left Amiga key - right Amiga key - enter or return key - space bar - tab key - backspace key - delete key - escape key - left mouse button < RMB> - right mouse button - use OS 2.0 drag box - cursor left key - cursor right key - cursor up key - cursor down key , - keys must be pressed in sequence There are three levels of keyboard support: Immediate Menu Function RPL Key Binding IMMEDIATE HOT-KEY ACTIONS Certain actions are invoked only by hot-keys, there are no menu equivalents. The following are the immediate hot-key actions: VIEW COORDINATE CONTROL ViewPoint Rotation - rotation of viewpoint around aimpoint: & - Tilt & - Pan & - Roll ViewPoint Movement: & - X axis & - Y axis & - Z axis SPECIALS - Cancel all - Cancel refresh - Refresh MOUSE ACTION MODIFIERS - Defines a new coordinate but leaves System Hot- Point unaltered. - Push coordinates onto Vector Stack - Performs an Average All action on all points contained within the drag box - Push points onto Vector Stack - Average All with points from selected objects - Push points from selected objects - Automatic group creation - Automatic group creation with selected objects CREATION HOT-KEYS - Close curve - Average coordinates in object creation (find centre) MACRO ARD SUPPORT SINGLE-KEY MACROS: Configurable. See the file "RPL-startup" MENU HOT-KEYS The following list shows the current Menu functions and corresponding hot-keys. Also the menu numbers are listed here; use these numbers when using MENU word of RPL to define custom key bindings. MAINMENU Function Hot-key RPL MENU Code PROJECT/ Objects/ Insert 0 0 0 Save 0 0 1 Replace 0 0 2 Project/ New 0 1 0 Insert 0 1 2 Save 0 1 3 Replace 0 1 4 Insert Sections 0 1 6 Save Sections 0 1 7 Replace Sections 0 1 8 Materials/ Window m 0 2 0 Delete 0 2 2 Delete_All 0 2 3 Insert 0 2 5 Save 0 2 6 Replace 0 2 7 Macros/ * Record_Macro 0 3 0 Execute_Current 0 3 2 Execute_Named 0 3 3 Repeat_Current 0 3 4 Spread_Current 0 3 5 Current_to_Named 0 3 7 Named_to_Current 0 3 8 Named Colors/ Select 0 4 0 Create 0 4 1 Modify 0 4 2 Delete 0 4 3 Insert 0 4 5 Save 0 4 6 Replace 0 4 7 Function Hot-key RPL MENU Code Windows/ Select 0 5 0 View 0 5 1 View_Superbitmap 0 5 2 View_Borderless 0 5 3 View_DBuffered 0 5 4 RPL 0 5 5 Tools 0 5 6 Animation a 0 5 7 Palette p 0 5 8 Measuring 0 5 9 Screen 0 5 10 Close 0 5 12 * No Gadgets 0 5 13 Environment/ Open_Screen 0 6 0 Make_Def. Pub 0 6 1 Close_Screen 0 6 2 Close_Current 0 6 3 Insert 0 6 5 Save 0 6 6 Replace 0 6 7 Save_Screen 0 6 9 Screen_Palette 0 6 10 External Screen/ Open 0 7 0 Close 0 7 1 Set_Modes 0 7 2 Settings 0 7 3 Save 0 7 4 Exit_Real 0 8 0 CREATE/ Visibles Polygon 1 0 0 Polyhedron 1 0 1 Polymid 1 0 2 Cut_polymid 1 0 3 Rectangle 1 0 5 Cube 1 0 6 pyramid 1 0 7 Cut_pyramid 1 0 8 Reg.polygon 1 0 10 Reg.polyhedr. 1 0 11 Reg.polymid 1 0 12 Reg.cut.plmd 1 0 13 Circle 1 0 15 3P_Circle 1 0 16 Cylinder 1 0 17 Cone 1 0 18 Cutcone 1 0 19 Sphere 1 0 21 Ellipsoid 1 0 22 Ellipsegment 1 0 23 Cut_ellipseg 1 0 24 Hyperbol 1 0 26 Cut_hyperb. 1 0 27 Sectors/ Circle 1 1 0 Cylinder 1 1 1 Cone 1 1 2 Cut_cone 1 1 3 Ellipsegment 1 1 5 Cut_ellipseg. 1 1 6 Hyperbol 1 1 8 Cut_hyperbol 1 1 9 Structure/ Level 1 2 0 Link 1 2 1 Group 1 2 2 Method 1 2 3 Light-sources/ Point 1 3 0 Line 1 3 1 Wall 1 3 2 Controls/ Attribute 1 4 0 Offset 1 4 1 Axis 1 4 2 Coordsys 1 4 3 Open_Line 1 4 5 Closed_Line 1 4 6 Circular_Line 1 4 7 Function Hot-key RPL MENU Code B-Spline_Ctrlp 1 4 9 B-Spline_Knot 1 4 10 B-Spline_Curve 1 4 11 B-Spline_Closed 1 4 12 B-Spline_Cir. 1 4 13 B-Spline_Helix 1 4 14 Mapping/ Default 1 5 0 Parallel 1 5 1 Cylinder 1 5 2 Sphere 1 5 3 Disk 1 5 4 Observers/ Viewpoint 1 6 0 Aimpoint 1 6 1 Compound_Tools/ Lathe 1 7 0 Circular_Subdivided 1 7 2 Rounded_Circ._Subd. 1 7 3 Sharp_Circular 1 7 4 Rounded_Circular 1 7 5 Conical 1 7 7 Conical_Subdivided 1 7 8 Rectangular 1 7 10 Rectangular_Subdiv. 1 7 11 Rectangular_Conical 1 7 12 Rect.Conical_Subd. 1 7 13 Rounded_Polygon 1 7 15 Rounded_Polyhedron 1 7 16 Ellipsed_Polygon 1 7 17 Ellipsed_Polyhedron 1 7 18 Join_Primitives 1 7 20 ObJect-Pixel_Tool 1 7 21 Freeform/ Mesh 1 8 0 Coplanar 1 8 2 Orthogonal 1 8 3 Rotate 1 8 4 Swing/Move 1 8 5 Swing/Size 1 8 6 Build from Curves 1 8 7 MeshPixel_ Tool 1 8 8 Fractals/ Landscape 1 9 0 Tree 1 9 1 Boolean/ OR 1 10 0 AND 1 10 1 AND_NOT 1 10 2 AND_with_Paint 1 10 3 AND_NOT_with_Paint 1 10 4 Rethink 1 10 6 Rethink_All 1 10 7 Unthink 1 10 8 Unthink_All 1 10 9 MODIFY/ Linear/ Move 2 0 0 Move_COG 2 0 1 Size_2D 2 0 2 Size_3D 2 0 3 Stretch 2 0 4 Extend 2 0 5 Rotate 2 0 6 Mirror 2 0 7 Shear 2 0 8 Rot&Ext 2 0 9 Deform 2 0 10 Structure/ Cut 2 1 0 Copy 2 1 1 Paste 2 1 2 Delete 2 1 3 Duplicate 2 1 4 Swap 2 1 5 Properties/ Color 2 2 0 Name 2 2 1 Attributes 2 2 2 Alpha Channel 2 2 3 Tags 2 2 4 Animation 2 2 5 Replace_Tags 2 2 6 COG 2 2 7 Direction 2 2 8 Velocity 2 2 9 Spin 2 2 10 Size 2 2 11 Function Hot-key RPL MENU Code Bend_Local/ Move_2D 2 3 0 Move_3D 2 3 1 Move_Radial 2 3 2 Size_2D 2 3 4 Size_3D 2 3 5 Size_Radial 2 3 6 Bend Global/ Move_2D 2 4 0 Move_3D 2 4 1 Move_Radial 2 4 2 Size_2D 2 4 4 Size_3D 2 4 5 Size_Radial 2 4 6 Bend_Endp./ Move_2D 2 5 0 Move_3D 2 5 1 Move_Radial 2 5 2 Size_2D 2 5 4 Size_3D 2 5 5 Size_Radial 2 5 6 Bend Linear Move_2D 2 6 0 Move_3D 2 6 1 Move_Radial 2 6 2 Size_2D 2 6 4 Size_3D 2 6 5 Size_Radial 2 6 6 Non-linear/ Move 2 7 0 Size 2 7 1 Stretch 2 7 2 Rotate 2 7 3 * Parabola 2 7 5 * Linear 2 7 6 * Circle 2 7 7 * Sine 2 7 8 * Curve 2 7 9 Set_Tool 2 7 11 Special/ Project_to_Object 2 8 0 Inverse_Kinematic 2 8 1 COGs/ Size_2D 2 9 0 Size_3D 2 9 1 Stretch 2 9 2 Extend 2 9 3 Rotate 2 9 4 Mirror 2 9 5 Shear 2 9 6 Rot&Ext 2 9 7 About COGs/ Size_2D 2 10 0 Size_3D 2 10 1 Stretch 2 10 2 Extend 2 10 3 Rotate 2 10 4 Mirror 2 10 5 Shear 2 10 6 Rot&Ext 2 10 7 Freeform/ Reparametrize 2 11 0 Move_Knotpoint k 1 11 1 Concatenate 2 11 2 Swap_Direction 2 11 3 Open/Close 2 11 4 Type 2 11 5 Invert 2 11 6 Remap 2 11 7 Surf.to_curves 2 11 8 Distribute 2 11 9 Assign 2 11 10 xchange_u_&_v 2 11 11 Snap to 2 11 12 Delete 2 11 13 Insert 2 11 14 Break 2 11 15 Draw Mode/ * Accurate 2 12 0 * Bounding_box 2 12 1 Function Hot-key RPL MENU Code VIEW/ Type/ * Parallel 3 0 0 * Perspective 3 0 1 * Separate IO 3 0 3 Input Crd/ Set_XY x 3 1 0 Set_YZ y 3 1 1 Set_ZX z 3 1 2 Set_Custom c 3 1 3 Set_Origin 3 1 4 Define_X 3 1 5 Define_Y 3 1 6 ObJect_Space->View 3 1 7 Camera/ Forwards f 3 2 0 Backwards b 3 2 1 Orientation 3 2 2 View->Camera v 3 2 3 Camera->View w 3 2 4 Create_Camera 3 2 5 * Camera_View 3 2 7 Display/ Zoom_In + 3 3 0 Zoom_Out - 3 3 1 Custom_Scale 3 3 2 Position 3 3 3 Pos&Zoom_In i 3 3 4 Pos&Zoom_Out o 3 3 5 Reset e 3 3 6 Auto focus 3 3 7 Grid/ Select 3 4 0 Create 3 4 1 Modify 3 4 2 Reposition 3 4 3 Delete 3 4 4 * Visible 3 4 6 * Snap_to_Grid 3 4 7 Render/ Window r 3 5 0 Boxes t 3 5 1 Greyscale g 3 5 3 HAM h 3 5 4 * Selected 3 5 6 Settings s 3 5 7 Export_RPL 3 5 9 Render_Hierarchy 3 5 10 Drawing_Set d 3 6 0 Boxes/ Define 3 7 0 Modify 3 7 1 Delete 3 7 2 Delete_All 3 7 3 Show_All 3 7 4 ANIMATE/ Create/ Path 4 0 0 Direction 4 0 1 Rotation 4 0 2 Sweep 4 0 3 Stretch 4 0 4 Size 4 0 5 RPL 4 0 6 Control/ Play_Forwards 4 1 0 Play_Backwards 4 1 1 Go_to_Beginning 4 1 2 Go_to_End 4 1 3 Go_to_? 4 1 4 Step_Forwards 4 1 5 Step_Backwards 4 1 6 Refresh 4 1 8 Function Hot-key RPL MENU Code EXTRAS/ Vectors/ Push 5 0 0 Pull . 5 0 1 Enter 5 0 2 Clear 5 0 3 Add 5 0 5 Subtract 5 0 6 Average 5 0 7 Average_All 5 0 8 Cross_Product 5 0 9 Eval._Current 5 0 11 Define_&_Eval. 5 0 12 Length_evaluate 5 0 13 Lasso 5 0 15 Undo u 5 1 0 Statistics 5 2 0 Refresh_All/ Wire-frame 5 3 0 Ray_Trace 5 3 1 Cancel_All 5 4 0 Evaluate/ Curve_Length 5 5 0 Parameter 5 5 1 Select_Objects 5 6 0 Free_Images 5 7 0 SETTINGS/ Clip Boxes/ * Active 5 0 0 Select 5 0 2 Deselect 5 0 3 General 5 1 0 Refresh/ * None 5 2 0 * Current 5 2 1 * All 5 2 2 Oper.Level/ * Active 5 3 0 Depth 5 3 2 Creation/ * Qry._Level_Name 5 4 0 * Qry._Prim._Name 5 4 1 * Auto_current 5 4 2 * Auto_selected 5 4 3 * Auto_index 5 4 4 Paths 5 5 0 Alpha_Channel 5 6 0 Attributes 5 7 0 RPL 5 8 0 View Resolutions/ Rotation 5 9 0 Position 5 9 1 Zoom 5 9 2 Undo/ * Active 5 10 0 Set_Depth 5 10 1 Clear 5 10 2 File Icons 5 10 3 TOOLS/ Icons/ * Visibles 6 0 0 * Sectors 6 0 1 * Structures 6 0 2 * Lights 6 0 3 * Controls 6 0 4 * Compounds 6 0 5 * Freef.Tools 6 0 6 * Booleans 6 0 7 * Mod/Linear 6 0 8 * Mod/Structure 6 0 9 Create_Icon 6 1 0 Delete_Icon 6 2 0 MATERIAL WINDOW MENU DEFINE/ Texture d Show_Image s Transp._Color c Tags t RENDER SETTINGS REQUESTER MENU IMAGES/ Backdrop Image Define Show Environment Map Define Show COLORS/ Ambient Background Background_gradient Environment Environment_gradient SET/ File_Name Memory_Use * Color_Shading @endnode @node "AC" @title "Appendix C UTILITY SOFTWARE" Appendix C UTILITY SOFTWARE --------------------------- C.1 CONVERSION SOFTWARE C.1.1 RealConvert Conversion program for converting Professional Draw clips, Sculpt 4D scenes and REAL 3D v.1.x object, animation and material files to REAL 3D v.2 binary format. If the program is run from CLI with full arguments, it does not display any interface but does the conversion silently. If the program is run from Workbench or if the CLI arguments were not sufficient, an easy to use interface is displayed. Use the program in the following way: 1. Double click the program icon to run Realconvert. 2. Press the READ FILE gadget and use the file selector to specify the file to be converted. 3. Press the SAVE AS gadget and use the file selector to specify the name for saving the result file. 4. If you convert PDraw clips, specify conversion quality to the Density gadget. 5. Press CONVERT. Depending on the type of the input file, the program asks what kind of objects to produce. Select the suitable alternative and press OK. 6. You can cancel the conversion using the CANCEL gadget. Realconvert gives you messages in the Status field. When the conversion is finished, you can convert another file by repeating the steps 2-5. 7. You can exit the program by pressing the "Close window" gadget on the top left corner of the window. The CLI template of the program is: NAME/A/K,TO/A/K,T=TYPE/K/N,D=DENSITY/K/N - NAME defines the file to be converted - TO defines the destination file - TYPE defines the output type as follows: PDraw clip: DTYPE 1 -> Curves DTYPE 2 -> Polyhedrons (default) Sculpt file: DTYPE 1 -> Separate triangles DTYPE 2 -> One triangle mesh (default) - DENSITY defines point density for pdraw clip file conversion (default 3, min 1, max 20). For example: RealConvert NAME pdclip TO ram: real_obj T=2 D=3 When converting V.1.4 files, the type and density parameters are unused. Cli template can be checked in the usual way by typing "RealConvert ?". The Sculpt file conversion converts obJect shape definitions of Sculpt scene files. It is possible to create a point-editable primitive or several individual triangles, each having its own attributes such as color and material. In the latter case the output file requires much more space than when using single primitive conversion. The Professional draw conversion a 1lows the user to select two alternatives: producing curves or producing extruded polyhedrons. The latter one is easier and a more straight forward way to produce 3D objects, but on the other hand, curves can be used in a variety of ways and the approach is more flexible. C.1.2 DxfToRPL This program can be executed from CLI. The template is: DxfToRPL dxf _file real - file The program produces a RPL description of the DXF file. You can load the file in to REAL 3D by using the menu ProJect/Macros/Execute Named and by then selecting the RPL file (from where you had converted it to). @endnode @node "A2" @title "Appendix C UTILITY SOFTWARE" C.2 IMAGE& ANIMATION DISPLAY C.2.1 Display This program can be used to view IFF pictures. When REAL 3D saves a picture with an icon, it sets the R3D2:Display as the default tool program. So, when you double click the picture's icon, the Display will start automatically and show the picture. You can also pass multiple parameters to the Display program using normal Workbench icon multiselection; the program shows all the images as a double-buffered presentation. When using the command line interpreter, the command has the form Real:Display T=TIME/K/N,R=REPS/K/N,Q=QUIT/S,NAME/M - TIME defines a delay (excluding the loading time) between consecutive pictures as 1/50th seconds. - REPS defines how many times the given picture sequence is shown repeatedly - QUIT defines that the program automatically closes the display after showing the last image; otherwise the last image will be shown until the left mouse button is pressed or a key is hit. - NAME parameter means the actual picture names, possibly multiple ones. The command also supports wildcards. For example: r3d2:display T=25 R=3 Q dh0:mypics/pic#? The string above shows all the pictures whose name starts with the charcters "pic", in "mypics" drawer three times, delaying after each frame half a second, and automatically restores the display after the last picture. The program can also show 24 bit targa/IFF images created with REAL 3D by converting them to HAM mode. C.2.2 DeltaConvert With this program you can convert a series of IFF pictures to a new file in which the pictures are stored as the differences between the consecutive pictures. If the pictures are similar, they will be fitted in a very small space. Displaying the pictures in succession is much more rapid than using the Display program. Usually the speed is 10 to 25 pictures a second, which makes the animation appear continuous. All pictures must use the same palette and display mode (e.g. HAM/INTERLACE). Suppose we want to convert ten pictures DF0: pic0-pic9 to a Deltafile. The following example illustrates the program's use: 1. Start the program either by double clicking its icon or by using the command line interpreter (CLI parameters are explained later in detail). 2. Give an unique name to save the animation by using the DELTAFILE string gadget. You can use the file selector to specify the name by pressing the DELTAFILE gadget. 3. Define the name of the first picture to be converted to the PICTURE string gadget: enter "DF0:pic" or press "PICTURE" and use file selector to specify the name. Do not add any index to the picture name. 4. Define the start index 0 to the "First index" gadget. 5. Define the last index 9 to the "Last index" gadget. 6. The default format string "%d" is suitable. 7. Specify which optimization mode to use. If you select Small delta, the smallest deltafile is produced. If you choose Fast delta, the program outputs a bigger deltafile, which can be shown somewhat faster. The option Anim5 produces a standard anim5 format file, which gives the best compression but which is not as flexible and fast as REAL 3D deltaformat. Choose for example Fast delta. 8. Hit the CONVERT gadget. 9. The program starts the conversion, and you can see how it proceeds by checking the "Status" field where the picture counter is displayed. During the conversion, all gadgets but the "CANCEL" gadgets are ghosted. You can cancel the conversion by pressing the "CANCEL" gadget. 10. After the program has processed all the pictures with the given name and the given index range, it waits for more pictures. As an indication of this state, the gadgets become active again (not the DELTAFILE and the delta type gadgets, because you cannot change them during the conversion). If you have more pictures that belong to the animation, define a new name and a new index interval (and possibly a format string). Then press CONVERT again, and the corresponding pictures are appended to the animation. 11. When all the pictures have been processed, choose CLOSE. 12. After closing the delta file, you can repeat the steps 2-11 again to produce another delta file. At this point, you can change all earlier selections, including the delta file type. 13. During the conversion, CANCEL-button cancels the conversion and discards the current delta file. Closing the program from the standard "Close window" gadget has a similar effect. Note: Deltaconvert keeps 4 frames in memory during conversion; the current 2 and the next 2. If space runs out during conversion then all but the 1 st 4 frames and up to the one before the current can be deleted. Deltaconvert includes a CLI-oriented interface, too. This is a slightly more restricted way to use the program, allowing only one name and index interval to be converted at a time. On the other hand, CLI interface allows "quiet" execution. Therefore, Realconvert can be integrated for example to an automatic RPL script for rendering, converting, and playing an animation. The CLI template can be seen by typing Deltaconvert ?. The template is: DeltaConvert NAME/A/K,F=FIRSTINDEX/K/N,L=LASTINDEX/K/N,TO/A/K,DT= DELTATYPE/K/N,FORMAT/K If proper parameters are not given, the program automatically uses the normal Worbench interface. The parameters are: - NAME/A/K: The name of the pictures to be converted (without index!). This must be always given. - F=FIRSTINDEX/K/N: First index (defaults to 0). - L=LASTINDEX/K/N: Last index (defaults to 1000000). - TO/A/K: The name of the destination file. Must be defined. - DT=DELTATYPE/K/N: 1=fast delta (default), 2=small delta, 3=anim5. - FORMAT/K: Optional format string, defaults to "%d". - Q=QUIET/S: No messages option. Nevertheless, certain important messages, e.g. "Overwrite old file ?", are always given. For example: Deltaconvert NAME ram:mypic TO ram:delta F=5 L=15 DT=2 FORMAT %d.iff Q The Delta convert program saves the deltadata for both directions. That is, if changes from Picture1 to Picture2 are saved, then changes from Picture2 to Picture1 are saved, too. This allows much more flexible animation representation, but requires more space. Therefore, the delta data method Comes to its best if only a part, say less than 2/3 of the whole display, is changing in the animation. Because of the principle according to which all display information of the Amiga is organized in the main memory, stable picture areas in the vertical direction can be utilized effectively, whereas horizontal direction has less importance. For example, if the top quarter of the display of an animation does not change, then the animation is certainly much faster to show and requires one fourth less space than an animation involving whole display changes. Instead, if the stable quarter is in the left side of the display, then the animation may be Just as slow and large as any whole display animation. You can create a test animation using only perhaps five pictures and size optimization (small delta). If the speed is high enough, then the whole animation can be processed with the same optimization mode. Note that when the animation is shown, the pictures are synchronized with the display refresh cycle. In a PAL system, the refresh rate is 50 Hz, and therefore possible animation rates are 50 pictures per second, 50/2 pictures per second, 50/3 pictures per second, 50/4 pictures per second and so on. The differences between these rates are very significant, and usually only the first three rates are fast enough to produce the impression of continuity. Anyway, even 50/4 = 12.5 pictures per second may suffice, if the differences between consecutive pictures are small. It should be noted that the REAL 3D delta format used is not any standard format. Instead, one can use original IFF pictures as a link between various programs. Note: When you produce Anim5 files, Deltaconvert does not automatically close the animation loop. To create continuous loops, add the two first pictures of the animation to the end of the animation. C.2.3 Deltaplay With this program you can display the delta files created by Deltaconvert. Deltaplay is also their Default tool program, hence a delta animation is shown simply by double clicking the icon of a delta file. The show ends when you hit first "q" and then "return". Note: Deltaplay does not play Anim5 files. The file is read to memory before the animation is shown, therefore the size of the animation is restricted by the amount of free RAM. All RAM memory, not only CHIP memory, can be utilized. So, if you have 18 megabytes of RAM, you can show quite large animations with your Amiga. If the animation is too big to fit to the memory, Deltaplay shows as much of it as possible. You can also give a control file as a parameter to Deltaplay. This enables an infinite number of different ways to represent the same picture material. A control file can be any text file, and it can contain the following commands: COMMAND EXPLANATION Shows next pictures E Shows previous pictures D Delay /50 seconds T Delay /50 seconds in every picture S Shows the animation backwards to the first picture E Shows the animation to the last picture L Play forward forever K Play backward forever P Play back and forth forever Q Quit It is also possible to add comments to a control file, which may be necessary when doing long control files. Deltaplay ignores all the characters after a semicolon to the end of the line. The following example script demonstrates how to create a show several minutes long from an animation of 50 pictures: ; Deltaplay control file F 49 ; Show the animation from the first to the last picture D 100 ; Shows the last picture 2 seconds B 10 ; Goes 10 pictures backwards D 50 ; Delay one second E ; From 40th to the last picture S ; Show the animation backwards from the last to the first picture, T 50 ; Animation speed 1 frame per second from now on B 100 ; Shows the animation 2 times backwards, D 50 TO ; A small pause and maximal animation speed again B 1 ; The previous picture D 50 F 2000 ; Shows the animation many times E ; And once again to the end Q ; Then quit You can use this script from CLI by the command Deltaplay