Package apple.metalperformanceshaders

Class MPSNDArray

  • All Implemented Interfaces:
    NSObject
    Direct Known Subclasses:
    MPSTemporaryNDArray
    public class MPSNDArray
extends NSObject
    MPSNDArray A MPSNDArray object is a MTLBuffer based storage container for multi-dimensional data. Operations on MPSNDArrays will commonly implicitly reshape the multidimensional structure into a 2-dimensional structure by reinterpreting higher dimensions as a single dimensional array of matrix rows. For example a [a, b, c, d] NDArray passed to a matrix multiplication may be implicitly reinterpreted as a [a*b*c, d] matrix and a 2D matrix multiplication performed. In practice, the major row (the dimension in which successive elements appear adjacent to one another in memory) is the 0th dimension (represented as 'd' in the above example). It has both a dimension size indicating the number of elements and a storage size which may be slightly bigger to allow for performance improvement arising from better data alignment in memory. In principle, the rowBytes may also be used to create a 0th-dimension slice out of a larger array stored in the underlying MTLBuffer. MPS will automatically manage the storage size of the major row ("rowBytes") though you may set it in the descriptor if you have a need to do so. Generally, it should be at least a multiple of 16 bytes. Dimensions after the 0th are a densely packed array of rows of size rowBytes. Thus, the 1st dimension is an array of rows. The 2nd dimension is an array of arrays of rows with identical size, and so forth. When the reduction to 2 dimensions is done, no data is moved. MPS just reinterprets a higher order N-1 dimensions of matrix rows as a single large 1-dimensional array of rows. It is a common desire to reorder the dimensions of NDArrays or define a subregion thereof. A transpose or slice operation is performed by making a MPSNDArray view of the original. The dimensions to transpose or slice are given by the descriptor for the new view. If both a transpose and slice operation are defined, then the slice is performed first and the result of the slice is transposed. Because many MPS kernels can operate on transposed data at speed, MPS will usually defer doing a physical transpose operation until later, when it becomes clear that one is actually required. For this reason, conversions to formats that do not support deferred transposes and slices such as MPSMatrix MPSVector view or using -exportWithCommandBuffer: toBuffer:offset:rowStrides, may cause substantial new computation to be done and new memory to be allocated. These should be avoided except when necessary. As a general rule, transposes that do not involve the 0th dimension should be able to be handled by nearly everything natively. MPSNDArrayMatrixMultiplication and reductions can handle 0th dimension transposes. Other filters may insert a physical repacking operation. If you wish to force a physical repacking use MPSAliasingStrategyShallNotAlias. To avoid confusion with aliased NDArrays the parent property is provided. MPSNDArrays that alias share a common ancestor.

    • Constructor Detail

      • MPSNDArray

        protected MPSNDArray​(org.moe.natj.general.Pointer peer)

    • Method Detail

      • accessInstanceVariablesDirectly

        public static boolean accessInstanceVariablesDirectly()

      • allocWithZone

        public static java.lang.Object allocWithZone​(org.moe.natj.general.ptr.VoidPtr zone)

      • arrayViewWithCommandBufferDescriptorAliasing

        public MPSNDArray arrayViewWithCommandBufferDescriptorAliasing​(MTLCommandBuffer cmdBuf,
                                                               MPSNDArrayDescriptor descriptor,
                                                               long aliasing)
        Make a new representation of a MPSNDArray with a slice, transpose or other change in property If possible, the views will merely record the slice or transpose without performing the operation. Many MPSKernels are able to operate on subregions of a MPSNDArray or operate on transposed data, so making a new copy of the data for these operations would be wasteful. A copy may be forced by a change in dataType, rowBytes, or when using a view with a MPSKernel that does not support the deferred operation. To force an operation to occur immediately, use MPSAliasingStrategyShallNotAlias Otherwise, it is likely that the new MPSNDArray will share a MTLBuffer with the parent and alias its memory.
        Parameters:
        cmdBuf - The command buffer on which to perform physical copies if any are required
        descriptor - A MPSNDArrayDescriptor describing the shape of the new view of the data
        aliasing - A aliasing strategy to direct MPS how to respond to cases when aliasing can or can not be performed.
        Returns:
        A new MPSNDArray, if it is possible to make one. Otherwise nil is returned. The MPSNDArray is autoreleased.

      • automaticallyNotifiesObserversForKey

        public static boolean automaticallyNotifiesObserversForKey​(java.lang.String key)

      • cancelPreviousPerformRequestsWithTarget

        public static void cancelPreviousPerformRequestsWithTarget​(java.lang.Object aTarget)

      • cancelPreviousPerformRequestsWithTargetSelectorObject

        public static void cancelPreviousPerformRequestsWithTargetSelectorObject​(java.lang.Object aTarget,
                                                                         org.moe.natj.objc.SEL aSelector,
                                                                         java.lang.Object anArgument)

      • classFallbacksForKeyedArchiver

        public static NSArray<java.lang.String> classFallbacksForKeyedArchiver()

      • classForKeyedUnarchiver

        public static org.moe.natj.objc.Class classForKeyedUnarchiver()

      • dataType

        public int dataType()
        The type of data stored by each element in the array

      • dataTypeSize

        public long dataTypeSize()
        The size of one element in the MPSNDArray

      • debugDescription_static

        public static java.lang.String debugDescription_static()

      • defaultAllocator

        public static MPSNDArrayAllocator defaultAllocator()
        Get a well known that makes standard MTLBuffers

      • description_static

        public static java.lang.String description_static()

      • descriptor

        public MPSNDArrayDescriptor descriptor()
        Create a MPSNDArrayDescriptor that describes this MPSNDArray The descriptor will describe the shape of the MPSNDArray after all deferred slicing and transposes have completed. A new descriptor is created each time to allow for further customization of the descriptor by the application.
        Returns:
        A new autoreleased MPSNDArrayDescriptor that matches the shape of the MPSNDArray, suitable for introduction of slice, cast and transpose operations.

      • device

        public MTLDevice device()
        [@property] device The device on which the MSPNDArray may be used

      • exportDataWithCommandBufferToBufferDestinationDataTypeOffsetRowStrides

        public void exportDataWithCommandBufferToBufferDestinationDataTypeOffsetRowStrides​(MTLCommandBuffer cmdBuf,
                                                                                   MTLBuffer buffer,
                                                                                   int destinationDataType,
                                                                                   long offset,
                                                                                   org.moe.natj.general.ptr.NIntPtr rowStrides)
        Do a GPU side copy of the contents of a MPSNDArray to a MTLBuffer To do a transpose or slice as part of the operation, make a MPSNDArray view first that encodes that operation.
        Parameters:
        cmdBuf - The command buffer on which to encode the operation
        buffer - The destination to overwrite
        destinationDataType - The destination data type.
        offset - The byte offset to where the {0,0,0...}th element will be written
        rowStrides - An optional array of (numberOfDimensions-1) byte counts which describe the byte offset from position 0 of the respective dimension to position 1.

      • hash_static

        public static long hash_static()

      • importDataWithCommandBufferFromBufferSourceDataTypeOffsetRowStrides

        public void importDataWithCommandBufferFromBufferSourceDataTypeOffsetRowStrides​(MTLCommandBuffer cmdBuf,
                                                                                MTLBuffer buffer,
                                                                                int sourceDataType,
                                                                                long offset,
                                                                                org.moe.natj.general.ptr.NIntPtr rowStrides)
        Do a GPU side copy of the contents of a MTLBuffer into a MPSNDArray Copy data from provided buffer to the NDArray. Implicit transposes and slicing shall be honored.
        Parameters:
        cmdBuf - The command buffer on which to encode the operation
        buffer - The destination to read from
        sourceDataType - The source data type.
        offset - The byte offset in the buffer from where the {0,0,0...}th element is to be read.
        rowStrides - An optional array of (numberOfDimensions-1) byte counts which describe the byte offset from position 0 of the respective dimension to position 1.

      • initWithDeviceDescriptor

        public MPSNDArray initWithDeviceDescriptor​(MTLDevice device,
                                           MPSNDArrayDescriptor descriptor)
        Initialize an MPSNDArrayDescriptor object on a device for given dimension sizes in descriptor.
        Parameters:
        device - The device on which the data type will be created.
        descriptor - The MPSNDArrayDescriptor used for initializing the the NDArray
        Returns:
        A valid MPSNDArray object or nil, if failure.

      • initWithDeviceScalar

        public MPSNDArray initWithDeviceScalar​(MTLDevice device,
                                       double value)
        Create a 1-Dimensional length=1 NDArray to hold a scalar

      • instanceMethodSignatureForSelector

        public static NSMethodSignature instanceMethodSignatureForSelector​(org.moe.natj.objc.SEL aSelector)

      • instancesRespondToSelector

        public static boolean instancesRespondToSelector​(org.moe.natj.objc.SEL aSelector)

      • isSubclassOfClass

        public static boolean isSubclassOfClass​(org.moe.natj.objc.Class aClass)

      • keyPathsForValuesAffectingValueForKey

        public static NSSet<java.lang.String> keyPathsForValuesAffectingValueForKey​(java.lang.String key)

      • label

        public java.lang.String label()
        A used specified string to help identify the array during debugging. May be externally visible to tools like Instruments

      • lengthOfDimension

        public long lengthOfDimension​(long dimensionIndex)
        The number of elements in the dimension at dimensionIndex The dimension length is at least as large as the existing slice length. Views of this MPSNDArray may have differing dimension lengths.

      • new_objc

        public static java.lang.Object new_objc()

      • numberOfDimensions

        public long numberOfDimensions()
        Number of dimensions in the NDArray

      • parent

        public MPSNDArray parent()
        The parent MPSNDArray that this object aliases If the MPSNDArray was createrd as a array view of another MPSNDArray object, and aliases content in the same MTLBuffer, the original MPSNDArray will be retained as the parent here. Two MPSNDArrays alias if they share a common ancestor. Note that the parent may itself have a parent, and so forth.

      • readBytesStrideBytes

        public void readBytesStrideBytes​(org.moe.natj.general.ptr.VoidPtr buffer,
                                 org.moe.natj.general.ptr.NIntPtr strideBytesPerDimension)
        Copy bytes from MPSNDArray into buffer The dimensionality and size of the copy region is given by the size of the MPSNDArray For subregions, use a MPSNDArray view.
        Parameters:
        buffer - A pointer to memory where to write the data
        strideBytesPerDimension - An optional array of numberOfDimensions sizes, which gives the distance in bytes from one element to the next in that dimension in buffer. The first value is typically dataTypeSize. The next is a row bytes. The next is 2d matrix bytes, and so forth. If the value is nil, these are calculated for you assuming that the data is packed without additional space in between elements, rows, etc. 0 and negative values are permitted.

      • resolveClassMethod

        public static boolean resolveClassMethod​(org.moe.natj.objc.SEL sel)

      • resolveInstanceMethod

        public static boolean resolveInstanceMethod​(org.moe.natj.objc.SEL sel)

      • resourceSize

        public long resourceSize()
        Get the number of bytes used to allocate underyling MTLResources This is the size of the backing store of underlying MTLResources. It does not include all storage used by the object, for example the storage used to hold the MPSNDArray instantiation and MTLBuffer is not included. It only measures the size of the allocation used to hold the MPSNDArray data in the MTLBuffer. This value is subject to change between different devices and operating systems. Except when -initWithBuffer:descriptor: is used, most MPSNDArrays are allocated initiallly without a backing store. The backing store is allocated lazily when it is needed, typically when the MPSNDArray is written to the first time. Consequently, in most cases, it should be inexpensive to make a MPSImage to see how much memory it will need, and release it if it is too large.

      • setLabel

        public void setLabel​(java.lang.String value)
        A used specified string to help identify the array during debugging. May be externally visible to tools like Instruments

      • setVersion_static

        public static void setVersion_static​(long aVersion)

      • superclass_static

        public static org.moe.natj.objc.Class superclass_static()

      • synchronizeOnCommandBuffer

        public void synchronizeOnCommandBuffer​(MTLCommandBuffer commandBuffer)
        Use a blit encoder if a discrete device to update CPU contents of underlying buffer with latest GPU value
        Parameters:
        commandBuffer - The commandBuffer on which we transfer the contents.

      • version_static

        public static long version_static()

      • writeBytesStrideBytes

        public void writeBytesStrideBytes​(org.moe.natj.general.ptr.VoidPtr buffer,
                                  org.moe.natj.general.ptr.NIntPtr strideBytesPerDimension)
        Copy bytes from a buffer into the MPSNDArray The dimensionality and size of the copy region is given by the size of the MPSNDArray For subregions, use a MPSNDArray view.
        Parameters:
        buffer - A pointer to memory where to read the data
        strideBytesPerDimension - An optional array of numberOfDimensions sizes, which gives the distance in bytes from one element to the next in that dimension in buffer. The first value is typically dataTypeSize. The next is a row bytes. The next is 2d matrix bytes, and so forth. If strideBytesPerDimension is nil, these are calculated for you assuming that the data is packed without additional space in between elements, rows, etc. 0 and negative values are permitted.