@carbonenginejs/runtime 0.1.0-alpha.0 → 0.1.0-alpha.1

package/dist/trinityal/stub/Tr2TextureALStub.js

@@ -1,10 +1,13 @@
-import { Tr2BaseDeviceResourceAL, Tr2ALMemoryType } from '../Tr2DeviceResourceAL.js';
+import { CjsSchema } from '#schema';
+import { Tr2ALMemoryType } from '../Tr2DeviceResourceAL/Tr2BaseDeviceResourceAL.js';
+import { Tr2DeviceResourceAL } from '../Tr2DeviceResourceAL/Tr2DeviceResourceAL.js';
 import { ALResult } from '../ALResult.js';
 import { Tr2BitmapDimensions } from '../Tr2BitmapDimensions.js';
-import { Tr2MsaaDesc, Crop, Tr2TextureSubresource } from '../Tr2HalHelperStructures.js';
+import { Crop, Tr2TextureSubresource } from '../Tr2HalHelperStructures/Tr2TextureSubresource.js';
 import { TextureType, IsCompressedFormat } from '../../global/consts/renderContext/formats.js';
 import '../../global/consts/renderContext/pipeline.js';
 import { Tr2GpuUsage, Tr2CpuUsage, HasBufferFlags, HasFlag, IsWritable } from '../../global/consts/renderContext/resources.js';
+import { Tr2MsaaDesc } from '../Tr2HalHelperStructures/Tr2MsaaDesc.js';
 
 // Source: trinity/trinityal/stub/Tr2TextureALStub.cpp
 // Source: trinity/trinityal/stub/Tr2TextureALStub.h
@@ -35,7 +38,7 @@ import { Tr2GpuUsage, Tr2CpuUsage, HasBufferFlags, HasFlag, IsWritable } from '.
 // - Carbon's impl-level `Destroy` only resets the fields, because the registry
 //   entry goes when the C++ destructor runs. Ours must also unregister, so the
 //   reset lives in a private helper that `Create` calls and `Destroy` calls the
-//   base as well. See the head comment on `Tr2DeviceResourceAL.js`.
+//   base as well. See the head comment on `Tr2DeviceResourceAL/Tr2BaseDeviceResourceAL.js`.
 //
 // TWO FAITHFUL EMPTINESSES, worth knowing before relying on them: Carbon's stub
 // implements `Describe` as a no-op and returns null from `GetName`, so a stub
@@ -46,10 +49,10 @@ import { Tr2GpuUsage, Tr2CpuUsage, HasBufferFlags, HasFlag, IsWritable } from '.
 /** Carbon's "no descriptor heap index", returned by both heap accessors. */
 const NO_HEAP_INDEX = 0xffffffff;
 
-/**
- * A texture that validates like a real one and holds its pixels on the CPU.
+/**
+ * A texture that validates like a real one and holds its pixels on the CPU.
  */
