@carbonenginejs/runtime-resource 0.12.2 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (541) hide show
  1. package/LICENSE +21 -21
  2. package/NOTICE +32 -32
  3. package/README.md +129 -108
  4. package/dist/CjsMotherLode.js +1271 -1271
  5. package/dist/CjsResMan.js +3858 -3494
  6. package/dist/CjsResMan.js.map +1 -1
  7. package/dist/CjsResManFetchProvider.js +94 -94
  8. package/dist/CjsResManWorkQueue.js +301 -301
  9. package/dist/_virtual/_rollupPluginBabelHelpers.js +150 -150
  10. package/dist/format/CjsBlueReader.js +358 -358
  11. package/dist/format/CjsByteReader.js +310 -310
  12. package/dist/format/CjsByteWriter.js +242 -242
  13. package/dist/format/CjsFormat.js +223 -223
  14. package/dist/format/CjsFormatError.js +41 -41
  15. package/dist/format/CjsReader.js +22 -22
  16. package/dist/format/CjsResourceProbe.js +279 -279
  17. package/dist/format/CjsStringTable.js +268 -268
  18. package/dist/format/carbonEffect/CjsCarbonEffectReader.js +408 -361
  19. package/dist/format/carbonEffect/CjsCarbonEffectReader.js.map +1 -1
  20. package/dist/format/carbonEffect/CjsCarbonEffectWriter.js +373 -373
  21. package/dist/format/carbonEffect/buildCarbonEffectContainer.js +182 -0
  22. package/dist/format/carbonEffect/buildCarbonEffectContainer.js.map +1 -0
  23. package/dist/format/carbonEffect/carbonEffectBackendBlock.js +321 -427
  24. package/dist/format/carbonEffect/carbonEffectBackendBlock.js.map +1 -1
  25. package/dist/format/carbonEffect/carbonEffectRecords.js +1147 -955
  26. package/dist/format/carbonEffect/carbonEffectRecords.js.map +1 -1
  27. package/dist/format/carbonEffect/carbonEffectResourceTransform.js +197 -0
  28. package/dist/format/carbonEffect/carbonEffectResourceTransform.js.map +1 -0
  29. package/dist/format/compareUtf8.js +36 -36
  30. package/dist/format/effect/effectBodyInventory.js +146 -0
  31. package/dist/format/effect/effectBodyInventory.js.map +1 -0
  32. package/dist/format/effect/effectPermutationGraph.js +257 -257
  33. package/dist/format/effect/effectPermutationGraph.js.map +1 -1
  34. package/dist/format/effect/sha256.js +114 -114
  35. package/dist/format/index.js +11 -11
  36. package/dist/format/payloadContract.js +193 -193
  37. package/dist/formats/black/CjsBlackFormat.js +310 -292
  38. package/dist/formats/black/CjsBlackFormat.js.map +1 -1
  39. package/dist/formats/black/core/CjsBlackBinaryReader.js +260 -260
  40. package/dist/formats/black/core/CjsBlackPropertyReaders.js +448 -448
  41. package/dist/formats/black/core/CjsBlackReader.js +764 -764
  42. package/dist/formats/black/core/CjsBlackSchemaRegistry.js +540 -540
  43. package/dist/formats/black/core/black-schema-v1-2026-07-23.json.js +4 -4
  44. package/dist/formats/black/core/blackConstants.js +7 -7
  45. package/dist/formats/black/core/blackDefinitions.js +10 -10
  46. package/dist/formats/black/core/blackEnums.js +6 -6
  47. package/dist/formats/black/core/blackSchema.js +3 -3
  48. package/dist/formats/black/core/blackVersion.js +22 -22
  49. package/dist/formats/black/core/helpers.js +199 -199
  50. package/dist/formats/black/core/schema.js +4 -4
  51. package/dist/formats/black/index.js +2 -2
  52. package/dist/formats/bnk/CjsBnkFormat.js +175 -156
  53. package/dist/formats/bnk/CjsBnkFormat.js.map +1 -1
  54. package/dist/formats/bnk/core/busNodes.js +252 -0
  55. package/dist/formats/bnk/core/busNodes.js.map +1 -0
  56. package/dist/formats/bnk/core/effectNodes.js +147 -0
  57. package/dist/formats/bnk/core/effectNodes.js.map +1 -0
  58. package/dist/formats/bnk/core/eventAction.js +416 -305
  59. package/dist/formats/bnk/core/eventAction.js.map +1 -1
  60. package/dist/formats/bnk/core/globalSettings.js +215 -0
  61. package/dist/formats/bnk/core/globalSettings.js.map +1 -0
  62. package/dist/formats/bnk/core/graph.js +137 -137
  63. package/dist/formats/bnk/core/helpers.js +512 -480
  64. package/dist/formats/bnk/core/helpers.js.map +1 -1
  65. package/dist/formats/bnk/core/musicNodes.js +533 -509
  66. package/dist/formats/bnk/core/musicNodes.js.map +1 -1
  67. package/dist/formats/bnk/core/nodeBase.js +553 -532
  68. package/dist/formats/bnk/core/nodeBase.js.map +1 -1
  69. package/dist/formats/bnk/core/sfxNodes.js +632 -632
  70. package/dist/formats/bnk/core/soundbanksInfo.js +209 -209
  71. package/dist/formats/bnk/index.js +2 -2
  72. package/dist/formats/cmf/CjsCmfFormat.js +497 -497
  73. package/dist/formats/cmf/core/binary.js +194 -194
  74. package/dist/formats/cmf/core/buffers.js +237 -237
  75. package/dist/formats/cmf/core/constants.js +47 -47
  76. package/dist/formats/cmf/core/gr2Anim.js +453 -453
  77. package/dist/formats/cmf/core/helpers.js +318 -318
  78. package/dist/formats/cmf/core/pack.js +276 -276
  79. package/dist/formats/cmf/core/schema.js +374 -374
  80. package/dist/formats/cmf/core/shared.js +277 -277
  81. package/dist/formats/cmf/core/writer.js +571 -571
  82. package/dist/formats/cmf/index.js +2 -2
  83. package/dist/formats/dds/CjsDdsFormat.js +200 -200
  84. package/dist/formats/dds/core/bc6h.js +298 -298
  85. package/dist/formats/dds/core/bc7.js +272 -272
  86. package/dist/formats/dds/core/helpers.js +862 -862
  87. package/dist/formats/dds/index.js +2 -2
  88. package/dist/formats/dxbc/CjsDxbcFormat.js +142 -142
  89. package/dist/formats/dxbc/core/DxbcReader.js +266 -266
  90. package/dist/formats/dxbc/core/container.js +169 -169
  91. package/dist/formats/dxbc/core/decoder.js +789 -789
  92. package/dist/formats/dxbc/core/errors.js +19 -19
  93. package/dist/formats/dxbc/core/helpers.js +220 -220
  94. package/dist/formats/dxbc/core/opcodes.js +45 -45
  95. package/dist/formats/dxbc/core/program.js +91 -91
  96. package/dist/formats/dxbc/core/signature.js +172 -172
  97. package/dist/formats/dxbc/index.js +2 -2
  98. package/dist/formats/fbx/CjsFbxFormat.js +266 -266
  99. package/dist/formats/fbx/core/helpers.js +3932 -3932
  100. package/dist/formats/fbx/index.js +2 -2
  101. package/dist/formats/flac/CjsFlacFormat.js +142 -142
  102. package/dist/formats/flac/core/helpers.js +315 -315
  103. package/dist/formats/flac/index.js +2 -2
  104. package/dist/formats/gif/CjsGifFormat.js +141 -141
  105. package/dist/formats/gif/core/helpers.js +380 -380
  106. package/dist/formats/gif/index.js +2 -2
  107. package/dist/formats/gltf/CjsGltfFormat.js +290 -290
  108. package/dist/formats/gltf/core/helpers.js +307 -307
  109. package/dist/formats/gltf/core/json.js +79 -79
  110. package/dist/formats/gltf/core/parser.js +679 -679
  111. package/dist/formats/gltf/core/targets.js +173 -173
  112. package/dist/formats/gltf/index.js +2 -2
  113. package/dist/formats/gr2/CjsGr2Format.js +289 -289
  114. package/dist/formats/gr2/core/bitknit2.js +282 -282
  115. package/dist/formats/gr2/core/curves.js +1047 -1047
  116. package/dist/formats/gr2/core/gsf.js +72 -72
  117. package/dist/formats/gr2/core/helpers.js +352 -352
  118. package/dist/formats/gr2/core/json.js +622 -622
  119. package/dist/formats/gr2/core/oodle1.js +388 -388
  120. package/dist/formats/gr2/core/tangents.js +48 -48
  121. package/dist/formats/gr2/core/targets.js +361 -361
  122. package/dist/formats/gr2/index.js +2 -2
  123. package/dist/formats/hlsl/CjsHlslFormat.js +254 -254
  124. package/dist/formats/hlsl/core/HlslBinaryUtils.js +15 -15
  125. package/dist/formats/hlsl/core/HlslEffectReadError.js +19 -19
  126. package/dist/formats/hlsl/core/HlslEffectStateManager.js +130 -130
  127. package/dist/formats/hlsl/core/HlslRenderStateSetup.js +37 -37
  128. package/dist/formats/hlsl/core/HlslResourceSetDescription.js +94 -94
  129. package/dist/formats/hlsl/core/HlslShaderBytecode.js +44 -44
  130. package/dist/formats/hlsl/core/analysis.js +51 -51
  131. package/dist/formats/hlsl/core/carbonDescriptionToRuntime.js +850 -781
  132. package/dist/formats/hlsl/core/carbonDescriptionToRuntime.js.map +1 -1
  133. package/dist/formats/hlsl/core/detailMapFamily.js +128 -0
  134. package/dist/formats/hlsl/core/detailMapFamily.js.map +1 -0
  135. package/dist/formats/hlsl/core/helpers.js +270 -270
  136. package/dist/formats/hlsl/core/json.js +284 -284
  137. package/dist/formats/hlsl/core/localLightFamily.js +133 -0
  138. package/dist/formats/hlsl/core/localLightFamily.js.map +1 -0
  139. package/dist/formats/hlsl/core/metadata.js +327 -327
  140. package/dist/formats/hlsl/core/render-states.js +280 -280
  141. package/dist/formats/hlsl/core/tr2/HlslRenderContextEnum.js +43 -43
  142. package/dist/formats/hlsl/core/tr2/resources/HlslEffectRes.js +320 -314
  143. package/dist/formats/hlsl/core/tr2/resources/HlslEffectRes.js.map +1 -1
  144. package/dist/formats/hlsl/core/tr2/resources/HlslShaderPermutation.js +33 -33
  145. package/dist/formats/hlsl/core/tr2/shader/HlslEffectBindingManifest.js +416 -416
  146. package/dist/formats/hlsl/core/tr2/shader/HlslEffectConstant.js +40 -40
  147. package/dist/formats/hlsl/core/tr2/shader/HlslEffectDescription.js +62 -742
  148. package/dist/formats/hlsl/core/tr2/shader/HlslEffectDescription.js.map +1 -1
  149. package/dist/formats/hlsl/core/tr2/shader/HlslEffectLibrary.js +52 -52
  150. package/dist/formats/hlsl/core/tr2/shader/HlslEffectParameterAnnotation.js +38 -38
  151. package/dist/formats/hlsl/core/tr2/shader/HlslEffectResource.js +50 -50
  152. package/dist/formats/hlsl/core/tr2/shader/HlslEffectStageInput.js +86 -86
  153. package/dist/formats/hlsl/core/tr2/shader/HlslEffectTechnique.js +31 -31
  154. package/dist/formats/hlsl/core/tr2/shader/HlslPass.js +42 -42
  155. package/dist/formats/hlsl/core/tr2/shader/HlslSamplerDescription.js +55 -55
  156. package/dist/formats/hlsl/core/tr2/shader/HlslSamplerSetup.js +29 -29
  157. package/dist/formats/hlsl/core/tr2/shader/HlslShader.js +220 -220
  158. package/dist/formats/hlsl/core/tr2/shader/HlslShaderOption.js +30 -30
  159. package/dist/formats/hlsl/index.js +3 -3
  160. package/dist/formats/index.js +33 -31
  161. package/dist/formats/index.js.map +1 -1
  162. package/dist/formats/jpeg/CjsJpegFormat.js +212 -212
  163. package/dist/formats/jpeg/core/helpers.js +402 -402
  164. package/dist/formats/jpeg/core/jpeg.js +480 -480
  165. package/dist/formats/jpeg/index.js +2 -2
  166. package/dist/formats/mp3/CjsMp3Format.js +197 -197
  167. package/dist/formats/mp3/core/helpers.js +375 -375
  168. package/dist/formats/mp3/index.js +2 -2
  169. package/dist/formats/mp4/CjsMp4Format.js +197 -197
  170. package/dist/formats/mp4/core/helpers.js +484 -484
  171. package/dist/formats/mp4/index.js +2 -2
  172. package/dist/formats/obj/CjsObjFormat.js +253 -253
  173. package/dist/formats/obj/core/helpers.js +573 -573
  174. package/dist/formats/obj/core/json.js +64 -64
  175. package/dist/formats/obj/core/parser.js +321 -321
  176. package/dist/formats/obj/index.js +2 -2
  177. package/dist/formats/ogg/CjsOggFormat.js +143 -143
  178. package/dist/formats/ogg/core/helpers.js +410 -410
  179. package/dist/formats/ogg/core/imdct.js +178 -178
  180. package/dist/formats/ogg/core/vorbis.js +1017 -1017
  181. package/dist/formats/ogg/index.js +2 -2
  182. package/dist/formats/pickle/CjsPickleFormat.js +214 -0
  183. package/dist/formats/pickle/CjsPickleFormat.js.map +1 -0
  184. package/dist/formats/pickle/core/CjsPickleProtocol0Reader.js +551 -0
  185. package/dist/formats/pickle/core/CjsPickleProtocol0Reader.js.map +1 -0
  186. package/dist/formats/pickle/index.js +2 -0
  187. package/dist/formats/pickle/index.js.map +1 -0
  188. package/dist/formats/png/CjsPngFormat.js +201 -201
  189. package/dist/formats/png/core/helpers.js +635 -635
  190. package/dist/formats/png/index.js +2 -2
  191. package/dist/formats/red/CjsRedFormat.js +263 -263
  192. package/dist/formats/red/core/CjsRedReader.js +246 -246
  193. package/dist/formats/red/core/blackDefinitions.js +3 -3
  194. package/dist/formats/red/core/helpers.js +158 -158
  195. package/dist/formats/red/core/redGraph.js +71 -68
  196. package/dist/formats/red/core/redGraph.js.map +1 -1
  197. package/dist/formats/red/core/schema.js +4 -4
  198. package/dist/formats/red/index.js +2 -2
  199. package/dist/formats/stl/CjsStlFormat.js +365 -365
  200. package/dist/formats/stl/core/helpers.js +261 -261
  201. package/dist/formats/stl/core/json.js +51 -51
  202. package/dist/formats/stl/core/stl.js +642 -642
  203. package/dist/formats/stl/core/targets.js +173 -173
  204. package/dist/formats/stl/index.js +2 -2
  205. package/dist/formats/tga/CjsTgaFormat.js +197 -197
  206. package/dist/formats/tga/core/helpers.js +493 -493
  207. package/dist/formats/tga/index.js +2 -2
  208. package/dist/formats/wav/CjsWavFormat.js +198 -198
  209. package/dist/formats/wav/core/helpers.js +365 -365
  210. package/dist/formats/wav/index.js +2 -2
  211. package/dist/formats/webgl/CjsWebglFormat.js +199 -221
  212. package/dist/formats/webgl/CjsWebglFormat.js.map +1 -1
  213. package/dist/formats/webgl/core/buildGlslEffectContainer.js +70 -0
  214. package/dist/formats/webgl/core/buildGlslEffectContainer.js.map +1 -0
  215. package/dist/formats/webgl/core/effectPackage.js +900 -792
  216. package/dist/formats/webgl/core/effectPackage.js.map +1 -1
  217. package/dist/formats/webgl/core/errors.js +27 -27
  218. package/dist/formats/webgl/core/errors.js.map +1 -1
  219. package/dist/formats/webgl/core/glsl/DxbcGlslEmitter.js +2820 -2678
  220. package/dist/formats/webgl/core/glsl/DxbcGlslEmitter.js.map +1 -1
  221. package/dist/formats/webgl/core/glsl/DxbcGlslHelpers.js +89 -89
  222. package/dist/formats/webgl/core/glsl/DxbcGlslOperandFormatter.js +486 -428
  223. package/dist/formats/webgl/core/glsl/DxbcGlslOperandFormatter.js.map +1 -1
  224. package/dist/formats/webgl/core/glsl/packedLightFixups.js +98 -0
  225. package/dist/formats/webgl/core/glsl/packedLightFixups.js.map +1 -0
  226. package/dist/formats/webgl/core/glslBackendBlock.js +552 -0
  227. package/dist/formats/webgl/core/glslBackendBlock.js.map +1 -0
  228. package/dist/formats/webgl/core/glslBackendBodySet.js +243 -0
  229. package/dist/formats/webgl/core/glslBackendBodySet.js.map +1 -0
  230. package/dist/formats/webgl/core/{cewgCompleteness.js → glslEffectCompleteness.js} +85 -81
  231. package/dist/formats/webgl/core/glslEffectCompleteness.js.map +1 -0
  232. package/dist/formats/webgl/core/helpers.js +167 -306
  233. package/dist/formats/webgl/core/helpers.js.map +1 -1
  234. package/dist/formats/webgl/core/inspectGlslEffectContainer.js +122 -0
  235. package/dist/formats/webgl/core/inspectGlslEffectContainer.js.map +1 -0
  236. package/dist/formats/webgl/core/readGlslEffectContainer.js +303 -0
  237. package/dist/formats/webgl/core/readGlslEffectContainer.js.map +1 -0
  238. package/dist/formats/webgl/index.js +2 -2
  239. package/dist/formats/webgpu/CjsWebgpuFormat.js +357 -357
  240. package/dist/formats/webgpu/CjsWebgpuFormat.js.map +1 -1
  241. package/dist/formats/webgpu/core/buildCarbonEffectContainer.js +89 -197
  242. package/dist/formats/webgpu/core/buildCarbonEffectContainer.js.map +1 -1
  243. package/dist/formats/webgpu/core/{cewgpu/CewgpuContainer.js → carbonWebgpu/CarbonWebgpuContainer.js} +354 -368
  244. package/dist/formats/webgpu/core/carbonWebgpu/CarbonWebgpuContainer.js.map +1 -0
  245. package/dist/formats/webgpu/core/{cewgpu → carbonWebgpu}/containerViews.js +355 -355
  246. package/dist/formats/webgpu/core/carbonWebgpu/containerViews.js.map +1 -0
  247. package/dist/formats/webgpu/core/{cewgpu → carbonWebgpu}/validateContainer.js +90 -90
  248. package/dist/formats/webgpu/core/carbonWebgpu/validateContainer.js.map +1 -0
  249. package/dist/formats/webgpu/core/effectAnalysis.js +82 -82
  250. package/dist/formats/webgpu/core/effectBackendBodySet.js +289 -289
  251. package/dist/formats/webgpu/core/effectBackendBodySet.js.map +1 -1
  252. package/dist/formats/webgpu/core/errors.js +20 -20
  253. package/dist/formats/webgpu/core/errors.js.map +1 -1
  254. package/dist/formats/webgpu/core/helpers.js +443 -443
  255. package/dist/formats/webgpu/core/helpers.js.map +1 -1
  256. package/dist/formats/webgpu/core/ir/analyzeRegisterValues.js +212 -212
  257. package/dist/formats/webgpu/core/ir/buildControlFlow.js +220 -220
  258. package/dist/formats/webgpu/core/ir/indexableTemps.js +137 -137
  259. package/dist/formats/webgpu/core/ir/inferValueTypes.js +449 -449
  260. package/dist/formats/webgpu/core/ir/lowerDxbcToIr.js +494 -494
  261. package/dist/formats/webgpu/core/ir/resolveRegisterFlow.js +177 -177
  262. package/dist/formats/webgpu/core/ir/sourceLanes.js +61 -61
  263. package/dist/formats/webgpu/core/packageEffect.js +381 -385
  264. package/dist/formats/webgpu/core/packageEffect.js.map +1 -1
  265. package/dist/formats/webgpu/core/packageEffectSelection.js +164 -164
  266. package/dist/formats/webgpu/core/packageEffectSelection.js.map +1 -1
  267. package/dist/formats/webgpu/core/packageMetadata.js +17 -17
  268. package/dist/formats/webgpu/core/schema.js +4 -4
  269. package/dist/formats/webgpu/core/wgsl/buildResourceTransformPlan.js +263 -263
  270. package/dist/formats/webgpu/core/wgsl/buildResourceTransformPlan.js.map +1 -1
  271. package/dist/formats/webgpu/core/wgsl/buildWgslBindingPlan.js +172 -172
  272. package/dist/formats/webgpu/core/wgsl/buildWgslSet.js +320 -320
  273. package/dist/formats/webgpu/core/wgsl/buildWgslSet.js.map +1 -1
  274. package/dist/formats/webgpu/core/wgsl/emitWgsl.js +356 -356
  275. package/dist/formats/webgpu/core/wgsl/hoistEscapingValues.js +77 -77
  276. package/dist/formats/webgpu/core/wgsl/lowerBindingLayout.js +451 -451
  277. package/dist/formats/webgpu/core/wgsl/lowerComputeProgram.js +735 -735
  278. package/dist/formats/webgpu/core/wgsl/lowerCreateHistogramsComputeProgram.js +457 -457
  279. package/dist/formats/webgpu/core/wgsl/lowerFragmentProgram.js +1572 -1572
  280. package/dist/formats/webgpu/core/wgsl/lowerMergeHistogramsComputeProgram.js +659 -659
  281. package/dist/formats/webgpu/core/wgsl/lowerParticleClearComputePrograms.js +734 -734
  282. package/dist/formats/webgpu/core/wgsl/lowerParticleEmitComputeProgram.js +583 -583
  283. package/dist/formats/webgpu/core/wgsl/lowerSkinVerticesComputeProgram.js +621 -621
  284. package/dist/formats/webgpu/core/wgsl/lowerSortComputeProgram.js +824 -824
  285. package/dist/formats/webgpu/core/wgsl/lowerSortInnerComputeProgram.js +697 -697
  286. package/dist/formats/webgpu/core/wgsl/lowerSortStepComputeProgram.js +559 -559
  287. package/dist/formats/webgpu/core/wgsl/lowerVertexProgram.js +1328 -1328
  288. package/dist/formats/webgpu/core/wgsl/particleEmitSemanticDigest.js +110 -110
  289. package/dist/formats/webgpu/core/wgsl/precisionControls.js +55 -55
  290. package/dist/formats/webgpu/core/wgsl/selectionPlans.js +717 -717
  291. package/dist/formats/webgpu/core/wgsl/uniformity.js +78 -78
  292. package/dist/formats/webgpu/core/wgsl/validateExactComputeIr.js +196 -196
  293. package/dist/formats/webgpu/core/wgsl/validateHandleOperand.js +37 -37
  294. package/dist/formats/webgpu/index.js +2 -2
  295. package/dist/formats/webm/CjsWebmFormat.js +197 -197
  296. package/dist/formats/webm/core/helpers.js +572 -572
  297. package/dist/formats/webm/index.js +2 -2
  298. package/dist/formats/webp/CjsWebpFormat.js +140 -140
  299. package/dist/formats/webp/core/helpers.js +237 -237
  300. package/dist/formats/webp/index.js +2 -2
  301. package/dist/formats/wem/CjsWemFormat.js +250 -250
  302. package/dist/formats/wem/core/bitStream.js +261 -261
  303. package/dist/formats/wem/core/codebookLibrary.js +164 -164
  304. package/dist/formats/wem/core/helpers.js +437 -437
  305. package/dist/formats/wem/core/packedCodebooksAotuv603.js +30 -30
  306. package/dist/formats/wem/core/ptadpcm.js +77 -77
  307. package/dist/formats/wem/core/resolve.js +121 -121
  308. package/dist/formats/wem/core/wemToOgg.js +485 -485
  309. package/dist/formats/wem/index.js +2 -2
  310. package/dist/formats/yaml/CjsYamlFormat.js +134 -134
  311. package/dist/formats/yaml/CjsYamlFormat.js.map +1 -1
  312. package/dist/formats/yaml/core/CjsYamlReader.js +400 -402
  313. package/dist/formats/yaml/core/CjsYamlReader.js.map +1 -1
  314. package/dist/formats/yaml/core/helpers.js +196 -170
  315. package/dist/formats/yaml/core/helpers.js.map +1 -1
  316. package/dist/formats/yaml/index.js +2 -2
  317. package/dist/index.js +64 -62
  318. package/dist/index.js.map +1 -1
  319. package/dist/resource/CjsLoadingObject.js +19 -0
  320. package/dist/resource/CjsLoadingObject.js.map +1 -0
  321. package/dist/resource/CjsResource.js +801 -797
  322. package/dist/resource/CjsResource.js.map +1 -1
  323. package/dist/resource/ResourceHandlerMode.js +14 -0
  324. package/dist/resource/ResourceHandlerMode.js.map +1 -0
  325. package/dist/resource/Tr2LightProfileRes.js +32 -32
  326. package/dist/resource/audio/AudioGeometryResData.js +47 -47
  327. package/dist/resource/audio/CjsAudioBufferRes.js +86 -86
  328. package/dist/resource/audio/CjsAudioRes.js +213 -213
  329. package/dist/resource/audio/index.js +4 -4
  330. package/dist/resource/geometry/MeshDecalData.js +37 -37
  331. package/dist/resource/geometry/MeshDecalLodData.js +34 -34
  332. package/dist/resource/geometry/TriGeometryRes.js +675 -675
  333. package/dist/resource/geometry/TriGeometryResAreaData.js +59 -59
  334. package/dist/resource/geometry/TriGeometryResJointData.js +38 -38
  335. package/dist/resource/geometry/TriGeometryResLodData.js +88 -88
  336. package/dist/resource/geometry/TriGeometryResMeshData.js +63 -63
  337. package/dist/resource/geometry/TriGeometryResSkeletonData.js +34 -34
  338. package/dist/resource/geometry/TriJointBinding.js +38 -38
  339. package/dist/resource/geometry/TriMorphTargetGeometryConstants.js +46 -46
  340. package/dist/resource/geometry/TriRtGeometryConstants.js +88 -88
  341. package/dist/resource/geometry/granny/GStateBindingCallbackData.js +31 -31
  342. package/dist/resource/geometry/granny/Tr2GrannyIntersectionResult.js +60 -60
  343. package/dist/resource/geometry/granny/Tr2GrannyStateRes.js +36 -36
  344. package/dist/resource/geometry/granny/TriGrannyRes.js +35 -35
  345. package/dist/resource/geometry/granny/enums.js +10 -10
  346. package/dist/resource/geometry/granny/index.js +6 -6
  347. package/dist/resource/geometry/index.js +17 -17
  348. package/dist/resource/index.js +54 -52
  349. package/dist/resource/index.js.map +1 -1
  350. package/dist/resource/resourceBoundary.js +64 -64
  351. package/dist/resource/shader/Tr2EffectRes.js +336 -431
  352. package/dist/resource/shader/Tr2EffectRes.js.map +1 -1
  353. package/dist/resource/shader/Tr2MaterialArea.js +31 -31
  354. package/dist/resource/shader/Tr2MaterialMesh.js +27 -27
  355. package/dist/resource/shader/Tr2MaterialRes.js +31 -31
  356. package/dist/resource/shader/Tr2Shader.js +283 -261
  357. package/dist/resource/shader/Tr2Shader.js.map +1 -1
  358. package/dist/resource/shader/Tr2ShaderPermutation.js +43 -43
  359. package/dist/resource/shader/index.js +17 -17
  360. package/dist/resource/shader/reflection/Tr2EffectConstant.js +143 -135
  361. package/dist/resource/shader/reflection/Tr2EffectConstant.js.map +1 -1
  362. package/dist/resource/shader/reflection/Tr2EffectDefine.js +30 -30
  363. package/dist/resource/shader/reflection/Tr2EffectDescription.js +114 -109
  364. package/dist/resource/shader/reflection/Tr2EffectDescription.js.map +1 -1
  365. package/dist/resource/shader/reflection/Tr2EffectLibrary.js +168 -147
  366. package/dist/resource/shader/reflection/Tr2EffectLibrary.js.map +1 -1
  367. package/dist/resource/shader/reflection/Tr2EffectParameterAnnotation.js +125 -105
  368. package/dist/resource/shader/reflection/Tr2EffectParameterAnnotation.js.map +1 -1
  369. package/dist/resource/shader/reflection/Tr2EffectResource.js +120 -86
  370. package/dist/resource/shader/reflection/Tr2EffectResource.js.map +1 -1
  371. package/dist/resource/shader/reflection/Tr2EffectStageInput.js +372 -241
  372. package/dist/resource/shader/reflection/Tr2EffectStageInput.js.map +1 -1
  373. package/dist/resource/shader/reflection/Tr2EffectTechnique.js +78 -68
  374. package/dist/resource/shader/reflection/Tr2EffectTechnique.js.map +1 -1
  375. package/dist/resource/shader/reflection/Tr2Pass.js +168 -111
  376. package/dist/resource/shader/reflection/Tr2Pass.js.map +1 -1
  377. package/dist/resource/shader/reflection/carbonRecordFields.js +159 -0
  378. package/dist/resource/shader/reflection/carbonRecordFields.js.map +1 -0
  379. package/dist/resource/shader/reflection/shaderStage.js +22 -0
  380. package/dist/resource/shader/reflection/shaderStage.js.map +1 -0
  381. package/dist/resource/shader/sampler/Tr2SamplerSetup.js +135 -77
  382. package/dist/resource/shader/sampler/Tr2SamplerSetup.js.map +1 -1
  383. package/dist/resource/texture/CjsTextureArrayRes.js +472 -472
  384. package/dist/resource/texture/CjsTextureArrayResParameterProxy.js +179 -179
  385. package/dist/resource/texture/Tr2ImageRes.js +120 -120
  386. package/dist/resource/texture/Tr2TextureLodManager.js +82 -82
  387. package/dist/resource/texture/Tr2TextureLodUpdateRequest.js +37 -37
  388. package/dist/resource/texture/Tr2TexturePackChannel.js +37 -37
  389. package/dist/resource/texture/Tr2TexturePipeline.js +54 -54
  390. package/dist/resource/texture/Tr2TexturePipelineParams.js +34 -34
  391. package/dist/resource/texture/Tr2TexturePipelineStepCompress.js +40 -40
  392. package/dist/resource/texture/Tr2TexturePipelineStepGenerateMips.js +22 -22
  393. package/dist/resource/texture/Tr2TexturePipelineStepLimitSize.js +34 -34
  394. package/dist/resource/texture/Tr2TexturePipelineStepLoad.js +31 -31
  395. package/dist/resource/texture/Tr2TexturePipelineStepPack.js +43 -43
  396. package/dist/resource/texture/TriTextureRes.js +359 -359
  397. package/dist/resource/texture/index.js +15 -15
  398. package/dist/resource/texture/texturePipelineBehavior.js +308 -308
  399. package/dist/worker/CjsResManMainThreadLoader.js +89 -87
  400. package/dist/worker/CjsResManMainThreadLoader.js.map +1 -1
  401. package/dist/worker/CjsResManWorker.js +218 -217
  402. package/dist/worker/CjsResManWorker.js.map +1 -1
  403. package/dist/worker/CjsResManWorkerLoader.js +437 -434
  404. package/dist/worker/CjsResManWorkerLoader.js.map +1 -1
  405. package/dist/worker/protocol.js +12 -12
  406. package/docs/README.md +98 -98
  407. package/docs/architecture.md +118 -109
  408. package/docs/concepts/resource-lifecycle.md +226 -225
  409. package/docs/concepts/shader-resource-model.md +111 -114
  410. package/docs/concepts/writing-an-engine-adapter.md +115 -115
  411. package/docs/formats/README.md +138 -136
  412. package/docs/formats/carbon-effect-container.md +553 -452
  413. package/docs/formats/dxbc/README.md +68 -68
  414. package/docs/formats/dxbc/architecture.md +80 -80
  415. package/docs/formats/dxbc/reference/api.md +77 -77
  416. package/docs/formats/dxbc/reference/classes/README.md +9 -9
  417. package/docs/formats/dxbc/reference/decoded-output.md +122 -122
  418. package/docs/formats/gr2.md +160 -160
  419. package/docs/formats/hlsl/README.md +54 -54
  420. package/docs/formats/hlsl/architecture.md +65 -67
  421. package/docs/formats/hlsl/guides/hydrating-json-output.md +60 -62
  422. package/docs/formats/hlsl/guides/reading-effects.md +64 -64
  423. package/docs/formats/hlsl/reference/advanced-analysis.md +61 -66
  424. package/docs/formats/hlsl/reference/api.md +92 -98
  425. package/docs/formats/hlsl/reference/classes/README.md +11 -11
  426. package/docs/formats/hlsl/reference/json-graph.md +97 -100
  427. package/docs/formats/pickle.md +82 -0
  428. package/docs/formats/provenance.md +196 -196
  429. package/docs/formats/stl.md +37 -37
  430. package/docs/formats/webgl/README.md +115 -57
  431. package/docs/formats/webgl/architecture.md +69 -70
  432. package/docs/formats/webgl/carbon-constant-layouts.md +326 -326
  433. package/docs/formats/webgl/decl-io.md +1234 -1234
  434. package/docs/formats/webgl/memory-structured.md +890 -871
  435. package/docs/formats/webgl/reference/classes/README.md +9 -9
  436. package/docs/formats/webgl/texture-sample.md +964 -964
  437. package/docs/formats/webgpu/README.md +84 -84
  438. package/docs/formats/webgpu/architecture.md +95 -96
  439. package/docs/formats/webgpu/formats/{cewgpu.md → carbon-webgpu.md} +215 -216
  440. package/docs/formats/webgpu/guides/effect-packaging.md +189 -191
  441. package/docs/formats/webgpu/reference/api.md +196 -197
  442. package/docs/formats/webgpu/reference/classes/README.md +9 -9
  443. package/docs/formats/webgpu/reference/wgsl-compatibility.md +1546 -1543
  444. package/docs/formats/wwise.md +146 -85
  445. package/docs/reference/classes/README.md +35 -35
  446. package/docs/reference/classes/audio.md +30 -30
  447. package/docs/reference/classes/core.md +216 -206
  448. package/docs/reference/classes/dropped.md +46 -46
  449. package/docs/reference/classes/formats.md +944 -952
  450. package/docs/reference/classes/resources.md +456 -456
  451. package/docs/reference/classes/texture.md +26 -26
  452. package/docs/reference/events.md +117 -117
  453. package/docs/reference/motherlode-cache.md +275 -275
  454. package/docs/reference/queues.md +194 -110
  455. package/docs/reference/reload.md +107 -107
  456. package/docs/reference/texture-arrays.md +113 -113
  457. package/docs/reference/texture-pipeline.md +53 -53
  458. package/docs/reference/workers.md +142 -135
  459. package/docs/roadmap.md +150 -150
  460. package/format-notices/black/LICENSE +21 -21
  461. package/format-notices/black/NOTICE +47 -47
  462. package/format-notices/bnk/LICENSE +21 -21
  463. package/format-notices/bnk/NOTICE +21 -21
  464. package/format-notices/cmf/LICENSE +21 -21
  465. package/format-notices/cmf/NOTICE +36 -36
  466. package/format-notices/dds/LICENSE +21 -21
  467. package/format-notices/dds/NOTICE +14 -14
  468. package/format-notices/dxbc/LICENSE +21 -21
  469. package/format-notices/dxbc/NOTICE +20 -20
  470. package/format-notices/fbx/LICENSE +21 -21
  471. package/format-notices/fbx/NOTICE +14 -14
  472. package/format-notices/flac/LICENSE +21 -21
  473. package/format-notices/flac/NOTICE +14 -14
  474. package/format-notices/gif/LICENSE +21 -21
  475. package/format-notices/gif/NOTICE +14 -14
  476. package/format-notices/gltf/LICENSE +21 -21
  477. package/format-notices/gltf/NOTICE +27 -27
  478. package/format-notices/gr2/LICENSE +21 -21
  479. package/format-notices/gr2/NOTICE +60 -60
  480. package/format-notices/gr2/THIRD-PARTY-NOTICES.md +93 -93
  481. package/format-notices/hlsl/LICENSE +21 -21
  482. package/format-notices/hlsl/NOTICE +25 -25
  483. package/format-notices/jpeg/LICENSE +21 -21
  484. package/format-notices/jpeg/NOTICE +14 -14
  485. package/format-notices/mp3/LICENSE +21 -21
  486. package/format-notices/mp3/NOTICE +14 -14
  487. package/format-notices/mp4/LICENSE +21 -21
  488. package/format-notices/mp4/NOTICE +14 -14
  489. package/format-notices/obj/LICENSE +21 -21
  490. package/format-notices/obj/NOTICE +26 -26
  491. package/format-notices/ogg/LICENSE +21 -21
  492. package/format-notices/ogg/NOTICE +28 -28
  493. package/format-notices/png/LICENSE +21 -21
  494. package/format-notices/png/NOTICE +14 -14
  495. package/format-notices/red/LICENSE +21 -21
  496. package/format-notices/red/NOTICE +31 -31
  497. package/format-notices/stl/LICENSE +21 -21
  498. package/format-notices/stl/NOTICE +21 -21
  499. package/format-notices/tga/LICENSE +21 -21
  500. package/format-notices/tga/NOTICE +14 -14
  501. package/format-notices/wav/LICENSE +21 -21
  502. package/format-notices/wav/NOTICE +14 -14
  503. package/format-notices/webgl/LICENSE +21 -21
  504. package/format-notices/webgl/NOTICE +35 -35
  505. package/format-notices/webgpu/LICENSE +21 -21
  506. package/format-notices/webgpu/NOTICE +31 -31
  507. package/format-notices/webm/LICENSE +21 -21
  508. package/format-notices/webm/NOTICE +14 -14
  509. package/format-notices/webp/LICENSE +21 -21
  510. package/format-notices/webp/NOTICE +14 -14
  511. package/format-notices/wem/LICENSE +57 -57
  512. package/format-notices/wem/NOTICE +33 -33
  513. package/format-notices/yaml/LICENSE +21 -21
  514. package/format-notices/yaml/NOTICE +44 -44
  515. package/package.json +63 -63
  516. package/dist/format/carbonEffect/carbonDescriptionFromPortable.js +0 -372
  517. package/dist/format/carbonEffect/carbonDescriptionFromPortable.js.map +0 -1
  518. package/dist/format/effect/effectReflectionPackage.js +0 -636
  519. package/dist/format/effect/effectReflectionPackage.js.map +0 -1
  520. package/dist/formats/hlsl/core/HlslReader.js +0 -16
  521. package/dist/formats/hlsl/core/HlslReader.js.map +0 -1
  522. package/dist/formats/hlsl/core/portableReflection.js +0 -848
  523. package/dist/formats/hlsl/core/portableReflection.js.map +0 -1
  524. package/dist/formats/hlsl/portable.js +0 -2
  525. package/dist/formats/hlsl/portable.js.map +0 -1
  526. package/dist/formats/webgl/core/cewg/CewgPackage.js +0 -340
  527. package/dist/formats/webgl/core/cewg/CewgPackage.js.map +0 -1
  528. package/dist/formats/webgl/core/cewg/CewgPackageBuilder.js +0 -104
  529. package/dist/formats/webgl/core/cewg/CewgPackageBuilder.js.map +0 -1
  530. package/dist/formats/webgl/core/cewg/binary.js +0 -19
  531. package/dist/formats/webgl/core/cewg/binary.js.map +0 -1
  532. package/dist/formats/webgl/core/cewgCompleteness.js.map +0 -1
  533. package/dist/formats/webgl/core/effectPackageValidation.js +0 -331
  534. package/dist/formats/webgl/core/effectPackageValidation.js.map +0 -1
  535. package/dist/formats/webgpu/core/cewgpu/CewgpuContainer.js.map +0 -1
  536. package/dist/formats/webgpu/core/cewgpu/containerViews.js.map +0 -1
  537. package/dist/formats/webgpu/core/cewgpu/validateContainer.js.map +0 -1
  538. package/dist/resource/shader/portable.js +0 -33
  539. package/dist/resource/shader/portable.js.map +0 -1
  540. package/docs/formats/hlsl/reference/portable-reflection.md +0 -141
  541. package/docs/formats/webgl/effect-reflection.md +0 -127
