OpenCL™规范 5.3.1. 创建图像对象

5.3.1. Creating Image Objects

5.3.1. 创建图像对象

An image object may be created using the function

可以使用函数创建图像对象

// Provided by CL_VERSION_1_2
cl_mem clCreateImage(
    cl_context context,
    cl_mem_flags flags,
    const cl_image_format* image_format,
    const cl_image_desc* image_desc,
    void* host_ptr,
    cl_int* errcode_ret);

clCreateImage is missing before version 1.2. clCreateImage在版本1.2之前丢失。

An image object may also be created with additional properties using the function

也可以使用函数创建具有附加属性的图像对象

// Provided by CL_VERSION_3_0
cl_mem clCreateImageWithProperties(
    cl_context context,
    const cl_mem_properties* properties,
    cl_mem_flags flags,
    const cl_image_format* image_format,
    const cl_image_desc* image_desc,
    void* host_ptr,
    cl_int* errcode_ret);

clCreateImageWithProperties is missing before version 3.0. clCreateImageWithProperties在版本3.0之前丢失。

• context is a valid OpenCL context used to create the image object.

• context是用于创建图像对象的有效OpenCL上下文。

• properties is an optional list of properties for the image object and their corresponding values. The list is terminated with the special property 0. If no properties are required, properties may be NULL. OpenCL 3.0 does not define any optional properties for images, but extensions may define properties as described in the List of supported image creation properties.

• ​properties是图像对象的属性及其相应值的可选列表。该列表以特殊属性0终止。如果不需要任何属性，则属性可能为NULL。OpenCL 3.0没有为图像定义任何可选属性，但扩展可以定义支持的图像创建属性列表中所述的属性。

• flags is a bit-field that is used to specify allocation and usage information about the image memory object being created and is described in the supported memory flag values table.

• ​flags是用于指定关于正在创建的图像存储器对象的分配和使用信息的比特字段，并且在支持的存储器标志值表中进行描述。

• image_format is a pointer to a structure that describes format properties of the image to be allocated. A 1D image buffer or 2D image can be created from a buffer by specifying a buffer object in the image_desc→mem_object. A 2D image can be created from another 2D image object by specifying an image object in the image_desc→mem_object. Refer to the Image Format Descriptor section for a detailed description of the image format descriptor.

• ​image_format是指向描述要分配的图像的格式属性的结构的指针。通过在image_desc中指定缓冲对象，可以从缓冲区创建1D图像缓冲区或2D图像→mem_object。通过在image_desc中指定图像对象，可以从另一个2D图像对象创建2D图像→mem_object。有关图像格式描述符的详细描述，请参阅“图像格式描述符”部分。

• image_desc is a pointer to a structure that describes type and dimensions of the image to be allocated. Refer to the Image Descriptor section for a detailed description of the image descriptor.

• ​image_desc是指向描述要分配的图像的类型和尺寸的结构的指针。有关图像描述符的详细描述，请参阅图像描述符部分。

• host_ptr is a pointer to the image data that may already be allocated by the application. Refer to the table below for a description of how large the buffer that host_ptr points to must be.

• ​host_ptr是指向应用程序可能已经分配的图像数据的指针。有关host_ptr指向的缓冲区必须有多大的描述，请参阅下表。

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

• errcode_ret将返回相应的错误代码。如果errcode_ret为NULL，则不会返回任何错误代码。

The alignment requirements for data stored in image objects are described in Alignment of Application Data Types.

​应用程序数据类型的对齐中描述了存储在图像对象中的数据的对齐要求。

For all image types except CL_MEM_OBJECT_IMAGE1D_BUFFER, if the value specified for flags is 0, the default is used which is CL_MEM_READ_WRITE.

​对于除CL_MEM_OBJECT_IMAGE1D_BUFFER之外的所有图像类型，如果为标志指定的值为0，则使用默认值CL_MEM_READ_WRITE。

