The Away3D “dev” Branch

If you’ve been following the updates on the Away3D blog, you’ll have noticed the updated roadmap mentioning the dev branch on Github. This branch is basically where we’re working to get things towards Beta, so take a look if you’re curious to see where we’re headed. I personally advise anyone to use this branch if you’re starting out with a new project but make a snapshot of the revision you’re working with. Some things will still change and might very well break your code ;)

We’ll put up some proper blog posts introducing new features as we get to Beta, but for now I’ll quickly explain what I’ve personally been working on, and how I broke your existing code ;) I’ve also went ahead and updated the source code for the demos in previous blog posts to match the dev branch, so you can see how it differs concretely.


Death to BitmapMaterial! All hail TextureMaterial!

One of the biggest changes, I think. Favouring composition over inheritance, we deprecated BitmapMaterial, VideoMaterial, MovieMaterial etc. They have been replaced by a single TextureMaterial, which accepts a Texture2DBase object. In practice, this will for instance be a BitmapTexture (VideoTexture etc are still in development). This way, when supporting new texture types you don’t need to extend every type of material that needs to extend this material type, which is especially a mess when you start creating custom materials (and need to extend/duplicate those to support all possible texture types). The same applies for cube maps (fe: BitmapCubeTexture), the normal and specular maps that are set on the default materials, and the view’s backgroundImage (now simply View3D::background). It’s a big change that might annoy many of you, but it’s necessary. With things like ATF support coming up (and who knows what else), things would simply become unmanageable and error-prone otherwise.

Furthermore, there are some “special” convenience textures that can be used for the default materials. For instance, these materials expect a specular map to have the specular strength on the red channel, and the specular power (gloss) on the green. SpecularBitmapTexture allows you to pass two greyscale BitmapData objects (gloss is optional) and composites the data correctly. When using texture splatting, you can use SplatBlendBitmapTexture, which takes 3 BitmapData objects containing the blending value for each splatting layer and places each on the red, blue and green channels as expected by TerrainDiffuseMethod. However, in both cases, it’s usually better to do these things in your offline asset preparation stage and use simpler texture objects instead.


Light Picking

Another rather big change for those working with lights, but one that offers great benefits. Instead of assigning the lights as a static array as before, materials now expect a LightPickerBase object. Right now, that means StaticLightPicker, which in turn accepts the array of lights. Why this extra object? This way, you can create a DynamicLightPicker object that selects the most important lights from the EntityCollector, allowing different lights to be used without reassigning the light array (and as a result potentially invalidating the material). As light collection is often game-engine dependent, providing our own dynamic light picker is not the highest priority. At least it’s good to know the possibility is there, right? ;)



Before, most dispose(…) methods accepted a “deep” parameter, which caused “sub-assets” (Geometry of a Mesh, BitmapData of a BitmapTexture, etc) to be disposed as well. While in some cases this saves you from writing a trivial few lines of disposal code, in many cases it just is an open door to invalid state (accidentally disposing a BitmapData used by another BitmapTexture) and ambiguity (what will be cleared, and what will remain uncleaned?). Allowing an object to destroy objects it did not create is poor resource management and generally bad practice in my opinion. Hence the new credo: you clean up what you create!


Ambient lighting

There have been some changes in how ambient lighting works. Before, the ambient and ambientColor of the materials dictated how much ambient light is coming from the lights, rather than how much ambient light is actually reflected by the material. That has been changed, and lights now have ambient and ambientColor properties as well. As a result, ambient light now functions similar to diffuse and specular light. The lights emit it, the material reflects it. It’s usually best to only set ambient light properties on DirectionalLight objects, since ambient light is global. PointLight objects can get culled if they’re not affecting anything in the frustum and their ambient contribution would be dropped as a result.


Other changes and new features

  • Big refactor on how the materials and animations are compiled to facilitate building custom materials
  • Slight restructuring of the render flow to allow more intricate custom renderers
  • Light probes (default materials only support convoluted cube maps at this point)
  • Reduced shadow swimming with shadow mapping
  • RefractionEnvMapMethod for environment-map based refraction mapping
  • AnisotropicSpecularMethod for anisotropic specular highlights
  • Shadow mapping for point lights (HardShadowMapMethod only)
  • AlphaMaskMethod to influence the material’s alpha, optionally based on a secondary UV set
  • Light map methods: DiffuseLightMapMethod to apply light maps as diffuse light, and LightMapMethod to apply it on the final shaded result
  • WrapDiffuseMethod to perform a very cheap fake way for subsurface scattering, as outlined in GPU Gems #1
