ccl_image_wrapper.c

Go to the documentation of this file.

/*
 * This file is part of cf4ocl (C Framework for OpenCL).
 *
 * cf4ocl is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * cf4ocl is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with cf4ocl. If not, see
 * <http://www.gnu.org/licenses/>.
 * */

#include "ccl_image_wrapper.h"
#include "ccl_buffer_wrapper.h"
#include "_ccl_memobj_wrapper.h"
#include "_ccl_defs.h"

struct ccl_image {

    CCLMemObj mo;

};

static cl_mem ccl_image_new_deprecated(CCLContext* ctx, cl_mem_flags flags,
    const cl_image_format* image_format, const CCLImageDesc* img_dsc,
    void* host_ptr, CCLErr** err) {

    /* OpenCL image object. */
    cl_mem image = NULL;
    /* OpenCL function status. */
    cl_int ocl_status;

    CCL_BEGIN_IGNORE_DEPRECATIONS

    /* Check what type of image to create. */
    if (img_dsc->image_type == CL_MEM_OBJECT_IMAGE2D) {

        /* Create a 2D image. */
        image = clCreateImage2D(ccl_context_unwrap(ctx), flags,
            image_format, img_dsc->image_width, img_dsc->image_height,
            img_dsc->image_row_pitch, host_ptr, &ocl_status);

        ccl_if_err_create_goto(*err, CCL_OCL_ERROR,
            CL_SUCCESS != ocl_status, ocl_status, error_handler,
            "%s: unable to create image with clCreateImage2D() " \
            "(OpenCL error %d: %s).",
            CCL_STRD, ocl_status, ccl_err(ocl_status));

    } else if (img_dsc->image_type == CL_MEM_OBJECT_IMAGE3D) {

        /* Create a 3D image. */
        image = clCreateImage3D(ccl_context_unwrap(ctx), flags,
            image_format, img_dsc->image_width, img_dsc->image_height,
            img_dsc->image_depth, img_dsc->image_row_pitch,
            img_dsc->image_slice_pitch, host_ptr, &ocl_status);

        ccl_if_err_create_goto(*err, CCL_OCL_ERROR,
            CL_SUCCESS != ocl_status, ocl_status, error_handler,
            "%s: unable to create image with clCreateImage3D() " \
            "(OpenCL error %d: %s).",
            CCL_STRD, ocl_status, ccl_err(ocl_status));

    } else {

        /* Unknown or unsupported image type. */
        ccl_if_err_create_goto(*err, CCL_ERROR, CL_TRUE,
            CCL_ERROR_UNSUPPORTED_OCL, error_handler,
            "%s: unknown or unsuported image type (%x)", CCL_STRD,
            img_dsc->image_type);

    }

    CCL_END_IGNORE_DEPRECATIONS

    /* If we got here, everything is OK. */
    g_assert(err == NULL || *err == NULL);
    goto finish;

error_handler:

    /* If we got here there was an error, verify that it is so. */
    g_assert(err == NULL || *err != NULL);

finish:

    /* Return OpenCL image object. */
    return image;

}

CCL_EXPORT
CCLImage* ccl_image_new_wrap(cl_mem mem_object) {

    return (CCLImage*) ccl_wrapper_new(
        CCL_IMAGE, (void*) mem_object, sizeof(CCLImage));

}

CCL_EXPORT
void ccl_image_destroy(CCLImage* img) {

    ccl_wrapper_unref((CCLWrapper*) img, sizeof(CCLImage),
        (ccl_wrapper_release_fields) ccl_memobj_release_fields,
        (ccl_wrapper_release_cl_object) clReleaseMemObject, NULL);

}

