Package com.google.android.filament

Class RenderableManager.Builder

  • Enclosing class:
    RenderableManager
    public static class RenderableManager.Builder
extends java.lang.Object
    Adds renderable components to entities using a builder pattern.

    • Constructor Detail

      • Builder

        public Builder​(@IntRange(from=1L)
               int count)
        Creates a builder for renderable components.
        Parameters:
        count - the number of primitives that will be supplied to the builder Note that builders typically do not have a long lifetime since clients should discard them after calling build(com.google.android.filament.Engine, int). For a usage example, see RenderableManager.

    • Method Detail

      • geometry

        @NonNull
public RenderableManager.Builder geometry​(@IntRange(from=0L)
                                          int index,
                                          @NonNull
                                          RenderableManager.PrimitiveType type,
                                          @NonNull
                                          VertexBuffer vertices,
                                          @NonNull
                                          IndexBuffer indices,
                                          @IntRange(from=0L)
                                          int offset,
                                          @IntRange(from=0L)
                                          int minIndex,
                                          @IntRange(from=0L)
                                          int maxIndex,
                                          @IntRange(from=0L)
                                          int count)
        Specifies the geometry data for a primitive. Filament primitives must have an associated VertexBuffer and IndexBuffer. Typically, each primitive is specified with a pair of daisy-chained calls: geometry() and material().
        Parameters:
        index - zero-based index of the primitive, must be less than the count passed to Builder constructor
        type - specifies the topology of the primitive (e.g., RenderableManager.PrimitiveType.TRIANGLES)
        vertices - specifies the vertex buffer, which in turn specifies a set of attributes
        indices - specifies the index buffer (either u16 or u32)
        offset - specifies where in the index buffer to start reading (expressed as a number of indices)
        minIndex - specifies the minimum index contained in the index buffer
        maxIndex - specifies the maximum index contained in the index buffer
        count - number of indices to read (for triangles, this should be a multiple of 3)

      • material

        @NonNull
public RenderableManager.Builder material​(@IntRange(from=0L)
                                          int index,
                                          @NonNull
                                          MaterialInstance material)
        Binds a material instance to the specified primitive.

        If no material is specified for a given primitive, Filament will fall back to a basic default material.

        Parameters:
        index - zero-based index of the primitive, must be less than the count passed to Builder constructor
        material - the material to bind

      • blendOrder

        @NonNull
public RenderableManager.Builder blendOrder​(@IntRange(from=0L)
                                            int index,
                                            @IntRange(from=0L,to=32767L)
                                            int blendOrder)
        Sets an ordering index for blended primitives that all live at the same Z value.
        Parameters:
        index - the primitive of interest
        blendOrder - draw order number (0 by default). Only the lowest 15 bits are used.

      • boundingBox

        @NonNull
public RenderableManager.Builder boundingBox​(@NonNull
                                             Box aabb)
        The axis-aligned bounding box of the renderable.

        This is an object-space AABB used for frustum culling. For skinning and morphing, this should encompass all possible vertex positions. It is mandatory unless culling is disabled for the renderable.

      • layerMask

        @NonNull
public RenderableManager.Builder layerMask​(@IntRange(from=0L,to=255L)
                                           int select,
                                           @IntRange(from=0L,to=255L)
                                           int value)
        Sets bits in a visibility mask. By default, this is 0x1.

        This feature provides a simple mechanism for hiding and showing groups of renderables in a Scene. See View.setVisibleLayers(int, int).

        For example, to set bit 1 and reset bits 0 and 2 while leaving all other bits unaffected, do: builder.layerMask(7, 2).

        Parameters:
        select - the set of bits to affect
        value - the replacement values for the affected bits
        See Also:
        RenderableManager.setLayerMask(int, int, int)

      • priority

        @NonNull
public RenderableManager.Builder priority​(@IntRange(from=0L,to=7L)
                                          int priority)
        Provides coarse-grained control over draw order.

        In general Filament reserves the right to re-order renderables to allow for efficient rendering. However clients can control ordering at a coarse level using priority.

        For example, this could be used to draw a semitransparent HUD, if a client wishes to avoid using a separate View for the HUD. Note that priority is completely orthogonal to layerMask(int, int), which merely controls visibility.

        The priority is clamped to the range [0..7], defaults to 4; 7 is lowest priority (rendered last).

        See Also:
        blendOrder(int, int)

      • culling

        @NonNull
public RenderableManager.Builder culling​(boolean enabled)
        Controls frustum culling, true by default.

        Do not confuse frustum culling with backface culling. The latter is controlled via the material.

      • lightChannel

        @NonNull