I hope to scrape together some time to write some things about these new features as soon as possible. A recurring promise, I know, but bear with me here ;)
Update: Forgot to mention that there are also updated official Away3D demos in the examples’ texture-refactor branch (the name is due to a previous branch).

6 thoughts on “The Away3D “dev” Branch

  1. I am sure that you must have checked in some updated code to demo some of these many new facilities. But, whether I use the link you provided, or navigated down to the texturerefactor branch of the away3d-examples-fp11 repository, no commits more recent than “Fix Bear” on November 30th are available for download.

    At the top level of away3d, the summary for the 17 repositories being managed, the commend for away3d-examples-fp11, indeed, states that the last update was just two days ago — when you did the dev merge.

    Are the different levels of access to this open source project depending on permissions? What permissions are required to be able to view your demos so that we can get started on refactoring everything that we have produced during the alpha phase? I presume that Fabrice, Lidev and Muzerly have been busily assimilating your changes all along and I reckon that Darcey Llloyd will come through with his usually excellent tutorial examples as soon as he can re-write them to you new API.

    As the milestones have already slipped, I would really like to start getting my projects/commitments back on target by not having to wait until someone gets around to running ASDocs and making the demos public.

  2. Hey Terry,

    The Github repo for the examples is the latest version and contains all the new apis, it’s just showing the date when something was committed last (ie; in my local branch), not when it was pushed. If you look at the demos, they’re all using TextureMaterial instead of BitmapMaterial, for example.
    The updates outlined above is the work done since about September. Some new features from November onwards didn’t get pushed until now because of some outstanding details and lack of time in December, which didn’t really affect the example branch at all ;) Hence the “30 November” date!

    Hope that helps!

  3. Yes, it helps, thank you.

    I am not much of a github expert and I come to if from a Windows client, not *nix. Anyway, dispensing with my reliance on TortoiseGit and going to the command line, I find that there is indeed both a texturerefactor and a dev branch of the examples repository, paralleling the structure of the code library. That is why the github screen shows 3 branches although it only lists the master and texturerefactor. There is not, however, anything of interest in the dev branch of the examples, so I guess it got the December 27th timestamp for date of last update from something that was not committed, or was removed.

    In any case, I will take your Intermediate_LightProbes as my exemplar and see how it behaves when perturbed to add and remove some objects in a loop to watch memory consumption. As best as I have been able to watch, you have not really spent any time on the open issues addressing memory leaks as reported by different folks under varying conditions. While I can agree that having the programmer decide which of the assets owned by an object should be disposed, just having me call the method instead of having Mesh call the method is not going to fix the inherent problem of lingering references somewhere in the black box that prevents GC. So, I will retrace my steps of a couple of months ago to see whether it is in the sloppy code associated with material assets, or somewhere in the interface to the Molehill structures being passed back and forth to the GPU. Until someone can run a demo that successfully adds and removes well-behaved objects sharing textures/materials/sub-geometries or whatever, I cannot ship any of my applications as they will all die from the latent memory leaks. I guess I should just be happy to know that with all your enhancements, before my application dies, it will certainly look at lot cooler, but my users are not people seeing how fast a car can fall off of a cliff, so they apply a somewhat different standard to the definition of ‘coolness’.

    BTW, I am not sending this to inflame anyone; its just the most productive place to pass needed information back to you. Please just delete this after your review.

  4. As we’ve mentioned before in the roadmap, we’re currently spending time on getting to beta with a stable API, so that people can make sure their code won’t need to be rewritten. If bugs pop up, a developer could try to patch it by himself (it’s open source after all), whereas someone can’t anticipate API changes themselves. Hence this priority (this also includes “big” new features that cause us to refactor considerable parts of code). We’re aware of your memory leak reports, and we’re to look into that when we can.

  5. Pingback: Away3D 4.0里的绘图 | Flash开发者大会

  6. When can we expect a replacement for the missing MovieMaterial? – i get the impression a lot of people are missing this functionality.

    Regards ;)

Leave a Reply

Your email address will not be published. Required fields are marked *