@carbonenginejs/runtime 0.1.0-alpha.4 → 0.1.0-alpha.5

package/dist/resource/formats/dds/core/helpers.js

@@ -8,7 +8,6 @@ const OUTPUT_IMAGE = "image";
 const OUTPUT_TEXTURE = "texture";
 const OUTPUT_RGBA = "rgba";
 const OUTPUT_RAW = "raw";
-const OUTPUT_JSON = "json";
 const DEFAULT_VALUES = Object.freeze({
   emit: OUTPUT_RAW,
   inputType: "",
@@ -74,9 +73,9 @@ const DEBUG_OUTPUTS = Object.freeze({
   dds: "ddsJson"
 });
 
-/**
- * Normalizes reader options against their supported defaults for the DDS format
- * reader.
+/**
+ * Normalizes reader options against their supported defaults for the DDS format
+ * reader.
  */
 function normalizeValues(base = DEFAULT_VALUES, options = {}, readerName = "CjsImageFormat") {
   const values = {
@@ -99,8 +98,7 @@ function normalizeInputType(inputType) {
 /** Normalizes the requested output representation for the DDS format reader. */
 function normalizeEmit(emit, inputType, readerName) {
   if (emit === undefined || emit === null) return OUTPUT_RAW;
-  if (emit === OUTPUT_JSON && inputType) return DEBUG_OUTPUTS[inputType] || OUTPUT_JSON;
-  if ([OUTPUT_IMAGE, OUTPUT_TEXTURE, OUTPUT_RGBA, OUTPUT_RAW, OUTPUT_JSON].includes(emit)) return emit;
+  if ([OUTPUT_IMAGE, OUTPUT_TEXTURE, OUTPUT_RGBA, OUTPUT_RAW].includes(emit)) return emit;
   if (Object.values(DEBUG_OUTPUTS).includes(emit)) return emit;
   throw new TypeError(`${readerName}: unknown emit value ${JSON.stringify(emit)}`);
 }
@@ -123,9 +121,9 @@ function inspectWithValues(input, values = DEFAULT_VALUES, expectedType = "") {
   };
 }
 
-/**
- * Reports whether input is supported under normalized format options for the DDS
- * format reader.
+/**
+ * Reports whether input is supported under normalized format options for the DDS
+ * format reader.
  */
 function probeSupportWithValues(input, values = DEFAULT_VALUES, expectedType = "") {
   try {
@@ -204,11 +202,11 @@ function readWithValues(input, values = DEFAULT_VALUES, expectedType = "") {
       bytes
     };
   }
-  if (values.emit === OUTPUT_JSON || values.emit === DEBUG_OUTPUTS[metadata.sourceFormat]) {
+  if (values.emit === DEBUG_OUTPUTS[metadata.sourceFormat]) {
     return metadata;
   }
   if (values.emit === OUTPUT_TEXTURE && metadata.sourceFormat === "dds") {
-    return readDdsTexture(bytes, metadata);
+    return readDdsTexture(bytes, metadata, values);
   }
   if ((values.emit === OUTPUT_RGBA || values.emit === OUTPUT_IMAGE) && metadata.sourceFormat === "dds") {
     return readDdsToRgba(bytes, metadata);
@@ -220,9 +218,9 @@ function readWithValues(input, values = DEFAULT_VALUES, expectedType = "") {
   throw error;
 }
 
-/**
- * Inspects the supplied bytes without decoding their payload for the DDS format
- * reader.
+/**
+ * Inspects the supplied bytes without decoding their payload for the DDS format
+ * reader.
  */
 function inspectBytes(bytes) {
   const sourceFormat = identifyImageBytes(bytes);
@@ -346,7 +344,93 @@ function inspectDDS(bytes) {
     hasMipMaps: readU32LE(bytes, 28) > 1
   };
 }
-function readDdsTexture(bytes, metadata) {
+
+/**
+ * Carbon's load-time clean-up of 24-bit RGB: BGR -> BGRX with X = 0
+ * (imageio/Tr2DdsHandler.cpp Convert24BitTo32Bit, :774-795).
+ *
+ * @param {Uint8Array} source 24-bit pixels.
+ * @returns {Uint8Array} 32-bit pixels.
+ */
+function expand24To32(source) {
+  const pixels = Math.floor(source.length / 3);
+  const out = new Uint8Array(pixels * 4);
+  for (let p = 0, s = 0, d = 0; p < pixels; p++) {
+    out[d++] = source[s++];
+    out[d++] = source[s++];
+    out[d++] = source[s++];
+    out[d++] = 0;
+  }
+  return out;
+}
+
+/**
+ * Carbon's load-time clean-up of A8L8: luminance and alpha -> BGRA with
+ * B = G = R = L (Tr2DdsHandler.cpp:863-868, via HostBitmap::ConvertFormat
+ * R8G8 -> B8G8R8A8, HostBitmap.cpp:386-396).
+ *
+ * @param {Uint8Array} source L8A8 pixels.
+ * @returns {Uint8Array} BGRA pixels.
+ */
+function convertL8A8ToBgra(source) {
+  const pixels = Math.floor(source.length / 2);
+  const out = new Uint8Array(pixels * 4);
+  for (let p = 0, s = 0, d = 0; p < pixels; p++, s += 2) {
+    out[d++] = source[s];
+    out[d++] = source[s];
+    out[d++] = source[s];
+    out[d++] = source[s + 1];
+  }
+  return out;
+}
+
+/** The legacy layouts `expandLegacy` rewrites, with their converter and resulting format. */
+const LEGACY_EXPANSIONS = {
+  "bgr8unorm": {
+    convert: expand24To32,
+    pixelFormat: "bgrx8unorm",
+    scale: 4 / 3
+  },
+  "l8a8unorm": {
+    convert: convertL8A8ToBgra,
+    pixelFormat: "bgra8unorm",
+    scale: 2
+  }
+};
+
+/**
+ * Rewrite a 24-bit or A8L8 texture payload into Carbon's 32-bit shape, subresource
+ * by subresource, when `values.expandLegacy` asks for it.
+ */
+function expandLegacyTexture(texture) {
+  const rule = LEGACY_EXPANSIONS[texture.pixelFormat];
+  if (!rule) return texture;
+  const parts = [];
+  let offset = 0;
+  const subresources = texture.subresources.map(sub => {
+    const data = rule.convert(texture.data.subarray(sub.offset, sub.offset + sub.byteLength));
+    parts.push(data);
+    const next = {
+      ...sub,
+      offset,
+      byteLength: data.length,
+      rowPitch: Math.round(sub.rowPitch * rule.scale),
+      slicePitch: Math.round(sub.slicePitch * rule.scale)
+    };
+    offset += data.length;
+    return next;
+  });
+  const data = new Uint8Array(offset);
+  for (let i = 0, at = 0; i < parts.length; at += parts[i].length, i++) data.set(parts[i], at);
+  return {
+    ...texture,
+    pixelFormat: rule.pixelFormat,
+    dataBytes: offset,
+    subresources,
+    data
+  };
+}
+function readDdsTexture(bytes, metadata, values = DEFAULT_VALUES) {
   if (!metadata.pixelFormat) {
     const error = new Error("dds: texture format is not recognized yet");
     error.code = "CJS_FORMAT_OUTPUT_NOT_SUPPORTED";
@@ -354,7 +438,7 @@ function readDdsTexture(bytes, metadata) {
     throw error;
   }
   const subresources = buildDdsSubresources(bytes, metadata);
-  return {
+  const texture = {
     payloadType: OUTPUT_TEXTURE,
     sourceFormat: "dds",
     width: metadata.width,
@@ -377,17 +461,18 @@ function readDdsTexture(bytes, metadata) {
     metadata,
     data: bytes.subarray(metadata.dataOffset, metadata.dataOffset + subresources.reduce((sum, entry) => sum + entry.byteLength, 0))
   };
+  return values.expandLegacy ? expandLegacyTexture(texture) : texture;
 }
 
-/**
- * Block formats one slice can be decoded from, by pixel format alone.
- *
- * Narrower than `canDecodeDdsToRgba`, which answers for a whole file and
- * includes the uncompressed formats. A caller holding one slice of a volume has
- * no file to ask about, only a format name.
- *
- * @param {String} pixelFormat
- * @returns {Boolean}
+/**
+ * Block formats one slice can be decoded from, by pixel format alone.
+ *
+ * Narrower than `canDecodeDdsToRgba`, which answers for a whole file and
+ * includes the uncompressed formats. A caller holding one slice of a volume has
+ * no file to ask about, only a format name.
+ *
+ * @param {String} pixelFormat
+ * @returns {Boolean}
  */
 function canDecodeDdsBlockFormat(pixelFormat) {
   return /^bc[1-7]/u.test(String(pixelFormat ?? ""));
@@ -833,20 +918,20 @@ function decode565(value) {
   return [Math.round((value >>> 11 & 0x1f) * 255 / 31), Math.round((value >>> 5 & 0x3f) * 255 / 63), Math.round((value & 0x1f) * 255 / 31), 255];
 }
 
-/**
- * The floating-point `D3DFORMAT` enumerators, which a legacy DDS stores as a
- * NUMBER in the four-character-code field rather than as four characters.
- *
- * That is the whole trap. `DDPF_FOURCC` is set and the field reads `114`, which
- * as text is `"r\0\0\0"` and matches nothing, so a reader that only compares
- * character codes reports an unrecognized format for a file whose format is
- * perfectly ordinary. Every one of these six is a plain uncompressed surface.
- *
- * Two were mapped when BC6H support landed and the other four were not, so
- * `A16B16G16R16F` and `A32B32G32R32F` loaded while their one- and two-channel
- * siblings did not. Found 2026-08-16 on
- * `res:/dx9/model/ship/amarr/battleship/ab3/effects/ab3_traffic.dds`, a 256x9
- * `R32F` gradient.
+/**
+ * The floating-point `D3DFORMAT` enumerators, which a legacy DDS stores as a
+ * NUMBER in the four-character-code field rather than as four characters.
+ *
+ * That is the whole trap. `DDPF_FOURCC` is set and the field reads `114`, which
+ * as text is `"r\0\0\0"` and matches nothing, so a reader that only compares
+ * character codes reports an unrecognized format for a file whose format is
+ * perfectly ordinary. Every one of these six is a plain uncompressed surface.
+ *
+ * Two were mapped when BC6H support landed and the other four were not, so
+ * `A16B16G16R16F` and `A32B32G32R32F` loaded while their one- and two-channel
+ * siblings did not. Found 2026-08-16 on
+ * `res:/dx9/model/ship/amarr/battleship/ab3/effects/ab3_traffic.dds`, a 256x9
+ * `R32F` gradient.
  */
 const LEGACY_D3DFMT_PIXEL_FORMATS = {
   111: "r16float",
@@ -884,5 +969,5 @@ function getDdsPixelFormat(format) {
   return "";
 }
 
-export { DEFAULT_VALUES, OUTPUT_IMAGE, OUTPUT_JSON, OUTPUT_RAW, OUTPUT_RGBA, OUTPUT_TEXTURE, canDecodeDdsBlockFormat, decodeDdsSlice, inspectBytes, inspectWithValues, normalizeEmit, normalizeInputType, normalizeValues, probeSupportWithValues, readWithValues };
+export { DEFAULT_VALUES, OUTPUT_IMAGE, OUTPUT_RAW, OUTPUT_RGBA, OUTPUT_TEXTURE, canDecodeDdsBlockFormat, convertL8A8ToBgra, decodeDdsSlice, expand24To32, inspectBytes, inspectWithValues, normalizeEmit, normalizeInputType, normalizeValues, probeSupportWithValues, readWithValues };
 //# sourceMappingURL=helpers.js.map