objc2_core_ml/generated/

MLMultiArray.rs

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ffi::*;
use core::ptr::NonNull;
use objc2::__framework_prelude::*;
#[cfg(feature = "objc2-core-video")]
use objc2_core_video::*;
use objc2_foundation::*;

use crate::*;

/// The data type of scalars in the multi-array.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/coreml/mlmultiarraydatatype?language=objc)
// NS_ENUM
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct MLMultiArrayDataType(pub NSInteger);
impl MLMultiArrayDataType {
    #[doc(alias = "MLMultiArrayDataTypeDouble")]
    pub const Double: Self = Self(0x10000 | 64);
    #[doc(alias = "MLMultiArrayDataTypeFloat64")]
    pub const Float64: Self = Self(0x10000 | 64);
    #[doc(alias = "MLMultiArrayDataTypeFloat32")]
    pub const Float32: Self = Self(0x10000 | 32);
    #[doc(alias = "MLMultiArrayDataTypeFloat16")]
    pub const Float16: Self = Self(0x10000 | 16);
    #[doc(alias = "MLMultiArrayDataTypeFloat")]
    pub const Float: Self = Self(0x10000 | 32);
    #[doc(alias = "MLMultiArrayDataTypeInt32")]
    pub const Int32: Self = Self(0x20000 | 32);
    #[doc(alias = "MLMultiArrayDataTypeInt8")]
    pub const Int8: Self = Self(0x20000 | 8);
}

unsafe impl Encode for MLMultiArrayDataType {
    const ENCODING: Encoding = NSInteger::ENCODING;
}

unsafe impl RefEncode for MLMultiArrayDataType {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

extern_class!(
    /// Use `MLMultiArray` to store a multi-dimensional value.
    ///
    /// Unlike `MLShapedArray` or `MLTensor`, `MLMultiArray` can be used in Obj-C code. Unlike `MLTensor`, `MLMultiArray` is
    /// always backed by a concrete storage.
    ///
    /// The object has properties to define the interpretation of the storage.
    ///
    /// `.dataType` defines the interpretation of raw bytes into a numeric scalar value. For example,
    /// `MLMultiArrayDataTypeFloat32` means the backing storage uses IEEE 754 Float32 encoding.
    ///
    /// `.shape` defines the multi-dimensional space. For example, 30 x 20 image with three color components (Red, Green,
    /// Blue) could be defined using the shape `[3, 20, 30]`.
    ///
    /// `.strides` defines the offset addressing of the scalar for a given coordinates. For example, the image above might
    /// use `[640, 32, 1]` as the `strides`. Then, the scalar at (1, 10, 15) is stored at `640 * 1 + 32 * 10 + 1 * 15`, or
    /// 975th scalar in the storage. In general, the scalar offset for coordinates `index` and strides `strides` is:
    ///
    /// ```text
    /// scalarOffset = sum_d index[d]*strides[d]
    /// ```
    ///
    /// The backing storage can be a heap allocated buffer or CVPixelBuffer. Though CVPixelBuffer backing supports limited
    /// data types, `MLModel` could share the storage with backend hardware such as Apple Neural Engine without copy.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/coreml/mlmultiarray?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct MLMultiArray;
);

extern_conformance!(
    unsafe impl NSCoding for MLMultiArray {}
);

extern_conformance!(
    unsafe impl NSObjectProtocol for MLMultiArray {}
);

extern_conformance!(
    unsafe impl NSSecureCoding for MLMultiArray {}
);

impl MLMultiArray {
    extern_methods!(
        /// Unsafe pointer to underlying buffer holding the data
        #[deprecated = "Use getBytesWithHandler or getMutableBytesWithHandler instead. For Swift, use withUnsafeBytes or withUnsafeMutableBytes."]
        #[unsafe(method(dataPointer))]
        #[unsafe(method_family = none)]
        pub unsafe fn dataPointer(&self) -> NonNull<c_void>;

        /// Scalar's data type.
        #[unsafe(method(dataType))]
        #[unsafe(method_family = none)]
        pub unsafe fn dataType(&self) -> MLMultiArrayDataType;

        /// Shape of the multi-dimensional space that this instance represents.
        #[unsafe(method(shape))]
        #[unsafe(method_family = none)]
        pub unsafe fn shape(&self) -> Retained<NSArray<NSNumber>>;

        /// Strides.
        ///
        /// It defines the offset of the scalar of a given coordinate index in the storage, which is:
        /// ```text
        /// scalarOffset = sum_d index[d]*strides[d]
        /// ```
        #[unsafe(method(strides))]
        #[unsafe(method_family = none)]
        pub unsafe fn strides(&self) -> Retained<NSArray<NSNumber>>;

        /// Count of total number of addressable scalars.
        ///
        /// The value is same as `product_d shape[d]`.
        #[unsafe(method(count))]
        #[unsafe(method_family = none)]
        pub unsafe fn count(&self) -> NSInteger;

        #[cfg(feature = "objc2-core-video")]
        /// Returns the backing pixel buffer if exists, otherwise nil.
        #[unsafe(method(pixelBuffer))]
        #[unsafe(method_family = none)]
        pub unsafe fn pixelBuffer(&self) -> Option<Retained<CVPixelBuffer>>;
    );
}

/// Methods declared on superclass `NSObject`.
impl MLMultiArray {
    extern_methods!(
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}

/// Creation.
impl MLMultiArray {
    extern_methods!(
        /// Creates the object.
        ///
        /// The contents of the object are left uninitialized; the client must initialize it.
        ///
        /// The scalars will use the first-major contiguous layout.
        ///
        /// - Parameters:
        /// - shape: The shape
        /// - dataType: The data type
        /// - error: Filled with error information on error.
        #[unsafe(method(initWithShape:dataType:error:_))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithShape_dataType_error(
            this: Allocated<Self>,
            shape: &NSArray<NSNumber>,
            data_type: MLMultiArrayDataType,
        ) -> Result<Retained<Self>, Retained<NSError>>;