CCL_EXPORT
CCLImage* ccl_image_new_v(CCLContext* ctx, cl_mem_flags flags,
    const cl_image_format* image_format, const CCLImageDesc* img_dsc,
    void* host_ptr, CCLErr** err) {

    /* Make sure ctx is not NULL. */
    g_return_val_if_fail(ctx != NULL, NULL);
    /* Make sure img_dsc is not NULL. */
    g_return_val_if_fail(img_dsc != NULL, NULL);
    /* Make sure err is NULL or it is not set. */
    g_return_val_if_fail(err == NULL || *err == NULL, NULL);

    /* Image wrapper object. */
    CCLImage* img = NULL;
    /* OpenCL image object. */
    cl_mem image;
    /* Internal error handling object. */
    CCLErr* err_internal = NULL;

#ifdef CL_VERSION_1_2

    /* OpenCL function status. */
    cl_int ocl_status;
    /* OpenCL platform version. */
    double ocl_ver;

    /* Get OpenCL platform version. */
    ocl_ver = ccl_context_get_opencl_version(ctx, &err_internal);
    ccl_if_err_propagate_goto(err, err_internal, error_handler);

    /* Create image depending on OpenCL platform version.*/
    if (ocl_ver >= 120) {
        /* OpenCL is >= 1.2, use "new" API. */

        /* OpenCL image descriptor. Initialize it with data from
         * img_dsc (CCLImageDesc), unwrapping the wrapped buffer, if
         * any. */
        cl_mem memory_object = (img_dsc->memobj != NULL)
            ? ccl_memobj_unwrap(img_dsc->memobj) : NULL;
        const cl_image_desc image_desc = {
            .image_type = img_dsc->image_type,
            .image_width = img_dsc->image_width,
            .image_height = img_dsc->image_height,
            .image_depth = img_dsc->image_depth,
            .image_array_size = img_dsc->image_array_size,
            .image_row_pitch = img_dsc->image_row_pitch,
            .image_slice_pitch = img_dsc->image_slice_pitch,
            .num_mip_levels = img_dsc->num_mip_levels,
            .num_samples = img_dsc->num_samples,
#ifdef CL_VERSION_2_0
            .mem_object = memory_object
#else
            .buffer = memory_object
#endif
        };

        /* Create image. */
        image = clCreateImage(ccl_context_unwrap(ctx), flags,
            image_format, &image_desc, host_ptr, &ocl_status);
        ccl_if_err_create_goto(*err, CCL_OCL_ERROR,
            CL_SUCCESS != ocl_status, ocl_status, error_handler,
            "%s: unable to create image with clCreateImage() " \
            "(OpenCL error %d: %s).",
            CCL_STRD, ocl_status, ccl_err(ocl_status));

    } else {
        /* OpenCL is < 1.2, use "old" API. */

        image = ccl_image_new_deprecated(ctx, flags, image_format,
            img_dsc, host_ptr, &err_internal);
        ccl_if_err_propagate_goto(err, err_internal, error_handler);

    }

#else

    /* Create image. */
    image = ccl_image_new_deprecated(ctx, flags, image_format,
        img_dsc, host_ptr, &err_internal);
    ccl_if_err_propagate_goto(err, err_internal, error_handler);

#endif

    /* Wrap image. */
    img = ccl_image_new_wrap(image);

    /* If we got here, everything is OK. */
    g_assert(err == NULL || *err == NULL);
    goto finish;

error_handler:

    /* If we got here there was an error, verify that it is so. */
    g_assert(err == NULL || *err != NULL);

finish:

    /* Return image wrapper. */
    return img;

}

