Instance Method

newBufferWithBytesNoCopy:length:options:deallocator:

Creates a buffer by wrapping an existing contiguous memory allocation.

Required.

Declaration

- (id<MTLBuffer>)newBufferWithBytesNoCopy:(void *)pointer length:(NSUInteger)length options:(MTLResourceOptions)options deallocator:(void (^)(void *pointer, NSUInteger length))deallocator;

Parameters

pointer

The memory address from which the data starts. The memory allocation in the pointer argument must already be page-aligned.

length

The number of bytes of the existing memory allocation to cover. This value must result in a page-aligned region of memory.

options

Specifies the behavior of the new buffer.

deallocator

A block of code invoked when this buffer is deallocated. Pass nil if you do not need to perform an action.

Return Value

A new MTLBuffer object that references an existing contiguous memory allocation.

Discussion

The storage allocation of the returned new MTLBuffer object is the same as the pointer input value. The existing memory allocation must be covered by a single VM region, typically allocated with vm_allocate or mmap. Memory allocated by malloc is specifically disallowed.

The deallocator block can be used to free the wrapped memory allocation in any desired fashion.

Page size can vary for different hardware and should not be assumed to always be 4 kilobytes. For more information on querying a system’s page size, see getpagesize(3) macOS Developer Tools Manual Page.

MTLBuffer objects created with this method are CPU-accessible and can be specified with a MTLResourceStorageModeShared or MTLResourceStorageModeManaged storage mode, but not a MTLResourceStorageModePrivate storage mode.

Topics

Resource Options

MTLResourceOptions

Optional arguments used to set the behavior of a resource.

See Also

Creating Buffers

maxBufferLength

The maximum size of a buffer, in bytes.

Required.

- newBufferWithLength:options:

Allocates a new zero-filled buffer of a given length.

Required.

- newBufferWithBytes:length:options:

Allocates a new buffer of a given length and initializes its contents by copying existing data into it.

Required.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software