For CL_MEM_OBJECT_IMAGE1D_BUFFER image type, or an image created from another memory object (image or buffer), if the CL_MEM_READ_WRITE, CL_MEM_READ_ONLY or CL_MEM_WRITE_ONLY values are not specified in flags, they are inherited from the corresponding memory access qualifiers associated with mem_object. The CL_MEM_USE_HOST_PTR, CL_MEM_ALLOC_HOST_PTR and CL_MEM_COPY_HOST_PTR values cannot be specified in flags but are inherited from the corresponding memory access qualifiers associated with mem_object. If CL_MEM_COPY_HOST_PTR is specified in the memory access qualifier values associated with mem_object it does not imply any additional copies when the image is created from mem_object. If the CL_MEM_HOST_WRITE_ONLY, CL_MEM_HOST_READ_ONLY or CL_MEM_HOST_NO_ACCESS values are not specified in flags, they are inherited from the corresponding memory access qualifiers associated with mem_object.

​对于CL_MEM_OBJECT_IMAGE1D_BUFFER图像类型，或从另一个内存对象（图像或缓冲区）创建的图像，如果在标志中未指定CL_MEM_READ_WRITE、CL_MEM_READ_ONLY或CL_MEM_WRITE_ONLY值，则从与MEM_OBJECT相关联的相应内存访问限定符继承这些值。CL_MEM_USE_HOST_TR、CL_MEM_ALLOC_HOST_PTR和CL_MEM_COPY_HOST_PTR值不能在标志中指定，而是从与mem_object相关联的相应内存访问限定符继承而来。如果在与mem_object相关联的内存访问限定符值中指定了CL_MEM_COPY_HOST_PTR，则当从mem_objects创建图像时，这并不意味着有任何额外的副本。如果标志中未指定CL_MEM_HOST_WRITE_ONLY、CL_MEM_HOST_READ_ONLY或CL_MEM_HOST_NO_ACCESS值，则这些值将从与mem_object相关联的相应内存访问限定符中继承。

Mipmap Images

Mipmap图像

A mipmapped 1D image, 1D image array, 2D image, 2D image array or 3D image is created by specifying num_mip_levels to be a value greater than one in image_desc. The dimensions of a mipmapped image can be a power of two or a non-power of two. Each successively smaller mipmap level is half the size of the previous level, rounded down to the nearest integer.

通过在image_desc中将num_mip_levels指定为大于1的值来创建mipmated 1D图像、1D图像阵列、2D图像、2D图像阵列或3D图像。mipmated图像的维度可以是二次幂或非二次幂。每个连续较小的mipmap级别都是上一级别的一半大小，四舍五入到最接近的整数。

The following restrictions apply when mipmapped images are created with clCreateImage:

​使用clCreateImage创建mipmapped图像时，以下限制适用：

• CL_MEM_USE_HOST_PTR or CL_MEM_COPY_HOST_PTR cannot be specified if a mipmapped image is created.

• 如果创建了mipmap图像，则无法指定CL_MEM_USE_HOST_TR或CL_MEM_COPY_HOST_PTR。

• The host_ptr argument to clCreateImage must be a NULL value.

• ​clCreateImage的host_ptr参数必须为NULL值。

• Mip-mapped images cannot be created for CL_MEM_OBJECT_IMAGE1D_BUFFER images, depth images or multi-sampled (i.e. msaa) images.

• ​不能为CL_MEM_OBJECT_IMAGE1D_BUFFER图像、深度图像或多采样（即msaa）图像创建Mip映射图像。

Image Data in Host Memory

主机内存中的图像数据

For a 3D image or 2D image array, the image data specified by host_ptr is stored as a linear sequence of adjacent 2D image slices or 2D images respectively. Each 2D image is a linear sequence of adjacent scanlines. Each scanline is a linear sequence of image elements.