public RenderableManager.Builder lightChannel​(@IntRange(from=0L,to=7L)
                                              int channel,
                                              boolean enable)
        Enables or disables a light channel. Light channel 0 is enabled by default.
        Parameters:
        channel - Light channel to enable or disable, between 0 and 7.
        enable - Whether to enable or disable the light channel.

      • instances

        @NonNull
public RenderableManager.Builder instances​(@IntRange(from=1L,to=65535L)
                                           int instanceCount)
        Specifies the number of draw instance of this renderable. The default is 1 instance and the maximum number of instances allowed is 65535. 0 is invalid. All instances are culled using the same bounding box, so care must be taken to make sure all instances render inside the specified bounding box. The material can use getInstanceIndex() in the vertex shader to get the instance index and possibly adjust the position or transform.
        Parameters:
        instanceCount - the number of instances silently clamped between 1 and 65535.

      • receiveShadows

        @NonNull
public RenderableManager.Builder receiveShadows​(boolean enabled)
        Controls if this renderable receives shadows, true by default.

      • screenSpaceContactShadows

        @NonNull
public RenderableManager.Builder screenSpaceContactShadows​(boolean enabled)
        Controls if this renderable uses screen-space contact shadows. This is more expensive but can improve the quality of shadows, especially in large scenes. (off by default).

      • enableSkinningBuffers

        @NonNull
public RenderableManager.Builder enableSkinningBuffers​(boolean enabled)
        Allows bones to be swapped out and shared using SkinningBuffer. If skinning buffer mode is enabled, clients must call #setSkinningBuffer() rather than #setBonesAsQuaternions(). This allows sharing of data between renderables.
        Parameters:
        enabled - If true, enables buffer object mode. False by default.

      • skinning

        @NonNull
public RenderableManager.Builder skinning​(@IntRange(from=0L,to=255L)
                                          int boneCount,
                                          @NonNull
                                          java.nio.Buffer bones)
        Enables GPU vertex skinning for up to 255 bones, 0 by default.

        Skinning Buffer mode must be disabled.

        Each vertex can be affected by up to 4 bones simultaneously. The attached VertexBuffer must provide data in the BONE_INDICES slot (uvec4) and the BONE_WEIGHTS slot (float4).

        See also RenderableManager.setBonesAsMatrices(int, java.nio.Buffer, int, int), which can be called on a per-frame basis to advance the animation.

        Parameters:
        boneCount - Number of bones associated with this component
        bones - A FloatBuffer containing boneCount transforms. Each transform consists of 8 float. float 0 to 3 encode a unit quaternion w+ix+jy+kz stored as x,y,z,w. float 4 to 7 encode a translation stored as x,y,z,1
        See Also:
        SkinningBuffer.setBonesAsMatrices(com.google.android.filament.Engine, java.nio.Buffer, int, int)

      • morphing

        @NonNull
public RenderableManager.Builder morphing​(@IntRange(from=0L)
                                          int level,
                                          @IntRange(from=0L)
                                          int primitiveIndex,
                                          @NonNull
                                          MorphTargetBuffer morphTargetBuffer,
                                          @IntRange(from=0L)
                                          int offset,
                                          @IntRange(from=0L)
                                          int count)
        Specifies the morph target buffer for a primitive. The morph target buffer must have an associated renderable and geometry. Two conditions must be met: 1. The number of morph targets in the buffer must equal the renderable's morph target count. 2. The vertex count of each morph target must equal the geometry's vertex count.
        Parameters:
        level - the level of detail (lod), only 0 can be specified
        primitiveIndex - zero-based index of the primitive, must be less than the count passed to Builder constructor
        morphTargetBuffer - specifies the morph target buffer
        offset - specifies where in the morph target buffer to start reading (expressed as a number of vertices)
        count - number of vertices in the morph target buffer to read, must equal the geometry's count (for triangles, this should be a multiple of 3)

      • morphing

        @NonNull
public RenderableManager.Builder morphing​(@IntRange(from=0L)
                                          int level,
                                          @IntRange(from=0L)
                                          int primitiveIndex,
                                          @NonNull
                                          MorphTargetBuffer morphTargetBuffer)
        Utility method to specify morph target buffer for a primitive. For details, see the morphing(int).

      • build

        public void build​(@NonNull
                  Engine engine,
                  int entity)
        Adds the Renderable component to an entity.

        If this component already exists on the given entity and the construction is successful, it is first destroyed as if RenderableManager.destroy(int) was called.

        Parameters:
        engine - reference to the Engine to associate this renderable with
        entity - entity to add the renderable component to