Reminder: Papervision3D is still in 2.0 alpha. Before testing these samples, please make sure to update to the latest version of the Papervision3D 2.0 alpha Great White branch.

Materials
Why do you need to learn about materials in Papervision3D? Take a sphere for example: How do you determine whether the sphere is a globe, an eye, or a basketball? You only know by which material is mapped to the sphere.

This article will cover the basics of the materials available through Papervision3D and teach you how to add materials to Planes. Let's get started, we’ve got a lot of “material” to cover:

Materials Base Class
Before we dive into every material available, it's important to note that every material extends an abstract base class called “MaterialObject3D” (org.papervision3d.core.proto.MaterialObject3D). This means you'll find the following properties in every material:

Very Common Usage among All Materials
1. name (String): the name of the material
2. interactive (Boolean): allows listeners to be assigned. Interactivity will be covered in an upcoming article.
3. oneSide or doubleSided (Boolean): maps the material to the front AND back of the mesh. For instance, a spinning Plane will show the same material on both sides of the Plane.
4. smooth (Boolean): applies a smoothing algorithm to the material. Turning this on for many materials or high-resolution materials has an impact on performance.

Less Common, but Useful Usage
5. bitmap (BitmapData): gives you access to the bitmap data of the material.
6. tiled (Boolean): determines whether the texture is tiled across the material. On primitive objects, you’ll have to adjust the maxU and maxV for this to take effect. For more information on UV mapping visit: http://en.wikipedia.org/wiki/UV_mapping
7. maxU (Number): holds the max number of “U” in the UV map.
8. maxV (Number): holds the max number of “V” in the UV map.
9. scene (Scene3D): a reference to the scene where the object belongs.

Special Situation Usage
10. invisible (Boolean): indicates whether the mesh faces are drawn.
11. opposite (Boolean): indicates whether the face is flipped. Only use this if the material is double sided.
12. widthOffset (Number): holds the original width of the bitmap before auto mip-mapping resizes
13. heightOffset (Number): holds the original height of the bitmap before auto mip-mapping resizes

Wireframe Material (or Composite Material including Wireframe Material)
14. lineColor (Number): holds an RGB value (e.g., 0xabc123) of the faces’ outline.
15. lineAlpha (Number): holds a number between 0 and 1 representing the percentage of transparency for the line.
16. lineThickness (Number): determines the thicknesss of the line.

Color Material Only (or Composite Material including Wireframe Material)
1. fillColor (Number): holds an RGB value (e.g., 0xabc123) of the fill of the mesh.
2. fillAlpha (Number): holds a number between 0 and 1 representing the percentage of transparency for the fill.

1. Wireframe
We used Wireframe materials in Part 1 to show that our 3d objects were truly 3d. The Wireframe material outlines the triangles used to create the entire object.



WireframeMaterial( color:Number=0xFF00FF, alpha:Number=100, thickness:Number = 0 )

2. Color Color materials project a solid color on to the 3d object. I've mainly seen color materials used in demos as they don’t allow for much customization.



ColorMaterial( color:Number=0xFF00FF, alpha:Number = 1, interactive:Boolean = false )

3. Bitmap If you want to use an image on your 3d object, you’ll need to use one of the following methods to get the bitmap data of your .gif, .jpeg, or .png onto the object.



The bitmap used in the demos is the Wikimedia commons logo above. Bitmap Material, Bitmap Asset Material, and Bitmap File Material are three different ways of doing the same thing so they will all yield the following result:



a. Bitmap
The Bitmap Material allows you to take any BitmapData and attach it to the material. The most typical usage is embedding a bitmap then grabbing the bitmapData from the bitmap to pass into the material. You can find information on embedding bitmaps in Flex here:
http://livedocs.adobe.com/flex/3/html/help.html?content=embed_3.html
BitmapMaterial( asset:BitmapData=null, precise:Boolean = false)

b. Asset (Flash CS3 only)
Bitmap Asset Materials are used to map a bitmap in your Flash library to an object. Just add any bitmap to your library, right-click -> properties

BitmapAssetMaterial( linkageID:String, precise:Boolean = false )
c. Color
The Bitmap Color Material works practically the same as the Color Material above, but this bitmap version allows you access to the bitmapData to draw or change pixels of the color to your liking.
BitmapColorMaterial(color:Number=0xFF00FF, alpha:Number=1)

d. File
Bitmap File Materials simply take a string that points the location of the image. You can also add listeners to the material if you need to check on progress or when the bitmap finishes loading.
BitmapFileMaterial( url :String="" )

