scichart/utils/vectorToArray.js

Fast WebGL JavaScript Charting Library and Framework

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.vectorToArrayViewI32 = exports.vectorToArrayViewUi32 = exports.vectorToArrayViewF32 = exports.vectorToArrayViewF64 = exports.vectorToArray = void 0;
/**
 * Converts a WebAssembly vector to a JavaScript number array by creating a copy of the data.
 *
 * @remarks
 * This function creates a new JavaScript array containing a copy of all values from the WebAssembly vector.
 * The returned array is independent of the underlying WebAssembly memory, so it's safe to use even after
 * the original vector is deleted or modified.
 *
 * Use this function when you need to:
 * - Store vector data beyond the lifetime of the WebAssembly vector
 * - Pass data to JavaScript APIs that expect regular arrays
 * - Ensure data immutability
 *
 * @param vector - The WebAssembly vector to convert (SCRTDoubleVector2D, SCRTDoubleVector3D, FloatVector2D, UIntVector2D, or IntVector2D)
 * @param wasmContext - The WebAssembly context (TSciChart or TSciChart3D) that owns the vector
 * @returns A new number[] array containing a copy of all values from the vector
 */
function vectorToArray(vector, wasmContext) {
    // Use appropriate vectorToArrayViewXXX function to get typed array, then convert to regular array
    var typedArrayView;
    if (wasmContext.UIntVector && vector instanceof wasmContext.UIntVector) {
        typedArrayView = vectorToArrayViewUi32(vector, wasmContext);
    }
    else if (wasmContext.SCRTUintVector && vector instanceof wasmContext.SCRTUintVector) {
        typedArrayView = vectorToArrayViewUi32(vector, wasmContext);
    }
    else if (wasmContext.IntVector && vector instanceof wasmContext.IntVector) {
        typedArrayView = vectorToArrayViewI32(vector, wasmContext);
    }
    else if (wasmContext.FloatVector && vector instanceof wasmContext.FloatVector) {
        typedArrayView = vectorToArrayViewF32(vector, wasmContext);
    }
    else if (wasmContext.SCRTFloatVector && vector instanceof wasmContext.SCRTFloatVector) {
        typedArrayView = vectorToArrayViewF32(vector, wasmContext);
    }
    else {
        typedArrayView = vectorToArrayViewF64(vector, wasmContext);
    }
    return Array.from(typedArrayView);
}
exports.vectorToArray = vectorToArray;
/**
 * Creates a Float64Array view directly onto the WebAssembly memory backing the vector.
 *
 * @remarks
 * **IMPORTANT**: This function returns a view onto the underlying WebAssembly memory, NOT a copy.
 *
 * The returned Float64Array:
 * - Shares memory with the WebAssembly vector - changes to the underlying data will be reflected in the view
 * - Should be used for READ operations only - writing to this view may cause undefined behaviour
 * - Becomes invalid if the vector is deleted or resized
 * - Has zero-copy performance characteristics, making it very efficient for reading large datasets
 *
 * Use this function when you need:
 * - High-performance read access to vector data
 * - To avoid memory allocation overhead
 * - Temporary access to data that won't outlive the vector
 *
 * If used with a FIFO vector (ie from a dataSeries with fifoCapacity set) you will get the raw buffer
 * and will need to use (index + fifoStartIndex) % fifoCapacity to access the data in the original order
 *
 * If you need to modify data or keep it beyond the vector's lifetime, use {@link vectorToArray} instead.
 *
 * @param vector - The WebAssembly vector to create a view for (SCRTDoubleVector2D or SCRTDoubleVector3D)
 * @param wasmContext - The WebAssembly context (TSciChart or TSciChart3D) that owns the vector
 * @returns A Float64Array view onto the WebAssembly memory - DO NOT write to this array
 */
