Package com.google.android.filament

Class View

  • public class View
extends java.lang.Object
    Encompasses all the state needed for rendering a Scene.

    Renderer.render(com.google.android.filament.View) operates on View objects. These View objects specify important parameters such as:

    • The Scene
    • The Camera
    • The Viewport
    • Some rendering parameters

    View instances are heavy objects that internally cache a lot of data needed for rendering. It is not advised for an application to use many View objects.

    For example, in a game, a View could be used for the main scene and another one for the game's user interface. More View instances could be used for creating special effects (e.g. a View is akin to a rendering pass).

    See Also:
    Renderer, Scene, Camera, RenderTarget

    • Method Detail

      • setName

        public void setName​(@NonNull
                    java.lang.String name)
        Sets the View's name. Only useful for debugging.

      • getName

        @Nullable
public java.lang.String getName()
        Returns the View's name.

      • setScene

        public void setScene​(@Nullable
                     Scene scene)
        Sets this View instance's Scene.

        This method associates the specified Scene with this View. Note that a particular scene can be associated with several View instances. To remove an existing association, simply pass null.

        The View does not take ownership of the Scene pointer. Before destroying a Scene, be sure to remove it from all assoicated Views.

        See Also:
        getScene()

      • setCamera

        public void setCamera​(@Nullable
                      Camera camera)
        Sets this View's Camera.

        This method associates the specified Camera with this View. A Camera can be associated with several View instances. To remove an existing association, simply pass null.

        The View does not take ownership of the Scene pointer. Before destroying a Camera, be sure to remove it from all assoicated Views.

        See Also:
        getCamera()

      • setViewport

        public void setViewport​(@NonNull
                        Viewport viewport)
        Specifies the rectangular rendering area.

        The viewport specifies where the content of the View (i.e. the Scene) is rendered in the render target. The render target is automatically clipped to the Viewport.

        If you wish subsequent changes to take effect please call this method again in order to propagate the changes down to the native layer.

        Parameters:
        viewport - The Viewport to render the Scene into.

      • setVisibleLayers

        public void setVisibleLayers​(@IntRange(from=0L,to=255L)
                             int select,
                             @IntRange(from=0L,to=255L)
                             int values)
        Sets which layers are visible.

        Renderable objects can have one or several layers associated to them. Layers are represented with an 8-bits bitmask, where each bit corresponds to a layer. By default all layers are visible.

        Parameters:
        select - a bitmask specifying which layer to set or clear using values.
        values - a bitmask where each bit sets the visibility of the corresponding layer (1: visible, 0: invisible), only layers in select are affected.
        See Also:
        RenderableManager.setLayerMask(int, int, int)

      • setScreenSpaceRefractionEnabled

        public void setScreenSpaceRefractionEnabled​(boolean enabled)
        Enables or disables screen space refraction. Enabled by default.
        Parameters:
        enabled - true enables screen space refraction, false disables it.

      • setRenderTarget

        public void setRenderTarget​(@Nullable
                            RenderTarget target)
        Specifies an offscreen render target to render into.

        By default, the view's associated render target is null, which corresponds to the SwapChain associated with the engine.

        A view with a custom render target cannot rely on Renderer.ClearOptions, which only applies to the SwapChain. Such view can use a Skybox instead.

        Parameters:
        target - render target associated with view, or null for the swap chain

      • setSampleCount

        @Deprecated
public void setSampleCount​(int count)
        Deprecated.
        use setMultiSampleAntiAliasingOptions instead
        Sets how many samples are to be used for MSAA in the post-process stage. Default is 1 and disables MSAA.

        Note that anti-aliasing can also be performed in the post-processing stage, generally at lower cost. See the FXAA option in setAntiAliasing(com.google.android.filament.View.AntiAliasing).

        Parameters:
        count - number of samples to use for multi-sampled anti-aliasing.

      • getSampleCount

        @Deprecated
public int getSampleCount()
        Deprecated.
        use getMultiSampleAntiAliasingOptions instead
        Returns the effective MSAA sample count.

        A value of 0 or 1 means MSAA is disabled.

        Returns:
        value set by setSampleCount(int)

      • setAntiAliasing

        public void setAntiAliasing​(@NonNull
                            View.AntiAliasing type)
        Enables or disables anti-aliasing in the post-processing stage. Enabled by default.

        For MSAA anti-aliasing, see setSampleCount(int).

        Parameters:
        type - FXAA for enabling, NONE for disabling anti-aliasing.

      • getAntiAliasing

        @NonNull
public View.AntiAliasing getAntiAliasing()
        Queries whether anti-aliasing is enabled during the post-processing stage. To query whether MSAA is enabled, see getSampleCount().
        Returns:
        The post-processing anti-aliasing method.

      • setMultiSampleAntiAliasingOptions

        public void setMultiSampleAntiAliasingOptions​(@NonNull
                                              View.MultiSampleAntiAliasingOptions options)
        Enables or disable multi-sample anti-aliasing (MSAA). Disabled by default.
        Parameters:
        options - multi-sample anti-aliasing options

      • getMultiSampleAntiAliasingOptions

        @NonNull
public View.MultiSampleAntiAliasingOptions getMultiSampleAntiAliasingOptions()
        Returns multi-sample anti-aliasing options.
        Returns:
        multi-sample anti-aliasing options

      • setTemporalAntiAliasingOptions

        public void setTemporalAntiAliasingOptions​(@NonNull
                                           View.TemporalAntiAliasingOptions options)
        Enables or disable temporal anti-aliasing (TAA). Disabled by default.
        Parameters:
        options - temporal anti-aliasing options

      • setScreenSpaceReflectionsOptions

        public void setScreenSpaceReflectionsOptions​(@NonNull
                                             View.ScreenSpaceReflectionsOptions options)
        Enables or disable screen-space reflections. Disabled by default.
        Parameters:
        options - screen-space reflections options

      • getTemporalAntiAliasingOptions

        @NonNull
