Este es el primer post sobre la tecnología 3D con flash llamada Papervision3D. Ya que estoy empezando con ello, iré posteando referencias sobre las pruebas que haga. Hay muchos tutoriales por ahí con los que empezar, pero creo que otro punto de vista nunca viene mal, y sobretodo si está en español (la mayoría no lo son)

Nota: Este artículo parte de cero en cuanto a que no solo explica el comienzo de un proyecto con papervision, sino también a cómo usar un cliente de subversion para actualizar y/o descargar el uso de código de terceras partes, la configuración de un proyecto en Flex Builder y conceptos básicos con los que empezamos a lidiar cuando damos el salto desde Flash a otro modo de desarrollar ActionScript

Si nunca has desarrollado una aplicación con papervision creo que primero habría que entender cuál es su funcionamiento básico y cómo ponerlo en marcha, así como conceptos fundamentales, como qué es una escena, un viewport, renderizado, etc.

Antes de empezar: preparar nuestro entorno de desarrollo.

Papervision3D en realidad no se instala. Se trata de una librería de clases de ActionScript de la que se servirá nuestra aplicación para implementar sus funciones. En nuestro caso usaremos la herramienta Flex Builder 3 para codificar, lo que no significa que usemos el framework de Flex, ya que solo escribiremos ActionScript.

Primer paso: descargar la última versión de papervision3D

Normalmente las librerías de código se encuentran en repositorios de control de versiones como Subversion. Así funciona Google Code, que es donde se encuentra alojado el repositorio de papervision. Para poder descargar (check out) un repositorio necesitamos un cliente de subversion. Hay muchos de ellos. El más común y usado es Tortoise (no por ello el mejor), que se integra con el explorador de windows y es muy simple de usar. Si usas Mac OSX, una solución casi idéntica es SCPlugin, que podéis descargar aquí.

Descarga uno según tu sistema operativo y después de instalarlo crea una carpeta en tu disco duro que se llame por ejemplo “papervision3D”. Sobre la carpeta presiona con el botón derecho y busca el menu “SVN Checkout…” (windows) o “Más > Subversion > Checkout” (mac).