        /// Creates the object with specified strides.
        ///
        /// The contents of the object are left uninitialized; the client must initialize it.
        ///
        /// ```swift
        /// let shape = [2, 3];
        /// let strides = [4, 1]
        ///
        /// let multiArray = MLMultiArray(shape: shape, dataType: .float32, strides: strides)
        /// XCTAssertEqual(multiArray.shape, shape as [NSNumber])
        /// XCTAssertEqual(multiArray.strides, strides as [NSNumber])
        /// ```
        ///
        /// ```objc
        /// NSArray
        /// <NSNumber
        /// *> *shape =
        /// @
        /// [
        /// @
        /// 2,
        /// @
        /// 3];
        /// NSArray
        /// <NSNumber
        /// *> *strides =
        /// @
        /// [
        /// @
        /// 4,
        /// @
        /// 1];
        ///
        /// MLMultiArray *multiArray = [[MLMultiArray alloc] initWithShape:shape
        /// dataType:MLMultiArrayDataTypeFloat32
        /// strides:strides];
        /// XCTAssertEqualObjects(multiArray.shape, shape);
        /// XCTAssertEqualObjects(multiArray.strides, strides);
        /// ```
        ///
        /// - Parameters:
        /// - shape: The shape
        /// - dataType: The data type
        /// - strides: The strides.
        #[unsafe(method(initWithShape:dataType:strides:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithShape_dataType_strides(
            this: Allocated<Self>,
            shape: &NSArray<NSNumber>,
            data_type: MLMultiArrayDataType,
            strides: &NSArray<NSNumber>,
        ) -> Retained<Self>;