e. Viewport


A Bitmap Viewport Material takes a bitmap snapshot of a viewport and allows you to project that snapshot onto another 3d object. Think of it like being at a basketball game and watching the game on the jumbotron instead of looking directly at the game.
f. Wireframe
The Bitmap Wireframe Material is similar to the standard Wireframe Material, but it allows for access to the bitmapData of the material.

BitmapWireframeMaterial(color:Number=0xFF00FF, alpha:Number=1,thickness:Number=3)

4. MovieClip
Papervision3D allows you to take your MovieClip directly from your Flash library and attach them your 3d objects using the linkage identifier. For Flex, you embed the published .swfs and MovieClip as you normally would. The following image demonstrates an attached MovieClip in the middle of an animation of a shape tween:



a. Asset (Flash CS3 Only)
MovieAssetMaterial( linkageID:String="", transparent:Boolean=false, animated:Boolean=false, createUnique:Boolean=false, precise:Boolean = false)
b. MovieMaterial
MovieMaterial( movieAsset:DisplayObject=null, transparent:Boolean=false, animated:Boolean=false, precise:Boolean = false )

5. Video Stream
Yes, you can play videos on 3d objects. Yes, it looks really cool.



VideoStreamMaterial ( video:Video, stream:NetStream , precise:Boolean = false )

6. Shade
Since Shaded Materials are all based on a light pointing at a material and reflecting (or not-reflecting) the light, you’ve probably guessed that you need to create a light first:

light = new PointLight3D();

You can position this light wherever you want using its x, y, and z properties then the shaded objects will appear to look at the light. If you want the light to be visible, you need to add pass in a parameter of “true” then “addChild” it to the scene. Although, you’ll probably find yourself leaving the light invisible and creating a 3d object at the same location that appears to be the light source like a sun, lamp, or sunlamp.

This “light” will become the first parameter of each shaded material. Only one light is currently supported in Papervision3D, but there are plans to allow multiple lights in the distant future.

The best way to see how all of these materials work is to test them out with the included reference sheet at the end of the article.

a. Cell
http://en.wikipedia.org/wiki/Cel-shaded_animation
The Cell Material uses two colors and an amount of steps you want to take to blend the two.



CellMaterial(light:LightObject3D, color_1:int, color_2:int, steps:int)

b. Environment Map
http://en.wikipedia.org/wiki/Environment_map
An environment map is receiving a bitmap being projected from the light. More advanced environment maps require “shaders” which will be covered in a later article.



EnvMapMaterial(light:LightObject3D, lightMap:BitmapData, backEnvMap:BitmapData=null, ambientColor:int = 0)

c. Flat Shade
http://en.wikipedia.org/wiki/Flat_shading
Flat shading gives one solid shade of light to each polygon. This effect is much more noticeable on spheres than plane and cubes to you can see the light curve around the sphere.



FlatShadeMaterial(light:LightObject3D, diffuse:uint=0xffffff, ambient:uint=0x000000)

d. Gouraud
http://en.wikipedia.org/wiki/Gouraud_shading
Gouraud Materials allow for smoother shading. Limitations are discussed in the link above.



GouraudMaterial(light3D:LightObject3D, lightColor:int = 0xFFFFFF, ambientColor:int=0x000000)

e. Phong
http://en.wikipedia.org/wiki/Phong_shading
Phong Materials are similar to Gouraud Materials, but they also allow for specular highlights.



PhongMaterial(light3D:LightObject3D, lightColor:int, ambientColor:int, specular:int)

7.Composite
A composite material is simply multiple materials mashed together to form one material. Here we see a bitmap material put together with a wireframe material.



8. Run-Time Material Swapping
Swapping material at run-time is simple as can be (thanks to a recent update by Ralph):

my3DObject.material = myMaterial;

The most obvious use is for rollovers, but interactivity with Papervision3D is being saved for a later article.

9. Examples of Materials around the Web
*Note: Some of these examples use Papervision3D’s shaders (which I will cover in a later article) and may not be working off the latest Papervision3D repository.

http://www.zeropointnine.com/blog/a-papervision-20-alpha-example
http://www.unitzeroone.com/blog/2008/03/12/papervision3d-shaders-bumpmap-example-sourcecode-for-cs3/

10. Reference Sheets
This article includes reference sheets for all the materials covered here so you can test all of the properties yourself within Flash and Flex. The Flash sheet covers the two asset materials that are Flash-specific while the Flex sheet covers all of the other materials in an ActionScript project.

Read more from John Lindquist.