public View.TemporalAntiAliasingOptions getTemporalAntiAliasingOptions()
        Returns temporal anti-aliasing options.
        Returns:
        temporal anti-aliasing options

      • getScreenSpaceReflectionsOptions

        @NonNull
public View.ScreenSpaceReflectionsOptions getScreenSpaceReflectionsOptions()
        Returns screen-space reflections options.
        Returns:
        screen-space reflections options

      • setColorGrading

        public void setColorGrading​(@Nullable
                            ColorGrading colorGrading)
        Sets this View's color grading transforms.
        Parameters:
        colorGrading - Associate the specified ColorGrading to this view. A ColorGrading can be associated to several View instances. Can be null to dissociate the currently set ColorGrading from this View. Doing so will revert to the use of the default color grading transforms.

      • setDithering

        public void setDithering​(@NonNull
                         View.Dithering dithering)
        Enables or disables dithering in the post-processing stage. Enabled by default.
        Parameters:
        dithering - dithering type

      • getDithering

        @NonNull
public View.Dithering getDithering()
        Queries whether dithering is enabled during the post-processing stage.
        Returns:
        the current dithering type for this view.

      • setDynamicResolutionOptions

        public void setDynamicResolutionOptions​(@NonNull
                                        View.DynamicResolutionOptions options)
        Sets the dynamic resolution options for this view.

        Dynamic resolution options controls whether dynamic resolution is enabled, and if it is, how it behaves.

        If you wish subsequent changes to take effect please call this method again in order to propagate the changes down to the native layer.

        Parameters:
        options - The dynamic resolution options to use on this view

      • setRenderQuality

        public void setRenderQuality​(@NonNull
                             View.RenderQuality renderQuality)
        Sets the rendering quality for this view (e.g. color precision).
        Parameters:
        renderQuality - The render quality to use on this view

      • setFrontFaceWindingInverted

        public void setFrontFaceWindingInverted​(boolean inverted)
        Inverts the winding order of front faces. By default front faces use a counter-clockwise winding order. When the winding order is inverted, front faces are faces with a clockwise winding order. Changing the winding order will directly affect the culling mode in materials (see Material#getCullingMode). Inverting the winding order of front faces is useful when rendering mirrored reflections (water, mirror surfaces, front camera in AR, etc.).
        Parameters:
        inverted - True to invert front faces, false otherwise.

      • setDynamicLightingOptions

        public void setDynamicLightingOptions​(float zLightNear,
                                      float zLightFar)
        Sets options relative to dynamic lighting for this view.

        Together zLightNear and zLightFar must be chosen so that the visible influence of lights is spread between these two values.

        Parameters:
        zLightNear - Distance from the camera where the lights are expected to shine. This parameter can affect performance and is useful because depending on the scene, lights that shine close to the camera may not be visible -- in this case, using a larger value can improve performance. e.g. when standing and looking straight, several meters of the ground isn't visible and if lights are expected to shine there, there is no point using a short zLightNear. (Default 5m).
        zLightFar - Distance from the camera after which lights are not expected to be visible. Similarly to zLightNear, setting this value properly can improve performance. (Default 100m).

      • setShadowType

        public void setShadowType​(View.ShadowType type)
        Sets the shadow mapping technique this View uses. The ShadowType affects all the shadows seen within the View.

        View.ShadowType.VSM imposes a restriction on marking renderables as only shadow receivers (but not casters). To ensure correct shadowing with VSM, all shadow participant renderables should be marked as both receivers and casters. Objects that are guaranteed to not cast shadows on themselves or other objects (such as flat ground planes) can be set to not cast shadows, which might improve shadow quality.

        Warning: This API is still experimental and subject to change.

      • setAmbientOcclusionOptions

        public void setAmbientOcclusionOptions​(@NonNull
                                       View.AmbientOcclusionOptions options)
        Sets ambient occlusion options.
        Parameters:
        options - Options for ambient occlusion.

      • getAmbientOcclusionOptions

        @NonNull
public View.AmbientOcclusionOptions getAmbientOcclusionOptions()
        Gets the ambient occlusion options.
        Returns:
        ambient occlusion options currently set.

      • setBloomOptions

        public void setBloomOptions​(@NonNull
                            View.BloomOptions options)
        Sets bloom options.
        Parameters:
        options - Options for bloom.
        See Also:
        getBloomOptions()

      • setFogOptions

        public void setFogOptions​(@NonNull
                          View.FogOptions options)
        Sets fog options.
        Parameters:
        options - Options for fog.
        See Also:
        getFogOptions()

      • pick

        public void pick​(int x,
                 int y,
                 @Nullable
                 java.lang.Object handler,
                 @Nullable
                 View.OnPickCallback callback)
        Creates a picking query. Multiple queries can be created (e.g.: multi-touch). Picking queries are all executed when Renderer.render(com.google.android.filament.View) is called on this View. The provided callback is guaranteed to be called at some point in the future. Typically it takes a couple frames to receive the result of a picking query.
        Parameters:
        x - Horizontal coordinate to query in the viewport with origin on the left.
        y - Vertical coordinate to query on the viewport with origin at the bottom.
        handler - An Executor. On Android this can also be a Handler.
        callback - User callback executed by handler when the picking query result is available.

      • getNativeObject

        public long getNativeObject()