CCL_EXPORT
CCLImage* ccl_image_new(CCLContext* ctx, cl_mem_flags flags,
    const cl_image_format* image_format, void* host_ptr, CCLErr** err,
    ...) {

    /* Make sure ctx is not NULL. */
    g_return_val_if_fail(ctx != NULL, NULL);
    /* Make sure err is NULL or it is not set. */
    g_return_val_if_fail(err == NULL || *err == NULL, NULL);

    /* The va_list, which represents the variable argument list. */
    va_list args_va;
    /* A key. */
    const char* key;
    /* The image description object, initialized to zeros. */
    CCLImageDesc image_dsc = CCL_IMAGE_DESC_BLANK;

    /* Initialize the va_list. */
    va_start(args_va, err);

    /* Check if any arguments are given, and if so, populate
     * image_dsc. */
    while ((key = va_arg(args_va, const char*)) != NULL) {

        if (g_strcmp0(key, "image_type") == 0) {
            image_dsc.image_type = va_arg(args_va, cl_mem_object_type);
        } else if (g_strcmp0(key, "image_width") == 0) {
            image_dsc.image_width = va_arg(args_va, size_t);
        } else if (g_strcmp0(key, "image_height") == 0) {
            image_dsc.image_height = va_arg(args_va, size_t);
        } else if (g_strcmp0(key, "image_depth") == 0) {
            image_dsc.image_depth = va_arg(args_va, size_t);
        } else if (g_strcmp0(key, "image_array_size") == 0) {
            image_dsc.image_array_size = va_arg(args_va, size_t);
        } else if (g_strcmp0(key, "image_row_pitch") == 0) {
            image_dsc.image_row_pitch = va_arg(args_va, size_t);
        } else if (g_strcmp0(key, "image_slice_pitch") == 0) {
            image_dsc.image_slice_pitch = va_arg(args_va, size_t);
        } else if (g_strcmp0(key, "num_mip_levels") == 0) {
            image_dsc.num_mip_levels = va_arg(args_va, cl_uint);
        } else if (g_strcmp0(key, "num_samples") == 0) {
            image_dsc.num_samples = va_arg(args_va, cl_uint);
        } else if (g_strcmp0(key, "memobj") == 0) {
            image_dsc.memobj = va_arg(args_va, CCLMemObj*);
        } else {
            g_set_error(err, CCL_ERROR, CCL_ERROR_ARGS,
                "%s: unknown key '%s'", CCL_STRD, key);
            va_end(args_va);
            return NULL;
        }
    }

    /* Close the va_list. */
    va_end(args_va);

    /* Create the image using the vector version of this function. */
    return ccl_image_new_v(ctx, flags, image_format,
        (const CCLImageDesc*) &image_dsc, host_ptr, err);

}

CCL_EXPORT
CCLEvent* ccl_image_enqueue_read(CCLImage* img, CCLQueue* cq,
    cl_bool blocking_read, const size_t* origin, const size_t* region,
    size_t row_pitch, size_t slice_pitch, void *ptr,
    CCLEventWaitList* evt_wait_lst, CCLErr** err) {

    /* Make sure cq is not NULL. */
    g_return_val_if_fail(cq != NULL, NULL);
    /* Make sure img is not NULL. */
    g_return_val_if_fail(img != NULL, NULL);
    /* Make sure err is NULL or it is not set. */
    g_return_val_if_fail(err == NULL || *err == NULL, NULL);

    /* OpenCL function status. */
    cl_int ocl_status;
    /* OpenCL event object. */
    cl_event event = NULL;
    /* Event wrapper object. */
    CCLEvent* evt = NULL;

    /* Read image from device into host. */
    ocl_status = clEnqueueReadImage(ccl_queue_unwrap(cq),
        ccl_memobj_unwrap(img), blocking_read, origin, region,
        row_pitch, slice_pitch, ptr,
        ccl_event_wait_list_get_num_events(evt_wait_lst),
        ccl_event_wait_list_get_clevents(evt_wait_lst), &event);
    ccl_if_err_create_goto(*err, CCL_OCL_ERROR,
        CL_SUCCESS != ocl_status, ocl_status, error_handler,
        "%s: unable to enqueue an image read (OpenCL error %d: %s).",
        CCL_STRD, ocl_status, ccl_err(ocl_status));

    /* Wrap event and associate it with the respective command queue.
     * The event object will be released automatically when the command
     * queue is released. */
    evt = ccl_queue_produce_event(cq, event);

    /* Clear event wait list. */
    ccl_event_wait_list_clear(evt_wait_lst);

    /* If we got here, everything is OK. */
    g_assert(err == NULL || *err == NULL);
    goto finish;

error_handler:
    /* If we got here there was an error, verify that it is so. */
    g_assert(err == NULL || *err != NULL);

    /* An error occurred, return NULL to signal it. */
    evt = NULL;

finish:

    /* Return event. */
    return evt;

}

