Papervision3D Essentials: Create interactive Papervision 3D applications with stunning effects and powerful animations

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.

The next sections will cover all three options, starting with SVN.

We will use TortoiseSVN as the SVN client for Windows. We will download and install this program and then use it to download the Papervison3D source code.

The download may take a while to complete due to the size of the files included. The Papervision3D team added not only the source code to the SVN server, but also examples and documentation for the project. When the download has completed, open the papervision3d_source folder and take a quick look at what's inside. You will see quite an amount of folders and files. These are the folders and files you have just downloaded.

Every now and then you may want to download the latest version of the source code to keep the code up-to-date. Similar to your first checkout, go to the papervision3d_source folder and right-click on it. But this time select TortoiseSVN | Update. The latest revision on the SVN server will now get incorporated in your local working copy.

Next, we will configure the authoring tool of your choice so that we can actually use the code. You can continue reading Configuring your authoring tool for Papervison3D.

For Mac OS X, we will use svnX as our SVN client. We will download and install this program and then use it to download the Papervison3D source code.

If you visit the download page of svnX at http://www.lachoseinteractive.net/en/community/subversion/svnx/download/, it will tell you that there are two requirements for using svnX. It assumes you have Mac OS X 10.4 or higher and you'll need a working install of Subversion. Although there are several others available, the svnX download page links to a working install that was made by Martin Ott. So, let's get this one first.

Now that we have successfully installed svnX as our SVN client, we're ready to download the Papervision3D source code.

The download may take a while to complete, due to the size of the files included. The Papervision3D team added not only the source code to the SVN server, but also examples and documentation for the project. When the download is complete, open the papervision3d_source folder and take a quick look at what's inside. These are the folders and files you have just downloaded.

If you want to download the latest version of the source code to keep the code up-to-date, open svnX and go to Window | Working Copies. Double-click the working copy of Papervision3D and a new window will appear. Click the green Update button to replace the local copy in your papervision3d_source folder with the latest revision on the SVN server.

Next, we will configure the authoring tool of your choice, so that we can actually use the code. Continue reading Configuring your authoring tool for Papervision3D.

We have downloaded the source code, but how can we make it work? Normally, if you download a software program, like we did with our SVN client, you would need to install it. But keep in mind that Papervision3D is not a software program—it's a library of folders and classes. What we need to do now is tell Flash where these folders are located so that we can access them when we work in the Flash IDE. In other words, within Flash we must set the path to the source code in our papervision3d_source folder. This is what we mean by configuring Flash.

We have downloaded the source code, but how can we make it work? Normally, if you download a software program, like we did with our SVN client, you would need to install it. But keep in mind that Papervision3D is not a software program—it's a library of folders and classes. What we need to do now is tell Flash where these folders are located so that we can access them when we work in the Flash IDE. In other words, within Flash we must set the path to the source code in our papervision3d_source folder. This is what we mean by configuring Flash.

Flash can handle the following two ways of setting such a path:

We will use the second approach in this book, so we'll only have to set the path once.

Both Flash CS3 and CS4 lets you set the path to the non-compiled source, but only Flash CS4 allows for setting the path to a SWC or SWC folder. If you decided to work with the SWC, you can continue reading Set the path to the compiled source code in Flash (only CS4).

By configuring Flex Builder and Flash Builder, we mean that we need to set the path to the Papervision3D source code. We will first import an existing project (that is, the example that is shipped with this book) and then set the path to the source code for this project.