JavaScript 模型处理

在 NTE 中一种较为基础的处理模型的方法是，模型文件首先可以加载为 RawModel，接下来可以随意对他进行一些处理，然后要进行一个上传过程得到 ModelCluster 或 DynamicModelHolder，最后在渲染时将 ModelCluster 或 DynamicModelHolder 交给 NTE 显示。

如果不使用模型文件而是程序地添加顶点数据，可以使用 RawMeshBuilder 构建 RawMesh 以及 RawModel ，接下来可以对他进行一些处理，然后上传得到 ModelCluster 或 DynamicModelHolder。

NTE 使用这些类加载和处理模型：

• Face：面，存储了顶点的索引
• Vertex：顶点，存储了位置、法线、颜色、UV坐标、亮度
• VertAttrType ：顶点属性类型，存储了顶点属性
• VertAttrSrc ：顶点属性类型，存储了顶点内容
• VertAttrMapping：顶点属性映射，存储了一些 VertAttrType 和 VertAttrSrc 同时还有缓冲区信息
• VertAttrState：顶点属性状态，存储了坐标、法线、颜色、UV坐标、叠加UV坐标、光照UV坐标、法线方向、矩阵模型
• MaterialProp: 材质属性，存储了所要使用的贴图路径、着色器种类、材质颜色（在 VertAttrState 内）等。
• VertArray：相当于上传之后的 RawMesh，是绑定了对应的 VBO 和 EBO 的 VAO 对象的引用。
• VertArrays：相当于上传之后的 RawModel，包含多个 VertArray。
• RawMeshBuilder：原始网格构造器，用于构造 RawMesh 。其包含一个 RawMesh ,一个面顶点数量和一个 Vertex 存储临时顶点信息。
• RawMesh：原始网格类，包含了一个 MaterialProp ，一个 Face 数组、以一个 Face 数组。
• RawModel：原始网格模型，含有来源和一个 meshList(HashMap<MaterialProp, RawMesh>)，存储了多个 由 MaterialProp 和 RawMesh 组成的键值对。
• ModelCluster：实际上上传 RawModel 所得到的，以及渲染相关函数所接受的类型。分别存储了透明和不透明部分的 RawModel 和 VertArray，以便于特定处理。
• DynamicModelHolder：动态模型容器，以解决因调用不在主线程而无法在函数内通过 ModelManager 上传 RawModel 为 ModelCluster 的问题，包含一个 ModelCluster。
• ModelManager：模型管理器，用于加载模型或上传模型如加载 OBJ 为 RawModel 或上传 RawModel 为 ModelCluster。
  下面将详细介绍这些类及其用法，末尾有一些示例代码，也可以参考其他示例代码。

NTE 提供了一个方便的模型管理器方便加载模型等，打包了一些常用的加载模型的函数。

源码为 ModelManager.java 文件。

• static ModelManager.loadRawModel(Resources.manager(), path: ResourceLocation, null): RawModel 将一个模型整体地加载为一个 RawModel。
• static ModelManager.loadPartedRawModel(Resources.manager(), path: ResourceLocation, null): Map<String, RawModel> 将一个模型的每个分组分别加载成各个 RawModel，返回一个 Java Map。
• static ModelManager.uploadVertArrays(rawModel: RawModel): ModelCluster 把一个 RawModel 上传到显存，返回上传好的 ModelCluster。注意由于线程问题，不能在 create/render/dispose 中调用它。如需动态更新模型需使用 DynamicModelHolder。
  如果需要在函数内（如create、render、dispose或在其中调用的函数）上传 RawModel 为 ModelCluster 需要使用 DynamicModelHolder。

NTE 有 RawMeshBuilder 类，用于在程序中创建 RawMesh 。该类在DisplayHelper类中有用到，用于在程序中创建网格对象。 RawMeshBuilder 支持链式调用，可以将一个操作跟到另一个操作后面，在下面的示例文件中可以看到具体的用法。

源码为 RawMeshBuilder.java 文件。

下面是一些函数可以使用