CCL_EXPORT
CCLEvent* ccl_image_enqueue_write(CCLImage* img, CCLQueue* cq,
    cl_bool blocking_write, const size_t* origin, const size_t* region,
    size_t input_row_pitch, size_t input_slice_pitch, void *ptr,
    CCLEventWaitList* evt_wait_lst, CCLErr** err) {

    /* Make sure cq is not NULL. */
    g_return_val_if_fail(cq != NULL, NULL);
    /* Make sure img is not NULL. */
    g_return_val_if_fail(img != NULL, NULL);
    /* Make sure err is NULL or it is not set. */
    g_return_val_if_fail(err == NULL || *err == NULL, NULL);

    /* OpenCL function status. */
    cl_int ocl_status;
    /* OpenCL event object. */
    cl_event event = NULL;
    /* Event wrapper object. */
    CCLEvent* evt = NULL;

    /* Write image to device from host. */
    ocl_status = clEnqueueWriteImage(ccl_queue_unwrap(cq),
        ccl_memobj_unwrap(img), blocking_write, origin, region,
        input_row_pitch, input_slice_pitch, ptr,
        ccl_event_wait_list_get_num_events(evt_wait_lst),
        ccl_event_wait_list_get_clevents(evt_wait_lst), &event);
    ccl_if_err_create_goto(*err, CCL_OCL_ERROR,
        CL_SUCCESS != ocl_status, ocl_status, error_handler,
        "%s: unable to enqueue an image write (OpenCL error %d: %s).",
        CCL_STRD, ocl_status, ccl_err(ocl_status));

    /* Wrap event and associate it with the respective command queue.
     * The event object will be released automatically when the command
     * queue is released. */
    evt = ccl_queue_produce_event(cq, event);

    /* Clear event wait list. */
    ccl_event_wait_list_clear(evt_wait_lst);

    /* If we got here, everything is OK. */
    g_assert(err == NULL || *err == NULL);
    goto finish;

error_handler:
    /* If we got here there was an error, verify that it is so. */
    g_assert(err == NULL || *err != NULL);

    /* An error occurred, return NULL to signal it. */
    evt = NULL;

finish:

    /* Return event. */
    return evt;

}

CCL_EXPORT
CCLEvent* ccl_image_enqueue_copy(CCLImage* src_img, CCLImage* dst_img,
    CCLQueue* cq, const size_t* src_origin, const size_t* dst_origin,
    const size_t* region, CCLEventWaitList* evt_wait_lst,
    CCLErr** err) {

    /* Make sure cq is not NULL. */
    g_return_val_if_fail(cq != NULL, NULL);
    /* Make sure src_img is not NULL. */
    g_return_val_if_fail(src_img != NULL, NULL);
    /* Make sure dst_img is not NULL. */
    g_return_val_if_fail(dst_img != NULL, NULL);
    /* Make sure err is NULL or it is not set. */
    g_return_val_if_fail(err == NULL || *err == NULL, NULL);

    /* OpenCL function status. */
    cl_int ocl_status;
    /* OpenCL event object. */
    cl_event event = NULL;
    /* Event wrapper object. */
    CCLEvent* evt = NULL;

    /* Copy image. */
    ocl_status = clEnqueueCopyImage(ccl_queue_unwrap(cq),
        ccl_memobj_unwrap(src_img), ccl_memobj_unwrap(dst_img),
        src_origin, dst_origin, region,
        ccl_event_wait_list_get_num_events(evt_wait_lst),
        ccl_event_wait_list_get_clevents(evt_wait_lst), &event);
    ccl_if_err_create_goto(*err, CCL_OCL_ERROR,
        CL_SUCCESS != ocl_status, ocl_status, error_handler,
        "%s: unable to enqueue an image copy (OpenCL error %d: %s).",
        CCL_STRD, ocl_status, ccl_err(ocl_status));

    /* Wrap event and associate it with the respective command queue.
     * The event object will be released automatically when the command
     * queue is released. */
    evt = ccl_queue_produce_event(cq, event);

    /* Clear event wait list. */
    ccl_event_wait_list_clear(evt_wait_lst);

    /* If we got here, everything is OK. */
    g_assert(err == NULL || *err == NULL);
    goto finish;

error_handler:
    /* If we got here there was an error, verify that it is so. */
    g_assert(err == NULL || *err != NULL);

    /* An error occurred, return NULL to signal it. */
    evt = NULL;

finish:

    /* Return event. */
    return evt;

}

