Package apple.metalperformanceshaders

Class MPSCommandBuffer

  • All Implemented Interfaces:
    MTLCommandBuffer, NSObject
    public class MPSCommandBuffer
extends NSObject
implements MTLCommandBuffer
    MPSCommandBuffer [@dependency] This depends on Metal.framework A MPSCommandBuffer object is used to wrap an existing command buffer with MPS specific options. A MPS kernel typically operates between a fixed set of inputs and outputs. The MPSCommandBuffer class provides a way to add further encode-time parameters to the encode call using the command buffer. Currently the only parameter included in the MPSCommandBuffer that all MPS kernels support is the the predicate option, which can be used to pre-empt the kernel from the GPU side. NOTE: the options that contain metal resources will be referenced by this object and therefore it is advisable to make the lifetime of this object as short as possible as is the case for all command buffers.

    • Constructor Detail

      • MPSCommandBuffer

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

    • Method Detail

      • GPUEndTime

        public double GPUEndTime()
        Description copied from interface: MTLCommandBuffer
        [@property] GPUEndTime The host time in seconds that GPU finishes executing this command buffer. Returns zero if CPU has not received completion notification. This usually can be called in command buffer completion handler.
        Specified by:
        GPUEndTime in interface MTLCommandBuffer

      • GPUStartTime

        public double GPUStartTime()
        Description copied from interface: MTLCommandBuffer
        [@property] GPUStartTime The host time in seconds that GPU starts executing this command buffer. Returns zero if it has not started. This usually can be called in command buffer completion handler.
        Specified by:
        GPUStartTime in interface MTLCommandBuffer

      • accessInstanceVariablesDirectly

        public static boolean accessInstanceVariablesDirectly()

      • allocWithZone

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

      • 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()

      • commandBuffer

        public MTLCommandBuffer commandBuffer()
        [@property] commandBuffer The Metal Command Buffer that was used to initialize this object.

      • commandBufferFromCommandQueue

        public static MPSCommandBuffer commandBufferFromCommandQueue​(MTLCommandQueue commandQueue)
        Initializes a MPSCommandBuffer object from a given command queue.
        Returns:
        A pointer to the newly initialized MPSCommandBuffer object.

      • commandBufferWithCommandBuffer

        public static MPSCommandBuffer commandBufferWithCommandBuffer​(MTLCommandBuffer commandBuffer)
        Initializes a MPSCommandBuffer object with given MTLCommandBuffer.
        Returns:
        A pointer to the newly initialized MPSCommandBuffer object.

      • commit

        public void commit()
        Description copied from interface: MTLCommandBuffer
        commit Commit a command buffer so it can be executed as soon as possible.
        Specified by:
        commit in interface MTLCommandBuffer

      • commitAndContinue

        public void commitAndContinue()
        Commit work encoded so far and continue with a new underlying command buffer This method commits the underlying root MTLCommandBuffer, and makes a new one on the same command queue. The MPS heap is moved forward to the new command buffer such that temporary objects used by the previous command buffer can be still be used with the new one. This provides a way to move work already encoded into consideration by the Metal back end sooner. For large workloads, e.g. a neural networking graph periodically calling -commitAndContinue may allow you to improve CPU / GPU parallelism without the substantial memory increases associated with double buffering. It will also help decrease overall latency. Any Metal schedule or completion callbacks previously attached to this object will remain attached to the old command buffer and will fire as expected as the old command buffer is scheduled and completes. If your application is relying on such callbacks to coordinate retain / release of important objects that are needed for work encoded after -commitAndContinue, your application should retain these objects before calling commitAndContinue, and attach new release callbacks to this object with a new completion handler so that they persist through the lifetime of the new underlying command buffer. You may do this, for example by adding the objects to a mutable array before calling -commitAndContinue, then release the mutable array in a new completion callback added after -commitAndContinue. Because -commitAndContinue commits the old command buffer then switches to a new one, some aspects of command buffer completion may surprise unwary developers. For example, -waitUntilCompleted called immediately after -commitAndContinue asks Metal to wait for the new command buffer to finish, not the old one. Since the new command buffer presumably hasn't been committed yet, it is formally a deadlock, resources may leak and Metal may complain. Your application should ether call -commit before -waitUntilCompleted, or capture the -rootCommandBuffer from before the call to -commitAndContinue and wait on that. Similarly, your application should be sure to use the appropriate command buffer when querying the [MTLCommandBuffer status] property. If the underlying MTLCommandBuffer also implements -commitAndContinue, then the message will be forwarded to that object instead. In this way, underlying predicate objects and other state will be preserved.

      • computeCommandEncoderWithDispatchType

        public MTLComputeCommandEncoder computeCommandEncoderWithDispatchType​(long dispatchType)
        Description copied from interface: MTLCommandBuffer
        computeCommandEncoderWithDispatchType returns a compute command encoder to encode into this command buffer. Optionally allow this command encoder to execute dispatches concurrently. On devices that do not support concurrent command encoders, this call is equivalent to computeCommandEncoder
        Specified by:
        computeCommandEncoderWithDispatchType in interface MTLCommandBuffer

      • debugDescription_static

        public static java.lang.String debugDescription_static()

      • description_static

        public static java.lang.String description_static()

      • encodeSignalEventValue

        public void encodeSignalEventValue​(MTLEvent event,
                                   long value)
        Description copied from interface: MTLCommandBuffer
        encodeSignalEvent:value: Encodes a command that signals an event with a given value. This method may only be called if there is no current command encoder on the receiver.
        Specified by:
        encodeSignalEventValue in interface MTLCommandBuffer

      • encodeWaitForEventValue

        public void encodeWaitForEventValue​(MTLEvent event,
                                    long value)
        Description copied from interface: MTLCommandBuffer
        encodeWaitForEvent:value: Encodes a command that pauses execution of this command buffer until the specified event reaches a given value. This method may only be called if there is no current command encoder on the receiver.
        Specified by:
        encodeWaitForEventValue in interface MTLCommandBuffer

      • enqueue

        public void enqueue()
        Description copied from interface: MTLCommandBuffer
        enqueue Append this command buffer to the end of its MTLCommandQueue.
        Specified by:
        enqueue in interface MTLCommandBuffer

      • error

        public NSError error()
        Description copied from interface: MTLCommandBuffer
        [@property] error If an error occurred during execution, the NSError may contain more details about the problem.
        Specified by:
        error in interface MTLCommandBuffer

      • hash_static

        public static long hash_static()

      • heapProvider

        public MPSHeapProvider heapProvider()
        [@property] heapProvider A application supplied object to allocate MTLHeaps for MPS By default this is nil, which will use MPS' device level global heap cache to allocate the heaps. This is a reasonable choice. However, it may be inefficient if you are keeping your own MTLHeap, since there will be two pessimistically sized free stores which may be larger than is strictly necessary, and of course fragmentation across multiple heaps. In such cases, the problem may be solved either by using MPS' automatically managed heap (simple) or having MPS use your heap. The heapProvider allows you to implement the second case. To use the MPS heap, simply make temporary MPSImages, vectors and matrices. If multiple MPSCommandBuffers reference the same MTLCommandBuffer, changing the heapProvider on one will change the heap provider for all of them.

      • initWithCommandBuffer

        public MPSCommandBuffer initWithCommandBuffer​(MTLCommandBuffer commandBuffer)
        Initializes an empty MPSCommandBuffer object with given MTLCommandBuffer.
        Returns:
        A pointer to the newly initialized MPSCommandBuffer object.

      • 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()
        Description copied from interface: MTLCommandBuffer
        [@property] label A string to help identify this object.
        Specified by:
        label in interface MTLCommandBuffer

      • new_objc

        public static java.lang.Object new_objc()

      • predicate

        public MPSPredicate predicate()
        [@property] predicate A GPU predicate object. Default: nil.

      • prefetchHeapForWorkloadSize

        public void prefetchHeapForWorkloadSize​(long size)
        Prefetch heap into the MPS command buffer heap cache. If there is not sufficient free storage in the MPS heap for the command buffer for allocations of total size size, pre-warm the MPS heap with a new MTLHeap allocation of sufficient size. If this size turns out to be too small MPS may ask for more heaps later to cover additional allocations. If heapProvider is not nil, the heapProvider will be used.
        Parameters:
        size - The minimum size of the free store needed

      • presentDrawable

        public void presentDrawable​(MTLDrawable drawable)
        Description copied from interface: MTLCommandBuffer
        presentDrawable: Add a drawable present that will be invoked when this command buffer has been scheduled for execution. The submission thread will be lock stepped with present call been serviced by window server
        Specified by:
        presentDrawable in interface MTLCommandBuffer

      • presentDrawableAfterMinimumDuration

        public void presentDrawableAfterMinimumDuration​(MTLDrawable drawable,
                                                double duration)
        Description copied from interface: MTLCommandBuffer
        presentDrawable:afterMinimumDuration: Add a drawable present for a specific host time that allows previous frame to be on screen for at least duration time. The difference of this API versus presentDrawable:atTime is that this API defers calculation of the presentation time until the previous frame's actual presentation time is known, thus to be able to maintain a more consistent and stable frame time. This also provides an easy way to set frame rate. The submission thread will be lock stepped with present call been serviced by window server
        Specified by:
        presentDrawableAfterMinimumDuration in interface MTLCommandBuffer
        Parameters:
        drawable - The drawable to be presented
        duration - The minimum time that previous frame should be displayed. The time is double preceision floating point in the unit of seconds.

      • presentDrawableAtTime

        public void presentDrawableAtTime​(MTLDrawable drawable,
                                  double presentationTime)
        Description copied from interface: MTLCommandBuffer
        presentDrawable:atTime: Add a drawable present for a specific host time that will be invoked when this command buffer has been scheduled for execution. The submission thread will be lock stepped with present call been serviced by window server
        Specified by:
        presentDrawableAtTime in interface MTLCommandBuffer

      • pushDebugGroup

        public void pushDebugGroup​(java.lang.String string)
        Description copied from interface: MTLCommandBuffer
        pushDebugGroup: Push a new named string onto a stack of string labels.
        Specified by:
        pushDebugGroup in interface MTLCommandBuffer

      • resolveClassMethod

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

      • resolveInstanceMethod

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

      • retainedReferences

        public boolean retainedReferences()
        Description copied from interface: MTLCommandBuffer
        [@property] retainedReferences If YES, this command buffer holds strong references to objects needed to execute this command buffer.
        Specified by:
        retainedReferences in interface MTLCommandBuffer

      • rootCommandBuffer

        public MTLCommandBuffer rootCommandBuffer()
        [@property] rootCommandBuffer The base MTLCommandBuffer underlying the MPSCommandBuffer MPSCommandBuffers may wrap other MPSCommandBuffers, in the process creating what is in effect a stack of predicate objects that may be pushed or popped by making new MPSCommandBuffers or by calling -commandBuffer. In some circumstances, it is preferable to use the root command buffer, particularly when trying to identify the command buffer that will be commited by -commitAndContinue.

      • setHeapProvider

        public void setHeapProvider​(MPSHeapProvider value)
        [@property] heapProvider A application supplied object to allocate MTLHeaps for MPS By default this is nil, which will use MPS' device level global heap cache to allocate the heaps. This is a reasonable choice. However, it may be inefficient if you are keeping your own MTLHeap, since there will be two pessimistically sized free stores which may be larger than is strictly necessary, and of course fragmentation across multiple heaps. In such cases, the problem may be solved either by using MPS' automatically managed heap (simple) or having MPS use your heap. The heapProvider allows you to implement the second case. To use the MPS heap, simply make temporary MPSImages, vectors and matrices. If multiple MPSCommandBuffers reference the same MTLCommandBuffer, changing the heapProvider on one will change the heap provider for all of them.

      • setLabel

        public void setLabel​(java.lang.String value)
        Description copied from interface: MTLCommandBuffer
        [@property] label A string to help identify this object.
        Specified by:
        setLabel in interface MTLCommandBuffer

      • setPredicate

        public void setPredicate​(MPSPredicate value)
        [@property] predicate A GPU predicate object. Default: nil.

      • setVersion_static

        public static void setVersion_static​(long aVersion)

      • status

        public long status()
        Description copied from interface: MTLCommandBuffer
        [@property] status status reports the current stage in the lifetime of MTLCommandBuffer, as it proceeds to enqueued, committed, scheduled, and completed.
        Specified by:
        status in interface MTLCommandBuffer

      • superclass_static

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

      • version_static

        public static long version_static()

      • waitUntilScheduled

        public void waitUntilScheduled()
        Description copied from interface: MTLCommandBuffer
        waitUntilScheduled Synchronously wait for this command buffer to be scheduled.
        Specified by:
        waitUntilScheduled in interface MTLCommandBuffer

      • errorOptions

        public long errorOptions()
        Description copied from interface: MTLCommandBuffer
        The set of options configuring the error reporting of the created command buffer.
        Specified by:
        errorOptions in interface MTLCommandBuffer

      • logs

        public MTLLogContainer logs()
        Description copied from interface: MTLCommandBuffer
        [@property] logs Logs generated by the command buffer during execution of the GPU commands. Valid after GPU execution is completed
        Specified by:
        logs in interface MTLCommandBuffer