Papervision3D Part 2: Features

This is part 2 of a 4 part series outlining 3D in Flash by dissecting the open source Papervision3D library. Before getting deep into features let me first make a few points about using Papervision3D.

The Papervision3d source SVN location includes the standard AS3 version of Papervision3D (version 1.7 as of this writing). If you look at the branches folder inside trunk you will find version 2.0 which is code-named “Great White”. This series is focused on that branch, and NOT version 1.7. Also, its important to know that Great White is probably the fastest and most frequently changing part of the Papervision source and thus details in this article will likely change over time.

Also, as a convention in these posts, I’ll be putting direct references to actual Google Code hosted repository files inside this page. If you don’t wish to open that repository each time you want to know the path of a class, then simply mouse over the link and look at the link address or the tool tip that shows up for the link. All references to Papervision3D classes assume that all uses of the term “pv3d” refer to the root Papervision3D package.

All Flash demonstrations are interactive. After focusing on the Flash applet, you can use the following key controls to control the camera.

Please note that nothing will promote your understanding of the code better than just reading it yourself. Although that may seem daunting, you’ll end up doing it anyway if you really get into the project. A good place to start might be reading the comments for classes in the folder pv3d.core.proto. If you’ve happened upon this page but are unfamiliar with computer graphics from a technical standpoint, please read Part 1

Geometry
In Papervision, all geometry is basically stored in the form of vertex data (Vertex3D). Collections of Vertices are stored in GeometryObject3D instances. Every DisplayObject3D class contains object information (such as location, transformation, orientation axis, etc) AND a reference to a GeometryObject3D instance. The DisplayObject3D class is the building block of all 3D data in Papervision –much like the flash.display.DisplayObject class is the building block of a 2D stage. However, one important difference is that a DisplayObject3D will not contain any rasterized visual data (as the DisplayObject does in its graphics object). It contains only data that is used by the rendering engine (BasicRenderEngine) and the object’s material (* MaterialObject3D) which is used to draw the object onto a Viewport3D object.

*Note: the actual method performing all drawing operations is NOT MaterialObject3D.drawTriangle but instead any of its subclassses that are overriding that method (for example ColorMaterial.drawTriangle).

Texture Mapping
Up until now, all discussion about 3D rendering has excluded the use of images used on geometric surfaces. This feature, called texture mapping, is very widely used. Unfortunately, it can also be quite an expensive process in terms of CPU cylces. Texture mapping has also evolved to allow for plenty of visual effects like bump mapping, normal mapping, displacement mapping, light mapping and more.

As you may recall from Part 1, all surface geometry in Papervision is divided into triangles. However, since images used in texture mapping are rectangular, something must be done to determine how the image can be mapped onto triangles in order to render the rectangular map as a single image. This is where the UV coordinates come in. A UV is simply a 2D coordinate that represents a location on the texture map that is associated with the 3D point on a triangle. Figure A1 shows this relationship.

Figure A1: Three example UVs for texture mapping a rectangular plane.

In Papervision, all the actual drawing commands exist in the material class being used for an object (as I mentioned above). Please note that two options for texture mapping exist. There’s ‘normal’ texture mapping which is also known as ‘affine‘ texture mapping. And then there’s ‘precise’ texture mapping which would be perspective correct. Normal texture mapping is a bit less accurate but far faster in rendering then precise textures. Exhibit A2 shows an example.

Exhibit A2: Normal (left) vs precise (right) texture mapping in Papervision3D 2.0

[kml_flashembed movie="http://www.calebjohnston.com/storage/posts/textureExample.swf" height="250" width="450" /]

Materials
A Material is a term borrowed from 3D development tools (like 3D Studio Max) that describes a collection of properties that will determine how a 3D surface will be rendered. Materials can become very complicated in production 3D rendering tools, but in Papervision a material has only a few properties. Those properties will determine whether lines, fills and/or a bitmap is drawn and how they’re drawn. The real key component of all materials is the drawTriangle method which is called by the engine during the render cycle.

Lighting and Shading
Light simulation is probably one of the most intricate and complicated aspects of 3D rasterisation. Other forms of computer rendering (like ray tracing) don’t treat lighting the way the rasterisation technique does. The reason is simple, performance. So in order to mimic light phenomena using rasterisation, shaders can be used. With the Great White branch of Papervision, lighting and shading have been added. Outside of Papervision, the term “shader” sort of has multiple definitions. Shaders are used in 3D development tools to determine how light will appear on a surface. But in real-time rendering APIs (like OpenGL and Direct3D) a shader is used to modify the graphics pipeline. There are actually several languages that govern shader authoring. Even Adobe has their own brand of shader language called Adobe Image Foundation. Although shading and lighting are rather complicated features in GPU accelerated APIs, in Great White they’re actually much simpler.

With Papervision, shaders are probably most useful for applying native flash effects (filters and blend modes) to any desired surface. Although, filters are not fully supported yet. Aside from that, applying a shader to a material is basically the same as applying a gradient-like light map to the BitmapData surface. So if you understand gradients and BitmapData objects in Flash, you basically understand Papervision shading as well. There are really 4 types of light maps you can use and those are Phong, Flat, Gouraud, and Cell. For each of those light maps there is a shader. There is also one other shader that can create an environment map. Its the EnvMapShader. It allows one to pass in bitmap objects that are used in combination with the surface texture map. Also you can use bump maps in Papervision3D shaders. See the BumpmapGenerator class. Exhibit B illustrates a simple example of various shaders. While this is not really the same ‘shading’ that happens in video games, with Flash 10, shading could definitely change radically in Papervision.

Exhibit B: Shading examples in Papervision3D 2.0

[kml_flashembed movie="http://www.calebjohnston.com/storage/posts/shadersExample.swf" height="250" width="450" /]

Its also important to note that shading requires a light source. Unlike other popular 3D APIs, there is no default ambient light. And any light sources that are used are not a part of the scene. Instead you must add a light source to the shader and its position is used in determining what the light map looks like. At the time of this writing there is only one light source supported per shader in Papervision3D. Also there is only one type of light to choose from -a point light.

Cameras
Cameras aren’t that complicated in Papervision3D. There are three types of Cameras: free, target, and debug. A free camera is totally unattached to anything that exists in the environment and can be moved ‘freely’. But a target camera will have a focus object within the scene. That object can be moved freely, but the camera will always come along. It works just like a focus camera object would work in a 3D development tool like 3D Studio Max or Maya. And thus a key aspect of that behavior is that if you want to translate a Camera3D object, it will actually rotate about its focus object. The last type of camera (debug) allows for key control, so that you can move the camera around as desired. This is highly useful when you’re building a complex scene or importing geometry from an external editor.

The only three camera-specific properties you can manipulate to control the view are zoom, focus and field of view (fov). The fov is in degrees. Normally 60 is representative of a normal 35mm camera lens. But the debug camera defaults to 90 degrees. Zoom and focus can be determined based on the fov and the camera’s distance to the near clipping plane. Exhibit C demonstrates the interaction of the fov and focus value. Also, here are some rather crude numbers for comparison:

Note: all camera focus values are used with a default debug zoom value of 24. Field of view values are in degrees.

Exhibit C: Demonstration of camera field of view and focus. Use keys r and f to increase and decrease the fov respectively.

[kml_flashembed movie="http://www.calebjohnston.com/storage/posts/cameraExample.swf" height="250" width="450" /]

Stay tuned for more feature dissection in Part 3. In the meantime, download examples source files here.