CCL_EXPORT
CCLEvent* ccl_image_enqueue_copy_to_buffer(CCLImage* src_img,
    CCLBuffer* dst_buf, CCLQueue* cq, const size_t *src_origin,
    const size_t *region, size_t dst_offset,
    CCLEventWaitList* evt_wait_lst, CCLErr** err) {

    /* Make sure cq is not NULL. */
    g_return_val_if_fail(cq != NULL, NULL);
    /* Make sure src_img is not NULL. */
    g_return_val_if_fail(src_img != NULL, NULL);
    /* Make sure dst_buf is not NULL. */
    g_return_val_if_fail(dst_buf != NULL, NULL);
    /* Make sure err is NULL or it is not set. */
    g_return_val_if_fail(err == NULL || *err == NULL, NULL);

    /* OpenCL function status. */
    cl_int ocl_status;
    /* OpenCL event object. */
    cl_event event = NULL;
    /* Event wrapper object. */
    CCLEvent* evt = NULL;

    /* Copy image to buffer. */
    ocl_status = clEnqueueCopyImageToBuffer(ccl_queue_unwrap(cq),
        ccl_memobj_unwrap(src_img), ccl_memobj_unwrap(dst_buf),
        src_origin, region, dst_offset,
        ccl_event_wait_list_get_num_events(evt_wait_lst),
        ccl_event_wait_list_get_clevents(evt_wait_lst), &event);
    ccl_if_err_create_goto(*err, CCL_OCL_ERROR,
        CL_SUCCESS != ocl_status, ocl_status, error_handler,
        "%s: unable to copy image to buffer (OpenCL error %d: %s).",
        CCL_STRD, ocl_status, ccl_err(ocl_status));

    /* Wrap event and associate it with the respective command queue.
     * The event object will be released automatically when the command
     * queue is released. */
    evt = ccl_queue_produce_event(cq, event);

    /* Clear event wait list. */
    ccl_event_wait_list_clear(evt_wait_lst);

    /* If we got here, everything is OK. */
    g_assert(err == NULL || *err == NULL);
    goto finish;

error_handler:
    /* If we got here there was an error, verify that it is so. */
    g_assert(err == NULL || *err != NULL);

    /* An error occurred, return NULL to signal it. */
    evt = NULL;

finish:

    /* Return event. */
    return evt;

}

CCL_EXPORT
void* ccl_image_enqueue_map(CCLImage* img, CCLQueue* cq,
    cl_bool blocking_map, cl_map_flags map_flags, const size_t* origin,
    const size_t* region, size_t *image_row_pitch,
    size_t *image_slice_pitch, CCLEventWaitList* evt_wait_lst,
    CCLEvent** evt, CCLErr** err) {

    /* Make sure cq is not NULL. */
    g_return_val_if_fail(cq != NULL, NULL);
    /* Make sure img is not NULL. */
    g_return_val_if_fail(img != NULL, NULL);
    /* Make sure err is NULL or it is not set. */
    g_return_val_if_fail(err == NULL || *err == NULL, NULL);

    cl_int ocl_status;
    cl_event event = NULL;
    CCLEvent* evt_inner = NULL;
    void* ptr = NULL;

    /* Perform image map. */
    ptr = clEnqueueMapImage(ccl_queue_unwrap(cq),
        ccl_memobj_unwrap(img), blocking_map, map_flags,
        origin, region, image_row_pitch, image_slice_pitch,
        ccl_event_wait_list_get_num_events(evt_wait_lst),
        ccl_event_wait_list_get_clevents(evt_wait_lst),
        &event, &ocl_status);
    ccl_if_err_create_goto(*err, CCL_OCL_ERROR,
        CL_SUCCESS != ocl_status, ocl_status, error_handler,
        "%s: unable to map image (OpenCL error %d: %s).",
        CCL_STRD, ocl_status, ccl_err(ocl_status));

    /* Wrap event and associate it with the respective command queue.
     * The event object will be released automatically when the command
     * queue is released. */
    evt_inner = ccl_queue_produce_event(cq, event);
    if (evt != NULL)
        *evt = evt_inner;

    /* Clear event wait list. */
    ccl_event_wait_list_clear(evt_wait_lst);

    /* If we got here, everything is OK. */
    g_assert(err == NULL || *err == NULL);
    goto finish;

error_handler:
    /* If we got here there was an error, verify that it is so. */
    g_assert(err == NULL || *err != NULL);

    /* An error occurred, return NULL to signal it. */
    ptr = NULL;

finish:

    /* Return host pointer. */
    return ptr;

}

