# Using MaterialOverride Schema

**URL:** <https://forum.aousd.org/t/using-materialoverride-schema/2269>\
**Category:** Hydra\
**Tags:** rendering, cpp, beginner\
**Created:** [February 26, 2025, 7:22am UTC](https://forum.aousd.org/t/using-materialoverride-schema/2269 "2025-02-26T07:22:29Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![Nicola](https://avatars.discourse-cdn.com/v4/letter/n/41988e/32.png) [@Nicola](https://forum.aousd.org/u/Nicola)\
**Post date:** [February 26, 2025, 7:22am UTC](https://forum.aousd.org/t/using-materialoverride-schema/2269/1 "2025-02-26T07:22:29Z")

</div>

I’m experimenting the Hydra 2.0 and I’m trying to understand how I can use the MaterialOverride schema to apply tweaks to the material parameters using a UI. What is the correct way to specify material overrides in a usda file? Let’s say I have this material in the file:

```auto
   def Material "RedMaterial" {
        token outputs:surface.connect = <SurfaceShader.outputs:surface>  
        color3f inputs:diffuseColor = (1, 0, 0)
        def Shader "SurfaceShader" {
            uniform token info:id = "UsdPreviewSurface"
            color3f inputs:diffuseColor.connect = </World/RedMaterial.inputs:diffuseColor>
            token outputs:surface
        }
    }

```

How would I specify a material override for the diffuseColor parameter?

---

<div class="post-metadata">

**Author:** ![dlanier](https://sea2.discourse-cdn.com/flex016/user_avatar/forum.aousd.org/dlanier/32/166_2.png) [@dlanier](https://forum.aousd.org/u/dlanier)\
**Post date:** [February 26, 2025, 10:58am UTC](https://forum.aousd.org/t/using-materialoverride-schema/2269/2 "2025-02-26T10:58:39Z")

</div>

Hi Nicola,  
I am not an expert, but I think it may be related to the “over” keyword like in these usda files :

> **[OpenUSD/pxr/usdImaging/usdImagingGL/testenv/testUsdImagingGLDisplacement at dev...](https://github.com/PixarAnimationStudios/OpenUSD/tree/dev/pxr/usdImaging/usdImagingGL/testenv/testUsdImagingGLDisplacement)**
>
> Universal Scene Description. Contribute to PixarAnimationStudios/OpenUSD development by creating an account on GitHub.

Some people also use a “variant” with the “over” keyword to override a value.  
Regards,  
David

---

<div class="post-metadata">

**Author:** ![dlanier](https://sea2.discourse-cdn.com/flex016/user_avatar/forum.aousd.org/dlanier/32/166_2.png) [@dlanier](https://forum.aousd.org/u/dlanier)\
**Post date:** [February 26, 2025, 11:02am UTC](https://forum.aousd.org/t/using-materialoverride-schema/2269/3 "2025-02-26T11:02:26Z")

</div>

You may also look at this file :

> <https://github.com/PixarAnimationStudios/OpenUSD/blob/dev/pxr/usd/bin/usdcompress/testenv/testCube/CubeCompressedTriangles.usda>

which uses variants to override the displaycolor of a Cube.  
Regards,  
David

---

<div class="post-metadata">

**Author:** ![Nicola](https://avatars.discourse-cdn.com/v4/letter/n/41988e/32.png) [@Nicola](https://forum.aousd.org/u/Nicola)\
**Post date:** [February 26, 2025, 11:29am UTC](https://forum.aousd.org/t/using-materialoverride-schema/2269/4 "2025-02-26T11:29:54Z")

</div>

Hi David, thanks for the answer. I tried the following:

file simple-cube.usda:

```auto
#usda 1.0

def Xform "World" {
    def Cube "Cube" (
        prepend apiSchemas = ["MaterialBindingAPI"]
    ) {
        float3 xformOp:translate = (2, 0, 0)
        uniform token[] xformOpOrder = ["xformOp:translate"]
        rel material:binding = </World/RedMaterial>
    }

    def Material "RedMaterial" {
        token outputs:suface.connect = <SurfaceShader.outputs:surface>  
        color3f inputs:diffuseColor = (1, 0, 0)
        def Shader "SurfaceShader" {
            uniform token info:id = "UsdPreviewSurface"
            color3f inputs:diffuseColor.connect = </World/RedMaterial.inputs:diffuseColor>
            token outputs:surface
        }
    }
}

```

file simple-cube-over.usda:

```auto
#usda 1.0
(
    subLayers = [@./simple-cube.usda@]
)
over "World" {
    over "RedMaterial" {
        color3f inputs:diffuseColor = (0, 1, 0)
    }
}

```

If I load the simple-cube-over.usda, the input RedMaterial.diffuseColor gets correctly resolved as (0,1,0).

To clarify, I’m writing a SceneIndexObserver for our Hydra 2.0 render delegate.

In the following C++ code, I’m trying the extract the MaterialOverrideSchema from the material primitive’s data source. But the primitive doesn’t seem to contain the data corresponding to the MaterialOverrideSchema. I’m trying to figure out why.

```auto
Observer::PrimAdded(HdSceneIndexObserver::AddedPrimEntry entry, Observer* observer) {
    if(entry.primType == HdPrimTypeTokens->material) {
        return CreateMaterialPrim(entry.primPath, observer);
    }
}

Prim* CreateMaterialPrim(SdfPath primPath, Observer* observer) {
    HdContainerDataSourceHandle primSource = observer->GetSceneIndex()>GetPrim(path).dataSource;

    HdMaterialOverrideSchema materialOverrideSchema = HdMaterialOverrideSchema::GetFromParent(primSource);
    if(materialOverrideSchema.IsDefined()) {
        std::cout << "OK" << std::endl;
    } else {
        std::cout << "Something's wrong" << std::endl;
    }
}

```

---

<div class="post-metadata">

**Author:** ![dlanier](https://sea2.discourse-cdn.com/flex016/user_avatar/forum.aousd.org/dlanier/32/166_2.png) [@dlanier](https://forum.aousd.org/u/dlanier)\
**Post date:** [February 27, 2025, 8:46am UTC](https://forum.aousd.org/t/using-materialoverride-schema/2269/5 "2025-02-27T08:46:55Z")

</div>

It’s not really clear to me what a HdMaterialOverrideSchema does…  
But my understanding is that it is not used to override material’s values but the public UI :  
// The MaterialOverride schema allows overrides to be made to the material’s  
// public UI. Overrides can be applied to both material or geometry scene  
// index prim locations.  
To me the “over” keyword seems more like a Hydra : HdContainerDataSourceEditor or HdOverlayContainerDataSource but that is just a guess. I am not 100% sure… And I am not aware of a way to use a schema to detect an override made with one of those classes.  
You can find usage of these classes on :

> <https://github.com/PixarAnimationStudios/OpenUSD/blob/62847554c9abce257729f9f6c7071165ccd680a4/extras/imaging/docs/examples_hydra_getting_started.cpp#L140>

And line 152.

Regards,  
David

---

<div class="post-metadata">

**Author:** ![Nicola](https://avatars.discourse-cdn.com/v4/letter/n/41988e/32.png) [@Nicola](https://forum.aousd.org/u/Nicola)\
**Post date:** [February 27, 2025, 10:06am UTC](https://forum.aousd.org/t/using-materialoverride-schema/2269/6 "2025-02-27T10:06:54Z")

</div>

Thanks for the link. I’m interested in the HdMaterialOverrideSchema because it allows to specify the public UI parameter values in a way that is loosely coupled to the shader parameters in the node graph.

Let’s say that I want to tweak a parameter value from a DCC application. If I author the parameter directly in the shader network, or even as an override, that would most likely trigger a shader recompilation, because the parameter values are inside the shader graph contained in the HdMaterialSchema locators.  
But if I author the parameters in the public UI managed by the HdMaterialOverrideSchema, then no shader recompilation would be triggered, and I could just update the parameter values in the already compiled shaders.

According to the documentation in the files

/pxr/imaging/hd/materialSchema.h  
/pxr/imaging/hd/materialOverriedSchema.h

You could author a public UI attribute as (please correct me here, I’m still new to OpenUSD)

```auto
def Material "RedMaterial" {
        custom color3f materialOverride:interfaceValues:diffuseColor:value = (1, 0, 0)
        # rest omitted
}

```

The problem is that if I try to author the public UI attributes in like the above, they are not available in the primSource of the scene index:

```auto
Prim* CreateMaterialPrim(SdfPath primPath, Observer* observer) {
    HdContainerDataSourceHandle primSource = observer->GetSceneIndex()>GetPrim(path).dataSource;

    HdMaterialOverrideSchema materialOverrideSchema = HdMaterialOverrideSchema::GetFromParent(primSource);
    if(materialOverrideSchema.IsDefined()) {
        std::cout << "OK" << std::endl;
    } else {
        std::cout << "Something's wrong" << std::endl;
    }
}

```

It looks like the problem stems from the fact that the UsdImagingDataSourceMaterialPrim (file dataSourceMaterial.cpp) in usdImaging scene index is skipping the data for the materialOverrideSchema, making it unavailable to downstream scene indices.

The question is, if the materialOverrideSchema is missing from the implementation, what is the common way to specify material parameters without triggering shader recompilation?

PS. I added an issue on Github: [UsdImagingDataSourceMaterialPrim is missing the the MaterialOverrideSchema · Issue #3550 · PixarAnimationStudios/OpenUSD · GitHub](https://github.com/PixarAnimationStudios/OpenUSD/issues/3550)

---

<div class="post-metadata">

**Author:** ![dlanier](https://sea2.discourse-cdn.com/flex016/user_avatar/forum.aousd.org/dlanier/32/166_2.png) [@dlanier](https://forum.aousd.org/u/dlanier)\
**Post date:** [February 27, 2025, 10:49am UTC](https://forum.aousd.org/t/using-materialoverride-schema/2269/7 "2025-02-27T10:49:57Z")

</div>

> [@Nicola](#):
>
> Let’s say that I want to tweak a parameter value from a DCC application. If I author the parameter directly in the shader network, or even as an override, that would most likely trigger a shader recompilation, because the parameter values are inside the shader graph contained in the HdMaterialSchema locators.

My experience with shader recompilation in HdStorm with MaterialX shaders is that updating a color in Maya doesn’t trigger a recompilation of the MaterialX GLSL shader in Storm.  
Regards,  
David

---

<div class="post-metadata">

**Author:** ![Nicola](https://avatars.discourse-cdn.com/v4/letter/n/41988e/32.png) [@Nicola](https://forum.aousd.org/u/Nicola)\
**Post date:** [February 27, 2025, 11:34am UTC](https://forum.aousd.org/t/using-materialoverride-schema/2269/8 "2025-02-27T11:34:16Z")

</div>

Thanks for pointing that out. Probably looking at the hdStorm implementation will clarify how to handle parameter changes without triggering shader recompilation. Thanks!