Composition: SubLayers management

[rdeioris]

Hi, i am working with composition arcs and i am tracking the various differences between openusd and tinyusdz.

This issue is about the sublayers side. Note that tusdcat is currently broken in the last step (where it converts the final layer to a Stage) so the output i am taking into account is the last composition step printed on stdout by tusdcat and compare it to usdcat.

Given the following 4 layers:

levels.usda:

#usda 1.0

(
    subLayers = [
        @level000.usda@
    ]
    "Hello World"
    doc = "Test"
)

def "Root"
{
    def "Hello"
    {
        string value = "Hello World"
    }

    def "Child"
    {
        string here = "now"
    }
}

level000.usda:

#usda 1.0
(
    "Hello World"
    doc = "Ops"
    upAxis = "Z"

    subLayers = [
        @one.usda@,
        @two.usda@
    ]
)

def "One"
{
    def "Two"
    {
        string before = "before"
        def Test "Three"
        {
            def Test "Four"
            {
                string value = "xyz"
            }
        }
        string after = "after"
    }
}

over "Root"
{
    over "Broken"
    {
        string value = "broken"
    }

    def "Child"
    {
        def "SubChild"
        {
            float value = 17
        }

        string another = "one"
    }

    string additional = "HEY!"
}

one.usda:

#usda 1.0

def "Rooter"
{
    def Scope "FirstLayer"
    {

    }

    def Scope "FirstLayerCheck"
    {

    }
}

two.usda:

#usda 1.0

def Scope "SecondLayer"
{

}

def Scope "SecondLayerCheck"
{
    
}

def "Root"
{
    def "AdditionalScope"
    {
        
    }
}

OpenUSD usdcat returns:

#usda 1.0
(
    "Hello World"
    doc = """Test

Generated from Composed Stage of root layer /mnt/e/Documents/Unreal Projects/GltfUsdPlayground/Assets/levels.usda
"""
)

def Scope "SecondLayer"
{
}

def Scope "SecondLayerCheck"
{
}

def "Root"
{
    string additional = "HEY!"

    def "AdditionalScope"
    {
    }

    over "Broken"
    {
        string value = "broken"
    }

    def "Child"
    {
        string another = "one"
        string here = "now"

        def "SubChild"
        {
            float value = 17
        }
    }

    def "Hello"
    {
        string value = "Hello World"
    }
}

def "Rooter"
{
    def Scope "FirstLayer"
    {
    }

    def Scope "FirstLayerCheck"
    {
    }
}

def "One"
{
    def "Two"
    {
        string after = "after"
        string before = "before"

        def Test "Three"
        {
            def Test "Four"
            {
                string value = "xyz"
            }
        }
    }
}

While tusdcat:

#usda 1.0
(
    doc = "Test"
    "Hello World"
)

def "Rooter"
{
    def Scope "FirstLayer"
    {
    }

    def Scope "FirstLayerCheck"
    {
    }
}

def Scope "SecondLayerCheck"
{
}

def Scope "SecondLayer"
{
}

def "Root"
{
    def "Hello"
    {
        string value = "Hello World"
    }

    def "Child"
    {
        string here = "now"
    }
}

def "One"
{
    def "Two"
    {
        string after = "after"
        string before = "before"
        def Test "Three"
        {
            def Test "Four"
            {
                string value = "xyz"
            }
        }
    }
}

The "/Root/Child" PrimSpec is probably the most interesting here.

The sublayers logic (by Pixar specifications) is the following:

The highest layer in the chain has priority, so every new PrimSpec with matching name (independently by the specifier) does NOT override the parent one, but just append non-existent properties and children. Non matching PrimSpec are blindly added (along their children). The only Layer metas applied are the one from the Root Layer (this part is correct in tinyusdz).

The current main issue is the lack of recursiveness in the process. I have prepared a patch for it, Pull Request will follow.

[syoyo]

Thanks! Composition arcs in TinyUSDZ are not complete, so your contribution is very helpful.

Let me give some time to investigate the logic of Sublayers in USD spec and its implementation in TinyUSDZ.

[syoyo]

The sublayers logic (by Pixar specifications) is the following:

Where can I find the info of the logic of Sublayers in OpenUSD?
(Is there a info somewhere in https://openusd.org/release/glossary.html ? )

[rdeioris]

I generally prefer the docs from remedy-entertainment: https://remedy-entertainment.github.io/USDBook/terminology/local_sublayer.html

But even the houdini docs are useful: https://www.sidefx.com/docs/houdini/nodes/lop/sublayer.html

In pixar docs i think the LayerStack paragraph has the best description

[syoyo]

@rdeioris After some investigation on subLayers' behavior, I have prepared pseudo code of subLayer composition: https://github.com/lighttransport/tinyusdz/wiki/Composition-arcs#sublayerslayerstack

I think this pseudo code exactly matches your description:

The highest layer in the chain has priority, so every new PrimSpec with matching name (independently by the specifier) does NOT override the parent one, but just append non-existent properties and children. Non matching PrimSpec are blindly added (along their children). The only Layer metas applied are the one from the Root Layer (this part is correct in tinyusdz).

[rdeioris]

@syoyo great, i will cleanuo the pull request #208 by adding the typeName fix and the debug messages to be consistent with the other functions

[syoyo]

👍