        #[cfg(feature = "block2")]
        /// Creates the object with existing data without copy.
        ///
        /// Use this initializer to reference the existing buffer as the storage without copy.
        ///
        /// ```objc
        /// int32_t *buffer = malloc(sizeof(int32_t) * 2 * 3 * 4);
        /// MLMultiArray *multiArray = [[MLMultiArray alloc] initWithDataPointer:buffer
        /// shape:
        /// @
        /// [
        /// @
        /// 2,
        /// @
        /// 3,
        /// @
        /// 4]
        /// dataType:MLMultiArrayDataTypeInt32
        /// strides:
        /// @
        /// [
        /// @
        /// 12,
        /// @
        /// 4,
        /// @
        /// 1]
        /// deallocator:^(void *bytes) { free(bytes); }
        /// error:NULL];
        /// ```
        ///
        /// - Parameters:
        /// - dataPointer: The pointer to the buffer.
        /// - shape: The shape
        /// - dataType: The data type
        /// - strides: The strides.
        /// - deallocator: Block to be called on the deallocation of the instance.
        /// - error: Filled with error information on error.
        ///
        /// # Safety
        ///
        /// `data_pointer` must be a valid pointer.
        #[unsafe(method(initWithDataPointer:shape:dataType:strides:deallocator:error:_))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithDataPointer_shape_dataType_strides_deallocator_error(
            this: Allocated<Self>,
            data_pointer: NonNull<c_void>,
            shape: &NSArray<NSNumber>,
            data_type: MLMultiArrayDataType,
            strides: &NSArray<NSNumber>,
            deallocator: Option<&block2::DynBlock<dyn Fn(NonNull<c_void>)>>,
        ) -> Result<Retained<Self>, Retained<NSError>>;

        #[cfg(feature = "objc2-core-video")]
        /// Create by wrapping a pixel buffer.
        ///
        /// Use this initializer to create an IOSurface backed MLMultiArray, which can reduce the inference latency by avoiding the buffer copy.
        ///
        /// The instance will own the pixel buffer and release it on the deallocation.
        ///
        /// The pixel buffer's pixel format type must be either `kCVPixelFormatType_OneComponent16Half` for `MLMultiArrayDataTypeFloat16` or
        /// `kCVPixelFormatType_OneComponent8` for `MLMultiArrayDataTypeInt8`.
        ///
        /// ```objc
        /// CVPixelBufferRef pixelBuffer = NULL;
        /// NSDictionary* pixelBufferAttributes =
        /// @
        /// {
        /// (id)kCVPixelBufferIOSurfacePropertiesKey:
        /// @
        /// {}
        /// };
        ///
        /// // Since shape == [2, 3, 4], width is 4 (= shape[2]) and height is 6 (= shape[0] * shape[1]).
        /// CVPixelBufferCreate(kCFAllocatorDefault, 4, 6, kCVPixelFormatType_OneComponent16Half, (__bridge CFDictionaryRef)pixelBufferAttributes,
        /// &pixelBuffer
        /// );
        /// MLMultiArray *multiArray = [[MLMultiArray alloc] initWithPixelBuffer:pixelBuffer shape:
        /// @
        /// [
        /// @
        /// 2,
        /// @
        /// 3,
        /// @
        /// 4]];
        /// ```
        ///
        /// - Parameters:
        /// - pixelBuffer: The pixel buffer to be owned by the instance.
        /// - shape: The shape of the MLMultiArray. The last dimension of `shape` must match the pixel buffer's width. The product of the rest of the dimensions must match the height.
        #[unsafe(method(initWithPixelBuffer:shape:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithPixelBuffer_shape(
            this: Allocated<Self>,
            pixel_buffer: &CVPixelBuffer,
            shape: &NSArray<NSNumber>,
        ) -> Retained<Self>;
    );
}

