Include examples on how to use opencl3::memory::Image

[Dainerx]

Hello,

I discovered this new crate recently, I couldn't find no examples online nor on this repository on how to work with images. A minimalist example that creates an opencl image using Image::create would be helpful enough.

I suggest an example that performs a simple copy given an opencl image as input and image buffer as output.

__kernel void copy_image(__read_only image2d_t input, __write_only image2d_t output) {
    int2 pos = (int2)(get_global_id(0), get_global_id(1));
    float4 pixel = read_imagef(input, CLK_NORMALIZED_COORDS_FALSE, pos);
    write_imagef(output, pos, pixel);
}

[kenba]

Hi Ossama, I agree that an image example would be useful. Please feel free to create an example file and submit it as a pull request.

[Draghtnod]

Have you found out how to use Image?
I can't get the most simplistic Example to work. :(

unsafe {
    let mut image = Image::create(
        &self.context,
        CL_MEM_READ_ONLY,
        &cl_image_format {
            image_channel_order: CL_RGB,
            image_channel_data_type: CL_UNSIGNED_INT8,
        },
        &cl_image_desc {
            image_type: CL_MEM_OBJECT_IMAGE2D,
            image_width: 1200 as usize,
            image_height: 1200 as usize,
            image_depth: 1,
            image_array_size: 1,
            image_row_pitch: 0,
            image_slice_pitch: 0,
            num_mip_levels: 0,
            num_samples: 0,
            buffer: ptr::null_mut(),
        },
        ptr::null_mut(),
    )
    .map_err(|error| format!("Failed to create Image: {}", error))?;

    let origin: [usize; 3] = [0, 0, 0];
    let region: [usize; 3] = [1200, 1200, 1];
    let fill_color: [cl_uint; 4] = [127, 80, 10, 0];

    let wait_event = queue
        .enqueue_fill_image(
            &mut image,
            fill_color.as_ptr() as *const c_void,
            origin.as_ptr(),
            region.as_ptr(),
            &[],
        )
        .map_err(|error| format!("Failed to fill image: {}", error))?;
    wait_event
        .wait()
        .map_err(|error| format!("Failed to wait for fill event: {}", error))?;
}

Failed to fill image: CL_OUT_OF_RESOURCES

[kenba]

No Ossama, I have found out how to use Image as I don't use OpenCL for image processing.
However, a simple google search for "opencl image processing example" found a number of examples in C that you could use.
Also, if you search for opencl in crates.io you can find other rust implementations with image examples.

[Dainerx]

@kenba I've found severals examples written in C++ too. I've tried to replicate the same behavior using your crate, I faced many errors. Similar to @Draghtnod, I could not get the simplest example to work.

I am currently using ocl, which works fine. I'll keep trying with your crate, in case I get something working, I'll fill a PR under examples.

[kenba]

Thank you Ossama (and sorry to @Draghtnod for misidentifying you!).
Please submit an example PR whether working or not, since it sounds like it's a bug in this crate and it would be good to identify and fix it.

[Draghtnod]

Alright I got it working! This is not a bug. It's just tricky to use.

First clue was that enqueue_nd_range threw a CL_OUT_OF_RESOURCES. According to spec here this could be an issue with missing/limited image support.

Which led me to check CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS as documented here. Turns out that my OpenCL implementation does not behave according to spec, because CL_DEVICE_IMAGE_SUPPORT is CL_TRUE, but CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS is actually 0. So just using read-only and write-only images worked and led to the next issue.

Checking context.get_supported_image_formats() unveiled, that my system actually does not support CL_RGB. Changing that to CL_RGBA made it finally work!

[kenba]

Thank you @Draghtnod.
I'm relieved to hear that it wasn't a bug in the library, but I'm sorry to hear about the problems that you encountered.
However, it doesn't surprise me. OpenCL is very dependant on the implementation and one of the most common environments (i.e. Nvidia) has historically been very poor at supporting OpenCL.
Congratulations on persevering and getting your example to work. And thanks again for providing your example via PR #66.
I'll close this issue after thay PR is merged into the next release.

[Draghtnod]

@kenba Happy to help. Maybe this helps other people to get started.

[Dainerx]

Amazing! thank you @Draghtnod!

@kenba now since I have the image working, can I create another example where you execute an openCL script on the image? For instance I can submit a PR on how to normalize the pixels of an image.

[kenba]

Yes please @Dainerx