Getting an open source project such as Papervision3D up and running can be daunting if you don't know where to start. In this chapter, we will walk through the process of setting up your development environment step by step. You will learn how to download, install, and configure everything you need to create Papervision3D applications.
This chapter covers the following:
Three ways to download Papervision3D
Configuring your authoring tool to make the code work
Running some examples
Using the documentation
When we call Papervision3D an open source 3D engine for the Flash platform, what exactly does "engine" stand for?
Basically, Papervision3D is made up of a set of folders with a certain structure. These folders comprise of custom ActionScript classes that provide a well-laid-out architecture, which allows you to create 3D content in Flash. There is nothing like a .exe or .app file that you can download. There's no file that you can double-click and install. However, by downloading these set of folders and by including them in your ActionScript project, you can access them the same way you would access the Flash API or the custom classes that you may have written yourself.
For example, if you are familiar with ActionScript 3.0 you have probably heard of the DisplayObject class. MovieClip, Sprite, and Button are all display object classes. Analogous to this class, there is a class within the Papervision3D library called DisplayObject3D with its own variables, methods, and properties. Therefore, after downloading and installing these set of folders, you'll be able to access DisplayObject3D's variables, methods, and properties just like you would access them in a regular built-in class such as DisplayObject.
To illustrate, let's compare some code, based on the Flash API to the code written with the Papervision3D library. The next two lines may look familiar as they instantiate the Flash DisplayObject class and add the instance to the stage:
var myObject:DisplayObject = new DisplayObject(); stage.addChild(myObject);
Now, take a look at the following two lines that hold some Papervision3D code:
var myObject3D:DisplayObject3D = new DisplayObject3D(); scene3D.addChild(myObject3D);
This time the Papervision3D DisplayObject3D class is instantiated and the instance is added to a 3D scene. You can clearly see the similarity between the 2D Flash code and the Papervision3D code. More on 3D scenes will be discussed in Chapter 2. The Papervision3D API has many methods and properties that resemble their 2D equivalents. Methods such as addChild() and removeChild() have been added to Papervision3D, in order to stay as close as possible to the Flash API and its display list.
Let's take a look at how we can download the library of Papervision3D classes, also known as the source code.
Papervision3D is hosted by Google Code. You can find the Project Home at: http://code.google.com/p/papervision3d/
This page serves as an important resource with lots of references to examples, tutorials, and documentation. But for now we are interested in the source code. We could visit the page and go to Source | Browse and download all the files one by one manually, but that would be a lot of work. Apart from that, the other ways to get our hands on the code are as follows:
There are some important differences however. The SWC file contains compiled code whereas downloading the code in the ZIP or using Subversion will give you non-compiled code. Before we take a closer look at the ZIP file, the SWC file, and what Subversion is, let's see what compiled and non-compiled code are all about.
Downloading the non-compiled source means that you will get the folders and classes, just as they are without them being compiled in any format. You can actually open the classes and read the code. This can be extremely helpful in the process of learning. Taking a look at what's inside a class is a good way to improve your programming skills. You could even experiment and modify the source classes; however, we will not do this throughout the course of the book. Although modifying code in an external library may sometimes be tempting. A better practice is to leave the code as it is and find other ways to modify or extend it. A disadvantage of altering the source is that the modification may get overwritten and lost the moment you download a newer version of the source code.
The non-compiled code will work for Flex Builder, Flash Builder, Flash CS3, and Flash CS4.
The SWC, however, contains source code that has already been compiled. Compare this with publishing a Flash movie. The moment you publish, your code gets compiled into an SWF. In this case, the classes are hidden, so you cannot see and open them anymore.
It is now clear that Subversion and the ZIP file will give you non-compiled code, and the SWC contains compiled code. By taking a closer look at these three options we'll make it easier to decide which one to choose.
Subversion, also known as SVN, is an open source version control system. It allows developers, or teams of developers, to upload and download current and historical versions of the project they're working on.
Suppose a team of developers is working on the same project, like the Papervision3D team. If one of the developers makes a change to the project and uploads, or commits it, SVN incorporates the change into a new version of the project. At the same time SVN, being a version control system, saves the previous versions. In other words, you can always retrieve older versions from the server. Many open source projects use SVN because it makes working on the same project by multiple developers less tedious.
You may wonder why this is important to us. If you think of SVN as the location where all the versions of a project are stored, then it is also the place where we can find and download the latest version of the project. For developers who prefer to work with the latest features, the need to keep the code up-to-date is inherent to Papervision3D being an open source project. It is constantly developing and changing.
So, how do you download the latest version of a project to your computer using SVN? You need an SVN client. This is a software program that you install on your computer. The client will serve as the tool to download the latest revision of the source code.
The ZIP file contains non-compiled source code. There is one difference with the source code on the SVN server though. Where the SVN server always contains the most recent revision, the ZIP file tends to be more or less outdated. This makes sense, as the SVN source code is the most recent code you'll ever see as a user. It's up to the members of a project to continuously release an updated ZIP. For several reasons, this does not always happen, resulting in a ZIP that may be outdated. However, the code in the ZIP file may be better tested and thus more stable compared to the SVN code. Due to the constant changes that are being made to an open source project, the code on the SVN server may contain new features or even bugs, which could result in breaking the code in your project(s) the moment you download a new revision.
Think of an SWC as a library of classes that already have been compiled. If you incorporate the Papervision3D SWC into your project, you have access to all the Papervision3D classes, but you won't be able to actually see and open them.
We've just seen that the code in the ZIP file may not always be up-to-date with the code on the SVN server. The same goes for the SWC. But we have also seen that the ZIP file may be more stable than the SVN code and this is also true for the SWC.
If there are three ways of getting the source code, which way should you go?
Clearly, the process of downloading the SWC or the ZIP is easier than downloading through SVN, as you don't have to install an SVN client. However, once you've set up your SVN client, the updating process is nicely integrated into your system and you will always be able to get the latest revision. It's up to you to decide what is important to you.
We've discussed several pros and cons of working with compiled and non-compiled source. Let's create an overview by putting them in a diagram.
Hopefully, by now you have enough information to decide whether you want to work with the SWC, the ZIP, or SVN.
Note
This book doesn't pretend to favor one way over the other as all three have their pros and cons. Therefore, deciding which way to go is mainly a matter of personal preferences and needs. However, the examples of this book are based on Papervision3D 2.1, revision 920. If you want to be sure that all the example work, then it’s best to go for the ZIP or the SWC, which contain this revision. The sections on downloading the ZIP and the SWC will show you where to get it.
If you prefer to work with SVN, you should realize that newer versions may lead to compatibility problems with the examples, for instance resulting in compile errors. If you download a version that leads to compile errors or other problems, you can always fall back on the tested source code in the ZIP or SWC with revision 920.
The next sections will cover all three options, starting with SVN.