/// ScopedBufferAccess.
impl MLMultiArray {
    extern_methods!(
        #[cfg(feature = "block2")]
        /// Get the underlying buffer pointer to read.
        ///
        /// The buffer pointer is valid only within the block.
        ///
        /// ```objc
        /// MLMultiArray * A = [[MLMultiArray alloc] initWithShape:
        /// @
        /// [
        /// @
        /// 3,
        /// @
        /// 2] dataType:MLMultiArrayDataTypeInt32 error:NULL];
        /// A[
        /// @
        /// [
        /// @
        /// 1,
        /// @
        /// 2]] =
        /// @
        /// 42;
        /// [A getBytesWithHandler:^(const void *bytes, NSInteger size) {
        /// const int32_t *scalarBuffer = (const int32_t *)bytes;
        /// const int strideY = A.strides[0].intValue;
        /// // Print 42
        /// NSLog(
        /// "
        /// Scalar at (1, 2): %d", scalarBuffer[1 * strideY + 2]);
        /// }];
        /// ```
        /// - Parameters:
        /// - handler: The block to receive the buffer pointer and its size in bytes.
        #[unsafe(method(getBytesWithHandler:))]
        #[unsafe(method_family = none)]
        pub unsafe fn getBytesWithHandler(
            &self,
            handler: &block2::DynBlock<dyn Fn(NonNull<c_void>, NSInteger) + '_>,
        );

        #[cfg(feature = "block2")]
        /// Get the underlying buffer pointer to mutate.
        ///
        /// The buffer pointer is valid only within the block.
        ///
        /// Use `strides` parameter passed in the block because the method may switch to a new backing buffer with different strides.
        ///
        /// ```objc
        /// MLMultiArray * A = [[MLMultiArray alloc] initWithShape:
        /// @
        /// [
        /// @
        /// 3,
        /// @
        /// 2] dataType:MLMultiArrayDataTypeInt32 error:NULL];
        /// [A getMutableBytesWithHandler:^(void *bytes, NSInteger __unused size, NSArray
        /// <NSNumber
        /// *> *strides) {
        /// int32_t *scalarBuffer = (int32_t *)bytes;
        /// const int strideY = strides[0].intValue;
        /// scalarBuffer[1 * strideY + 2] = 42;  // Set 42 at A[1, 2]
        /// }];
        /// ```
        ///
        /// - Parameters:
        /// - handler: The block to receive the buffer pointer, size in bytes, and strides.
        #[unsafe(method(getMutableBytesWithHandler:))]
        #[unsafe(method_family = none)]
        pub unsafe fn getMutableBytesWithHandler(
            &self,
            handler: &block2::DynBlock<
                dyn Fn(NonNull<c_void>, NSInteger, NonNull<NSArray<NSNumber>>) + '_,
            >,
        );
    );
}

/// Concatenating.
impl MLMultiArray {
    extern_methods!(
        /// Concatenate MLMultiArrays to form a new MLMultiArray.
        ///
        /// All the source MLMultiArrays must have a same shape except the specified axis. The resultant
        /// MLMultiArray has the same shape as inputs except this axis, which dimension will be the sum of
        /// all the input dimensions of the axis.
        ///
        /// For example,
        ///
        /// ```swift
        /// // Swift
        /// let A = try MLMultiArray(shape: [2, 3], dataType: .int32)
        /// let B = try MLMultiArray(shape: [2, 2], dataType: .int32)
        /// let C = MLMultiArray(concatenating: [A, B], axis: 1, dataType: .int32)
        /// assert(C.shape == [2, 5])
        /// ```
        ///
        /// ```objc
        /// // Obj-C
        /// MLMultiArray *A = [[MLMultiArray alloc] initWithShape:
        /// @
        /// [
        /// @
        /// 2,
        /// @
        /// 3] dataType:MLMultiArrayDataTypeInt32 error:NULL];
        /// MLMultiArray *B = [[MLMultiArray alloc] initWithShape:
        /// @
        /// [
        /// @
        /// 2,
        /// @
        /// 2] dataType:MLMultiArrayDataTypeInt32 error:NULL];
        /// MLMultiArray *C = [MLMultiArray multiArrayByConcatenatingMultiArrays:
        /// @
        /// [A, B] alongAxis:1 dataType:MLMultiArrayDataTypeInt32];
        /// assert(C.shape ==
        /// @
        /// [
        /// @
        /// 2,
        /// @
        /// 5])
        /// ```
        ///
        /// Numeric data will be up or down casted as needed.
        ///
        /// The method raises NSInvalidArgumentException if the shapes of input multi arrays are not
        /// compatible for concatenation.
        ///
        /// - Parameters:
        /// - multiArrays: Array of MLMultiArray instances to be concatenated.
        /// - axis: Axis index with which the concatenation will performed. The value is wrapped by the dimension of the axis. For example, -1 is the last axis.
        /// - dataType: The data type of the resultant MLMultiArray.
        #[unsafe(method(multiArrayByConcatenatingMultiArrays:alongAxis:dataType:))]
        #[unsafe(method_family = none)]
        pub unsafe fn multiArrayByConcatenatingMultiArrays_alongAxis_dataType(
            multi_arrays: &NSArray<MLMultiArray>,
            axis: NSInteger,
            data_type: MLMultiArrayDataType,
        ) -> Retained<Self>;
    );
}

