图形学【免费下载链接】glTFglTF – Runtime 3D Asset Delivery项目地址https://gitcode.com/gh_mirrors/gl/glTF点击查看免费下载glTF 2.0 规范The glTF 2.0 Specification是 Khronos 3D Formats Working Group 维护的官方技术文档定义了面向运行时 3D 资源交付的文件格式标准。本文以仓库 specification/2.0/README.md 为骨架完整讲解该规范文档在仓库中的组织形态AsciiDoc 源码 JSON Schema 自动生成章节、如何基于 Docker 与 Makefile 在本地构建 HTML/PDF 版规范、如何通过 GitHub Actions 自动化构建以及贡献者应当如何在正确的文件中提交规范修订。读完本文你将掌握 glTF 2.0 规范仓库的完整工作流能够独立搭建本地构建环境并定位规范修改的正确落点。一、glTF 2.0 规范的双重形态发布版与仓库源码规范文档在仓库中以两种形态存在二者互为表里发布版浏览器可读的 HTML 版与适合打印阅读的 PDF 版由 Khronos 官方在 glTF Registry 中发布是面向普通读者与实现者的正式文档。源码版本仓库 specification/2.0/ 目录下的 AsciiDoc.adoc与 JSON Schema.json源文件。Khronos 公开这些源码的目的正是为了鼓励社区反馈与二次编辑README 明确指出源码以 CC-BY-4.0 协议发布任何修订都需要从源码入手、重新构建后才能产出新的 HTML/PDF。在仓库根目录下规范相关源码的布局如下路径内容specification/2.0/Specification.adocglTF 2.0 规范全文主体约 3800 行 AsciiDoc含前言、概念、GLB 文件格式、BRDF 实现等章节specification/2.0/ObjectModel.adocglTF 2.0 资源对象模型规范Asset Object Model Specification独立成册specification/2.0/schema/35 个 JSON Schema 文件用于自动生成规范的属性参考与JSON Schema 参考两章specification/2.0/Makefile一键构建脚本产出Specification.html与Specification.pdfspecification/2.0/khronos.css 与 specification/2.0/docinfo.htmlHTML 构建使用的样式表与文档头信息specification/figures/glTF_RGB_June16.svgglTF 官方标识图被 README 与各.adoc文档头部引用二、规范源码的内部结构正文与自动生成章节的分工这是理解整个贡献工作流的关键规范不是一份单纯的手写文档而是手写正文 机器生成章节的混合体。README 明确划分了三类内容的编辑落点Section 5Properties Reference属性参考由 JSON Schema 文件 通过wetzel工具自动生成。措辞修正必须直接修改对应 JSON 文件目前不接受对 JSON 结构本身的改动。Appendix AJSON Schema Reference同样由 JSON Schema 文件自动生成编辑方式与上一条一致。其余所有章节全部包含在 Specification.adoc 中常规编辑直接修改该文件即可。2.1 Specification.adoc 的章节全景从 Specification.adoc 的标题结构可以看出规范的完整脉络以下节选主要章节Introduction前言涵盖文档约定、规范性术语MUST / SHOULD / MAY 等按 BCP 14 解释、技术术语表、规范引用以及 glTF 的定位——API 中立的运行时资源交付格式。glTF BasicsglTF 基础设计动机紧凑体积、运行时中立、完整 3D 场景表达、可扩展性、版本化规则、文件扩展名与 Media Type 约定.gltfmodel/gltfjson、.glbmodel/gltf-binary、.bin、.png、.jpeg等、JSON 编码约定UTF-8 无 BOM、ASCII 不转义、非 ASCII 可转义、属性名唯一性、整数值编码约束。Concepts核心概念Asset、索引与命名、坐标系与单位、Scenes 与 Nodes 层级、变换以及二进制数据存储的三层结构——Buffers字节数组→Buffer Views视图切片→Accessors类型化数据元素描述含稀疏 Accessor。Geometry几何Meshes、顶点属性、拓扑与连接、Morph Targets变形目标、Skins蒙皮、实例化。Texture Data 与 Materials纹理、图像、采样器过滤/环绕/非二次幂限制、Metallic-Roughness 材质、Alpha 覆盖、双面渲染、默认材质。Cameras 与 Animations视图矩阵、投影矩阵无限远/有限远透视与正交以及关键帧动画与插值。GLB File Format Specification二进制 glTF 容器的头Header、Chunk 结构、结构化 JSON 内容与二进制缓冲。附录Properties Reference自动生成、JSON Schema Reference自动生成、BRDF Implementation金属/电介质/微表面模型与示例实现、Animation Sampler Interpolation Modes阶跃/线性/球面线性/三次样条插值。2.2 JSON Schema 文件清单schema 目录 中每个文件对应规范中的一个对象类型例如glTF.schema.json——资产根对象也是 wetzel 生成的入口asset.schema.json、scene.schema.json、node.schema.jsonbuffer.schema.json、bufferView.schema.json、accessor.schema.json含 accessor.sparse.schema.json 等稀疏子结构mesh.schema.json、mesh.primitive.schema.jsonmaterial.schema.json含 material.pbrMetallicRoughness.schema.json、material.normalTextureInfo.schema.json 等texture.schema.json、sampler.schema.json、image.schema.jsoncamera.schema.json含 orthographic / perspective 子模式、animation.schema.json、skin.schema.json基础类型glTFProperty.schema.json、glTFChildOfRootProperty.schema.json、glTFid.schema.json、extras.schema.json、extension.schema.json值得注意的是Makefile 中的IGNORESCHEMA变量明确排除了gltfchildofrootproperty.schema.json、gltfid.schema.json、gltfproperty.schema.json这三个基础类型文件它们不进入自动生成的属性参考章节。三、扩展机制核心规范之外的贡献渠道核心 glTF 规范没有覆盖的功能通过扩展Extensions方式贡献README 指引读者前往 extensions/README.md即扩展注册表查看细节。仓库中扩展按版本与来源组织extensions/2.0/Khronos/Khronos 官方认可的扩展如KHR_materials_pbrSpecularGlossiness、KHR_materials_transmission、KHR_materials_volume、KHR_draco_mesh_compression、KHR_texture_basisu、KHR_mesh_quantization、KHR_lights_punctual、KHR_animation_pointer等extensions/2.0/Vendor/厂商扩展如EXT_mesh_gpu_instancing、EXT_texture_webp、MSFT_lod、AGI_articulations、MPEG_*系列等。每个扩展目录下通常包含自己的README.md说明文档与schema/模式文件结构上与核心规范一致——扩展自身的属性参考同样由 JSON Schema 驱动。广泛被采纳的扩展有可能会在未来的规范版本中被并入核心README 与规范正文均提及这一演进路径。四、贡献工作流在哪里提出问题、修改哪个文件4.1 提交前准备README 给出的贡献流程非常明确先查阅仓库的 issues 列表确认同一主题是否已有讨论若没有新建一个 issue 开启讨论。讨论达成一致后如确认需要对核心规范做修正以 Pull RequestPR形式提交到本仓库。提交前根据要修改的章节选择正确的文件见下表。要修改的内容应编辑的文件备注Section 5Properties Referencespecification/2.0/schema/ 中对应的 JSON Schema 文件只能改措辞不接受 JSON 结构变更Appendix AJSON Schema Reference同上由同一批 Schema 文件自动生成与上一条共用生成流程其余所有章节specification/2.0/Specification.adoc规范正文的常规编辑从源码看这两章自动生成的机制由 Makefile 落实构建时用npx wetzel0.2.2读取schema/glTF.schema.json及其引用的全部模式文件输出PropertiesReference.adoc与JsonSchemaReference.adoc两个生成文件再作为依赖参与Specification.adoc的组装。因此对 Schema 文件的任何措辞修改只有在重新构建后才会反映到规范正文中——这也是本地构建环节如此重要的原因。4.2 版本与格式约束glTF 2.0 的文件结构已定型贡献聚焦于错误修正与澄清说明。规范正文对版本化有严格约定见 Specification.adoc 的 Versioning 小节小版本更新必须向后与向前兼容可新增功能但不得改变既有行为、不得移除已存在功能大版本更新才允许不兼容变更。任何 glTF 资产必须显式声明asset.version。五、本地构建规范Docker make 完整实操构建规范最直接的方式是在预配置的 Docker 容器中完成README 给出了标准四步流程# 1. 拉取预置了 asciidoctor 工具链的官方镜像 docker pull khronosgroup/docker-images:asciidoctor-spec # 2. 克隆仓库或其 fork并切换到包含修改的分支 git clone 本仓库地址 git checkout 你的分支 # 3. 进入规范源码目录 cd specification/2.0 # 4. 执行构建 make构建成功后目录下会生成两个文件Specification.html—— 规范的 HTML 版Specification.pdf—— 规范的 PDF 版两者都包含当前 git 分支上的所有改动可用于本地审阅或提交 PR 前的自检。5.1 Makefile 构建原理详解从 specification/2.0/Makefile 源码可以梳理出完整构建链路这是 README 未展开、但对维护者极有价值的部分目标与产物SPEC Specification TARGETS $(SPEC).html $(SPEC).pdf all: $(TARGETS)默认make即同时产出 HTML 与 PDF。clean目标会清理生成的PropertiesReference.adoc、JsonSchemaReference.adoc与两个最终产物。Schema 生成步骤wetzelWETZEL npx wetzel0.2.2 SCHEMALINK schema EMBEDSCHEMA JsonSchemaReference.adoc PROPREF PropertiesReference.adoc IGNORESCHEMA [gltfchildofrootproperty.schema.json, gltfid.schema.json, gltfproperty.schema.json] $(GENERATED): $(wildcard schema/*.json) $(WETZEL) -n -acqo -ma -p $(SCHEMALINK) -e $(EMBEDSCHEMA) \ -i $(IGNORESCHEMA) -c icon:check[] -k **MUST**\ schema/glTF.schema.json $(PROPREF)几个关键点wetzel 版本被锁定在0.2.2。Makefile 注释明确要求保持版本锁定以便文档变更历史能准确反映 wetzel 版本对输出造成的影响升级需谨慎且手动进行。生成以schema/glTF.schema.json为根入口遍历其引用的全部子模式输出属性参考PropertiesReference.adoc并嵌入 JSON Schema 参考JsonSchemaReference.adoc。-k **MUST**让规范中的 MUST 关键词以醒目标记呈现-c icon:check[]注入校验图标。HTML 构建asciidoctorASCIIDOCTOR asciidoctor $(ADOCOPTS) ADOCOPTS -d book ADOCHTMLOPTS -a stylesheetkhronos.css -a sectanchors ... $(SPEC).html: $(SPECDEPS) $(ASCIIDOCTOR) -b html5 $(ADOCHTMLOPTS) $(ATTRIBOPTS) $(SPEC).adoc -o $HTML 构建使用-b html5后端套用 khronos.css 样式并启用章节锚点sectanchors便于链接到具体小节。PDF 构建asciidoctor-pdf 数学公式渲染$(SPEC).pdf: $(SPECDEPS) $(ASCIIDOCTOR) -b pdf $(ATTRIBOPTS) -a allow-uri-read -r asciidoctor-pdf \ -r asciidoctor-mathematical $(SPEC).adoc -o $ rm -f $(STEMIMAGES)PDF 构建额外加载asciidoctor-pdf与asciidoctor-mathematical两个 Ruby 库后者负责渲染规范中的数学公式BRDF 实现章节。allow-uri-read是为了让内嵌的远程数学图片能被处理构建完成后会清理stem-*.png这类中间公式图像。版本与修订信息注入PATCHVERSION 1 SPECREVISION 2.0.$(PATCHVERSION) SPECDATE $(shell echo date -u %Y-%m-%d %TZ) SPECREMARK from git branch: ... commit: ... ATTRIBOPTS -a revnumber$(SPECREVISION) -a revdate$(SPECDATE) -a revremark$(SPECREMARK)构建会自动把修订号当前为 2.0.1、ISO 8601 格式的 UTC 日期以及 git 分支与提交哈希写入规范首页的版本栏保证每一份构建产物的出处可追溯。六、通过 GitHub Actions 自动化构建除本地构建外仓库还配置了 CI 构建流程在本仓库或你的 fork上打开一个 PR会触发 GitHub Action 运行。在仓库的 Actions 标签页查看最新任务——注意这很可能是你自己的 fork 仓库而非 Khronos 主仓库最新任务的名称应显示你的提交或 PR 名。任务成功执行后在 Summary 页面底部会有一个名为spec-outputs的构建产物artifact是一个 ZIP 压缩包内含基于你本次改动重新生成的 HTML 与 PDF 版本可直接下载审阅。这条链路与本地构建共用同一套 Makefile 逻辑因此本地验证通过的改动在 CI 中应得到一致的产物。七、发布流程从合并到官方 Registry当新版本构建完成并被接受后维护者会将其发布到 Khronos 的 glTF Registry 供全球分发。也就是说贡献者的 PR 合并只是第一步正式发布由维护团队统一执行普通贡献者需要关注的是如何把改动构建出来、验证正确而何时发布由官方决定。对使用者而言正式文档始终以 Registry 上的 HTML/PDF 发布版为准仓库源码则提供了可追溯、可重构建的完整依据。结语glTF 2.0 规范仓库是一套文档即代码的典型工程实践正文用 AsciiDoc 手写、属性与 Schema 章节由 JSON Schema 自动生成、构建产物由 Makefile 与 Docker 镜像统一驱动。无论你是想阅读规范的实现者、准备提交修正的贡献者还是希望本地产出最新 HTML/PDF 的文档工程师都可以沿 specification/2.0/README.md 这条主线结合 Specification.adoc、schema/ 与 Makefile 快速定位自己需要的文件与流程。记住一条黄金法则改 Schema 就去 schema 目录改正文就去 Specification.adoc改完务必重新构建验证——这就是 glTF 2.0 规范仓库最核心的协作规则。赞分享图形学【免费下载链接】glTFglTF – Runtime 3D Asset Delivery项目地址https://gitcode.com/gh_mirrors/gl/glTF点击查看免费下载相关推荐JupyterHub 文档贡献指南Sphinx MyST 本地构建、nox 工作流与书写规范JupyterHub 文档贡献指南Sphinx MyST 本地构建、nox 工作流与书写规范 本文基于 JupyterHub 仓库中的贡献者文档页 do后端微服务霞鹜文楷2万字符免费商用开源楷体字体完整安装指南霞鹜文楷2万字符免费商用开源楷体字体完整安装指南 霞鹜文楷是一款 免费商用的开源楷体字体 它由日本 FONTWORKS 出品的日文字体 Klee OneUI组件python-guide 文档贡献指南Sphinx 构建、本地预览与写作风格规范全解析python guide 文档贡献指南Sphinx 构建、本地预览与写作风格规范全解析 导读 本文基于 CONTRIBUTING.md https://lin文档教程上一篇深度优化Langchain-Chatchat知识库问答的MultiQueryRetriever性能提升指南下一篇Turnip Prophet高级技巧如何通过历史数据优化你的大头菜交易策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考