function vectorToArrayViewF64(vector, wasmContext) {
    if (!vector)
        return undefined;
    // Access the memory pointer for the vector in webassembly.
    // For FIFO vectors dataPtrZero points to the actual start of the memory,
    // while dataPtr points to the logical start, ie 0 plus the StartIndex
    // @ts-ignore
    var ptr = vector.dataPtrZero ? vector.dataPtrZero() : vector.dataPtr(0);
    // Get the vector size
    var size = vector.size();
    // SCRTDoubleVector2D and SCRTDoubleVector3D both use 64-bit doubles
    // @ts-ignore
    return new Float64Array(wasmContext.HEAPF64.buffer, ptr, size);
}
exports.vectorToArrayViewF64 = vectorToArrayViewF64;
/**
 * Creates a Float32Array view directly onto the WebAssembly memory backing the vector.
 *
 * @remarks
 * **IMPORTANT**: This function returns a view onto the underlying WebAssembly memory, NOT a copy.
 *
 * The returned Float32Array:
 * - Shares memory with the WebAssembly vector - changes to the underlying data will be reflected in the view
 * - Should be used for READ operations only - writing to this view may cause undefined behaviour
 * - Becomes invalid if the vector is deleted or resized
 * - Has zero-copy performance characteristics, making it very efficient for reading large datasets
 *
 * Use this function when you need:
 * - High-performance read access to vector data
 * - To avoid memory allocation overhead
 * - Temporary access to data that won't outlive the vector
 *
 * If you need to modify data or keep it beyond the vector's lifetime, use {@link vectorToArray} instead.
 *
 * @param vector - The WebAssembly vector to create a view for (FloatVector2D)
 * @param wasmContext - The WebAssembly context (TSciChart) that owns the vector
 * @returns A Float32Array view onto the WebAssembly memory - DO NOT write to this array
 */
function vectorToArrayViewF32(vector, wasmContext) {
    // Access the memory pointer for the vector in webassembly
    var ptr = vector.dataPtr(0);
    // Get the vector size
    var size = vector.size();
    // FloatVector2D stores 32-bit floats
    // @ts-ignore
    return new Float32Array(wasmContext.HEAPF32.buffer, ptr, size);
}
exports.vectorToArrayViewF32 = vectorToArrayViewF32;
/**
 * Creates a Uint32Array view directly onto the WebAssembly memory backing the vector.
 *
 * @remarks
 * **IMPORTANT**: This function returns a view onto the underlying WebAssembly memory, NOT a copy.
 *
 * The returned Uint32Array:
 * - Shares memory with the WebAssembly vector - changes to the underlying data will be reflected in the view
 * - Should be used for READ operations only - writing to this view may cause undefined behaviour
 * - Becomes invalid if the vector is deleted or resized
 * - Has zero-copy performance characteristics, making it very efficient for reading large datasets
 *
 * Use this function when you need:
 * - High-performance read access to vector data
 * - To avoid memory allocation overhead
 * - Temporary access to data that won't outlive the vector
 *
 * If you need to modify data or keep it beyond the vector's lifetime, use {@link vectorToArray} instead.
 *
 * @param vector - The WebAssembly vector to create a view for (UIntVector2D)
 * @param wasmContext - The WebAssembly context (TSciChart) that owns the vector
 * @returns A Uint32Array view onto the WebAssembly memory - DO NOT write to this array
 */
function vectorToArrayViewUi32(vector, wasmContext) {
    // Access the memory pointer for the vector in webassembly
    var ptr = vector.dataPtr(0);
    // Get the vector size
    var size = vector.size();
    // UIntVector2D stores 32-bit unsigned integers
    // @ts-ignore
    return new Uint32Array(wasmContext.HEAPU32.buffer, ptr, size);
}
exports.vectorToArrayViewUi32 = vectorToArrayViewUi32;
/**
 * Creates a Int32Array view directly onto the WebAssembly memory backing the vector.
 *
 * @remarks
 * **IMPORTANT**: This function returns a view onto the underlying WebAssembly memory, NOT a copy.
 *
 * The returned Int32Array:
 * - Shares memory with the WebAssembly vector - changes to the underlying data will be reflected in the view
 * - Should be used for READ operations only - writing to this view may cause undefined behaviour
 * - Becomes invalid if the vector is deleted or resized
 * - Has zero-copy performance characteristics, making it very efficient for reading large datasets
 *
 * Use this function when you need:
 * - High-performance read access to vector data
 * - To avoid memory allocation overhead
 * - Temporary access to data that won't outlive the vector
 *
 * If you need to modify data or keep it beyond the vector's lifetime, use {@link vectorToArray} instead.
 *
 * @param vector - The WebAssembly vector to create a view for (IntVector2D)
 * @param wasmContext - The WebAssembly context (TSciChart) that owns the vector
 * @returns A Int32Array view onto the WebAssembly memory - DO NOT write to this array
 */
function vectorToArrayViewI32(vector, wasmContext) {
    // Access the memory pointer for the vector in webassembly
    var ptr = vector.dataPtr(0);
    // Get the vector size
    var size = vector.size();
    // IntVector2D stores 32-bit signed integers
    // @ts-ignore
    return new Int32Array(wasmContext.HEAP32.buffer, ptr, size);
}
exports.vectorToArrayViewI32 = vectorToArrayViewI32;