1 //---------------------------------------------------------------------------//
2 // Copyright (c) 2013 Kyle Lutz <kyle.r.lutz@gmail.com>
4 // Distributed under the Boost Software License, Version 1.0
5 // See accompanying file LICENSE_1_0.txt or copy at
6 // http://www.boost.org/LICENSE_1_0.txt
8 // See http://boostorg.github.com/compute for more information.
9 //---------------------------------------------------------------------------//
11 #ifndef BOOST_COMPUTE_CONTEXT_HPP
12 #define BOOST_COMPUTE_CONTEXT_HPP
16 #include <boost/throw_exception.hpp>
18 #include <boost/compute/config.hpp>
19 #include <boost/compute/device.hpp>
20 #include <boost/compute/exception/opencl_error.hpp>
21 #include <boost/compute/detail/assert_cl_success.hpp>
27 /// \brief A compute context.
29 /// The context class represents a compute context.
31 /// A context object manages a set of OpenCL resources including memory
32 /// buffers and program objects. Before allocating memory on the device or
33 /// executing kernels you must set up a context object.
35 /// To create a context for the default device on the system:
37 /// // get the default compute device
38 /// boost::compute::device gpu = boost::compute::system::default_device();
40 /// // create a context for the device
41 /// boost::compute::context context(gpu);
44 /// Once a context is created, memory can be allocated using the buffer class
45 /// and kernels can be executed using the command_queue class.
47 /// \see device, command_queue
51 /// Create a null context object.
57 /// Creates a new context for \p device with \p properties.
59 /// \see_opencl_ref{clCreateContext}
60 explicit context(const device &device,
61 const cl_context_properties *properties = 0)
63 BOOST_ASSERT(device.id() != 0);
65 cl_device_id device_id = device.id();
68 m_context = clCreateContext(properties, 1, &device_id, 0, 0, &error);
71 BOOST_THROW_EXCEPTION(opencl_error(error));
75 /// Creates a new context for \p devices with \p properties.
77 /// \see_opencl_ref{clCreateContext}
78 explicit context(const std::vector<device> &devices,
79 const cl_context_properties *properties = 0)
81 BOOST_ASSERT(!devices.empty());
85 m_context = clCreateContext(
87 static_cast<cl_uint>(devices.size()),
88 reinterpret_cast<const cl_device_id *>(&devices[0]),
95 BOOST_THROW_EXCEPTION(opencl_error(error));
99 /// Creates a new context object for \p context. If \p retain is
100 /// \c true, the reference count for \p context will be incremented.
101 explicit context(cl_context context, bool retain = true)
104 if(m_context && retain){
105 clRetainContext(m_context);
109 /// Creates a new context object as a copy of \p other.
110 context(const context &other)
111 : m_context(other.m_context)
114 clRetainContext(m_context);
118 /// Copies the context object from \p other to \c *this.
119 context& operator=(const context &other)
123 clReleaseContext(m_context);
126 m_context = other.m_context;
129 clRetainContext(m_context);
136 #ifndef BOOST_COMPUTE_NO_RVALUE_REFERENCES
137 /// Move-constructs a new context object from \p other.
138 context(context&& other) BOOST_NOEXCEPT
139 : m_context(other.m_context)
144 /// Move-assigns the context from \p other to \c *this.
145 context& operator=(context&& other) BOOST_NOEXCEPT
148 clReleaseContext(m_context);
151 m_context = other.m_context;
156 #endif // BOOST_COMPUTE_NO_RVALUE_REFERENCES
158 /// Destroys the context object.
162 BOOST_COMPUTE_ASSERT_CL_SUCCESS(
163 clReleaseContext(m_context)
168 /// Returns the underlying OpenCL context.
169 cl_context& get() const
171 return const_cast<cl_context &>(m_context);
174 /// Returns the device for the context. If the context contains multiple
175 /// devices, the first is returned.
176 device get_device() const
178 std::vector<device> devices = get_devices();
180 if(devices.empty()) {
184 return devices.front();
187 /// Returns a vector of devices for the context.
188 std::vector<device> get_devices() const
190 return get_info<std::vector<device> >(CL_CONTEXT_DEVICES);
193 /// Returns information about the context.
195 /// \see_opencl_ref{clGetContextInfo}
197 T get_info(cl_context_info info) const
199 return detail::get_object_info<T>(clGetContextInfo, m_context, info);
204 typename detail::get_object_info_type<context, Enum>::type
207 /// Returns \c true if the context is the same as \p other.
208 bool operator==(const context &other) const
210 return m_context == other.m_context;
213 /// Returns \c true if the context is different from \p other.
214 bool operator!=(const context &other) const
216 return m_context != other.m_context;
220 operator cl_context() const
226 cl_context m_context;
229 /// \internal_ define get_info() specializations for context
230 BOOST_COMPUTE_DETAIL_DEFINE_GET_INFO_SPECIALIZATIONS(context,
231 ((cl_uint, CL_CONTEXT_REFERENCE_COUNT))
232 ((std::vector<cl_device_id>, CL_CONTEXT_DEVICES))
233 ((std::vector<cl_context_properties>, CL_CONTEXT_PROPERTIES))
236 #ifdef BOOST_COMPUTE_CL_VERSION_1_1
237 BOOST_COMPUTE_DETAIL_DEFINE_GET_INFO_SPECIALIZATIONS(context,
238 ((cl_uint, CL_CONTEXT_NUM_DEVICES))
240 #endif // BOOST_COMPUTE_CL_VERSION_1_1
242 } // end compute namespace
243 } // end boost namespace
245 #endif // BOOST_COMPUTE_CONTEXT_HPP