/// NSNumberDataAccess.
impl MLMultiArray {
    extern_methods!(
        /// Get a value by its linear index (assumes C-style index ordering)
        #[unsafe(method(objectAtIndexedSubscript:))]
        #[unsafe(method_family = none)]
        pub unsafe fn objectAtIndexedSubscript(&self, idx: NSInteger) -> Retained<NSNumber>;

        /// Get a value by its multidimensional index (NSArray
        /// <NSNumber
        /// *>)
        #[unsafe(method(objectForKeyedSubscript:))]
        #[unsafe(method_family = none)]
        pub unsafe fn objectForKeyedSubscript(&self, key: &NSArray<NSNumber>)
            -> Retained<NSNumber>;

        /// Set a value by its linear index (assumes C-style index ordering)
        #[unsafe(method(setObject:atIndexedSubscript:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setObject_atIndexedSubscript(&self, obj: &NSNumber, idx: NSInteger);

        /// Set a value by subindicies (NSArray
        /// <NSNumber
        /// *>)
        #[unsafe(method(setObject:forKeyedSubscript:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setObject_forKeyedSubscript(&self, obj: &NSNumber, key: &NSArray<NSNumber>);
    );
}

/// Transferring.
impl MLMultiArray {
    extern_methods!(
        /// Transfer the contents to the destination multi-array.
        ///
        /// Numeric data will be up or down casted as needed. It can transfer to a multi-array with different layout (strides).
        ///
        /// ```swift
        /// let sourceMultiArray: MLMultiArray = ... // shape is [2, 3] and data type is Float64
        ///
        /// let newStrides = [4, 1]
        /// let destinationMultiArray = MLMultiArray(shape: [2, 3],
        /// dataType: .float32,
        /// strides: newStrides)
        /// sourceMultiArray.transfer(to: destinationMultiArray)
        /// ```
        ///
        /// ```objc
        /// NSArray
        /// <NSNumber
        /// *> *shape =
        /// @
        /// [
        /// @
        /// 2,
        /// @
        /// 3];
        /// NSArray
        /// <NSNumber
        /// *> *sourceStrides =
        /// @
        /// [
        /// @
        /// 3,
        /// @
        /// 1];
        /// NSArray
        /// <NSNumber
        /// *> *destinationStrides =
        /// @
        /// [
        /// @
        /// 4,
        /// @
        /// 1];
        /// MLMultiArray *source = [[MLMultiArray alloc] initWithShape:shape
        /// dataType:MLMultiArrayDataTypeDouble
        /// strides:sourceStrides];
        /// // Initialize source...
        ///
        /// MLMultiArray *destination = [[MLMultiArray alloc] initWithShape:shape
        /// dataType:MLMultiArrayDataTypeFloat32
        /// strides:destinationStrides];
        /// [source transferToMultiArray:destination];
        /// ```
        ///
        /// - Parameters:
        /// - destinationMultiArray: The transfer destination.
        #[unsafe(method(transferToMultiArray:))]
        #[unsafe(method_family = none)]
        pub unsafe fn transferToMultiArray(&self, destination_multi_array: &MLMultiArray);
    );
}