对于3D图像或2D图像阵列，由host_ptr指定的图像数据被分别存储为相邻2D图像切片或2D图像的线性序列。每个2D图像是相邻扫描线的线性序列。每条扫描线都是图像元素的线性序列。

For a 2D image, the image data specified by host_ptr is stored as a linear sequence of adjacent scanlines. Each scanline is a linear sequence of image elements.

对于2D图像，由host_ptr指定的图像数据被存储为相邻扫描线的线性序列。每条扫描线都是图像元素的线性序列。

For a 1D image array, the image data specified by host_ptr is stored as a linear sequence of adjacent 1D images. Each 1D image is stored as a single scanline which is a linear sequence of adjacent elements.

对于1D图像阵列，由host_ptr指定的图像数据被存储为相邻1D图像的线性序列。每个1D图像被存储为单个扫描线，该扫描线是相邻元素的线性序列。

For 1D image or 1D image buffer, the image data specified by host_ptr is stored as a single scanline which is a linear sequence of adjacent elements.

对于1D图像或1D图像缓冲器，由host_ptr指定的图像数据被存储为单个扫描线，该单个扫描线是相邻元素的线性序列。

Image elements are stored according to their image format as described in the Image Format Descriptor section.

​图像元素根据图像格式描述符部分中描述的图像格式进行存储。

Table 22. List of supported image creation properties

表22 支持的图像创建属性列表

Property 属性	Property Value 属性值	Description 描述
CL_MEM_DEVICE_HANDLE_LIST_KHR provided by the cl_khr_external_memory extension. 由cl_khr_external_memory扩展提供。	cl_device_id[]	Specifies the list of OpenCL devices (terminated with CL_MEM_DEVICE_HANDLE_LIST_END_KHR) to associate with the external memory handle. ​指定要与外部内存句柄关联的OpenCL设备的列表（以CL_MEM_DEVICE_HANDLE_LIST_END_KHR终止）。

If CL_MEM_DEVICE_HANDLE_LIST_KHR is not specified as part of properties, the memory object created by clCreateBufferWithProperties or clCreateImageWithProperties is by default accessible to all devices in the context.

​如果未将CL_MEM_DEVICE_HANDLE_LIST_KHR指定为属性的一部分，则默认情况下，上下文中的所有设备都可以访问clCreateBufferWithProperties或clCreateImageWithProperties创建的内存对象。

The properties used to create an image from an external memory handle are described for the corresponding extensions. When an image is created from an external memory handle, the flags used to specify usage information for the image must not include CL_MEM_USE_HOST_PTR, CL_MEM_ALLOC_HOST_PTR, or CL_MEM_COPY_HOST_PTR, and the host_ptr argument must be NULL. When images are created from an external memory handle, implementations may acquire information about image attributes such as format and layout at the time of creation. When such information is acquired at image creation time, it is used for the lifetime of the image object.

​用于从外部内存句柄创建图像的属性针对相应的扩展进行了描述。从外部内存句柄创建映像时，用于指定映像使用信息的标志不得包括CL_MEM_USE_HOST_PTR、CL_MEM_ALLOC_HOST_PTR或CL_MEM_COPY_HOST_PSTR，并且host_ptr参数必须为NULL。当从外部存储器句柄创建图像时，实现可以在创建时获取关于图像属性的信息，例如格式和布局。当在图像创建时获取这样的信息时，将其用于图像对象的寿命。

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

clCreateImage和clCreateImageWithProperties返回一个有效的非零图像对象，如果图像对象创建成功，则errcode_ret设置为CL_SUCCESS。否则，它们将返回一个NULL值，并在errcode_ret中返回以下错误值之一：

• CL_INVALID_CONTEXT if context is not a valid context.

• CL_INVALID_CONTEXT（如果上下文不是有效上下文）。

• CL_INVALID_PROPERTY if a property name in properties is not a supported property name, if the value specified for a supported property name is not valid, or if the same property name is specified more than once.