En el campo “URL” escribe la dirección del repositorio (http://papervision3d.googlecode.com/svn/trunk/), deja el resto de opciones tal cual y presiona “ok” o “checkout”.

Tendrás que esperar a que se descarguen todos los archivos. Al terminar verás que contiene 4 carpetas. La que nos interesa especialmente es lo que hay dentro de “branches/GreatWhite/src/”, ya que el resto son versiones deprecadas que ya no se actualizan. El proyecto está en constante evolución, y si lo actualizas a menudo (botón derecho sobre la carpeta > SVN update con windows o “más > svn update con mac) verás que casi siempre hay nuevas actualizaciones por parte del equipo de desarrollo.

Mi recomendación es crear una carpeta común para todas las librerías de código que utilicemos en nuestros proyectos. Yo tengo una carpeta “ActionScript” donde tengo todas las clases.
En este caso copié las contenidos de “branches/GreatWhite/src/” en mi carpeta “ActionScript”. (com, fl, org, nochump).

Segundo paso: configurar un proyecto en FlexBuilder

Abrimos Flex Builder y creamos un nuevo “ActionScript project”

Le damos un nombre al proyecto (ej: “PapervisionTest” y especificamos la carpeta donde se va a alojar, y pulsamos next:

En la pestaña “Source path” clicamos “Add folder…” y buscamos nuestra carpeta de “ActionScript” de la que os hablaba anteriormente, que es donde están alojadas nuestras clases incluidas las de papervision.
En “Main Source Folder” clicamos “Browse”, seleccionamos la carpeta de proyecto, clicamos new (automáticamente nos crea la carpeta “src”, la seleccionamos y clicamos “ok”. El resto lo dejamos tal cuál y clicamos “Finish”.

Ya tenemos todo funcionando, y ya podemos empezar a escribir código. Flex Builder crea automáticamente la clase principal de la aplicación o lo que se suele llamar “Document Class”.
Nota: esta clase debe tener un package sin nombre como en siguiente ejemplo:

Conceptos básicos

Viewport: es la parte visible de todos nuestros elementos 3D y el encargado de coordinar el tipo de renderizado, la cámara y la escena. Es lo que añadimos directamente a nuestro stage de Flash. Si definimos un viewport de 500 x 400 píxeles, todo lo que se encuentre fuera de esas dimensiones no se verá.

Escena (Scene): es el contenedor de todos los elementos visibles y formas que tendrá nuestra aplicación. Digamos que es como un “display list” interno de papervision.

Motor de renderizado (Renderer): como su nombre indica se encarga de renderizar la escena y cómo bien explica Wikipedia, en términos de visualizaciones en ordenador, más específicamente en 3D, la “renderización” es un proceso de cálculo complejo desarrollado por un ordenador destinado a generar una imagen 2D a partir de una escena 3D. En papervision, cada vez que modificamos algo en la escena 3D, debemos renderizar de nuevo. Lo que se suele hacer es un método que se encargue de ello y que se ejecuta en un intervalo fijo mediante el evento “ENTER_FRAME”.

Cámara: en papervision podemos controlar la posición, rotación y zoom de la cámara que visualiza el contenido.

Configuración típica

A continuación verás el código ActionScript con la configuración típica y básica de una aplicación papervision. En realidad no hace más que inicializar los elementos de los que hablaba en el punto anterior, y no tiene ningún efecto visual:

/**
 * Author: xleon, http://www.xinterface.net (malandro@gmail.com)
 */
 
package
{
    import flash.display.Sprite;
    import flash.events.Event;
 
    import org.papervision3d.cameras.Camera3D;
    import org.papervision3d.render.BasicRenderEngine;
    import org.papervision3d.scenes.Scene3D;
    import org.papervision3d.view.Viewport3D;
 
    // meta datos para el swf resultante:
    [SWF(frameRate="31", width="500", height="400", backgroundColor="0xffffff")]
 
    public class Sample1 extends Sprite
	{
		private var viewport:Viewport3D;
 
		// existe más de un tipo de renderizado, este es el mas comun
		private var renderer:BasicRenderEngine;
 
		private var scene:Scene3D;
 
		/*
		existe mas de un tipo de camara, con este tipo
		nos aseguramos de que siempre apunte hacia un target
		determinado, que si no se especifica, sera nuestra escena
		*/
		private var camera:Camera3D;
 
		// constructor
		public function Sample1()
		{
			// En este caso solo nos hace falta iniciar el 3D
			Init3D();
		}
		/*
		este metodo inicializa todo lo relacionado
		con nuestro entorno 3D
		*/
		private function Init3D():void
		{
			/*
			creamos el viewport y lo añadimos al displayList
			Si queremos que algun elemento de la escena sea interactivo
			o se pueda clicar en el, el parametro @interactive (el cuarto) debe ser "true"
			*/
			viewport = new Viewport3D(500, 400, false, true);
			addChild(viewport);
 
			renderer = new BasicRenderEngine;
			scene = new Scene3D;
			camera = new Camera3D;
 
			CreateObjects();
			addEventListener(Event.ENTER_FRAME, Loop3D);
		}
 
		/*
		esta función se encarga de crear y configurar los
		objetos de nuestra escena y los incluye en ella
		*/
		private function CreateObjects():void
		{
 
		}
		private function Loop3D(event:Event):void
		{
			/*
			Aquí añadimos movimientos de piezas, de camara, y toda
			la interactividad y comportamientos.
			Para que los cambios tengan efecto visualmente
			deberemos finalmente renderizar la escena
			*/
			Render();
		}
		/*
		este metodo es generico y no hará falta modificarlo
		si mantenemos la estructura
		*/
		private function Render():void
		{
			renderer.renderScene(scene, camera, viewport);
		}
	}
}

Añadiendo movimiento y un objeto simple

Ahora que ya tenemos todo en condiciones, podemos añadir un elemento a la escena, e incluir una ecuación sencilla para el movimiento de cámara, de tal forma que podremos interactuar con el movimiento del ratón.

En el método “Init3D()” añadimos este código para posicionar la cámara:

// configuracion de la camara
camera.zoom = 10;
camera.z = -1000;
camera.y = 300;
camera.x = 0;

Creamos un plano que es un elemento básico o primitiva. Para que un plano u otra primitiva sea visible deberemos asignarle un material.
Para ello creamos primero un WireframeMaterial, que no es sino un material donde solo se ven los triángulos de la maya 3D. Por último lo añadimos a la escena. Incluiremos todo esto en el método “CreateObjects()”:

private function CreateObjects():void
{
// Creamos un material con dos caras iguales:
var mat:WireframeMaterial = new WireframeMaterial;
mat.doubleSided = true;
 
// Creamos un plano con el material anterior:
var plane:Plane = new Plane(mat, 500, 500, 8, 8);
plane.rotationX = -90;
 
// lo añadimos a la escena
scene.addChild(plane);
}

Para finalizar el ejemplo añadiremos un código en el método “Loop3D()” que da movimiento circular a la cámara en función de la posición del ratón:

private function Loop3D(event:Event):void
{
/*
Creamos un movimiento de cámara circular que rodee nuestra escena
Podemos controlar la distancia con el valor del radio
*/
 
var radio:uint = 500;
 
var angulo:Number = mouseX + mouseX + stage.stageWidth / 2;
 
camera.x = radio * Math.cos(angulo / 100);
camera.z = radio * Math.sin(angulo / 100);
camera.y = - mouseY + stage.stageHeight / 2;
 
Render();
}

Resultado

Código fuente: Sample1.as (La clase final tiene algunas modificaciones pero son insignificantes)

Espero que este sea el primero de serie de artículos sobre este tema tan entretenido y potente. Como primer artículo me ha parecido bien hacerlo tan explícito y pasito a pasito. El siguiente será más directo.