MathEngine KarmaTM User Guide March 2002. Accompanying Karma Version 1.2. MathEngine Karma User Guide • MathEngine Karma User Guide Preface 7 About MathEngine 9 Contacting MathEngine 9 Introduction 1 Historical Background 2 Application to entertainment 2 Physics Engines 3 Usage† 3 The Structure of Karma 5 Overview 6 Karma Simulation 6 The Karma Pipeline 8 Karma Data Structures 11 Implementation of the Pipeline 13 Two Spheres Colliding 16 AABBs do not overlap. 16 AABBs overlap, but the objects do not. 16 The AABBs overlap and the spheres touch. 17 The AABBs overlap, but the spheres are not touching as they move away. 18 AABBs do not overlap as the spheres move away from each other. 18 Dynamics 21 Conventions 22 The MathEngine Dynamics Toolkit (Mdt) 24 Designing Efficient Simulations Using the Mdt Source Code 25 Designing Efficient Simulations Using the Mdt Library 25 Rigid Bodies: A Simplified Description of Reality 25 Karma Dynamics - Basic Usage 28 Creating the Dynamics World 28 Setting World Gravity 28 Defining a Body 28 Evolving the Simulation 29 Cleaning Up 30 Evolving a Simulation - Using the Basic Viewer Supplied with Karma 30 The Basic Steps Involved in Creating a Karma Dynamics Program 31 Constraints: Joints and Contacts 33 Degrees of Freedom 33 Joint Constraints and Articulated Bodies 33 Joint Types 34 Constraint Functionality 34 Constraint Usage 36 Joints 36 Contact Constraints and Collision Detection 42 Further features 44 Automatic Enabling and Disabling of Bodies 44 The Meaning of Friction, Damping, Drag, etc. 44 Simulating Friction 46 Slip: An Alternate Way to Model the Behavior at the Contact Between Two Bodies. 48 Setting Properties of the Virtual World - Epsilon e and Gamma g 49 MathEngine Karma User Guide Stacking Boxes 50 External Forces, Torques and Impulses 51 Collision 53 Overview of Collision Detection 54 Using Collision Detection within a Universe 54 Explanation of Model, Geometry, and Body 54 Making a Model with a Box Geometry 55 Making a Model with a Convex Mesh Geometry 55 Creating a Model with an Aggregate Geometry 56 Constructing an Immovable Model, such as a Terrain 57 Disabling and Enabling Pairs of Models 58 Time Of Impact 59 Querying Line Segment Intersections 59 Testing Collision Directly 60 Creating a Model Without Using the Universe 61 Geometrical Types and Their Interactions 62 Overview 62 Register Types of Geometries to be Used 62 Intersection Functions 62 Geometrical Primitives 63 Advanced Features 66 Collision Spaces 66 Transform and Synchronization with Graphics 67 Transition 67 Static Models 68 Change Blocks 68 Updating The Models 70 Testing for Collisions 70 Cleaning Up 73 The Bridge 75 Introduction 76 Creating a Universe 77 Fitting Out the Universe 78 Resetting 78 Setting the Universe in Motion 78 Cleaning Up 79 Building a Bridge 80 Callback Functions 80 Creating Good Simulations with Karma 83 Points to Remember When Using Karma 84 Further details: 84 Karma Project Usage 89 Dynamics 89 Collision 90 Performance Considerations 92 Implementation Considerations 94 Performance 97 Frame time used by Karma 98 Dynamics Algorithms - Technical Information 100 MathEngine Karma User Guide Karma x86 and SSE Optimizations 102 Benchmarks 103 Karma for PlayStation®2 104 Processor usage 104 Code size 104 Scratchpad, VUMEM0, MICROMEM0 and VU0 registers. 104 Vif0 chains 105 Compatibility with compilers 105 Compatibility with renderers 105 Optimizations 105 Summary 106 Performance of a ‘Rag Doll’ Simulation on the Sony PlaySta- tion®2 using MathEngine Karma 107 Application level Optimizations 107 Karma architecture 108 Current state of PlayStation®2 Optimization 109 Performance analyser results 109 Quadbike Tutorial 111 Introduction 112 Initializing the Karma Collision and Dynamics Framework 112 Creating a Four Wheel Vehicle 115 Creating a Rider for the Vehicle 119 Appendix A - Default Values 123 Appendix B - The Karma Viewer 129 Using the Viewer in an Application 130 First Steps 130 Initializing the Renderer 130 Creating the Graphics 130 Running the Simulation 131 Terminating the Program 131 Render Contexts 132 Render Lists 133 Creating Primitives 134 Creating Objects 136 Manipulating RGraphic Objects 137 Menu System 138 Help System 139 The Camera 140 Camera Movement 140 Lighting 141 Ambient Lighting 141 Directional Lighting 141 Point Light 141 Textures 142 Disabling an object's texture 142 Controls 143 Button Press Controls 143 Analog Controls 143 Performance Measurement 144 MathEngine Karma User Guide Utilities 145 Geometry Data Format 146 Creating New Objects 146 RObjectVertex 146 Object Geometry Files 148 File Format 148 Appendix C - Memory Allocation 149 Memory Allocation in Karma 150 Introduction 150 Re-Routing Memory Management In Karma 152 Setting Karma Memory Usage 152 Memory Usage In Kea 152 Matrix Capping 153 Per Constraint Memory Used by Kea 153 Appendix D: Constraints Reference 155 Common Constraint Functions 156 Common Accessors 157 Common Mutators 157 Base Constraint Functions 158 The Constraints Mutator Functions 159 The Constraint Accessor Functions 159 Ball-and-socket (BS) Joint: MdtBSJoint 161 Ball-and Socket Joint Functions 161 Hinge Joint: MdtHinge 162 Hinge Limits 162 Hinge Joint Functions 162 Prismatic: MdtPrismatic 164 Prismatic Limits 164 Prismatic Actuators 164 Prismatic Joint Functions 164 Universal Joint: MdtUniversal 166 Universal Joint Functions 166 Angular Joint: MdtAngular3 & MdtAngular2 167 Angular3 Joint Functions 167 CarWheel Joint: MdtCarWheel 169 CarWheel Joint Functions 169 Linear1 Joint: MdtLinear1 172 Linear2 Joint: MdtLinear2 173 Functions Specific to Linear2 Joint 173 Fixed-Path Joint: MdtFixedPath 174 Functions Specific to Fixed-Path Joint 174 Relative-Position-Relative-Orientation Joint: MdtRPRO- Joint 175 Functions Specific to RPRO Joint 176 Skeletal limit constraint: MdtSkeletal 178 Skeletal Joint Functions 178 Spring Joint: MdtSpring 180 Functions that are Specific to the Spring Joint 180 Cone Limit constraint: MdtConeLimit 182 MathEngine Karma User Guide Cone Limit Functions 182 Joint Limit: MdtLimit 184 The Single Joint Limit: MdtSingleLimit 187 Functions that are specific to Contacts 188 MdtContactGroups 191 Functions that are specific to MdtContactGroups 191 The MdtBclContactParams Structure 193 Glossary Gl 1 Gl 2 Bibliography Bib 1 References Bib 2 MathEngine Karma User Guide Preface MathEngine Karma is a physics and collision detection software package. Software libraries are provided that contain routines that users can call on to quickly and easily add physical behaviour to their 2D or 3D environment. While the Karma product is suitable for a wide range of applications users should note that it is targeted at the games and entertainment markets. This userguide provides a background to the subject and introduces the Karma package, before going on to explain in detail how Karma can be used and integrated into a project. Karma is aimed at developers of real-time entertainment simulation software who are familiar with the C programming language and have a basic knowledge of maths. Experience with Microsoft Visual C++ is an asset. The source that is provided is in C. Karma uses a C API. In broad terms Karma consists of collision detection and dynamic simulation modules that may be used alone or together. The Karma Bridge (Mst Library) provides an API that simplifies the interoperation of Karma Dynamics (Mdt Library) and Karma Collision (Mcd Library). A basic cross platform renderer that wraps the DirectX and OpenGL graphics libraries is provided. While this allows users to build 3D applications with simple scenes, it is intended that users will integrate Karma with their own rendering solution. Karma is available for: • Win32 built in single precision against the Microsoft LIBC, LIBCMT or MSVCRT libraries. • the Sony PlayStation®2 games console. • the Xbox games console. • Win32 double precision and Linux versions on request. Information about each library function is provided in the html online documentation that can be found by following the ‘Demos and Manuals’ hyperlink in the index.html file in the metoolkit directory. Preface MathEngine Karma User Guide The origins of physical simulation, and how it has developed from the early days of electronic games through to the recent introduction of what have become known as Physics Engines, are discussed in chapter 1. Chapter 2 introduces MathEngine’s Karma product - a physics engine - and outlines what it can be used for, and how it works. The internal data structures are discussed, along with the data flow during a game. An example of two spheres colliding is used to demonstrate this. Chapter 3 presents Karma Dynamics, including discussions on the units, scale, coordinate system and reference frames used. The dynamics library functions are discussed and demonstrated with explanations of relevant physical behavior and the provision of user examples - from basic user functionality through to more advanced usage of Karma’s libraries. World properties, bodies, constraints and forces are introduced. In chapter 4 an overview of collision detection is given, with an explanation of how the three main parts of Karma, namely Karma Dynamics, Karma Collision and the Karma Simulation Toolkit, work together. The distinction between collision primitives, aggregates, and static models is made and examples of their implementation provided. Determination of object intersection in a game environment is demonstrated, along with line of sight tests to determine any objects that lie on a line joining two points in 3D