• CL_INVALID_PROPERTY如果属性中的属性名称不是支持的属性名称，如果为支持的属性名指定的值无效，或者如果多次指定相同的属性名。

• CL_INVALID_VALUE if values specified in flags are not valid.

• CL_INVALID_VALUE（如果标志中指定的值无效）。

• CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if values specified in image_format are not valid or if image_format is NULL.

• CL_INVALID_IMAGE_FORMAT_DESCRIPTOR如果在IMAGE_FORMAT中指定的值无效或IMAGE_FORMAT为NULL。

• CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if a 2D image is created from a buffer and the row pitch and base address alignment does not follow the rules described for creating a 2D image from a buffer.

• CL_INVALID_IMAGE_FORMAT_DESCRIPTOR，如果从缓冲器创建2D图像并且行间距和基址对齐不遵循为从缓冲器创建二维图像所描述的规则。

• CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if a 2D image is created from a 2D image object and the rules described above are not followed.

• CL_INVALID_IMAGE_FORMAT_DESCRIPTOR，如果从2D图像对象创建2D图像并且不遵循上述规则。

• CL_INVALID_IMAGE_DESCRIPTOR if values specified in image_desc are not valid or if image_desc is NULL.

• 如果image_desc中指定的值无效或image_desc为NULL，则CL_INVALID_IMAGE_DESCRIPTOR。

• CL_INVALID_IMAGE_SIZE if image dimensions specified in image_desc exceed the maximum image dimensions described in the Device Queries table for all devices in context.

• CL_INVALID_IMAGE_SIZE，如果在image_desc中指定的图像尺寸超过上下文中所有设备的设备查询表中描述的最大图像尺寸。

• 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_INVALID_HOST_PTR，如果在标志中设置了HOST_PTR为NULL且CL_MEM_USE_HOST_PTR或CL_MEM_COPY_HOST_PTR，或者如果HOST_PTR不为NULL但在标志中未设置CL_MEM_COPY_HOST_PTR或CL_MEM_USE_HOST_PTR。

• CL_INVALID_VALUE if an image is being created from another memory object (buffer or image) under one of the following circumstances: 1) mem_object was created with CL_MEM_WRITE_ONLY and flags specifies CL_MEM_READ_WRITE or CL_MEM_READ_ONLY, 2) mem_object was created with CL_MEM_READ_ONLY and flags specifies CL_MEM_READ_WRITE or CL_MEM_WRITE_ONLY, 3) flags specifies CL_MEM_USE_HOST_PTR or CL_MEM_ALLOC_HOST_PTR or CL_MEM_COPY_HOST_PTR.

• CL_INVALID_VALUE，如果在以下情况之一下从另一个内存对象（缓冲区或图像）创建图像：1）mem_object是用CL_MEM_WRITE_ONLY创建的，并且标志指定CL_MEM_READ_WRITE或CL_MEM_READ_ONLY；2）mem_oobject是用CL_MEM_READ_ONLY创建的，而且标志指定CL_MEM_READ_WRITE或CL_MEM_WRITE_ONLY；​
  3） 标志指定CL_MEM_USE_HOST_TR或CL_MEM_ALLOC_HOST_PTR或CL_MEM_COPY_HOST_PTR
  ​

• CL_INVALID_VALUE if an image is being created from another memory object (buffer or image) and mem_object was created with CL_MEM_HOST_WRITE_ONLY and flags specifies CL_MEM_HOST_READ_ONLY, or if mem_object was created with CL_MEM_HOST_READ_ONLY and flags specifies CL_MEM_HOST_WRITE_ONLY, or if mem_object was created with CL_MEM_HOST_NO_ACCESS and_flags_ specifies CL_MEM_HOST_READ_ONLY or CL_MEM_HOST_WRITE_ONLY.

• CL_INVALID_VALUE如果是从另一个内存对象（缓冲区或图像）创建图像，并且mem_object是用CL_MEM_HOST_WRITE_ONLY创建的，并且标志指定CL_MEM_HOST_READ_ONLY，或者mem_objects是用CL_MEM_HOST_WRITE_ONLY创建的并且标志指定CL _MEM_HOST_WRITE_ONLY；或者​
  如果mem_object是用CL_MEM_HOST_NO_ACCESS创建的并且_flags_指定CL_MEM_HOST_READ_ONLY或CL_MEM_HOST_WRITE_ONLY。
  ​

• CL_IMAGE_FORMAT_NOT_SUPPORTED if there are no devices in context that support image_format.

• CL_IMAGE_FORMAT_NOT_SUPPORTED（如果上下文中没有支持IMAGE_FORMAT的设备）。

• CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for image object.

• CL_MEM_OBJECT_ALLOCATION_FAILURE（如果为图像对象分配内存失败）。

• CL_INVALID_OPERATION if there are no devices in context that support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the Device Queries table is CL_FALSE).

• CL_INVALID_OPERATION（如果上下文中没有支持映像的设备）（即“设备查询”表中指定的CL_DEVICE_IMAGE_SUPPORT为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_RESOURCES，如果在设备上分配OpenCL实现所需的资源失败。

• CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

• CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。

• CL_INVALID_DEVICE

  • if a device identified by the property CL_MEM_DEVICE_HANDLE_LIST_KHR is not a valid device or is not associated with context, or

  • ​如果由属性CL_MEM_DEVICE_HANDLE_LIST_KHR标识的设备不是有效设备或与上下文无关，或者

  • if a device identified by property CL_MEM_DEVICE_HANDLE_LIST_KHR cannot import the requested external memory object type, or

  • ​如果由属性CL_MEM_DEVICE_HANDLE_LIST_KHR标识的设备无法导入请求的外部内存对象类型，或者

  • if CL_MEM_DEVICE_HANDLE_LIST_KHR is not specified as part of properties and one or more devices in context cannot import the requested external memory object type.

  • ​如果CL_MEM_DEVICE_HANDLE_LIST_KHR未指定为属性的一部分，并且上下文中的一个或多个设备无法导入请求的外部内存对象类型。

• CL_INVALID_VALUE

  • if properties includes a supported external memory handle and flags includes CL_MEM_USE_HOST_PTR, CL_MEM_ALLOC_HOST_PTR, or CL_MEM_COPY_HOST_PTR.

  • ​如果属性包括支持的外部内存句柄，并且标志包括CL_MEM_USE_HOST_PTR、CL_MEM_ALLOC_HOST_PSTR或CL_MEM_COPY_HOST_PTR。

• CL_INVALID_HOST_PTR

  • if properties includes a supported external memory handle and host_ptr is not NULL.

  • 如果属性包括支持的外部内存句柄并且host_ptr不为NULL。

• CL_INVALID_PROPERTY

  • if properties does not include a supported external memory handle and CL_MEM_DEVICE_HANDLE_LIST_KHR is specified as part of properties.

  • ​如果属性不包括支持的外部内存句柄，并且CL_MEM_DEVICE_HANDLE_LIST_KHR被指定为属性的一部分。

Table 23. Required host_ptr buffer sizes for images

表23 图像所需的host_ptr缓冲区大小

Image Type 图像类型	Size of buffer that host_ptr points to host_ptr指向的缓冲区大小
CL_MEM_OBJECT_IMAGE1D missing before version 1.2.	≥ image_row_pitch
CL_MEM_OBJECT_IMAGE1D_BUFFER missing before version 1.2.	≥ image_row_pitch
CL_MEM_OBJECT_IMAGE2D	≥ image_row_pitch × image_height
CL_MEM_OBJECT_IMAGE3D	≥ image_slice_pitch × image_depth
CL_MEM_OBJECT_IMAGE1D_ARRAY missing before version 1.2.	≥ image_slice_pitch × image_array_size
CL_MEM_OBJECT_IMAGE2D_ARRAY missing before version 1.2.	≥ image_slice_pitch × image_array_size

A 2D image object can be created using the following function

可以使用以下功能创建2D图像对象

// Provided by CL_VERSION_1_0
cl_mem clCreateImage2D(
    cl_context context,
    cl_mem_flags flags,
    const cl_image_format* image_format,
    size_t image_width,
    size_t image_height,
    size_t image_row_pitch,
    void* host_ptr,
    cl_int* errcode_ret);

clCreateImage2D is deprecated by version 1.2. clCreateImage2D已被1.2版本弃用。

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

• context是要在其上创建图像对象的有效OpenCL上下文。

• flags is a bit-field that is used to specify allocation and usage information about the image memory object being created and is described in the supported memory flag values table. If the value specified for flags is 0, the default is used which is CL_MEM_READ_WRITE.

• ​flags是用于指定关于正在创建的图像存储器对象的分配和使用信息的比特字段，并且在支持的存储器标志值表中进行描述。如果为标志指定的值为0，则使用默认值CL_MEM_READ_WRITE。

• image_format is a pointer to a structure that describes format properties of the image to be allocated. Refer to the Image Format Descriptor section for a detailed description of the image format descriptor.

• ​image_format是指向描述要分配的图像的格式属性的结构的指针。有关图像格式描述符的详细描述，请参阅“图像格式描述符”部分。

• image_width and image_height are the width and height of the image in pixels. These must be values greater than or equal to 1.

• image_width和image_height是以像素为单位的图像的宽度和高度。这些值必须大于或等于1。

• image_row_pitch is the scan-line pitch in bytes. This must be 0 if host_ptr is NULL and can be either 0 or ≥ image_width × size of element in bytes if host_ptr is not NULL. If host_ptr is not NULL and image_row_pitch is 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_row_pitch是以字节为单位的扫描线间距。如果host_ptr为NULL，则该值必须为0；如果host_ptr非NULL，则可以为0或≥image_width×元素大小（以字节为单位）。如果host_ptr不为NULL并且image_row_pitch为0，则image_row_pritch计算为image_width×元素大小（以字节为单位）。如果image_row_pitch不为0，则它必须是以字节为单位的图像元素大小的倍数。

• host_ptr is a pointer to the image data that may already be allocated by the application. Refer to the CL_MEM_OBJECT_IMAGE2D entry in the required host_ptr buffer size table for a description of how large the buffer that host_ptr points to must be. The image data specified by host_ptr is stored as a linear sequence of adjacent scanlines. Each scanline is a linear sequence of image elements. Image elements are stored according to their image format as described in the Image Format Descriptor section.

• ​host_ptr是指向应用程序可能已经分配的图像数据的指针。有关host_ptr指向的缓冲区必须有多大的描述，请参阅所需host_ptr缓冲区大小表中的CL_MEM_OBJECT_IMAGE2D条目。host_ptr指定的图像数据存储为相邻扫描线的线性序列。每条扫描线都是图像元素的线性序列。图像元素根据图像格式描述符部分中描述的图像格式进行存储。

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

• errcode_ret将返回相应的错误代码。如果errcode_ret为NULL，则不会返回任何错误代码。

clCreateImage2D 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:

clCreateImage2D返回创建的有效非零图像对象，如果图像对象创建成功，则errcode_ret设置为CL_SUCCESS。否则，它将返回一个NULL值，并在errcode_ret中返回以下错误值之一：

• CL_INVALID_CONTEXT if context is not a valid context.

• CL_INVALID_CONTEXT（如果上下文不是有效上下文）。

• CL_INVALID_VALUE if values specified in flags are not valid.

• CL_INVALID_VALUE（如果标志中指定的值无效）。

• CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if values specified in image_format are not valid or if image_format is NULL.

• CL_INVALID_IMAGE_FORMAT_DESCRIPTOR如果在IMAGE_FORMAT中指定的值无效或IMAGE_FORMAT为NULL。

