glTF parse support custom extsnions and parser

[zhuxudong]

举个例子，如果 Unity 导出了以下 glTF 插件，希望能根据材质拓展 Unity_Material_Plugin 生成新的自定义材质，然后根据灯光插件 Unity_Light_Plugin 表示想在某个节点上面加一个灯光：

{
  ...
  materials:[{
    extensions:{
      Unity_Material_Plugin:{
        color: [1,1,1],
        ...
      }
    }
  }],
  nodes:[{
    extensions:{
      Unity_Light_Plugin:{
        type:"point",
        ...
      }
    }
  }]

}

1. 自定义创建解析

按照上面的例子，我们注册一个材质插件，第二个参数 GLTFExtensionMode.CreateAndParse 表示这个插件是用来创建实例和解析的：

@registerGLTFExtension("Unity_Material_Plugin", GLTFExtensionMode.CreateAndParse)
class UnityMaterialPluginParser extends GLTFExtensionParser {
  createAndParse(context: GLTFParserContext, schema: {color,...other}}): Promise<Material> {
    const { engine } = context.glTFResource;
    const yourCustomMaterial = new Material(engine,customShader);
    ...
    return yourCustomMaterial;
  }
}

2. 增量解析

按照上面的例子，我们注册一个灯光插件，第二个参数 GLTFExtensionMode.AdditiveParse 表示这个插件是在原来实例的基础上进行一些增量解析的,比如在这个实体上添加一个光源：

@registerGLTFExtension("Unity_Light_Plugin", GLTFExtensionMode.AdditiveParse)
class UnityLightPlugin extends GLTFExtensionParser {
  additiveParse(context: GLTFParserContext, entity: Entity, extensionSchema: {type,...other}): void {
    entity.addComponent(type==="point"?PointLight:DirectLight);
    ...
  }
}

3. 自定义管线

如果上面的方法还不能满足您的需求，还可以完全自定义解析管线，用来重写解析的逻辑：

class CustomMaterialParser extends GLTFParser{
   parse(context: GLTFParserContext): AssetPromise<Material[]> {
      const { glTF, glTFResource, materialsPromiseInfo } = context;
      glTFResource.materials = materials;
      for (let i = 0; i < glTF.materials.length; i++) {
        const materialInfo = glTF.materials[i];
        ...
      }
      materialsPromiseInfo.resolve(materials);
      return materialsPromiseInfo.promise;
   }
}

engine.resourceManager
    .load<GLTFResource>({
      type: AssetType.Prefab,
      url: "https://gw.alipayobjects.com/os/bmw-prod/150e44f6-7810-4c45-8029-3575d36aff30.gltf"
      params: {
        pipeline: new GLTFPipeline(
          ...
          CustomMaterialParser,
          ...
        )
      }
    })
    .then((gltf) => {
      const entity = rootEntity.createChild();
      entity.addChild(gltf.defaultSceneRoot);
    })

[codecov-commenter]

Codecov Report

Base: 41.83% // Head: 41.93% // Increases project coverage by +0.10% 🎉

Coverage data is based on head (e277f36) compared to base (f004089).
Patch coverage: 37.33% of modified lines in pull request are covered.

❗ Current head e277f36 differs from pull request most recent head ef8e1dd. Consider uploading reports for the commit ef8e1dd to get more accurate results

📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

Additional details and impacted files

@@             Coverage Diff             @@
##           dev/1.0    #1008      +/-   ##
===========================================
+ Coverage    41.83%   41.93%   +0.10%     
===========================================
  Files          351      351              
  Lines        17778    17795      +17     
  Branches      2605     2610       +5     
===========================================
+ Hits          7438     7463      +25     
+ Misses        9650     9638      -12     
- Partials       690      694       +4     

Impacted Files	Coverage Δ
packages/core/src/lighting/DirectLight.ts	19.23% <0.00%> (+1.37%)	⬆️
packages/core/src/lighting/SpotLight.ts	10.20% <0.00%> (+0.40%)	⬆️
...ckages/core/src/shadow/CascadedShadowCasterPass.ts	29.67% <0.00%> (-0.17%)	⬇️
packages/loader/src/GLTFLoader.ts	11.76% <0.00%> (-0.74%)	⬇️
packages/loader/src/gltf/GLTFSchema.ts	100.00% <ø> (ø)
packages/loader/src/gltf/GLTFUtil.ts	2.64% <ø> (ø)
...kages/loader/src/gltf/parser/GLTFMaterialParser.ts	3.57% <3.57%> (ø)
packages/loader/src/gltf/parser/GLTFParser.ts	22.72% <22.72%> (ø)
packages/loader/src/gltf/parser/GLTFValidator.ts	10.52% <28.57%> (ø)
packages/loader/src/gltf/GLTFPipeline.ts	33.33% <33.33%> (ø)
... and 27 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[GuoLei1990]

Rename GLTFSchema to GLTFExtensions.d.ts

[GuoLei1990]

add type

[GuoLei1990]

/**
 * Base class of glTF extension parser.
 */
export abstract class GLTFExtensionParser {
  /** The extension mode. */
  abstract readonly mode: GLTFExtensionMode;

  /**
   * Create a resource instance.
   * @remarks This method overrides the default resource creation
   * @param context - The parser context
   * @param extensionSchema - The extension schema
   * @param ownerSchema - The extension owner schema
   * @returns The resource or promise
   */
  createAndParse(
    context: GLTFParserContext,
    extensionSchema: GLTFExtensionSchema,
    ownerSchema: GLTFExtensionOwnerSchema
  ): EngineObject | Promise<EngineObject> {
    throw "Not implemented.";
  }

  /**
   * Additive parse to the resource.
   * @param context - The parser context
   * @param resource - The resource
   * @param extensionSchema - The extension schema
   * @param ownerSchema - The extension owner schema
   * @returns The void or promise
   */
  additiveParse(
    context: GLTFParserContext,
    resource: EngineObject,
    extensionSchema: GLTFExtensionSchema,
    ownerSchema: GLTFExtensionOwnerSchema
  ): void | Promise<void> {
    throw "Not implemented.";
  }
}

/**
 * glTF Extension mode.
 */
enum GLTFExtensionMode {
  /** Cerate instance and parse mode, `createAndParse()` will be called when resource instance, usually only one in the extension owner schema. */
  CreateAndParse,
  /** Additive parse mode, `additiveParse()` will be called when resource parse, can be multiple in extension owner schema. */
  AdditiveParse
}

export type GLTFExtensionOwnerSchema = IMeshPrimitive | IMaterial | ITexture | INode;

export type GLTFExtensionSchema =
  | IKHRLightsPunctual_Light
  | IKHRDracoMeshCompression
  | IKHRMaterialsClearcoat
  | IKHRMaterialsIor
  | IKHRMaterialsUnlit
  | IKHRMaterialsPbrSpecularGlossiness
  | IKHRMaterialsSheen
  | IKHRMaterialsSpecular
  | IKHRMaterialsTransmission
  | IKHRMaterialsTranslucency
  | IKHRMaterialVariants_Mapping
  | IKHRMaterialVariants_Variants
  | IKHRTextureBasisU
  | IKHRTextureTransform
  | IKHRXmp
  | IKHRXmp_Node
  | object;