How to use the BillboardRenderer in Unity?

Since version 5 (?) Unity has a new component-type BillboardRenderer. Unfortunately the documentation is quite poor.

It can be added in the inspector by clicking on "Add Component -> Misceallaneous -> Billboard Renderer" but apparently it requires a Billboard Asset to do anything. There doesn't seem to be any way to create one from the Unity interface.

One of the few sentences from the equally poor documentation of BillboardAsset reads:

imageCount Number of pre-baked images that can be switched when the billboard is viewed from different angles.

My newest project will have sprite/polygon mix graphics, so a component which renders a billboard with a different sprite depending on the view angle is something I could really make use of. But there doesn't seem to be any method to add such images.

So I wondered if you could post an example how this component is used.

Answer

UPDATE (2018): There are more properties exposed since I wrote this answer. Maybe we can create it now, maybe not. Gotta research.

You can't use it.

Here is decompiled BillboardAsset code:

using System;

namespace UnityEngine
{

    /// 

    ///   BillboardAsset describes how a billboard is rendered.
    /// 
    public sealed class BillboardAsset : Object
    {
        /// 

        ///   Height of the billboard that is below ground.
        /// 
        public float bottom
        {

            [WrapperlessIcall]
            get;
            [WrapperlessIcall]
            set;
        }

        /// 

        ///   Height of the billboard.
        /// 
        public float height

        {
            [WrapperlessIcall]
            get;
            [WrapperlessIcall]
            set;
        }

        /// 

        ///   Number of pre-baked images that can be switched when the billboard is viewed from different angles.
        /// 

        public int imageCount
        {
            [WrapperlessIcall]
            get;
        }

        /// 

        ///   Number of indices in the billboard mesh. The mesh is not necessarily a quad. It can be a more complex shape which fits the actual image more precisely.
        /// 
        public int indexCount

        {
            [WrapperlessIcall]
            get;
        }

        /// 

        ///   The material used for rendering.
        /// 
        public Material material
        {

            [WrapperlessIcall]
            get;
            [WrapperlessIcall]
            set;
        }

        /// 

        ///   Number of vertices in the billboard mesh. The mesh is not necessarily a quad. It can be a more complex shape which fits the actual image more precisely.
        /// 
        public int vertexCount

        {
            [WrapperlessIcall]
            get;
        }

        /// 

        ///   Width of the billboard.
        /// 
        public float width
        {

            [WrapperlessIcall]
            get;
            [WrapperlessIcall]
            set;
        }

        /// 

        ///   Constructs a new BillboardAsset.
        /// 
        public BillboardAsset()

        {
        }

        [WrapperlessIcall]
        internal extern void MakeMaterialProperties(MaterialPropertyBlock properties, Camera camera);

        [WrapperlessIcall]
        internal extern void MakePreviewMesh(Mesh mesh);

        [WrapperlessIcall]

        internal extern void MakeRenderMesh(Mesh mesh, float widthScale, float heightScale, float rotation);
    }
}

There is literally no way to set images, even by reflection. One may think: “okay, you can't do it directly, but maybe there is some kind of factory provided?”. I press Find Usages in decompiler and get: BillboardAssetInspector and BillboardRenderer.

Here is BillboardRenderer:

using System;

namespace UnityEngine
{

    /// 

    ///   Renders a billboard.
    /// 
    public sealed class BillboardRenderer : Renderer
    {
        /// 

        ///   The BillboardAsset to render.
        /// 
        public BillboardAsset billboard
        {

            [WrapperlessIcall]
            get;
            [WrapperlessIcall]
            set;
        }

        /// 

        ///   Constructor.
        /// 
        public BillboardRenderer()

        {
        }
    }
}

Wow, this class is even dumber. It's just logic-less data holder. Obviously, all work is done by Renderer. More precisely, by one or couple of [WraplessIcall]-methods in it. I won't put its code here because it's long and useless list of [WraplessIcall]-members.

Unlike UnityEngine.dll content, BillboardAssetInspector (that is residing in UnityEditor.dll) has real code in it. Again, I won't put its code here, because it's clear from its name that it's nothing more than Inspector, anyway.

Same situation with BillboardAssetInspector.

---

Got it, it's for internal usage; but where is it used exactly?

In SpeedTree system (look at the last image in particular).

Why does documentation explain useless stuff instead of warning against using it right away?

Probably, just copy-pasted everything from internal development documentation, improved parts that are important for newcomers and in general usage; then was too busy participating in VR hype to bother polishing such dark corners of documentation.

What can we do about it?

Tell them that they overlooked this “dark corner” in the documentation, for example: In Unity Editor, open Help → Report a bug..., in What is problem related to choose documentation, etc.

What can one use instead?

Possible options include: