Package com.google.android.filament

Class MaterialInstance

  • public class MaterialInstance
extends java.lang.Object

    • Constructor Detail

      • MaterialInstance

        public MaterialInstance​(Engine engine,
                        long nativeMaterialInstance)

    • Method Detail

      • getMaterial

        @NonNull
public Material getMaterial()
        Returns:
        the Material associated with this instance

      • getName

        @NonNull
public java.lang.String getName()
        Returns:
        the name associated with this instance

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         boolean x)
        Sets the value of a bool parameter.
        Parameters:
        name - the name of the material parameter
        x - the value of the material parameter

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         float x)
        Sets the value of a float parameter.
        Parameters:
        name - the name of the material parameter
        x - the value of the material parameter

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         int x)
        Sets the value of an int parameter.
        Parameters:
        name - the name of the material parameter
        x - the value of the material parameter

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         boolean x,
                         boolean y)
        Sets the value of a bool2 parameter.
        Parameters:
        name - the name of the material parameter
        x - the value of the first component
        y - the value of the second component

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         float x,
                         float y)
        Sets the value of a float2 parameter.
        Parameters:
        name - the name of the material parameter
        x - the value of the first component
        y - the value of the second component

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         int x,
                         int y)
        Sets the value of an int2 parameter.
        Parameters:
        name - the name of the material parameter
        x - the value of the first component
        y - the value of the second component

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         boolean x,
                         boolean y,
                         boolean z)
        Sets the value of a bool3 parameter.
        Parameters:
        name - the name of the material parameter
        x - the value of the first component
        y - the value of the second component
        z - the value of the third component

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         float x,
                         float y,
                         float z)
        Sets the value of a float3 parameter.
        Parameters:
        name - the name of the material parameter
        x - the value of the first component
        y - the value of the second component
        z - the value of the third component

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         int x,
                         int y,
                         int z)
        Sets the value of a int3 parameter.
        Parameters:
        name - the name of the material parameter
        x - the value of the first component
        y - the value of the second component
        z - the value of the third component

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         boolean x,
                         boolean y,
                         boolean z,
                         boolean w)
        Sets the value of a bool4 parameter.
        Parameters:
        name - the name of the material parameter
        x - the value of the first component
        y - the value of the second component
        z - the value of the third component
        w - the value of the fourth component

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         float x,
                         float y,
                         float z,
                         float w)
        Sets the value of a float4 parameter.
        Parameters:
        name - the name of the material parameter
        x - the value of the first component
        y - the value of the second component
        z - the value of the third component
        w - the value of the fourth component

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         int x,
                         int y,
                         int z,
                         int w)
        Sets the value of a int4 parameter.
        Parameters:
        name - the name of the material parameter
        x - the value of the first component
        y - the value of the second component
        z - the value of the third component
        w - the value of the fourth component

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         @NonNull
                         Texture texture,
                         @NonNull
                         TextureSampler sampler)
        Sets a texture and sampler parameter on this material's default instance.

        Note: Depth textures can't be sampled with a linear filter unless the comparison mode is set to COMPARE_TO_TEXTURE.

        Parameters:
        name - The name of the material texture parameter
        texture - The texture to set as parameter
        sampler - The sampler to be used with this texture

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         @NonNull
                         MaterialInstance.BooleanElement type,
                         @NonNull
                         boolean[] v,
                         @IntRange(from=0L)
                         int offset,
                         @IntRange(from=1L)
                         int count)
        Set a bool parameter array by name.
        Parameters:
        name - name of the parameter array as defined by this Material
        type - the number of components for each individual parameter
        v - array of values to set to the named parameter array
        offset - the number of elements in v to skip
        count - the number of elements in the parameter array to set

        For example, to set a parameter array of 4 bool4s: 

        
     boolean[] a = new boolean[4 * 4];
     instance.setParameter("param", MaterialInstance.BooleanElement.BOOL4, a, 0, 4);

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         @NonNull
                         MaterialInstance.IntElement type,
                         @NonNull
                         int[] v,
                         @IntRange(from=0L)
                         int offset,
                         @IntRange(from=1L)
                         int count)
        Set an int parameter array by name.
        Parameters:
        name - name of the parameter array as defined by this Material
        type - the number of components for each individual parameter
        v - array of values to set to the named parameter array
        offset - the number of elements in v to skip
        count - the number of elements in the parameter array to set

        For example, to set a parameter array of 4 int4s: 

        
     int[] a = new int[4 * 4];
     instance.setParameter("param", MaterialInstance.IntElement.INT4, a, 0, 4);

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         @NonNull
                         MaterialInstance.FloatElement type,
                         @NonNull
                         float[] v,
                         @IntRange(from=0L)
                         int offset,
                         @IntRange(from=1L)
                         int count)
        Set a float parameter array by name.
        Parameters:
        name - name of the parameter array as defined by this Material
        type - the number of components for each individual parameter
        v - array of values to set to the named parameter array
        offset - the number of elements in v to skip
        count - the number of elements in the parameter array to set

        For example, to set a parameter array of 4 float4s: 

        
     float[] a = new float[4 * 4];
     material.setDefaultParameter("param", MaterialInstance.FloatElement.FLOAT4, a, 0, 4);

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         @NonNull
                         Colors.RgbType type,
                         float r,
                         float g,
                         float b)
        Sets the color of the given parameter on this material's default instance.
        Parameters:
        name - the name of the material color parameter
        type - whether the color is specified in the linear or sRGB space
        r - red component
        g - green component
        b - blue component

      • setParameter

        public void setParameter​(@NonNull
                         java.lang.String name,
                         @NonNull
                         Colors.RgbaType type,
                         float r,
                         float g,
                         float b,
                         float a)
        Sets the color of the given parameter on this material's default instance.
        Parameters:
        name - the name of the material color parameter
        type - whether the color is specified in the linear or sRGB space
        r - red component
        g - green component
        b - blue component
        a - alpha component

      • setScissor

        public void setScissor​(@IntRange(from=0L)
                       int left,
                       @IntRange(from=0L)
                       int bottom,
                       @IntRange(from=0L)
                       int width,
                       @IntRange(from=0L)
                       int height)
        Set-up a custom scissor rectangle; by default it is disabled.

        The scissor rectangle gets clipped by the View's viewport, in other words, the scissor cannot affect fragments outside of the View's Viewport.

        Currently the scissor is not compatible with dynamic resolution and should always be disabled when dynamic resolution is used.

        Parameters:
        left - left coordinate of the scissor box relative to the viewport
        bottom - bottom coordinate of the scissor box relative to the viewport
        width - width of the scissor box
        height - height of the scissor box
        See Also:
        unsetScissor(), View.setViewport(com.google.android.filament.Viewport), View.setDynamicResolutionOptions(com.google.android.filament.View.DynamicResolutionOptions)

      • setPolygonOffset

        public void setPolygonOffset​(float scale,
                             float constant)
        Sets a polygon offset that will be applied to all renderables drawn with this material instance. The value of the offset is scale * dz + r * constant, where dz is the change in depth relative to the screen area of the triangle, and r is the smallest value that is guaranteed to produce a resolvable offset for a given implementation. This offset is added before the depth test. Warning: using a polygon offset other than zero has a significant negative performance impact, as most implementations have to disable early depth culling. DO NOT USE unless absolutely necessary.
        Parameters:
        scale - scale factor used to create a variable depth offset for each triangle
        constant - scale factor used to create a constant depth offset for each triangle

      • setMaskThreshold

        public void setMaskThreshold​(float threshold)
        Overrides the minimum alpha value a fragment must have to not be discarded when the blend mode is MASKED. Defaults to 0.4 if it has not been set in the parent Material. The specified value should be between 0 and 1 and will be clamped if necessary.
        See Also:
        Blending and transparency: maskThreshold

      • getMaskThreshold

        public float getMaskThreshold()
        Gets the minimum alpha value a fragment must have to not be discarded when the blend mode is MASKED

      • setSpecularAntiAliasingVariance

        public void setSpecularAntiAliasingVariance​(float variance)
        Sets the screen space variance of the filter kernel used when applying specular anti-aliasing. The default value is set to 0.15. The specified value should be between 0 and 1 and will be clamped if necessary.
        See Also:
        Anti-aliasing: specularAntiAliasingVariance

      • getSpecularAntiAliasingVariance

        public float getSpecularAntiAliasingVariance()
        Gets the screen space variance of the filter kernel used when applying specular anti-aliasing.

      • setSpecularAntiAliasingThreshold

        public void setSpecularAntiAliasingThreshold​(float threshold)
        Sets the clamping threshold used to suppress estimation errors when applying specular anti-aliasing. The default value is set to 0.2. The specified value should be between 0 and 1 and will be clamped if necessary.
        See Also:
        Anti-aliasing: specularAntiAliasingThreshold

      • getSpecularAntiAliasingThreshold

        public float getSpecularAntiAliasingThreshold()
        Gets the clamping threshold used to suppress estimation errors when applying specular anti-aliasing.

      • setDoubleSided

        public void setDoubleSided​(boolean doubleSided)
        Enables or disables double-sided lighting if the parent Material has double-sided capability, otherwise prints a warning. If double-sided lighting is enabled, backface culling is automatically disabled.
        See Also:
        Rasterization: doubleSided

      • isDoubleSided

        public boolean isDoubleSided()
        Returns whether double-sided lighting is enabled when the parent Material has double-sided capability.

      • getCullingMode

        @NonNull
public Material.CullingMode getCullingMode()
        Returns the face culling mode.

      • setColorWrite

        public void setColorWrite​(boolean enable)
        Overrides the default color-buffer write state that was set on the material.
        See Also:
        Rasterization: colorWrite

      • isColorWriteEnabled

        public boolean isColorWriteEnabled()
        Returns whether color write is enabled.

      • setDepthWrite

        public void setDepthWrite​(boolean enable)
        Overrides the default depth-buffer write state that was set on the material.
        See Also:
        Rasterization: depthWrite

      • isDepthWriteEnabled

        public boolean isDepthWriteEnabled()
        Returns whether depth write is enabled.

      • setStencilWrite

        public void setStencilWrite​(boolean enable)
        Enables or Disable stencil writes

      • isStencilWriteEnabled

        public boolean isStencilWriteEnabled()
        Returns whether stencil write is enabled.

      • setDepthCulling

        public void setDepthCulling​(boolean enable)
        Overrides the default depth testing state that was set on the material.
        See Also:
        Rasterization: depthCulling

      • isDepthCullingEnabled

        public boolean isDepthCullingEnabled()
        Returns whether depth culling is enabled.

      • setStencilCompareFunction

        public void setStencilCompareFunction​(TextureSampler.CompareFunction func,
                                      MaterialInstance.StencilFace face)
        Sets the stencil comparison function (default is TextureSampler.CompareFunction.ALWAYS).

        It's possible to set separate stencil comparison functions; one for front-facing polygons, and one for back-facing polygons. The face parameter determines the comparison function(s) updated by this call.

        Parameters:
        func - the stencil comparison function
        face - the faces to update the comparison function for

      • setStencilOpStencilFail

        public void setStencilOpStencilFail​(MaterialInstance.StencilOperation op,
                                    MaterialInstance.StencilFace face)
        Sets the stencil fail operation (default is MaterialInstance.StencilOperation.KEEP).

        The stencil fail operation is performed to update values in the stencil buffer when the stencil test fails.

        It's possible to set separate stencil fail operations; one for front-facing polygons, and one for back-facing polygons. The face parameter determines the stencil fail operation(s) updated by this call.

        Parameters:
        op - the stencil fail operation
        face - the faces to update the stencil fail operation for

      • setStencilOpDepthFail

        public void setStencilOpDepthFail​(MaterialInstance.StencilOperation op,
                                  MaterialInstance.StencilFace face)
        Sets the depth fail operation (default is MaterialInstance.StencilOperation.KEEP).

        The depth fail operation is performed to update values in the stencil buffer when the depth test fails.

        It's possible to set separate depth fail operations; one for front-facing polygons, and one for back-facing polygons. The face parameter determines the depth fail operation(s) updated by this call.

        Parameters:
        op - the depth fail operation
        face - the faces to update the depth fail operation for

      • setStencilOpDepthStencilPass

        public void setStencilOpDepthStencilPass​(MaterialInstance.StencilOperation op,
                                         MaterialInstance.StencilFace face)
        Sets the depth-stencil pass operation (default is MaterialInstance.StencilOperation.KEEP).

        The depth-stencil pass operation is performed to update values in the stencil buffer when both the stencil test and depth test pass.

        It's possible to set separate depth-stencil pass operations; one for front-facing polygons, and one for back-facing polygons. The face parameter determines the depth-stencil pass operation(s) updated by this call.

        Parameters:
        op - the depth-stencil pass operation
        face - the faces to update the depth-stencil operation for

      • setStencilReferenceValue

        public void setStencilReferenceValue​(@IntRange(from=0L,to=255L)
                                     int value,
                                     MaterialInstance.StencilFace face)
        Sets the stencil reference value (default is 0).

        The stencil reference value is the left-hand side for stencil comparison tests. It's also used as the replacement stencil value when MaterialInstance.StencilOperation is MaterialInstance.StencilOperation.REPLACE.

        It's possible to set separate stencil reference values; one for front-facing polygons, and one for back-facing polygons. The face parameter determines the reference value(s) updated by this call.

        Parameters:
        value - the stencil reference value (only the least significant 8 bits are used)
        face - the faces to update the reference value for

      • setStencilReferenceValue

        public void setStencilReferenceValue​(@IntRange(from=0L,to=255L)
                                     int value)
        Sets the stencil reference value for both front and back-facing polygons.
        See Also:
        setStencilReferenceValue(int, StencilFace)

      • setStencilReadMask

        public void setStencilReadMask​(@IntRange(from=0L,to=255L)
                               int readMask,
                               MaterialInstance.StencilFace face)
        Sets the stencil read mask (default is 0xFF).

        The stencil read mask masks the bits of the values participating in the stencil comparison test- both the value read from the stencil buffer and the reference value.

        It's possible to set separate stencil read masks; one for front-facing polygons, and one for back-facing polygons. The face parameter determines the stencil read mask(s) updated by this call.

        Parameters:
        readMask - the read mask (only the least significant 8 bits are used)
        face - the faces to update the read mask for

      • setStencilReadMask

        public void setStencilReadMask​(@IntRange(from=0L,to=255L)
                               int readMask)
        Sets the stencil read mask for both front and back-facing polygons.
        See Also:
        setStencilReadMask(int, StencilFace)

      • setStencilWriteMask

        public void setStencilWriteMask​(@IntRange(from=0L,to=255L)
                                int writeMask,
                                MaterialInstance.StencilFace face)
        Sets the stencil write mask (default is 0xFF).

        The stencil write mask masks the bits in the stencil buffer updated by stencil operations.

        It's possible to set separate stencil write masks; one for front-facing polygons, and one for back-facing polygons. The face parameter determines the stencil write mask(s) updated by this call.

        Parameters:
        writeMask - the write mask (only the least significant 8 bits are used)
        face - the faces to update the read mask for

      • setStencilWriteMask

        public void setStencilWriteMask​(int writeMask)
        Sets the stencil write mask for both front and back-facing polygons.
        See Also:
        setStencilWriteMask(int, StencilFace)

      • getNativeObject

        public long getNativeObject()