clCreateImage2D

Creates a 2D image object.

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)

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

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

errcode_ret

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

Errors

clCreateImage2D returns a valid non-zero image object and 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 or image_height are 0 or if they exceed 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_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

clCreateImage3D, 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.