• CL_INVALID_IMAGE_SIZE if image_width or image_height are 0 or if they exceed the maximum values specified in CL_DEVICE_IMAGE2D_MAX_WIDTH or CL_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_IMAGE_SIZE，如果image_width或image_height为0，或者如果它们分别超过上下文中所有设备的CL_DEVICE_IMAGE2D_MAX_WIDTH或CL_DEVICE_IMAGE2D_MAX_HEIGHT中指定的最大值，或者如果image_row_pitch指定的值不遵循上述参数描述中描述的规则。

• 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_INVALID_HOST_PTR，如果在标志中设置了HOST_PTR为NULL且CL_MEM_USE_HOST_PTR或CL_MEM_COPY_HOST_PTR，或者如果HOST_PTR不为NULL但在标志中未设置CL_MEM_COPY_HOST_PTR或CL_MEM_USE_HOST_PTR。

• CL_IMAGE_FORMAT_NOT_SUPPORTED if there are no devices in context that support image_format.

• CL_IMAGE_FORMAT_NOT_SUPPORTED（如果上下文中没有支持IMAGE_FORMAT的设备）。

• CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for image object.

• CL_MEM_OBJECT_ALLOCATION_FAILURE（如果为图像对象分配内存失败）。

• CL_INVALID_OPERATION if there are no devices in context that support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the Device Queries table is CL_FALSE).

• CL_INVALID_OPERATION（如果上下文中没有支持映像的设备）（即“设备查询”表中指定的CL_DEVICE_IMAGE_SUPPORT为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_RESOURCES，如果在设备上分配OpenCL实现所需的资源失败。

• CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

• CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。

A 3D image object can be created using the following function

可以使用以下功能创建3D图像对象

// Provided by CL_VERSION_1_0
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);

clCreateImage3D is deprecated by version 1.2. clCreateImage3D已被1.2版本弃用。

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

• context是要在其上创建图像对象的有效OpenCL上下文。

• flags is a bit-field that is used to specify allocation and usage information about the image memory object being created and is described in the supported memory flag values table. If the value specified for flags is 0, the default is used which is CL_MEM_READ_WRITE.

• ​flags是用于指定关于正在创建的图像存储器对象的分配和使用信息的比特字段，并且在支持的存储器标志值表中进行描述。如果为标志指定的值为0，则使用默认值CL_MEM_READ_WRITE。

• image_format is a pointer to a structure that describes format properties of the image to be allocated. Refer to the Image Format Descriptor section for a detailed description of the image format descriptor.

• ​image_format是指向描述要分配的图像的格式属性的结构的指针。有关图像格式描述符的详细描述，请参阅“图像格式描述符”部分。

• image_width and image_height are the width and height of the image in pixels. These must be values greater than or equal to 1.

• image_width和image_height是以像素为单位的图像的宽度和高度。这些值必须大于或等于1。

• image_depth is the depth of the image in pixels. For clCreateImage3D, this must be a value > 1.

• ​image_depth是以像素为单位的图像深度。对于clCreateImage3D，该值必须大于1。

• image_row_pitch is the scan-line pitch in bytes. This must be 0 if host_ptr is NULL and can be either 0 or ≥ image_width × size of element in bytes if host_ptr is not NULL. If host_ptr is not NULL and image_row_pitch is 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_row_pitch是以字节为单位的扫描线间距。如果host_ptr为NULL，则该值必须为0；如果host_ptr非NULL，则可以为0或≥image_width×元素大小（以字节为单位）。如果host_ptr不为NULL并且image_row_pitch为0，则image_row_pritch计算为image_width×元素大小（以字节为单位）。如果image_row_pitch不为0，则它必须是以字节为单位的图像元素大小的倍数。

• image_slice_pitch is the size in bytes of each 2D slice in the 3D image. This must be 0 if host_ptr is NULL and can be 0 or ≥ image_row_pitch × image_height if host_ptr is not NULL. If host_ptr is not NULL and image_slice_pitch is 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.