CCL_EXPORT
CCLEvent* ccl_image_enqueue_fill(CCLImage* img, CCLQueue* cq,
    const void *fill_color, const size_t *origin, const size_t *region,
    CCLEventWaitList* evt_wait_lst, CCLErr** err) {

    /* Make sure cq is not NULL. */
    g_return_val_if_fail(cq != NULL, NULL);
    /* Make sure img is not NULL. */
    g_return_val_if_fail(img != NULL, NULL);
    /* Make sure err is NULL or it is not set. */
    g_return_val_if_fail(err == NULL || *err == NULL, NULL);

    /* OpenCL function status. */
    cl_int ocl_status;
    /* OpenCL event object. */
    cl_event event = NULL;
    /* Event wrapper object. */
    CCLEvent* evt = NULL;
    /* OpenCL version of the underlying platform. */
    double ocl_ver;
    /* Internal error handling object. */
    CCLErr* err_internal = NULL;

#ifndef CL_VERSION_1_2

    CCL_UNUSED(fill_color);
    CCL_UNUSED(origin);
    CCL_UNUSED(region);
    CCL_UNUSED(evt_wait_lst);
    CCL_UNUSED(ocl_status);
    CCL_UNUSED(event);
    CCL_UNUSED(ocl_ver);
    CCL_UNUSED(err_internal);

    /* If cf4ocl was not compiled with support for OpenCL >= 1.2, always throw
     * error. */
    ccl_if_err_create_goto(*err, CCL_ERROR, TRUE,
        CCL_ERROR_UNSUPPORTED_OCL, error_handler,
        "%s: Image fill requires cf4ocl to be deployed with "
        "support for OpenCL version 1.2 or newer.",
        CCL_STRD);

#else

    /* Check that context platform is >= OpenCL 1.2 */
    ocl_ver = ccl_memobj_get_opencl_version(
        (CCLMemObj*) img, &err_internal);
    ccl_if_err_propagate_goto(err, err_internal, error_handler);

    /* If OpenCL version is not >= 1.2, throw error. */
    ccl_if_err_create_goto(*err, CCL_ERROR, ocl_ver < 120,
        CCL_ERROR_UNSUPPORTED_OCL, error_handler,
        "%s: Image fill requires OpenCL version 1.2 or newer.",
        CCL_STRD);

    /* Fill image. */
    ocl_status = clEnqueueFillImage(ccl_queue_unwrap(cq),
        ccl_memobj_unwrap(img), fill_color, origin, region,
        ccl_event_wait_list_get_num_events(evt_wait_lst),
        ccl_event_wait_list_get_clevents(evt_wait_lst), &event);
    ccl_if_err_create_goto(*err, CCL_OCL_ERROR,
        CL_SUCCESS != ocl_status, ocl_status, error_handler,
        "%s: unable to enqueue a fill image command (OpenCL error %d: %s).",
        CCL_STRD, ocl_status, ccl_err(ocl_status));

    /* Wrap event and associate it with the respective command queue.
     * The event object will be released automatically when the command
     * queue is released. */
    evt = ccl_queue_produce_event(cq, event);

    /* Clear event wait list. */
    ccl_event_wait_list_clear(evt_wait_lst);

#endif

    /* If we got here, everything is OK. */
    g_assert(err == NULL || *err == NULL);
    goto finish;

error_handler:
    /* If we got here there was an error, verify that it is so. */
    g_assert(err == NULL || *err != NULL);

    /* An error occurred, return NULL to signal it. */
    evt = NULL;

finish:

    /* Return event. */
    return evt;

}