• new RawMeshBuilder(faceSize: int, renderType: String, texture: ResourceLocation) 创建一个 RawMeshBuilder 对象。
• RawMeshBuilder.reset(): RawMeshBuilder 重置此 RawMeshBuilder 对象，并返回此 RawMeshBuilder 对象。
• RawMeshBuilder.vertex(position: Vector3f): RawMeshBuilder
• RawMeshBuilder.vertex(x: double, y: double, z: double): RawMeshBuilder 添加一个顶点到此 RawMeshBuilder 对象，并返回此 RawMeshBuilder 对象。
• RawMeshBuilder.normal(x: double, y: double, z: double): RawMeshBuilder 设定顶点的法向量，并返回此 RawMeshBuilder 对象。
• RawMeshBuilder.uv(x: float, y: float): RawMeshBuilder 设定顶点的 UV 坐标，并返回此 RawMeshBuilder 对象。
• RawMeshBuilder.endVertex(): RawMeshBuilder 结束一个顶点的定义，并返回此 RawMeshBuilder 对象。
• RawMeshBuilder.color(red : int, green : int, blue : int, alpha : int): RawMeshBuilder 设置 RGBA 颜色值到此 RawMeshBuilder 对象的材质中，并返回此 RawMeshBuilder 对象。
• RawMeshBuilder.lightMapUV(x: float, y: float): RawMeshBuilder 设置 lightMapUV 值到此 RawMeshBuilder 对象的材质中，并返回此 RawMeshBuilder 对象。
• RawMeshBuilder.setNewDefaultVertex(texture: ResourceLocation): RawMeshBuilder 设置一个新的默认顶点到此 RawMeshBuilder 对象，并返回此 RawMeshBuilder 对象。(提一嘴在 Build #619 前此方法不会返回 RawMeshBuilder )
  

  RawModel

  NTE 使用 RawModel 来初加载模型，它可以通过 ModelManager 快捷的加载 OBJ 文件、CSV 文件、 NMB 文件等（NMB 文件是 NTE 的字节模型格式，全称为“NTE Model Binary”，不要想歪）或通过其提供的方法 添加 RawMesh 对象为 RawModel 。

每一个 RawModel 类内含有 sourceLocation(ResourceLocation) 和 meshList(HashMap<MaterialProp, RawMesh>) 两个成员变量。可以直接通过RawModel.sourceLocation 或 RawModel.meshList 来访问或更改。

sourceLocation 变量用于记录来源，如果两个的 RawModel 的来源一样，那么这两个 RawModel 实际上都是同一个 RawModel ，使用 RawModel.copy() 或RawModel.copyForMaterialChanges() 新的RawModel 都会记录此来源为原 RawModel 的来源 ，如果你不希望新对的 RawModel 的操作会影响原 RawModel ，可以在.copy()或.copyForMaterialChanges() 后设置 newRawModel.sourceLocation = null 来断开与原 RawModel 的关联，之后对两个模型的操作不会影响另一个 RawModel 。

源码为 RawModel.java 文件。

RawModel 类提供了以下方法：

模型上传之后就不能再修改顶点数据和渲染阶段了，不过也还可以替换贴图。因此一个模型需要多次替换贴图时，可以先上传再替换，避免每次都替换后再上传产生的不必要的上传操作。

其中含有 uploadedOpaqueParts（VertArrays）、opaqueParts（RawModel）、uploadedTranslucentParts（VertArrays）、translucentParts（RawModel）几个成员变量。他们都带有final修饰符，不能被二次修改为其他值，但可以被读取并使用其的函数。RawModel 可以参考上面的 RawModel 部分，VertArrays 可以获得MatreialProp ，可以开发更加基本的渲染功能，详见下面MaterialProp。

下面是一些函数可以使用：

下面还有一些成员变量可以获取：

VertArrays 可以从 ModelCluster 获得，其包含有以下方法：

• VertArrays.meshList: ArrayList<VertArray> 获取 VertArrays 中的各个不同材质所对应的 VertArray。
• VertArrays.replaceTexture(String oldTexture, ResourceLocation newTexture) 所有文件名为 oldFileName 字符串的贴图替换为 resourceLocation 所指定的贴图。
• VertArrays.replaceAllTexture(ResourceLocation newTexture) 把所有贴图替换为 resourceLocation 所指定的贴图。
  

  VertArray

  VertArray 可以从 VertArrays 获得，由于有些函数较为深入底层，这里只介绍一些常用的函数：

• VertArray.materialProp: MaterialProp 获取 VertArray 的 MaterialProp 。
• VertArray.mapping: VertAttrMapping 获取 VertArray 的 VertAttrMapping 。
  

  MaterialProp

  MaterialProp 可以从 VertArray 获得，其包含有以下方法：

• MaterialProp.shaderName: String 获取材质名。
• MaterialProp.texture: ResourceLocation 获取材质使用的贴图路径。
• MaterialProp.translucent: boolean 获取材质是否透明。
• MaterialProp.writeDepthBuf: boolean 获取材质是否写入深度缓冲区。
• MaterialProp.billboard: boolean： 获取材质是否始终面向摄像机。
• MaterialProp.attrState: VertAttrState 获取 VertAttrState 。
  

  VertAttrState

  VertAttrState 可以从 MaterialProp 获得。材质颜色在此处设定，其中设定的颜色会与贴图上的颜色相乘。

• VertAttrState.color: int 获取颜色。(格式为RRGGBBAA)
• VertAttrState.setColor(rgba: int): void 或
• VertAttrState.setColor(red: int, green: int, blue: int, alpha: int): void 设置颜色。每项为 0~255 的整数。
  

  DynamicModelHolder

  为了解决 ModelManager 无法在函数内上传 RawModel 为 ModelCluster 这一问题 NTE 添加了 DynamicModelHolder 类。 此功能在 Build #618 后可用，之前的版本不支持此类或存在问题，请更新至最新版本。

源码为 DynamicModelHolder.java 文件。

首先使用 new DynamicModelHolder() 关键字创建一个新的 DynamicModelHolder 实例

• DynamicModelHolder.uploadLater(rawModel: RawModel): void 将 rawModel 添加到上传队列中，稍后（在接下来某一帧时主线程上）会将它上传为 ModelCluster，成为新的 uploadedModel。
• DynamicModelHolder.getUploadedModel(): ModelCluster | null 获取已上传的 ModellCluster。如果未进行过上传操作，或 uploadLater 刚刚调用操作还没实际进行，会返回 null。
• DynamicModelHolder.close(): void 关闭 DynamicModelHolder 实例，释放资源。同时 uploadedModel 也将不再可用。
  

  示例代码

  示例1：加载一个 OBJ 模型为 RawModel，翻转 RawModel 的 UV y坐标，使用 ModelManager 上传 RawModel 得到一个 ModelCluster。

  <code javascript>

加载一个rawModel let rawModel = ModelManager.loadRawModel(Resources.manager(), Resources.id(“mtr:models/cube.obj”), null); 翻转 V 坐标

rawModel.applyUVMirror(false, true);

上传得到一个ModelCluster let modelCluster = ModelManager.uploadVertArrays(rawModel); </code> ==== 示例2：使用RawMeshBuilder创建RawModel，并生成法线，最终使用 DynamicModelHolder 上传 RawModel 得到一个 ModelCluster。 ==== <code javascript> function create(ctx, state, block) { 创建一个RawModel

  let rawModel = new RawModel();

  //创建一个RawMeshBuilder
  let rawModelBuilder = new RawMeshBuilder(4, "interior", Resources.id("minecraft:textures/misc/white.png"));

  //设置顶点
  rawModelBuilder.vertex(0.5, 0.5, 0).normal(0, 0, 0).uv(0, 0).endVertex()
  .vertex(0.5, -0.5, 0).normal(0, 0, 0).uv(0, 1).endVertex()
  .vertex(-0.5, -0.5, 0).normal(0, 0, 0).uv(1, 1).endVertex()
  .vertex(-0.5, 0.5, 0).normal(0, 0, 0).uv(1, 0).endVertex();

  //上传为RawModel
  rawModel.append(rawModelBuilder.getMesh());

  //生成法线
  rawModel.generateNormals();

  //声明一个DynamicModelHolder并存入state
  state.dynamicModelHolder = new DynamicModelHolder();

  //添加到上传队列
  state.dynamicModelHolder.uploadLater(rawModel);

}

function render(ctx, state, block) {

  //得到ModelCluster
  if(state.dynamicModelHolder.getUploadedModel()!= null){
  state.model = dynamicModelHolder.getUploadedModel();
  }

}

</code>

function alterAllRGBA (modelCluster, red ,green , blue, alpha) {
    let vertarray = modelCluster.uploadedTranslucentParts.meshList;
    let vert = vertarray[0];
    for(let i = 0; i < vertarray.length; i++) {
        vert = vertarray[i];
        vert.materialProp.attrState.setColor(red , green , blue , alpha);
    }
    vertarray = modelCluster.uploadedOpaqueParts.meshList;
    vert = vertarray[0];
    for(let i = 0; i < vertarray.length; i++) {
        vert = vertarray[i];
        vert.materialProp.attrState.setColor(red , green , blue , alpha);
    }
}
 
function getAllColor (modelCluster) {
    let result = [];
    let vertarray = modelCluster.uploadedTranslucentParts.meshList;
    let vert = vertarray[0];
    for(let i = 0; i < vertarray.length; i++) {
        vert = vertarray[i];
        result.push(vert.materialProp.attrState.color);
    }
    vertarray = modelCluster.uploadedOpaqueParts.meshList;
    vert = vertarray[0];
    for(let i = 0; i < vertarray.length; i++) {
        vert = vertarray[i];
        result.push(vert.materialProp.attrState.color);
    }
    return result;
}
 
function alterAllAlpha(modelCluster, newAlpha) {
    let vertarrays = modelCluster.uploadedTranslucentParts.meshList;
    let vertarray = vertarrays[0];
    let color = vertarray.materialProp.attrState.color;
    let red=0,green=0,blue=0;
    for(let i = 0; i < vertarrays.length; i++) {
        vertarray = vertarrays[i];
        color = vertarray.materialProp.attrState.color;
        red = (color >> 16) & 0xFF;
        green = (color >> 8) & 0xFF;
        blue = color & 0xFF;
        vertarray.materialProp.attrState.setColor(red , green , blue , newAlpha);
    }
    vertarrays = modelCluster.uploadedOpaqueParts.meshList;
    vertarray = vertarrays[0];
    color = vertarray.materialProp.attrState.color;
    red=0,green=0,blue=0;
    for(let i = 0; i < vertarrays.length; i++) {
        vertarray = vertarrays[i];
        color = vertarray.materialProp.attrState.color;
        red = (color >> 16) & 0xFF;
        green = (color >> 8) & 0xFF;
        blue = color & 0xFF;
        vertarray.materialProp.attrState.setColor(red , green , blue , newAlpha);
    }
}