• image_slice_pitch是3D图像中的每个2D切片的以字节为单位的大小。如果host_ptr为NULL，则此值必须为0；如果host_ptr不为NULL，此值可以为0或≥image_row_pitch×image_height。如果host_ptr不为NULL并且image_slice_pitch为0，则image_slice_pitch将计算为image_row_pitch×image_height。如果image_slice_pitch不为0，则它必须是image_row_pitch的倍数。

• host_ptr is a pointer to the image data that may already be allocated by the application. Refer to the CL_MEM_OBJECT_IMAGE3D entry in the required host_ptr buffer size table for a description of how large the buffer that host_ptr points to must be. The image data specified by host_ptr is stored as a linear sequence of adjacent 2D slices. Each scanline is a linear sequence of image elements. Image elements are stored according to their image format as described in the Image Format Descriptor section.

• ​host_ptr是指向应用程序可能已经分配的图像数据的指针。有关host_ptr指向的缓冲区必须有多大的描述，请参阅所需host_ptr缓冲区大小表中的CL_MEM_OBJECT_IMAGE3D条目。host_ptr指定的图像数据存储为相邻2D切片的线性序列。每条扫描线都是图像元素的线性序列。图像元素根据图像格式描述符部分中描述的图像格式进行存储。

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

• errcode_ret将返回相应的错误代码。如果errcode_ret为NULL，则不会返回任何错误代码。

clCreateImage3D 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:

clCreateImage3D返回创建的有效非零图像对象，如果图像对象创建成功，则errcode_ret设置为CL_SUCCESS。否则，它将返回一个NULL值，并在errcode_ret中返回以下错误值之一：

• CL_INVALID_CONTEXT if context is not a valid context.

• CL_INVALID_CONTEXT（如果上下文不是有效上下文）。

• CL_INVALID_VALUE if values specified in flags are not valid.

• CL_INVALID_VALUE（如果标志中指定的值无效）。

• CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if values specified in image_format are not valid or if image_format is NULL.

• CL_INVALID_IMAGE_FORMAT_DESCRIPTOR如果在IMAGE_FORMAT中指定的值无效或IMAGE_FORMAT为NULL。

• CL_INVALID_IMAGE_SIZE if image_width or image_height are 0 or if image_depth ≤ 1, or if they exceed the maximum 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_IMAGE_SIZE如果image_width或image_height为0，或者image_depth≤1，或者如果它们超过了上下文中所有设备分别在CL_DEVICE_IMAGE3D_MAX_WIDTH、CL_DEVICE_IMAGE3D_MAX_HEIGHT或CL_DEVICE_IMAGE3D_MAX_DEPTH中指定的最大值，或者如果image_row_pitch和image_slice_pitch指定的值不遵循上述参数描述中描述的规则。

• 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_INVALID_HOST_PTR，如果在标志中设置了HOST_PTR为NULL且CL_MEM_USE_HOST_PTR或CL_MEM_COPY_HOST_PTR，或者如果HOST_PTR不为NULL但在标志中未设置CL_MEM_COPY_HOST_PTR或CL_MEM_USE_HOST_PTR。

• CL_IMAGE_FORMAT_NOT_SUPPORTED if there are no devices in context that support image_format.

• CL_IMAGE_FORMAT_NOT_SUPPORTED（如果上下文中没有支持IMAGE_FORMAT的设备）。

• CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for image object.

• CL_MEM_OBJECT_ALLOCATION_FAILURE（如果为图像对象分配内存失败）。

• CL_INVALID_OPERATION if there are no devices in context that support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the Device Queries table is CL_FALSE).

• CL_INVALID_OPERATION（如果上下文中没有支持映像的设备）（即“设备查询”表中指定的CL_DEVICE_IMAGE_SUPPORT为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_RESOURCES，如果在设备上分配OpenCL实现所需的资源失败。

• CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

• CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。