useOwnContainer [scrap]

http://blog.zupko.info/?p=129

GREAT WHITE, MEET EFFECTS

So, after getting asked for the hundredth time the other day when I was going to integrate some of the features of the Effects Branch to Great White - I decided it was about time to do so. Things are settling in with my new job, and I've finished up my other obligations as well - so I put in the the time.

And now... They have been merged!!!

There are A LOT of changes though: creating layers, controlling layers, creating dynamic layers, sorting layers... its all different. Fortunately, I think for the better. I've comped up a set of VERY simple demos (all in one class) and will go over some of the new functionality here - just for you. Keep in mind this is still beta - so PLEASE report any bugs to me here or on the list.

--ViewportLayer has now replaced RenderLayer

Thats right - sorry. Forgot everything you ever knew about RenderLayers and RenderLayer syntax. Now - instead of layers being controlled by the objects - they are entirely controlled by the viewport. This means that you can create a layer for an object across multiple viewports.

Here's how you can create a new ViewportLayer:

PLAIN TEXT

Actionscript:

1. var layer:ViewportLayer = viewport.getChildLayer(do3d, true);
2. //now you can mess with your ViewportLayer all you want...
3. layer.alpha = 0.5;

getChildLayer() is the function to receive or create a new ViewportLayer. The second parameter, createNew, specifies if a new ViewportLayer should be created if one is not found for the specified DisplayObject3D. If you set createNew to false- getChildLayer will simply return the ViewportLayer for the DO3D if it exists, otherwise it will return null.

Note that your DO3D is now going to be rendered to the layer created in getChildLayer(). If you want to add other DO3Ds to this layer, you can do so by using the following function of ViewportLayer:

PLAIN TEXT

Actionscript:

1. //add a new DO3D to the layer created above.
2. layer.addDisplayObject3D(new Sphere(new ColorMaterial()));

Likewise, you can remove DO3Ds from rendering to a specific layer by using removeDisplayObject3D.

--Nesting

Something else cool about ViewportLayers is they can be nested. Each ViewportLayer handles the sorting of its own children. So lets say you want to use INDEX sort for a COLLADA object with a fair number of z-fighting children - but you want that COLLADA to be z-sorted with the rest of your world. Now, you can.

Check out initNestingDemo() from the source. You will notice that we can create an empty ViewportLayer and add it to the viewport.containerSprite (also a ViewportLayer). Then we can create children inside that layer that will be INDEX sorted. Finally we create an external layer that will be Z sorted:

PLAIN TEXT

Actionscript:

1. //s, s2, and s3 are three spheres added to the scene.
2.  
3. //create an empty viewport layer and add it to the container
4. var parentLayer:ViewportLayer = new ViewportLayer(viewport, null);
5. viewport.containerSprite.addLayer(parentLayer);
6. parentLayer.sortMode = ViewportLayerSortMode.INDEX_SORT;
7.  
8. //create new layers inside the empty parentLayer and set some layer indexes for them
9. parentLayer.getChildLayer(s, true).layerIndex = 1;
10. parentLayer.getChildLayer(s2, true).layerIndex = 2;
11.  
12. //add s3 to a different layer off the main container - this will be z-sorted with parentLayer (with two index sorted children)
13. viewport.getChildLayer(s3, true);

--useOwnContainer

This property gives you the ability to tell Papervision to dynamically create a layer for your DisplayObject3D when it is rendered in the viewport. By setting DisplayObject3D.useOwnContainer to true, your object will be rendered with its own ViewportLayer. Moreover, you can assign properties to your DisplayObject3D that will be passed along to your generated Layer. These properties are:

• filters
• blendMode
• alpha

By setting these properties, you can add any filter to the layer, change the blendMode of your Layer, and control the alpha of the layer. Keep in mind that you can change these properties at runtime, as a new layer is generated every render, and it will inherit the updated settings. Here is a simple snippet of using these new properties:

PLAIN TEXT

Actionscript:

1. var p:Plane = new Plane(new ColorMaterial());
2. p.useOwnContainer = true;
3. p.filters = [new BlurFilter(int(Math.random()*16)+2, int(Math.random()*16)+2)];
4. p.blendMode= BlendMode.ADD;
5. p.alpha = Math.random()+0.1;

You can see that we are creating a new plane, setting it to create a unique container, and then set an Additive blend mode, have a random alpha, and a random blur. In my code demo you will see that i create a large number of planes and change their filter's blur based on screenDepth (distance from the camera). Be sure to play with it.

--Effects

Effects have changed somewhat for GreatWhite too - but not too much. You still have BitmapEffectLayer - but it now extends ViewportLayer. You simply need to create a BitmapEffectLayer, at it to the containerSprite, and add your DisplayObject3Ds using addDisplayObject3D:

PLAIN TEXT

Actionscript:

1. //create a new BitmapEffectLayer
2. var bfx:BitmapEffectLayer = new BitmapEffectLayer(viewport, 500, 500);
3. viewport.containerSprite.addLayer(bfx);
4.  
5. var s:Sphere = new Sphere(new WireframeMaterial());
6. scene.addChild(s);
7.  
8. //add the sphere to the layer
9. bfx.addDisplayObject3D(s);
10.  
11. //add a blur effect to the layer
12. bfx.addEffect(new BitmapLayerEffect(new BlurFilter(2, 2, 8)));

You can add effects to other ViewportLayers by simply using the filters property inherent to all Sprites.

--Selective Layer Rendering

One other thing that has been added is the ability to render only selected ViewportLayers. I added this with the following scenario in mind: You have a large room, but the camera doesn't move much. You don't want to have to create a new Viewport for the floor, walls, etc - but also don't want them rendered every frame. Well, now you can tell your renderer which layers you want updated, and which to ignore. You can see this in the source under initLayerRenderDemo().

So how do we do it? All we need to do is create an Array with the ViewportLayers we want rendered - then call renderer.renderLayers(). Thats it! Here's a quick look:

PLAIN TEXT

Actionscript:

1. layersToRender = new Array();
2. layersToRender.push(viewport.getChildLayer(s, true));
3. viewport.getChildLayer(s2, true);
4. viewport.getChildLayer(s3, true);
5. //pass the layer for s only to be rendered
6. renderer.renderLayers(scene, camera, viewport, layersToRender);

Please note, that at this time, interaction will be lost for objects that aren't rendered again. I'll look into fixing this down the line.

--A Few Final Notes

Those sum up some of the biggest changes - there is some other stuff that might popup - if you have any questions, or need help figuring out whats going on - just let me know. Here are a few final tidbits:

DisplayObject3D.container - this references the last ViewportLayer your DO3D was rendered too. It is null before your object is rendered for the first time.

DisplayObject3D.createViewportLayer() - This function is another way to create a ViewportLayer. The first parameter is the viewport you want the layer created in. The second parameter specifies if you should set this to be the layer for all children of the current DO3D.

ViewportLayer.forceDepth - set this to true to set how far into the Z order your layer is rendered. Say, you know your floor should always be sorted 4500 away from the camera - but other things can sort around that. set forceDepth = true, and screenDepth = 4500 - and you've got it.

ViewportLayer.layerIndex - I mentioned it before - but you set this property when you have your layer.sortMode == RenderLayerSortMode.INDEX_SORT. Higher numbers will be higher on the DisplayList.

And again - this is beta - things will probably change. But let me or the team know if you find any bugs!!!

Get the Source

Enjoy!