package/docs/roadmap.md CHANGED
@@ -1,150 +1,150 @@
1
- # Roadmap
2
-
3
- Status: Evolving
4
- Scope: `@carbonenginejs/runtime-resource`
5
- Audience: Integrators and maintainers
6
- Summary: Records approved future direction, open design questions, and the current shader-format boundary needed to interpret that direction.
7
-
8
- Unless a section is explicitly marked **Current**, everything below is future
9
- work. Current behavior is documented in the
10
- [reference pages](reference/motherlode-cache.md); where this page and a
11
- reference page disagree, the reference page describes the shipped package.
12
-
13
- ## Runtime manager follow-up
14
-
15
- The ResMan/MotherLode contract is complete for its current consumers. Future
16
- work should be driven by measured application needs rather than another
17
- resource preparation abstraction:
18
-
19
- - main-queue priority and starvation policy;
20
- - cancellation/abort propagation for work that has already started;
21
- - `WaitUrgent()` after real priority and bounded fairness;
22
- - queue-time and reader/format-time telemetry;
23
- - application-level default retention policy selection;
24
- - automatic resource/payload byte estimation and separate CPU/adapter
25
- budgets;
26
- - additional browser-source response types and configurable worker-pool
27
- concurrency.
28
-
29
- ## Browser shader formats
30
-
31
- **Current:** HLSL, DXBC, WebGL, and WebGPU are consolidated into
32
- runtime-resource and exposed as independently importable
33
- `@carbonenginejs/runtime-resource/formats/<name>` entry points. HLSL and DXBC
34
- remain directly usable; WebGL and WebGPU compose them to read DX11/DX12 effect
35
- inputs and translate them.
36
-
37
- **Planned:** Browser delivery and fallback policy still needs a stable
38
- application-facing contract.
39
-
40
- Browser-targeted production modules must not import or require Node-only
41
- shader libraries. A format package may use local Node libraries as development
42
- or test dependencies for fixtures, comparison, and conformance checks, but
43
- those libraries must not ship and must not be runtime dependencies.
44
-
45
- ccpwgl currently preserves an authored `.fx` path while `Tw2Device` maps it to
46
- a backend-specific remote namespace such as `effect.gles2` or `effect.webgl2`
47
- and appends the selected shader-model extension. The resource/format
48
- contract must retain both use cases:
49
-
50
- - resolve and load a pretranslated backend artifact from a remote resource
51
- provider or tools-core cache; and
52
- - fall back to the authored effect input and translate it in the browser.
53
-
54
- The authored effect path should remain the stable identity. Backend profile,
55
- shader model, translated cache path, and translation capabilities are
56
- resolution facts rather than changes a caller must make to its source path.
57
-
58
- ## Format buffer ownership and destination reuse
59
-
60
- **Current:** The CMF, DDS, FBX, GIF, glTF, JPEG, MP3, MP4, Ogg, PNG, STL,
61
- TGA, WAV, WebM, and WebP byte normalizers preserve an existing `Uint8Array`.
62
- `ArrayBuffer` and other byte-addressable views are exposed through a
63
- `Uint8Array` view over the same backing storage rather than copied merely for
64
- input normalization. Decode operations that produce new pixel, sample,
65
- geometry, or decompression payloads currently allocate those result arrays
66
- internally. Resource payload references are shared read-only by default;
67
- [MotherLode retention](reference/motherlode-cache.md) defines the cases where
68
- a consumer must make an explicit copy.
69
-
70
- **Planned:** Known-size decode and transform operations should gain
71
- format-specific optional destination-array seams. Omitting the destination
72
- must preserve the convenient allocating call. Supplying a valid destination
73
- must fill and return that exact object. Each seam must:
74
-
75
- - require the correct typed-array kind and sufficient capacity before writing;
76
- - support non-zero-offset input and destination views;
77
- - leave input unchanged unless the operation explicitly documents an
78
- in-place transform;
79
- - produce the same bytes and typed-array kind as the allocating form; and
80
- - behave deterministically when one destination is reused across sequential
81
- calls.
82
-
83
- The first candidates are CMF decompression, FBX inflate and packed-array
84
- helpers, DDS block and uncompressed decoders, PNG row/RGBA decode, JPEG
85
- component and final RGBA output, TGA RGBA decode, GIF compositing canvas, WAV
86
- PCM decode, and glTF data-URI decode. Decoder workspaces such as JPEG
87
- coefficient blocks, cached lookup tables, CRC tables, and small fixed scratch
88
- arrays remain implementation-owned rather than becoming public output
89
- arguments.
90
-
91
- Some copies remain necessary: mutation of otherwise shared data,
92
- `ArrayBuffer` transfer/detachment, compacting a small retained range out of a
93
- large backing buffer, immutable frame history, and platform APIs that expose
94
- no destination seam. Those copies should stay explicit at the owning call
95
- site. This direction does not introduce a generic deep-copy operation for
96
- payload objects or typed-array bundles.
97
-
98
- ## Scoped lock token
99
-
100
- **Planned:** add `AcquireLock()` as an async-safe wrapper around the current
101
- `Lock()`/`Unlock()` contract. Existing `KeepAlive()` and
102
- `KeepPayloadAlive()` behavior remains current package API; this roadmap does
103
- not propose removing it.
104
-
105
- Raw `Lock()` / `Unlock()` is easy to mis-pair across asynchronous success,
106
- failure, cancellation, and disposal. Prefer a JS-only acquired-lock API:
107
-
108
- ```js
109
- const hold = resource.AcquireLock();
110
- try {
111
- const payload = await resource.Ready();
112
- await consume(payload);
113
- } finally {
114
- hold.Release();
115
- }
116
- ```
117
-
118
- The acquired token should add exactly one lock, capture the canonical key and
119
- ownership generation that received it, and release that exact lock at most
120
- once. `Release()` must be idempotent. If the original record has been
121
- deleted, replaced, purged, or rebound, releasing the stale token must not
122
- decrement a new owner's lock. Acquisition and release must never fetch,
123
- reconstruct, prepare, or release payload data themselves.
124
-
125
- The token is an async-safety replacement for exposing the existing raw lock
126
- count, not a new retention policy. For example, runtime-audio can hold
127
- source/PCM payload through decode and release the token once it owns the
128
- resulting WebAudio `AudioBuffer`; keeping the resource locked for the full
129
- playback or decoded-cache lifetime would unnecessarily retain both
130
- representations. Runtime-lifetime and group retention remain caller policy
131
- built from explicit tokens, not an implicit default on every loaded resource.
132
-
133
- ## Open design questions
134
-
135
- - Should `Unload()` drop only adapter payloads by default, or CPU payloads
136
- too?
137
- - Should there be explicit `UnloadAdapterResources()`, `UnloadPayload()`, and
138
- `Purge()` phases?
139
- - Which format/resource-specific estimators should supply separate identity,
140
- CPU-payload, and adapter byte weights without double-counting shared
141
- buffers?
142
- - Should manually attached/dynamic resources default to locked, like ccpwgl's
143
- manual shader resources use `doNotPurge`?
144
- - Should a resource-level `Purge()` complement the existing automatic and
145
- MotherLode-level eviction operations?
146
-
147
- ## Related documentation
148
-
149
- - [MotherLode identity, cache, and retention](reference/motherlode-cache.md)
150
- - [Candidate-first atomic reload](reference/reload.md)
1
+ # Roadmap
2
+
3
+ Status: Evolving
4
+ Scope: `@carbonenginejs/runtime-resource`
5
+ Audience: Integrators and maintainers
6
+ Summary: Records approved future direction, open design questions, and the current shader-format boundary needed to interpret that direction.
7
+
8
+ Unless a section is explicitly marked **Current**, everything below is future
9
+ work. Current behavior is documented in the
10
+ [reference pages](reference/motherlode-cache.md); where this page and a
11
+ reference page disagree, the reference page describes the shipped package.
12
+
13
+ ## Runtime manager follow-up
14
+
15
+ The ResMan/MotherLode contract is complete for its current consumers. Future
16
+ work should be driven by measured application needs rather than another
17
+ resource preparation abstraction:
18
+
19
+ - main-queue priority and starvation policy;
20
+ - cancellation/abort propagation for work that has already started;
21
+ - `WaitUrgent()` after real priority and bounded fairness;
22
+ - queue-time and reader/format-time telemetry;
23
+ - application-level default retention policy selection;
24
+ - automatic resource/payload byte estimation and separate CPU/adapter
25
+ budgets;
26
+ - additional browser-source response types and configurable worker-pool
27
+ concurrency.
28
+
29
+ ## Browser shader formats
30
+
31
+ **Current:** HLSL, DXBC, WebGL, and WebGPU are consolidated into
32
+ runtime-resource and exposed as independently importable
33
+ `@carbonenginejs/runtime-resource/formats/<name>` entry points. HLSL and DXBC
34
+ remain directly usable; WebGL and WebGPU compose them to read DX11/DX12 effect
35
+ inputs and translate them.
36
+
37
+ **Planned:** Browser delivery and fallback policy still needs a stable
38
+ application-facing contract.
39
+
40
+ Browser-targeted production modules must not import or require Node-only
41
+ shader libraries. A format package may use local Node libraries as development
42
+ or test dependencies for fixtures, comparison, and conformance checks, but
43
+ those libraries must not ship and must not be runtime dependencies.
44
+
45
+ ccpwgl currently preserves an authored `.fx` path while `Tw2Device` maps it to
46
+ a backend-specific remote namespace such as `effect.gles2` or `effect.webgl2`
47
+ and appends the selected shader-model extension. The resource/format
48
+ contract must retain both use cases:
49
+
50
+ - resolve and load a pretranslated backend artifact from a remote resource
51
+ provider or tools-core cache; and
52
+ - fall back to the authored effect input and translate it in the browser.
53
+
54
+ The authored effect path should remain the stable identity. Backend profile,
55
+ shader model, translated cache path, and translation capabilities are
56
+ resolution facts rather than changes a caller must make to its source path.
57
+
58
+ ## Format buffer ownership and destination reuse
59
+
60
+ **Current:** The CMF, DDS, FBX, GIF, glTF, JPEG, MP3, MP4, Ogg, PNG, STL,
61
+ TGA, WAV, WebM, and WebP byte normalizers preserve an existing `Uint8Array`.
62
+ `ArrayBuffer` and other byte-addressable views are exposed through a
63
+ `Uint8Array` view over the same backing storage rather than copied merely for
64
+ input normalization. Decode operations that produce new pixel, sample,
65
+ geometry, or decompression payloads currently allocate those result arrays
66
+ internally. Resource payload references are shared read-only by default;
67
+ [MotherLode retention](reference/motherlode-cache.md) defines the cases where
68
+ a consumer must make an explicit copy.
69
+
70
+ **Planned:** Known-size decode and transform operations should gain
71
+ format-specific optional destination-array seams. Omitting the destination
72
+ must preserve the convenient allocating call. Supplying a valid destination
73
+ must fill and return that exact object. Each seam must:
74
+
75
+ - require the correct typed-array kind and sufficient capacity before writing;
76
+ - support non-zero-offset input and destination views;
77
+ - leave input unchanged unless the operation explicitly documents an
78
+ in-place transform;
79
+ - produce the same bytes and typed-array kind as the allocating form; and
80
+ - behave deterministically when one destination is reused across sequential
81
+ calls.
82
+
83
+ The first candidates are CMF decompression, FBX inflate and packed-array
84
+ helpers, DDS block and uncompressed decoders, PNG row/RGBA decode, JPEG
85
+ component and final RGBA output, TGA RGBA decode, GIF compositing canvas, WAV
86
+ PCM decode, and glTF data-URI decode. Decoder workspaces such as JPEG
87
+ coefficient blocks, cached lookup tables, CRC tables, and small fixed scratch
88
+ arrays remain implementation-owned rather than becoming public output
89
+ arguments.
90
+
91
+ Some copies remain necessary: mutation of otherwise shared data,
92
+ `ArrayBuffer` transfer/detachment, compacting a small retained range out of a
93
+ large backing buffer, immutable frame history, and platform APIs that expose
94
+ no destination seam. Those copies should stay explicit at the owning call
95
+ site. This direction does not introduce a generic deep-copy operation for
96
+ payload objects or typed-array bundles.
97
+
98
+ ## Scoped lock token
99
+
100
+ **Planned:** add `AcquireLock()` as an async-safe wrapper around the current
101
+ `Lock()`/`Unlock()` contract. Existing `KeepAlive()` and
102
+ `KeepPayloadAlive()` behavior remains current package API; this roadmap does
103
+ not propose removing it.
104
+
105
+ Raw `Lock()` / `Unlock()` is easy to mis-pair across asynchronous success,
106
+ failure, cancellation, and disposal. Prefer a JS-only acquired-lock API:
107
+
108
+ ```js
109
+ const hold = resource.AcquireLock();
110
+ try {
111
+ const payload = await resource.Ready();
112
+ await consume(payload);
113
+ } finally {
114
+ hold.Release();
115
+ }
116
+ ```
117
+
118
+ The acquired token should add exactly one lock, capture the canonical key and
119
+ ownership generation that received it, and release that exact lock at most
120
+ once. `Release()` must be idempotent. If the original record has been
121
+ deleted, replaced, purged, or rebound, releasing the stale token must not
122
+ decrement a new owner's lock. Acquisition and release must never fetch,
123
+ reconstruct, prepare, or release payload data themselves.
124
+
125
+ The token is an async-safety replacement for exposing the existing raw lock
126
+ count, not a new retention policy. For example, runtime-audio can hold
127
+ source/PCM payload through decode and release the token once it owns the
128
+ resulting WebAudio `AudioBuffer`; keeping the resource locked for the full
129
+ playback or decoded-cache lifetime would unnecessarily retain both
130
+ representations. Runtime-lifetime and group retention remain caller policy
131
+ built from explicit tokens, not an implicit default on every loaded resource.
132
+
133
+ ## Open design questions
134
+
135
+ - Should `Unload()` drop only adapter payloads by default, or CPU payloads
136
+ too?
137
+ - Should there be explicit `UnloadAdapterResources()`, `UnloadPayload()`, and
138
+ `Purge()` phases?
139
+ - Which format/resource-specific estimators should supply separate identity,
140
+ CPU-payload, and adapter byte weights without double-counting shared
141
+ buffers?
142
+ - Should manually attached/dynamic resources default to locked, like ccpwgl's
143
+ manual shader resources use `doNotPurge`?
144
+ - Should a resource-level `Purge()` complement the existing automatic and
145
+ MotherLode-level eviction operations?
146
+
147
+ ## Related documentation
148
+
149
+ - [MotherLode identity, cache, and retention](reference/motherlode-cache.md)
150
+ - [Candidate-first atomic reload](reference/reload.md)
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 CarbonEngineJS contributors
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CarbonEngineJS contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -1,47 +1,47 @@
1
- format-black
2
-
3
- Copyright (c) CarbonEngineJS contributors.
4
- CarbonEngine source material, formats, class names, and schema semantics remain
5
- copyright their original CarbonEngine authors.
6
- Fenris Creations (CCP Games) source material, tools, assets, shader behavior,
7
- and EVE-related data remain copyright their original holders.
8
-
9
- This package is a CarbonEngineJS-facing reader for `.black` files. It
10
- contains original project code unless third-party material is explicitly listed
11
- below.
12
- CarbonEngine and Fenris Creations (CCP Games) are mentioned for
13
- interoperability, provenance, and future migration context only. This package is
14
- not affiliated with or endorsed by CCP Games.
15
-
16
- Third-party reference material
17
- ------------------------------
18
-
19
- black-reader-js
20
- Repository: https://github.com/rawrafox/black-reader-js
21
- Author: rawrafox
22
- Package author: aurora
23
- License: MIT
24
- Local license notice: Copyright (c) 2023 @rawrafox and @cppctamber
25
-
26
- CarbonEngineJS uses black-reader-js as reference material for `.black` format
27
- behavior. The format-black package is implemented against CarbonEngineJS
28
- runtime-utils/canonical schema definitions and emits CarbonEngineJS public
29
- Black payload data.
30
-
31
- Provenance and legal requirements
32
- ---------------------------------
33
-
34
- This scaffold currently contains CarbonEngineJS original project code plus the
35
- third-party reference attribution listed above. It does not include copied
36
- CarbonEngine source code or third-party parser code.
37
-
38
- If future work copies, ports, translates, or derives from CarbonEngine, ccpwgl,
39
- Fenris Creations (CCP Games) / EVE assets or tools, or any third-party library,
40
- update this NOTICE before committing that work with:
41
-
42
- - upstream copyright holders;
43
- - upstream project/repository, file path, and revision when known;
44
- - upstream license name, license text or required notice location, and any
45
- redistribution obligations;
46
- - whether the material was copied/ported/adapted, or used only as a behavioral
47
- reference with no copied expression.
1
+ format-black
2
+
3
+ Copyright (c) CarbonEngineJS contributors.
4
+ CarbonEngine source material, formats, class names, and schema semantics remain
5
+ copyright their original CarbonEngine authors.
6
+ Fenris Creations (CCP Games) source material, tools, assets, shader behavior,
7
+ and EVE-related data remain copyright their original holders.
8
+
9
+ This package is a CarbonEngineJS-facing reader for `.black` files. It
10
+ contains original project code unless third-party material is explicitly listed
11
+ below.
12
+ CarbonEngine and Fenris Creations (CCP Games) are mentioned for
13
+ interoperability, provenance, and future migration context only. This package is
14
+ not affiliated with or endorsed by CCP Games.
15
+
16
+ Third-party reference material
17
+ ------------------------------
18
+
19
+ black-reader-js
20
+ Repository: https://github.com/rawrafox/black-reader-js
21
+ Author: rawrafox
22
+ Package author: aurora
23
+ License: MIT
24
+ Local license notice: Copyright (c) 2023 @rawrafox and @cppctamber
25
+
26
+ CarbonEngineJS uses black-reader-js as reference material for `.black` format
27
+ behavior. The format-black package is implemented against CarbonEngineJS
28
+ runtime-utils/canonical schema definitions and emits CarbonEngineJS public
29
+ Black payload data.
30
+
31
+ Provenance and legal requirements
32
+ ---------------------------------
33
+
34
+ This scaffold currently contains CarbonEngineJS original project code plus the
35
+ third-party reference attribution listed above. It does not include copied
36
+ CarbonEngine source code or third-party parser code.
37
+
38
+ If future work copies, ports, translates, or derives from CarbonEngine, ccpwgl,
39
+ Fenris Creations (CCP Games) / EVE assets or tools, or any third-party library,
40
+ update this NOTICE before committing that work with:
41
+
42
+ - upstream copyright holders;
43
+ - upstream project/repository, file path, and revision when known;
44
+ - upstream license name, license text or required notice location, and any
45
+ redistribution obligations;
46
+ - whether the material was copied/ported/adapted, or used only as a behavioral
47
+ reference with no copied expression.
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 CarbonEngineJS contributors
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CarbonEngineJS contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -1,21 +1,21 @@
1
- formats/bnk
2
-
3
- Copyright (c) CarbonEngineJS contributors.
4
- CarbonEngine source material, formats, class names, and schema semantics remain
5
- copyright their original CarbonEngine authors.
6
- Fenris Creations (CCP Games) source material, tools, assets, shader behavior,
7
- and EVE-related data remain copyright their original holders.
8
- Wwise and the Wwise soundbank format are property of Audiokinetic Inc.
9
-
10
- This reader is original CarbonEngineJS code authored directly in
11
- runtime-resource; no legacy package was copied. The soundbank chunk layout,
12
- HIRC object field layouts, the event-graph resolution exposed as
13
- `eventMediaFromBanks`, and the typed version-150 authored-SFX node tails
14
- exposed as `sfxNodesFromBanks` were implemented from publicly documented
15
- community knowledge of the format (ww2ogg, vgmstream, wwiser documentation)
16
- and independently verified by hexdump against EVE Online soundbanks (bank
17
- generator version 150); no code was copied from those projects and no
18
- Audiokinetic SDK material was used.
19
- Audiokinetic, CarbonEngine, and Fenris Creations (CCP Games) are mentioned for
20
- interoperability, provenance, and future migration context only. This package
21
- is not affiliated with or endorsed by Audiokinetic Inc. or CCP Games.
1
+ formats/bnk
2
+
3
+ Copyright (c) CarbonEngineJS contributors.
4
+ CarbonEngine source material, formats, class names, and schema semantics remain
5
+ copyright their original CarbonEngine authors.
6
+ Fenris Creations (CCP Games) source material, tools, assets, shader behavior,
7
+ and EVE-related data remain copyright their original holders.
8
+ Wwise and the Wwise soundbank format are property of Audiokinetic Inc.
9
+
10
+ This reader is original CarbonEngineJS code authored directly in
11
+ runtime-resource; no legacy package was copied. The soundbank chunk layout,
12
+ HIRC object field layouts, the event-graph resolution exposed as
13
+ `eventMediaFromBanks`, and the typed version-150 authored-SFX node tails
14
+ exposed as `sfxNodesFromBanks` were implemented from publicly documented
15
+ community knowledge of the format (ww2ogg, vgmstream, wwiser documentation)
16
+ and independently verified by hexdump against EVE Online soundbanks (bank
17
+ generator version 150); no code was copied from those projects and no
18
+ Audiokinetic SDK material was used.
19
+ Audiokinetic, CarbonEngine, and Fenris Creations (CCP Games) are mentioned for
20
+ interoperability, provenance, and future migration context only. This package
21
+ is not affiliated with or endorsed by Audiokinetic Inc. or CCP Games.
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 CarbonEngineJS contributors
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CarbonEngineJS contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -1,36 +1,36 @@
1
- carbonenginejs/format-cmf
2
- =========================
3
-
4
- A pure-JavaScript reader for Carbon Mesh Format (.cmf) geometry containers.
5
-
6
- CarbonEngineJS-facing code is copyright CarbonEngineJS contributors.
7
- CarbonEngine source material, formats, class names, and schema semantics remain
8
- copyright their original CarbonEngine authors. Fenris Creations (CCP Games)
9
- source material, tools, assets, shader behavior, and EVE-related data remain
10
- copyright their original holders.
11
-
12
- CarbonEngine and Fenris Creations (CCP Games) are mentioned for interoperability
13
- and provenance context. This package is not affiliated with or endorsed by CCP
14
- Games.
15
-
16
- Format reference
17
- ----------------
18
-
19
- The CMF v1 structure names, enum names, layout, and validation behavior were
20
- implemented from the local CarbonEngine mesh headers and sources:
21
-
22
- - mesh/include/cmf/cmf.h
23
- - mesh/include/cmf/v1.h
24
- - mesh/include/cmf/span.h
25
- - mesh/include/cmf/writer.h
26
- - mesh/src/cmf/writer.cpp
27
- - mesh/src/cmf/utils.cpp
28
-
29
- No CarbonEngine implementation code is copied into this package.
30
-
31
- Third-party dependencies
32
- ------------------------
33
-
34
- meshoptimizer JavaScript package
35
- Used for decoding CMF GPU-buffer sections compressed with meshoptimizer
36
- vertex/index codecs. Copyright Arseny Kapoulkine, MIT License.
1
+ carbonenginejs/format-cmf
2
+ =========================
3
+
4
+ A pure-JavaScript reader for Carbon Mesh Format (.cmf) geometry containers.
5
+
6
+ CarbonEngineJS-facing code is copyright CarbonEngineJS contributors.
7
+ CarbonEngine source material, formats, class names, and schema semantics remain
8
+ copyright their original CarbonEngine authors. Fenris Creations (CCP Games)
9
+ source material, tools, assets, shader behavior, and EVE-related data remain
10
+ copyright their original holders.
11
+
12
+ CarbonEngine and Fenris Creations (CCP Games) are mentioned for interoperability
13
+ and provenance context. This package is not affiliated with or endorsed by CCP
14
+ Games.
15
+
16
+ Format reference
17
+ ----------------
18
+
19
+ The CMF v1 structure names, enum names, layout, and validation behavior were
20
+ implemented from the local CarbonEngine mesh headers and sources:
21
+
22
+ - mesh/include/cmf/cmf.h
23
+ - mesh/include/cmf/v1.h
24
+ - mesh/include/cmf/span.h
25
+ - mesh/include/cmf/writer.h
26
+ - mesh/src/cmf/writer.cpp
27
+ - mesh/src/cmf/utils.cpp
28
+
29
+ No CarbonEngine implementation code is copied into this package.
30
+
31
+ Third-party dependencies
32
+ ------------------------
33
+
34
+ meshoptimizer JavaScript package
35
+ Used for decoding CMF GPU-buffer sections compressed with meshoptimizer
36
+ vertex/index codecs. Copyright Arseny Kapoulkine, MIT License.