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.
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.
We'll first go over downloading and installing an SVN client that is appropriate for your system (especially Windows and Mac OS X) and then use the client to download the non-compiled source code. If you choose to work with the ZIP or the SWC, you can skip this section and continue reading Downloading the non-compiled source using the ZIP or Downloading the compiled source.
There are a whole bunch of SVN clients available on the Internet. We will first choose a client for Windows, then for Mac OS X.
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.
1. Go to http://tortoisesvn.net/downloads.
2. Download the latest installer. The Setup Wizard will take you through the process of installing. You don't have to change the default settings.
3. Restart your PC after you've finished the installation.
Note
A frequently asked question is whether you should download and install Subversion next to TortoiseSVN. The answer is NO. Subversion is included in TortoiseSVN.
Now that you have installed an SVN client, let's use it to download the Papervison3D source code.
4. Create a new folder somewhere on your computer. You can call it whatever you want. In this book, we'll call it
papervision3d_source. It's the folder that will contain the Papervision3D source code.5. Right-click on this folder. You'll notice that your context menu now has some extra options involving TortoiseSVN.
6. Select SVN Checkout….
7. A window pops up asking for the URL of repository. Fill in: http://papervision3d.googlecode.com/svn/trunk/as3/trunk
8. Then click OK. TortoiseSVN will start downloading the source files from the SVN server.
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.
1. Go to http://homepage.mac.com/martinott/.
2. Download the
My Subversion-#.#.#package (the version numbers may vary over time). This is a ZIP file.3. Open the ZIP and double-click the file inside, which is a PKG file. A window will appear that will guide you through the process of installing. When Mac's Easy Install has finished, we can download svnX.
4. Go back to the svnX download page at http://www.lachoseinteractive.net/en/community/subversion/svnx/download/.
5. Download svnX. This time you will download a DMG file. Double-clicking it will open a new Finder window where you will find the
svnX.app. Drag or copy it into yourApplicationsfolder.
Now that we have successfully installed svnX as our SVN client, we're ready to download the Papervision3D source code.
1. Create a new folder somewhere on your computer. You can call it whatever you want, but in this book we'll call it
papervision3d_source. This is the folder that will contain the Papervision3D source code.2. Launch svnX by double-clicking
svnX.appin yourApplicationsfolder.3. Go to Window and select Repositories. The Repositories window displays the list of projects that you have downloaded. It's still empty, but we're about to add Papervision3D.
4. Add a new project either by selecting the default repository or by clicking the + icon. You can fill in anything for Name but in our example we will use
Papervision3D. You can leave the fields User and Pass blank.5. Type or paste the following URL into the Path field: http://papervision3d.googlecode.com/svn/trunk/as3/trunk
6. Double-click on the project you've just added. A new pop up window appears with details of the project. You can see a list of commits done by the Papervision3D team members. Every list item represents a revision and you can tell who uploaded the change and when it was uploaded. There is also a log message, written by the developer who committed the change(s), with some basic information about what has been changed.
7. If not yet selected, select the revision at the top of the list.
8. Click on the SVN CHECKOUT button and browse to the
papervision3d_sourcefolder you've just created.9. Select it and click Open. By doing this, svnX will start downloading the files from the server into this folder.
10. At the same time, a new window will pop up. This is the Working Copies window.
11. Change the default Name into something more appropriate such as
Papervision3D.
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.
The ZIP file holds non-compiled source code. You can find it on the Google Code pages of Papervision3D. As discussed before, the examples in this book are based on Papervision3D 2.1, revision 920. We will download this version to make sure that all the examples work. The next steps demonstrate how to get the ZIP with this revision.
1. Create a new folder somewhere on your computer. You can give it any name, but in this book we'll call it
papervision3d_source. Inside this folder, create a new folder and call itsrc.2. Go to http://code.google.com/p/papervision3d/downloads/list.
3. Look for the ZIP file, which has the following summary: Papervision3D 2.1.920.zip (for use with "Papervision3D Essentials" book).
4. Download the ZIP file, and save it anywhere on your computer.
5. Extract the ZIP file.
6. Put (or save if you use an extraction wizard) the extracted folders in the
srcfolder that we've just created inside thepapervision3d_sourcefolder.
At a certain moment, for instance when you need features that are incorporated in the most recent revision, you may decide you want to replace the code with the latest available version of the ZIP. Just look for the most recent, featured ZIP file on the list, repeat the download and extract process, and replace the folders in your papervision3d_source folder by your newly extracted folders. The source code will automatically be updated.
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.
If your authoring tool is Flex Builder, Flash Builder, or Flash CS4, both the non-compiled and the compiled source code will work for you. If you've decided to work with the compiled source code, you can download the SWC that contains this code from the Google Code page of Papervision3D. As the examples in this book are based on Papervision3D 2.1, revision 920, we will download this version to make sure that all the examples work. The next steps demonstrate how to get the SWC with revision 920.
1. Create a new folder somewhere on your computer. You can give it any name, but in this book we'll call it
papervision3d_source.2. Go to http://code.google.com/p/papervision3d/downloads/list.
3. Look for the SWC file, which has the following label: Papervision3D 2.1.920.swc (for use with "Papervision3D Essentials" book).
4. Download the SWC file, and save it in the
papervision3d_sourcefolder we've just created.
Every now and then you may want to download the latest version of the SWC to keep up with the changes that are being made to the project. Just look for the most recent, featured SWC file on the list, repeat the download process and replace your current SWC with the updated SWC.
Now that we have downloaded the source code, we will configure the authoring tool of our choice so that we can actually use Papervision3D. If your authoring tool is Flex Builder or Flash Builder, you can continue reading Configuring Flex Builder and Flash Builder.
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:
You can set it separately for each FLA
You can set it globally, which means that every FLA that you open or create automatically has access to the source
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).
If you've downloaded the ZIP or used SVN, the following steps will set the path to the source code from within Flash:
1. Open Flash. You don't have to create a new FLA or open an existing one.
2. Go to Flash | Preferences. on MAC, or Edit | Preferences on Windows
3. Select Actionscript in the category list at the left. Click the Actionscript 3.0 Settings button.
4. The following step shows a slight difference between Flash CS4 and its predecessor CS3.
5. Browse to the folder where the source code is located—
papervision3d_sourcein our example.6. Select src and click Choose. You will now see that the path has been added.
7. Click OK twice to close the dialog windows.
Now that the dialog windows are closed, it's a good idea to check if the process of downloading and setting paths went right. To do this, we will take a look at one of the examples that comes with this book. Continue reading Running an example in Flash.
1. Open Flash. You don't have to create a new FLA or open an existing one.
2. Go to Flash | Preferences on MAC, or Edit | Preferences on Windows.
3. Select Actionscript in the category list at the left. Click the Actionscript 3.0 Settings button.
4. Click on the + icon next to Library path. Then click on the red SWC icon.
5. Browse to the folder where the SWC is located—
papervision3d_sourcein our example.6. Select the SWC and click Choose. You will now see that the path has been added.
7. Click OK twice to close the dialog windows.
Now that the dialog windows are closed and the path to the SWC is set, it may be a good idea to check if everything went right. To do this, we will take a look at one of the examples that comes with this book.
Let's open the example that is shipped with this book using the Flash IDE. By doing this, we'll be able to find out if we installed and configured everything correctly. More than that, it gives us the chance to see some Papervision3D at work!
1. Open Flash.
2. Go to File | Open.
3. Browse to the
examplesfolder, which can be found in the book downloads.4. Browse to CH01 | Flash | SetupTest.
5. Open SetupTest.fla and publish it.
Do you see the earth turning and a 3D text? Congratulations, you've set up Papervision3D correctly!
If you get errors when compiling this project, please read the previous sections again. The most common error is:
Type was not found or was not a compile-time constant: [ class name ]
If you get this error, you probably have not set the path correctly.
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.
Both Flex Builder and Flash Builder allow you to import projects. Let's import one of the examples that come with this book.
2. Go to File | Import | Other.
3. Open the folder called
Generaland select Existing Projects into workspace.4. Click Next, and then select the radio-button Select root directory if it is not selected yet.
5. Click Browse and browse to the
examplesfolder in the book download.6. Go to CH01 | FlexBuilder.
7. By clicking Choose a list of projects will be displayed that are recognized as valid projects. Make sure that only the checkbox for SetupTest is selected.
8. Click Finish.
9. The project will now be imported. Flex Builder will display it in the Flex Navigator view, Flash Builder in the Package Explorer view. Open the project called SetupTest by double-clicking on it.
Take a look at the Problems view. Chances are that you will see some errors.
The project we imported uses the Papervision3D source code. The developer has set the path to the code from his authoring tool. But this path could be, and probably is, different on your computer, as it's most likely that we named our source folder differently and stored it somewhere else than the developer did. Therefore, let's fix that by changing the path.
Note
Whether you import an existing project, or create a new one, you must always set the correct path to the external source code you would like to use. Keep in mind that in this example we are importing an existing project and that we will change the path that has previously been added. However, if you create a new project, no path has been added yet. Therefore, every time you create a new project, you must add the path to the source code that you want to access.
Setting the path to the SWC requires a different approach than setting it to the non-compiled source code. We'll first set the path to the non-compiled source. If you decided to use the SWC, you can continue reading Setting the path to the SWC in Flex Builder and Flash Builder.
If you've downloaded the ZIP or used SVN, the following steps will set the path to the source code from your project:
1. Right-click on the SetupTest project folder. You can find this in the Flex Navigator view in the Flex Builder, and in the Project Explorer view in the Flash Builder.
2. Select Properties.
3. Select Actionscript Build Path and click on Source path if it is not selected yet. You'll see a path that points to an additional source folder. To edit the path, double-click on it and browse to our
papervision3d_sourcefolder. Then select src.4. Click Choose and OK.
5. Click OK to close the Properties window.
The path that we've changed was set by the developer of the project, but would not have worked for us. We needed to set the path to the source folder on our computer.
If you've downloaded the SWC, the following steps will set the path to it from your project:
1. Right-click on the project folder in the Flex Navigator view (Flex Builder) or the Package Explorer view (Flash Builder).
2. Select Properties.
3. Select Actionscript Build Path and click on Source path if it is not selected yet. You'll see a path that points to an additional source folder. Highlight the folder by clicking on it and click the Remove button.
4. Select Library path.
5. Click on the Add SWC Folder button.
6. Browse to the
papervision3d_sourcefolder and select it. Click Choose and OK.
7. Click OK to close the Properties window.
The path we removed pointed to the Papervision3D source code that was stored on the developer's computer. We needed to remove this path because we have decided to use the SWC instead of the non-compiled source code.
The errors in the Problems view should be gone now. But what just happened? First we imported an existing project that came with the examples. Then we edited the path so that it points to our Papervision3D source code. Now that we have configured this project correctly, we're ready to run the example. Select the project and publish it.
Your browser should open and show the compiled SWF. Do you see the earth turning accompanied by a 3D text? Congratulations, you've set up Papervision3D correctly!
If you get errors when compiling this project, please re-read the previous sections. The most common error is:
The definition of [ class name ] was not found.
If you get this error, you probably have not set the path correctly.
If you're familiar with the ActionScript 3.0 Language Reference, you will undoubtedly know that it's a good source for looking things up about ActionScript. It's an extensive and handy reference manual for the API's for Flash Player and Adobe Air.
Papervision3D also provides documentation. If you have downloaded the source code through SVN, you can find it inside the papervision3d_source | docs folder. Opening index.html gives you an overview of all the packages and classes.
In case you didn't choose to work with SVN, there is also an online version of the documentation. You can find it here: http://docs.pv3d.org/.
Note
The address of the online documentation may vary over time. If the address above is not valid, please visit the errata page that accompanies this book.
You can use documentation to look up how to use methods and properties, along with event handlers and listeners. It's a good idea to add either of the index.html pages as a bookmark in your browser. That way you always have easy access to the documentation. Keep in mind though that many open source projects are a constant work in progress. This may result in incomplete documentation and a lack of sample code.
Papervision3D is not a software program—it's basically a library of ActionScript classes. This open source library is available in two forms—compiled and non-compiled. The compiled code is downloadable as an SWC, which is compatible with Flex Builder, Flash Builder, and Flash CS4, but not with Flash CS3. The non-compiled code is downloadable through Subversion and as a ZIP file, and works for all four authoring tools.
We have discussed how to download and install SVN clients for both Windows and Mac OS X. With those clients we downloaded the non-compiled source code through SVN. We've also seen how to download the SWC and the ZIP. Then we configured the authoring tool of our choice by setting paths to Papervision3D. To test if our setup was done correctly, we ran some examples. Finally, we shed some light on where to find documentation.
In the next chapter, we're going to get our hands dirty by creating our first Papervision3D scene. Before we build this simple application, we will walk through some basics of 3D theory and object-oriented programming.
