- type CLMem = Ptr ()
- type CLSampler = Ptr ()
- data CLMemFlag
- data CLMemObjectType
- data CLAddressingMode
- data CLFilterMode
- data CLImageFormat = CLImageFormat {
- image_channel_order :: !CLChannelOrder
- image_channel_data_type :: !CLChannelType
- clCreateBuffer :: Integral a => CLContext -> [CLMemFlag] -> (a, Ptr ()) -> IO CLMem
- clRetainMemObject :: CLMem -> IO Bool
- clReleaseMemObject :: CLMem -> IO Bool
- clGetMemType :: CLMem -> IO CLMemObjectType
- clGetMemFlags :: CLMem -> IO [CLMemFlag]
- clGetMemSize :: CLMem -> IO CSize
- clGetMemHostPtr :: CLMem -> IO (Ptr ())
- clGetMemMapCount :: CLMem -> IO CLuint
- clGetMemReferenceCount :: CLMem -> IO CLuint
- clGetMemContext :: CLMem -> IO CLContext
- clCreateImage2D :: Integral a => CLContext -> [CLMemFlag] -> CLImageFormat -> a -> a -> a -> Ptr () -> IO CLMem
- clCreateImage3D :: Integral a => CLContext -> [CLMemFlag] -> CLImageFormat -> a -> a -> a -> a -> a -> Ptr () -> IO CLMem
- clGetSupportedImageFormats :: CLContext -> [CLMemFlag] -> CLMemObjectType -> IO [CLImageFormat]
- clGetImageFormat :: CLMem -> IO CLImageFormat
- clGetImageElementSize :: CLMem -> IO CSize
- clGetImageRowPitch :: CLMem -> IO CSize
- clGetImageSlicePitch :: CLMem -> IO CSize
- clGetImageWidth :: CLMem -> IO CSize
- clGetImageHeight :: CLMem -> IO CSize
- clGetImageDepth :: CLMem -> IO CSize
- clCreateSampler :: CLContext -> Bool -> CLAddressingMode -> CLFilterMode -> IO CLSampler
- clRetainSampler :: CLSampler -> IO Bool
- clReleaseSampler :: CLSampler -> IO Bool
- clGetSamplerReferenceCount :: CLSampler -> IO CLuint
- clGetSamplerContext :: CLSampler -> IO CLContext
- clGetSamplerAddressingMode :: CLSampler -> IO CLAddressingMode
- clGetSamplerFilterMode :: CLSampler -> IO CLFilterMode
- clGetSamplerNormalizedCoords :: CLSampler -> IO Bool
Types
-
CL_MEM_READ_WRITE
, This flag specifies that the memory object will be read and written by a kernel. This is the default. -
CL_MEM_WRITE_ONLY
, This flags specifies that the memory object will be written but not read by a kernel. Reading from a buffer or image object created withCLMEM_WRITE_ONLY
inside a kernel is undefined. -
CL_MEM_READ_ONLY
, This flag specifies that the memory object is a read-only memory object when used inside a kernel. Writing to a buffer or image object created withCLMEM_READ_ONLY
inside a kernel is undefined. -
CL_MEM_USE_HOST_PTR
, This flag is valid only if host_ptr is not NULL. If specified, it indicates that the application wants the OpenCL implementation to use memory referenced by host_ptr as the storage bits for the memory object. OpenCL implementations are allowed to cache the buffer contents pointed to by host_ptr in device memory. This cached copy can be used when kernels are executed on a device. The result of OpenCL commands that operate on multiple buffer objects created with the same host_ptr or overlapping host regions is considered to be undefined. -
CL_MEM_ALLOC_HOST_PTR
, This flag specifies that the application wants the OpenCL implementation to allocate memory from host accessible memory.CL_MEM_ALLOC_HOST_PTR
andCL_MEM_USE_HOST_PTR
are mutually exclusive. -
CL_MEM_COPY_HOST_PTR
, This flag is valid only if host_ptr is not NULL. If specified, it indicates that the application wants the OpenCL implementation to allocate memory for the memory object and copy the data from memory referenced by host_ptr.CL_MEM_COPY_HOST_PTR
andCL_MEM_USE_HOST_PTR
are mutually exclusive.CL_MEM_COPY_HOST_PTR
can be used withCL_MEM_ALLOC_HOST_PTR
to initialize the contents of the cl_mem object allocated using host-accessible (e.g. PCIe) memory.
data CLMemObjectType Source
-
CL_MEM_OBJECT_BUFFER
if memobj is created withclCreateBuffer
. -
CL_MEM_OBJECT_IMAGE2D
if memobj is created withclCreateImage2D
-
CL_MEM_OBJECT_IMAGE3D
if memobj is created withclCreateImage3D
.
data CLAddressingMode Source
data CLImageFormat Source
CLImageFormat | |
|
Memory Functions
clCreateBuffer :: Integral a => CLContext -> [CLMemFlag] -> (a, Ptr ()) -> IO CLMemSource
Creates a buffer object. Returns a valid non-zero buffer object if the
buffer object is created successfully. Otherwise, it throws the CLError
:
-
CL_INVALID_CONTEXT
if context is not a valid context. -
CL_INVALID_VALUE
if values specified in flags are not valid. -
CL_INVALID_BUFFER_SIZE
if size is 0 or is greater thanclDeviceMaxMemAllocSize
value for all devices in context. -
CL_INVALID_HOST_PTR
if host_ptr is NULL andCL_MEM_USE_HOST_PTR
orCL_MEM_COPY_HOST_PTR
are set in flags or if host_ptr is not NULL butCL_MEM_COPY_HOST_PTR
orCL_MEM_USE_HOST_PTR
are not set in flags. -
CL_MEM_OBJECT_ALLOCATION_FAILURE
if there is a failure to allocate memory for buffer object. -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host.
clRetainMemObject :: CLMem -> IO BoolSource
Increments the memory object reference count. returns True
if the
function is executed successfully. After the memobj reference count becomes
zero and commands queued for execution on a command-queue(s) that use memobj
have finished, the memory object is deleted. It returns False
if memobj is
not a valid memory object.
clReleaseMemObject :: CLMem -> IO BoolSource
Decrements the memory object reference count. After the memobj reference
count becomes zero and commands queued for execution on a command-queue(s)
that use memobj have finished, the memory object is deleted. Returns True
if the function is executed successfully. It returns False
if memobj is not
a valid memory object.
clGetMemType :: CLMem -> IO CLMemObjectTypeSource
Returns the mem object type.
This function execute OpenCL clGetMemObjectInfo with CL_MEM_TYPE
.
clGetMemFlags :: CLMem -> IO [CLMemFlag]Source
Return the flags argument value specified when memobj was created.
This function execute OpenCL clGetMemObjectInfo with CL_MEM_FLAGS
.
clGetMemSize :: CLMem -> IO CSizeSource
Return actual size of memobj in bytes.
This function execute OpenCL clGetMemObjectInfo with CL_MEM_SIZE
.
clGetMemHostPtr :: CLMem -> IO (Ptr ())Source
Return the host_ptr argument value specified when memobj is created.
This function execute OpenCL clGetMemObjectInfo with CL_MEM_HOST_PTR
.
clGetMemMapCount :: CLMem -> IO CLuintSource
Map count. The map count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for debugging.
This function execute OpenCL clGetMemObjectInfo with CL_MEM_MAP_COUNT
.
clGetMemReferenceCount :: CLMem -> IO CLuintSource
Return memobj reference count. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
This function execute OpenCL clGetMemObjectInfo with CL_MEM_REFERENCE_COUNT
.
clGetMemContext :: CLMem -> IO CLContextSource
Return context specified when memory object is created.
This function execute OpenCL clGetMemObjectInfo with CL_MEM_CONTEXT
.
Image Functions
:: Integral a | |
=> CLContext | A valid OpenCL context on which the image object is to be created. |
-> [CLMemFlag] | A list of flags that is used to specify allocation and usage information about the image memory object being created. |
-> CLImageFormat | Structure that describes format properties of the image to be allocated. |
-> a | The width of the image in pixels. It must be values greater than or equal to 1. |
-> a | The height of the image in pixels. It must be values greater than or equal to 1. |
-> a | The scan-line pitch in bytes. This must be 0 if
host_ptr is |
-> Ptr () | A pointer to the image data that may already be allocated by the application. The size of the buffer that host_ptr points to must be greater than or equal to image_row_pitch * image_height. The size of each element in bytes must be a power of 2. The image data specified by host_ptr is stored as a linear sequence of adjacent scanlines. Each scanline is stored as a linear sequence of image elements. |
-> IO CLMem |
Creates a 2D image object.
clCreateImage2D
returns a valid non-zero image object created if the image
object is created successfully. Otherwise, it throws one of the following
CLError
exceptions:
-
CL_INVALID_CONTEXT
if context is not a valid context. -
CL_INVALID_VALUE
if values specified in flags are not valid. -
CL_INVALID_IMAGE_FORMAT_DESCRIPTOR
if values specified in image_format are not valid. -
CL_INVALID_IMAGE_SIZE
if image_width or image_height are 0 or if they exceed values specified inCL_DEVICE_IMAGE2D_MAX_WIDTH
orCL_DEVICE_IMAGE2D_MAX_HEIGHT
respectively for all devices in context or if values specified by image_row_pitch do not follow rules described in the argument description above. -
CL_INVALID_HOST_PTR
if host_ptr isnullPtr
andCL_MEM_USE_HOST_PTR
orCL_MEM_COPY_HOST_PTR
are set in flags or if host_ptr is notnullPtr
butCL_MEM_COPY_HOST_PTR
orCL_MEM_USE_HOST_PTR
are not set in flags. -
CL_IMAGE_FORMAT_NOT_SUPPORTED
if the image_format is not supported. -
CL_MEM_OBJECT_ALLOCATION_FAILURE
if there is a failure to allocate memory for image object. -
CL_INVALID_OPERATION
if there are no devices in context that support images (i.e.CL_DEVICE_IMAGE_SUPPORT
(specified in the table of OpenCL Device Queries forclGetDeviceInfo
) isFalse
). -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host.
:: Integral a | |
=> CLContext | A valid OpenCL context on which the image object is to be created. |
-> [CLMemFlag] | A list of flags that is used to specify allocation and usage information about the image memory object being created. |
-> CLImageFormat | Structure that describes format properties of the image to be allocated. |
-> a | The width of the image in pixels. It must be values greater than or equal to 1. |
-> a | The height of the image in pixels. It must be values greater than or equal to 1. |
-> a | The depth of the image in pixels. This must be a value greater than 1. |
-> a | The scan-line pitch in bytes. This must be 0 if
host_ptr is |
-> a | The size in bytes of each 2D slice in the 3D
image. This must be 0 if host_ptr is |
-> Ptr () | A pointer to the image data that may already be allocated by the application. The size of the buffer that host_ptr points to must be greater than or equal to image_slice_pitch * image_depth. The size of each element in bytes must be a power of 2. The image data specified by host_ptr is stored as a linear sequence of adjacent 2D slices. Each 2D slice is a linear sequence of adjacent scanlines. Each scanline is a linear sequence of image elements. |
-> IO CLMem |
Creates a 3D image object.
clCreateImage3D
returns a valid non-zero image object created if the image
object is created successfully. Otherwise, it throws one of the following
CLError
exceptions:
-
CL_INVALID_CONTEXT
if context is not a valid context. -
CL_INVALID_VALUE
if values specified in flags are not valid. -
CL_INVALID_IMAGE_FORMAT_DESCRIPTOR
if values specified in image_format are not valid. -
CL_INVALID_IMAGE_SIZE
if image_width, image_height are 0 or if image_depth less than or equal to 1 or if they exceed values specified inCL_DEVICE_IMAGE3D_MAX_WIDTH
, CL_DEVICE_IMAGE3D_MAX_HEIGHT' orCL_DEVICE_IMAGE3D_MAX_DEPTH
respectively for all devices in context or if values specified by image_row_pitch and image_slice_pitch do not follow rules described in the argument description above. -
CL_INVALID_HOST_PTR
if host_ptr isnullPtr
andCL_MEM_USE_HOST_PTR
orCL_MEM_COPY_HOST_PTR
are set in flags or if host_ptr is notnullPtr
butCL_MEM_COPY_HOST_PTR
orCL_MEM_USE_HOST_PTR
are not set in flags. -
CL_IMAGE_FORMAT_NOT_SUPPORTED
if the image_format is not supported. -
CL_MEM_OBJECT_ALLOCATION_FAILURE
if there is a failure to allocate memory for image object. -
CL_INVALID_OPERATION
if there are no devices in context that support images (i.e.CL_DEVICE_IMAGE_SUPPORT
(specified in the table of OpenCL Device Queries for clGetDeviceInfo) isFalse
). -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host.
clGetSupportedImageFormatsSource
:: CLContext | A valid OpenCL context on which the image object(s) will be created. |
-> [CLMemFlag] | A bit-field that is used to specify allocation and usage information about the image memory object. |
-> CLMemObjectType | Describes the image type
and must be either
|
-> IO [CLImageFormat] |
Get the list of image formats supported by an OpenCL
implementation. clGetSupportedImageFormats
can be used to get the list of
image formats supported by an OpenCL implementation when the following
information about an image memory object is specified:
- Context * Image type - 2D or 3D image * Image object allocation information
Throws CL_INVALID_CONTEXT
if context is not a valid context, throws
CL_INVALID_VALUE
if flags or image_type are not valid.
clGetImageFormat :: CLMem -> IO CLImageFormatSource
Return image format descriptor specified when image is created with clCreateImage2D or clCreateImage3D.
This function execute OpenCL clGetImageInfo with CL_IMAGE_FORMAT
.
clGetImageElementSize :: CLMem -> IO CSizeSource
Return size of each element of the image memory object given by image. An
element is made up of n channels. The value of n is given in CLImageFormat
descriptor.
This function execute OpenCL clGetImageInfo with CL_IMAGE_ELEMENT_SIZE
.
clGetImageRowPitch :: CLMem -> IO CSizeSource
Return size in bytes of a row of elements of the image object given by image.
This function execute OpenCL clGetImageInfo with CL_IMAGE_ROW_PITCH
.
clGetImageSlicePitch :: CLMem -> IO CSizeSource
Return size in bytes of a 2D slice for the 3D image object given by image. For a 2D image object this value will be 0.
This function execute OpenCL clGetImageInfo with CL_IMAGE_SLICE_PITCH
.
clGetImageWidth :: CLMem -> IO CSizeSource
Return width of image in pixels.
This function execute OpenCL clGetImageInfo with CL_IMAGE_WIDTH
.
clGetImageHeight :: CLMem -> IO CSizeSource
Return height of image in pixels.
This function execute OpenCL clGetImageInfo with CL_IMAGE_HEIGHT
.
clGetImageDepth :: CLMem -> IO CSizeSource
Return depth of the image in pixels. For a 2D image, depth equals 0.
This function execute OpenCL clGetImageInfo with CL_IMAGE_DEPTH
.
Sampler Functions
clCreateSampler :: CLContext -> Bool -> CLAddressingMode -> CLFilterMode -> IO CLSamplerSource
Creates a sampler object. A sampler object describes how to sample an image when the image is read in the kernel. The built-in functions to read from an image in a kernel take a sampler as an argument. The sampler arguments to the image read function can be sampler objects created using OpenCL functions and passed as argument values to the kernel or can be samplers declared inside a kernel. In this section we discuss how sampler objects are created using OpenCL functions.
Returns a valid non-zero sampler object if the sampler object is created
successfully. Otherwise, it throws one of the following CLError
exceptions:
-
CL_INVALID_CONTEXT
if context is not a valid context. -
CL_INVALID_VALUE
if addressing_mode, filter_mode, or normalized_coords or a combination of these argument values are not valid. -
CL_INVALID_OPERATION
if images are not supported by any device associated with context (i.e.CL_DEVICE_IMAGE_SUPPORT
specified in the table of OpenCL Device Queries for clGetDeviceInfo isFalse
). -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host.
clRetainSampler :: CLSampler -> IO BoolSource
Increments the sampler reference count. clCreateSampler
does an implicit
retain. Returns True
if the function is executed successfully. It returns
False
if sampler is not a valid sampler object.
clReleaseSampler :: CLSampler -> IO BoolSource
Decrements the sampler reference count. The sampler object is deleted after
the reference count becomes zero and commands queued for execution on a
command-queue(s) that use sampler have finished. clReleaseSampler
returns
True
if the function is executed successfully. It returns False
if
sampler is not a valid sampler object.
clGetSamplerReferenceCount :: CLSampler -> IO CLuintSource
Return the sampler reference count. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
This function execute OpenCL clGetSamplerInfo with
CL_SAMPLER_REFERENCE_COUNT
.
clGetSamplerContext :: CLSampler -> IO CLContextSource
Return the context specified when the sampler is created.
This function execute OpenCL clGetSamplerInfo with CL_SAMPLER_CONTEXT
.
clGetSamplerAddressingMode :: CLSampler -> IO CLAddressingModeSource
Return the value specified by addressing_mode argument to clCreateSampler.
This function execute OpenCL clGetSamplerInfo with
CL_SAMPLER_ADDRESSING_MODE
.
clGetSamplerFilterMode :: CLSampler -> IO CLFilterModeSource
Return the value specified by filter_mode argument to clCreateSampler.
This function execute OpenCL clGetSamplerInfo with CL_SAMPLER_FILTER_MODE
.
clGetSamplerNormalizedCoords :: CLSampler -> IO BoolSource
Return the value specified by normalized_coords argument to clCreateSampler.
This function execute OpenCL clGetSamplerInfo with
CL_SAMPLER_NORMALIZED_COORDS
.