clCreateImage3D

Creates a 3D image object.

cl_mem clCreateImage3D ( cl_context context,
  cl_mem_flags flags,
  const cl_image_format *image_format,
  size_t image_width,
  size_t image_height,
  size_t image_depth,
  size_t image_row_pitch,
  size_t image_slice_pitch,
  void *host_ptr,
  cl_int *errcode_ret)

Parameters

context

A valid OpenCL context on which the image object is to be created.

flags

A bit-field that is used to specify allocation and usage information about the image memory object being created and is described in the table List of supported cl_mem_flags values for clCreateBuffer.

image_format

A pointer to a structure that describes format properties of the image to be allocated. See cl_image_format for a detailed description of the image format descriptor.

image_width , image_height

The width and height of the image in pixels. These must be values greater than or equal to 1.

image depth

The depth of the image in pixels. This must be a value greater than 1.

image_row_pitch

The scan-line pitch in bytes. This must be 0 if host_ptr is NULL and can be either 0 or greater than or equal to image_width * size of element in bytes if host_ptr is not NULL. If host_ptr is not NULL and image_row_pitch is equal to 0, image_row_pitch is calculated as image_width * size of element in bytes. If image_row_pitch is not 0, it must be a multiple of the image element size in bytes.

image_slice_pitch

The size in bytes of each 2D slice in the 3D image. This must be 0 if host_ptr is NULL and can be either 0 or greater than or equal to image_row_pitch * image_height if host_ptr is not NULL. If host_ptr is not NULL and image_slice_pitch equal to 0, image_slice_pitch is calculated as image_row_pitch * image_height. If image_slice_pitch is not 0, it must be a multiple of the image_row_pitch.

host_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.

errcode_ret

Will return an appropriate error code. If errcode_ret is NULL, no error code is returned.

Errors

Returns a valid non-zero image object created and the errcode_ret is set to CL_SUCCESS if the image object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

  • 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 or if image_format is NULL.
  • 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 in CL_DEVICE_IMAGE3D_MAX_WIDTH, CL_DEVICE_IMAGE3D_MAX_HEIGHT or CL_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 is NULL and CL_MEM_USE_HOST_PTR or CL_MEM_COPY_HOST_PTR are set in flags or if host_ptr is not NULL but CL_MEM_COPY_HOST_PTR or CL_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) is CL_FALSE).
  • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
  • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

Specification

OpenCL Specification

Also see

clCreateImage2D, cl_image_format, Cardinality Diagram

Copyright © 2007-2010 The Khronos Group Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.