-class Tr2TextureALStub extends Tr2BaseDeviceResourceAL {
+class Tr2TextureALStub extends Tr2DeviceResourceAL {
   /** m_desc */
   _desc = new Tr2BitmapDimensions();
 
@@ -65,20 +68,20 @@ class Tr2TextureALStub extends Tr2BaseDeviceResourceAL {
   /** m_data - allocated on first map, released on unmap unless kept "often". */
   _data = null;
 
-  /**
-   * Creates the texture.
-   *
-   * Every refusal below is Carbon's, in Carbon's order
-   * (`Tr2TextureALStub.cpp:18-95`).
-   *
-   * @param {Tr2BitmapDimensions} desc The texture description.
-   * @param {object} options Creation options.
-   * @param {number} [options.gpuUsage] A `Tr2GpuUsage` bit set.
-   * @param {number} [options.cpuUsage] A `Tr2CpuUsage` bit set.
-   * @param {Tr2MsaaDesc} [options.msaa] Multisample description.
-   * @param {object[]} [options.initialData] Initial subresource data, if any.
-   * @param {object} renderContext The context to create against.
-   * @returns {number} An `ALResult` value.
+  /**
+   * Creates the texture.
+   *
+   * Every refusal below is Carbon's, in Carbon's order
+   * (`Tr2TextureALStub.cpp:18-95`).
+   *
+   * @param {Tr2BitmapDimensions} desc The texture description.
+   * @param {object} options Creation options.
+   * @param {number} [options.gpuUsage] A `Tr2GpuUsage` bit set.
+   * @param {number} [options.cpuUsage] A `Tr2CpuUsage` bit set.
+   * @param {Tr2MsaaDesc} [options.msaa] Multisample description.
+   * @param {object[]} [options.initialData] Initial subresource data, if any.
+   * @param {object} renderContext The context to create against.
+   * @returns {number} An `ALResult` value.
    */
   Create(desc, options, renderContext) {
     this._Reset();
@@ -139,12 +142,12 @@ class Tr2TextureALStub extends Tr2BaseDeviceResourceAL {
     return ALResult.S_OK;
   }
 
-  /**
-   * Adopts a texture shared by another device.
-   *
-   * Carbon's stub refuses: sharing needs a real device on both sides.
-   *
-   * @returns {number} An `ALResult` value.
+  /**
+   * Adopts a texture shared by another device.
+   *
+   * Carbon's stub refuses: sharing needs a real device on both sides.
+   *
+   * @returns {number} An `ALResult` value.
    */
   OpenShared() {
     return ALResult.E_FAIL;
@@ -165,155 +168,155 @@ class Tr2TextureALStub extends Tr2BaseDeviceResourceAL {
     super.Destroy();
   }
 
-  /**
-   * Whether the texture holds anything.
-   *
-   * Carbon's test is the width, because a created texture always has one.
-   *
-   * @returns {boolean} True when created.
+  /**
+   * Whether the texture holds anything.
+   *
+   * Carbon's test is the width, because a created texture always has one.
+   *
+   * @returns {boolean} True when created.
    */
   IsValid() {
     return this._desc.GetWidth() !== 0;
   }
 
-  /**
-   * Which memory class this texture occupies.
-   *
-   * @returns {number} A `Tr2ALMemoryType` value.
+  /**
+   * Which memory class this texture occupies.
+   *
+   * @returns {number} A `Tr2ALMemoryType` value.
    */
   GetMemoryClass() {
     return Tr2ALMemoryType.AL_MEMORY_MANAGED;
   }
 
-  /**
-   * The texture description.
-   *
-   * @returns {Tr2BitmapDimensions} The description.
+  /**
+   * The texture description.
+   *
+   * @returns {Tr2BitmapDimensions} The description.
    */
   GetDesc() {
     return this._desc;
   }
 
-  /**
-   * The multisample description.
-   *
-   * @returns {Tr2MsaaDesc} The description.
+  /**
+   * The multisample description.
+   *
+   * @returns {Tr2MsaaDesc} The description.
    */
   GetMsaaDesc() {
     return this._msaa;
   }
 
-  /**
-   * The GPU usage this texture was created with.
-   *
-   * @returns {number} A `Tr2GpuUsage` bit set.
+  /**
+   * The GPU usage this texture was created with.
+   *
+   * @returns {number} A `Tr2GpuUsage` bit set.
    */
   GetGpuUsage() {
     return this._gpuUsage;
   }
 
-  /**
-   * The CPU usage this texture was created with.
-   *
-   * @returns {number} A `Tr2CpuUsage` bit set.
+  /**
+   * The CPU usage this texture was created with.
+   *
+   * @returns {number} A `Tr2CpuUsage` bit set.
    */
   GetCpuUsage() {
     return this._cpuUsage;
   }
 
-  /**
-   * Width of mip zero.
-   *
-   * @returns {number} Width in pixels.
+  /**
+   * Width of mip zero.
+   *
+   * @returns {number} Width in pixels.
    */
   GetWidth() {
     return this._desc.GetWidth();
   }
 
-  /**
-   * Height of mip zero.
-   *
-   * @returns {number} Height in pixels.
+  /**
+   * Height of mip zero.
+   *
+   * @returns {number} Height in pixels.
    */
   GetHeight() {
     return this._desc.GetHeight();
   }
 
-  /**
-   * Volume depth.
-   *
-   * @returns {number} Depth in slices.
+  /**
+   * Volume depth.
+   *
+   * @returns {number} Depth in slices.
    */
   GetDepth() {
     return this._desc.GetDepth();
   }
 
-  /**
-   * The declared mip count.
-   *
-   * @returns {number} Mip levels as declared.
+  /**
+   * The declared mip count.
+   *
+   * @returns {number} Mip levels as declared.
    */
   GetMipCount() {
     return this._desc.GetMipCount();
   }
 
-  /**
-   * The mip count in effect.
-   *
-   * @returns {number} Mip levels.
+  /**
+   * The mip count in effect.
+   *
+   * @returns {number} Mip levels.
    */
   GetTrueMipCount() {
     return this._desc.GetTrueMipCount();
   }
 
-  /**
-   * The pixel format.
-   *
-   * @returns {number} A `PixelFormat` value.
+  /**
+   * The pixel format.
+   *
+   * @returns {number} A `PixelFormat` value.
    */
   GetFormat() {
     return this._desc.GetFormat();
   }
 
-  /**
-   * The texture type.
-   *
-   * @returns {number} A `TextureType` value.
+  /**
+   * The texture type.
+   *
+   * @returns {number} A `TextureType` value.
    */
   GetType() {
     return this._desc.GetType();
   }
 
-  /**
-   * Slices in the array.
-   *
-   * @returns {number} Array size.
+  /**
+   * Slices in the array.
+   *
+   * @returns {number} Array size.
    */
   GetArraySize() {
     return this._desc.GetArraySize();
   }
 
-  /**
-   * Bytes in one mip.
-   *
-   * @param {number} mip Mip level.
-   * @returns {number} Size in bytes.
+  /**
+   * Bytes in one mip.
+   *
+   * @param {number} mip Mip level.
+   * @returns {number} Size in bytes.
    */
   GetMipSize(mip) {
     return this._desc.GetMipSize(mip);
   }
 
-  /**
-   * Allocates and returns the storage for one subresource, for reading.
-   *
-   * The CPU-read check comes FIRST, before validity, because a texture that
-   * was never created for reading is a caller mistake rather than a state
-   * problem - which is why it answers `E_INVALIDCALL` and not `E_FAIL`.
-   *
-   * @param {Tr2TextureSubresource} region The subresource to map.
-   * @param {boolean} synchronize Whether to wait for outstanding GPU work.
-   * @param {object} renderContext The context to map against.
-   * @returns {{result: number, data: Uint8Array|null, pitch: number}} The mapping.
+  /**
+   * Allocates and returns the storage for one subresource, for reading.
+   *
+   * The CPU-read check comes FIRST, before validity, because a texture that
+   * was never created for reading is a caller mistake rather than a state
+   * problem - which is why it answers `E_INVALIDCALL` and not `E_FAIL`.
+   *
+   * @param {Tr2TextureSubresource} region The subresource to map.
+   * @param {boolean} synchronize Whether to wait for outstanding GPU work.
+   * @param {object} renderContext The context to map against.
+   * @returns {{result: number, data: Uint8Array|null, pitch: number}} The mapping.
    */
   MapForReading(region, synchronize, renderContext) {
     if (!HasFlag(this._cpuUsage, Tr2CpuUsage.READ)) return {
@@ -344,12 +347,12 @@ class Tr2TextureALStub extends Tr2BaseDeviceResourceAL {
     this._ReleaseUnlessKept();
   }
 
-  /**
-   * Allocates and returns the storage for one subresource, for writing.
-   *
-   * @param {Tr2TextureSubresource} region The subresource to map.
-   * @param {object} renderContext The context to map against.
-   * @returns {{result: number, data: Uint8Array|null, pitch: number}} The mapping.
+  /**
+   * Allocates and returns the storage for one subresource, for writing.
+   *
+   * @param {Tr2TextureSubresource} region The subresource to map.
+   * @param {object} renderContext The context to map against.
+   * @returns {{result: number, data: Uint8Array|null, pitch: number}} The mapping.
    */
   MapForWriting(region, renderContext) {
     if (!HasFlag(this._cpuUsage, Tr2CpuUsage.WRITE)) return {
@@ -417,18 +420,18 @@ class Tr2TextureALStub extends Tr2BaseDeviceResourceAL {
     }
   }
 
-  /**
-   * Writes pixels into one subresource.
-   *
-   * A texture mapped often is written through a map, not through this, so
-   * Carbon refuses `WRITE_OFTEN` here outright.
-   *
-   * @param {Tr2TextureSubresource} region The subresource to write.
-   * @param {ArrayBufferView} source The pixels.
-   * @param {number} pitch Bytes per row in the source.
-   * @param {number} slicePitch Bytes per slice in the source.
-   * @param {object} renderContext The context to write against.
-   * @returns {number} An `ALResult` value.
+  /**
+   * Writes pixels into one subresource.
+   *
+   * A texture mapped often is written through a map, not through this, so
+   * Carbon refuses `WRITE_OFTEN` here outright.
+   *
+   * @param {Tr2TextureSubresource} region The subresource to write.
+   * @param {ArrayBufferView} source The pixels.
+   * @param {number} pitch Bytes per row in the source.
+   * @param {number} slicePitch Bytes per slice in the source.
+   * @param {object} renderContext The context to write against.
+   * @returns {number} An `ALResult` value.
    */
   UpdateSubresource(region, source, pitch, slicePitch, renderContext) {
     if (HasFlag(this._cpuUsage, Tr2CpuUsage.WRITE_OFTEN)) return ALResult.E_INVALIDCALL;
@@ -439,17 +442,17 @@ class Tr2TextureALStub extends Tr2BaseDeviceResourceAL {
     return ALResult.S_OK;
   }
 
-  /**
-   * Copies a region from another texture.
-   *
-   * A whole-to-whole copy short-circuits; anything else must survive `Crop`,
-   * which is where a mismatched face count or an empty overlap is caught.
-   *
-   * @param {Tr2TextureSubresource} destSubresource The region to write.
-   * @param {Tr2TextureALStub} source The texture to read.
-   * @param {Tr2TextureSubresource} sourceSubresource The region to read.
-   * @param {object} renderContext The context to copy against.
-   * @returns {number} An `ALResult` value.
+  /**
+   * Copies a region from another texture.
+   *
+   * A whole-to-whole copy short-circuits; anything else must survive `Crop`,
+   * which is where a mismatched face count or an empty overlap is caught.
+   *
+   * @param {Tr2TextureSubresource} destSubresource The region to write.
+   * @param {Tr2TextureALStub} source The texture to read.
+   * @param {Tr2TextureSubresource} sourceSubresource The region to read.
+   * @param {object} renderContext The context to copy against.
+   * @returns {number} An `ALResult` value.
    */
   CopySubresourceRegion(destSubresource, source, sourceSubresource, renderContext) {
     if (!this.IsValid() || !renderContext.IsValid()) return ALResult.E_INVALIDCALL;
@@ -467,13 +470,13 @@ class Tr2TextureALStub extends Tr2BaseDeviceResourceAL {
     return ALResult.S_OK;
   }
 
-  /**
-   * Regenerates the mip chain.
-   *
-   * Only a texture that is both a render target and a shader resource can be
-   * generated into, because that is how the hardware does it.
-   *
-   * @returns {number} An `ALResult` value.
+  /**
+   * Regenerates the mip chain.
+   *
+   * Only a texture that is both a render target and a shader resource can be
+   * generated into, because that is how the hardware does it.
+   *
+   * @returns {number} An `ALResult` value.
    */
   GenerateMipMaps() {
     if (!HasFlag(this._gpuUsage, Tr2GpuUsage.RENDER_TARGET) || !HasFlag(this._gpuUsage, Tr2GpuUsage.SHADER_RESOURCE)) {
@@ -482,15 +485,15 @@ class Tr2TextureALStub extends Tr2BaseDeviceResourceAL {
     return ALResult.S_OK;
   }
 
-  /**
-   * Resolves a multisampled texture into a single-sampled one.
-   *
-   * With one sample there is nothing to resolve, so Carbon falls back to a
-   * plain copy - and inherits that copy's validation with it.
-   *
-   * @param {Tr2TextureALStub} destination The texture to resolve into.
-   * @param {object} renderContext The context to resolve against.
-   * @returns {number} An `ALResult` value.
+  /**
+   * Resolves a multisampled texture into a single-sampled one.
+   *
+   * With one sample there is nothing to resolve, so Carbon falls back to a
+   * plain copy - and inherits that copy's validation with it.
+   *
+   * @param {Tr2TextureALStub} destination The texture to resolve into.
+   * @param {object} renderContext The context to resolve against.
+   * @returns {number} An `ALResult` value.
    */
   Resolve(destination, renderContext) {
     if (this._msaa.samples <= 1) {
@@ -509,58 +512,58 @@ class Tr2TextureALStub extends Tr2BaseDeviceResourceAL {
     return ALResult.S_OK;
   }
 
-  /**
-   * The handle another device could open this texture by.
-   *
-   * @returns {number} Always zero; the stub shares nothing.
+  /**
+   * The handle another device could open this texture by.
+   *
+   * @returns {number} Always zero; the stub shares nothing.
    */
   GetSharedHandle() {
     return 0;
   }
 
-  /**
-   * Where the shader-resource view sits in the descriptor heap.
-   *
-   * @returns {number} Carbon's "no index".
+  /**
+   * Where the shader-resource view sits in the descriptor heap.
+   *
+   * @returns {number} Carbon's "no index".
    */
   GetSrvIndexInHeap() {
     return NO_HEAP_INDEX;
   }
 
-  /**
-   * Where the unordered-access view sits in the descriptor heap.
-   *
-   * @returns {number} Carbon's "no index".
+  /**
+   * Where the unordered-access view sits in the descriptor heap.
+   *
+   * @returns {number} Carbon's "no index".
    */
   GetUavIndexInHeap() {
     return NO_HEAP_INDEX;
   }
 
-  /**
-   * Names the texture for a debugger.
-   *
-   * @param {string} _name The name Carbon would attach; the stub discards it.
-   * @returns {number} An `ALResult` value; the stub keeps no name.
+  /**
+   * Names the texture for a debugger.
+   *
+   * @param {string} _name The name Carbon would attach; the stub discards it.
+   * @returns {number} An `ALResult` value; the stub keeps no name.
    */
   SetName(_name) {
     return ALResult.S_OK;
   }
 
-  /**
-   * The debug name.
-   *
-   * @returns {null} Always null, as Carbon's stub returns.
+  /**
+   * The debug name.
+   *
+   * @returns {null} Always null, as Carbon's stub returns.
    */
   GetName() {
     return null;
   }
 }
 
-/**
- * Copies a subresource region, so a call that crops does not alter its caller.
- *
- * @param {Tr2TextureSubresource} region The region to copy.
- * @returns {Tr2TextureSubresource} An independent copy.
+/**
+ * Copies a subresource region, so a call that crops does not alter its caller.
+ *
+ * @param {Tr2TextureSubresource} region The region to copy.
+ * @returns {Tr2TextureSubresource} An independent copy.
  */
 function CopyRegion(region) {
   const copy = new Tr2TextureSubresource();
@@ -577,5 +580,19 @@ function CopyRegion(region) {
   return copy;
 }
 
+// DECLARED AS A CALL, NOT A DECORATOR, for the reason recorded in
+// Tr2BitmapDimensions.js: the layer is imported straight from source by its
+// tests and raw Node cannot parse decorator syntax.
+//
+// The donor is NAMED rather than left to be derived from this class's name.
+// Carbon calls every backend's class the same thing and carries the backend in
+// the FILE name, because only one backend compiles at a time; we ship them
+// together, so the backend moves onto the class name. That divergence is the
+// author's to declare, never a checker's to guess.
+CjsSchema.define(Tr2TextureALStub, {
+  className: "Tr2TextureALStub",
+  carbon: "Tr2TextureAL"
+});
+
 export { CopyRegion, Tr2TextureALStub };
 //# sourceMappingURL=Tr2TextureALStub.js.map