Tutorial

| Home | Libraries | People | FAQ | More

## Tutorial

### Hello World

The hello world example gives a simple application that prints the name of the default compute device on the system.

The `boost::compute::system` class provides access to the OpenCL platforms and devices present on the host system.

Compute devices are represented with the `device` class.

    #include <iostream>

    #include <boost/compute/core.hpp>

    namespace compute = boost::compute;

    int main()
    {
        // get the default device
        compute::device device = compute::system::default_device();

        // print the device's name
        std::cout << "hello from " << device.name() << std::endl;

        return 0;
    }

### Transferring Data

Before any computation occurs, data must be transferred from the host to the compute device. The generic `copy()` function provides a simple interface for transfering data and the generic `vector<T>` class provides a container for storing data on a compute device.

The following example shows how to transfer data from an array on the host to a `vector<T>` on the device and then back to a separate `std::vector<T>` on the host. At the end of the example both `host_array` and `host_vector` contain the same values which were copied through the memory on the compute device.

    #include <vector>

    #include <boost/compute/algorithm/copy.hpp>
    #include <boost/compute/container/vector.hpp>

    namespace compute = boost::compute;

    int main()
    {
        // get default device and setup context
        compute::device device = compute::system::default_device();
        compute::context context(device);
        compute::command_queue queue(context, device);

        // create data array on host
        int host_data[] = { 1, 3, 5, 7, 9 };

        // create vector on device
        compute::vector<int> device_vector(5, context);

        // copy from host to device
        compute::copy(
            host_data, host_data + 5, device_vector.begin(), queue
        );

        // create vector on host
        std::vector<int> host_vector(5);

        // copy data back to host
        compute::copy(
            device_vector.begin(), device_vector.end(), host_vector.begin(), queue
        );

        return 0;
    }

### Transforming Data

The following example shows how to calculate the square-root of a vector of `float`s on a compute device using the `transform()` function.

    #include <vector>
    #include <algorithm>

    #include <boost/compute/algorithm/transform.hpp>
    #include <boost/compute/container/vector.hpp>
    #include <boost/compute/functional/math.hpp>

    namespace compute = boost::compute;

    int main()
    {
        // get default device and setup context
        compute::device device = compute::system::default_device();
        compute::context context(device);
        compute::command_queue queue(context, device);

        // generate random data on the host
        std::vector<float> host_vector(10000);
        std::generate(host_vector.begin(), host_vector.end(), rand);

        // create a vector on the device
        compute::vector<float> device_vector(host_vector.size(), context);

        // transfer data from the host to the device
        compute::copy(
            host_vector.begin(), host_vector.end(), device_vector.begin(), queue
        );

        // calculate the square-root of each element in-place
        compute::transform(
            device_vector.begin(),
            device_vector.end(),
            device_vector.begin(),
            compute::sqrt<float>(),
            queue
        );

        // copy values back to the host
        compute::copy(
            device_vector.begin(), device_vector.end(), host_vector.begin(), queue
        );

        return 0;
    }