~ubuntu-branches/ubuntu/trusty/khronos-opencl-man/trusty

« back to all changes in this revision

Viewing changes to clCreateContext.xml

  • Committer: Package Import Robot
  • Author(s): Mathieu Malaterre
  • Date: 2013-05-21 18:06:15 UTC
  • Revision ID: package-import@ubuntu.com-20130521180615-6e0s2n3pai95ip2f
Tags: upstream-1.0~svn21772
ImportĀ upstreamĀ versionĀ 1.0~svn21772

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
<?xml version="1.0" encoding="UTF-8"?>
 
2
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
 
3
              "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
 
4
 
 
5
<refentry>
 
6
    <refentryinfo>
 
7
        <keywordset><keyword>clCreateContext</keyword></keywordset>
 
8
    </refentryinfo>
 
9
    <refmeta>
 
10
        <refentrytitle>clCreateContext</refentrytitle>
 
11
        <refmiscinfo>
 
12
            <copyright>
 
13
                <year>2007-2011</year>
 
14
                <holder>The Khronos Group Inc.
 
15
 Permission is hereby granted, free of charge, to any person obtaining a
 
16
copy of this software and/or associated documentation files (the
 
17
"Materials"), to deal in the Materials without restriction, including
 
18
without limitation the rights to use, copy, modify, merge, publish,
 
19
distribute, sublicense, and/or sell copies of the Materials, and to
 
20
permit persons to whom the Materials are furnished to do so, subject to
 
21
the condition that this copyright notice and permission notice shall be included
 
22
in all copies or substantial portions of the Materials.</holder>
 
23
            </copyright>
 
24
        </refmiscinfo>
 
25
        <manvolnum>3</manvolnum>
 
26
    </refmeta>
 
27
 
 
28
<!-- ================================ SYNOPSIS -->
 
29
 
 
30
    <refnamediv id="clCreateContext">
 
31
        <refname>clCreateContext</refname>
 
32
        <refpurpose>Creates an OpenCL context.</refpurpose>
 
33
    </refnamediv>
 
34
 
 
35
    <refsynopsisdiv xmlns:xlink="http://www.w3.org/1999/xlink"><title></title>
 
36
        <funcsynopsis>
 
37
            <funcprototype><funcdef><link xlink:href="abstractDataTypes.html">cl_context</link> <function>clCreateContext</function></funcdef>
 
38
                <paramdef>const <link xlink:href="enums.html#cl_context_properties">cl_context_properties</link><parameter>*properties</parameter></paramdef>
 
39
                <paramdef><link xlink:href="scalarDataTypes.html">cl_uint</link><parameter>num_devices</parameter></paramdef>
 
40
                <paramdef>const <link xlink:href="abstractDataTypes.html">cl_device_id</link><parameter>*devices</parameter></paramdef>
 
41
 
 
42
                <paramdef><link xlink:href="scalarDataTypes.html">(void</link> CL_CALLBACK <parameter>*pfn_notify)</parameter>
 
43
                        <funcparams><literallayout>const <link xlink:href="scalarDataTypes.html">char</link> *errinfo,
 
44
                        const <link xlink:href="scalarDataTypes.html">void</link> *private_info, <link xlink:href="otherDataTypes.html">size_t</link> cb,
 
45
                        <link xlink:href="scalarDataTypes.html">void</link> *user_data</literallayout></funcparams></paramdef>
 
46
                <paramdef><link xlink:href="scalarDataTypes.html">void</link><parameter>*user_data</parameter></paramdef>
 
47
                <paramdef><link xlink:href="scalarDataTypes.html">cl_int</link><parameter>*errcode_ret</parameter></paramdef>
 
48
           </funcprototype>
 
49
        </funcsynopsis>
 
50
    </refsynopsisdiv>
 
51
 
 
52
<!-- ================================ DESCRIPTION  -->
 
53
 
 
54
    <refsect1 id="description"><title>Description</title>
 
55
        <para>
 
56
          An OpenCL context is created with one or more devices. Contexts are used by the
 
57
          OpenCL runtime for managing objects such as command-queues, memory, program and kernel
 
58
          objects and for executing kernels on one or more devices specified in the context.
 
59
        </para>
 
60
    </refsect1>
 
61
 
 
62
<!-- ================================ PARAMETERS -->
 
63
 
 
64
    <refsect1 xmlns:xlink="http://www.w3.org/1999/xlink" id="parameters"><title>Parameters</title>
 
65
        <variablelist>
 
66
 
 
67
        <!-- ================================ PARAMETER TABLE (OPTIONAL) -->
 
68
        <varlistentry>
 
69
            <term>properties</term>
 
70
            <listitem>
 
71
                <para>
 
72
                  <!-- core spec pg 54 --> Specifies a list of context property names and
 
73
                  their corresponding values. Each property name is immediately followed
 
74
                  by the corresponding desired value. The list is terminated with 0.
 
75
                  <varname>properties</varname> can be NULL in which case the platform
 
76
                  that is selected is implementation-defined. The list of supported
 
77
                  <varname>properties</varname> is described in the table below.
 
78
                </para>
 
79
 
 
80
                <para>
 
81
                  <!-- ext. spec p. 85, section 9.10.5; and
 
82
                  ext. spec p. 99, section 9.11.5 --> If the extension
 
83
                  <citerefentry><refentrytitle>cl_khr_dx9_media_sharing</refentrytitle></citerefentry>
 
84
                  is enabled, then <varname>properties</varname> specifies a list of context
 
85
                  property names and their corresponding values. Each property is followed
 
86
                  immediately by the corresponding desired value. The list is terminated with
 
87
                  zero. If a property is not specified in <varname>properties</varname>, then its
 
88
                  default value (listed in the table below) is used (it is said to be specified
 
89
                  implicitly).  If <varname>properties</varname> is NULL or empty (points to
 
90
                  a list whose first value is zero), all attributes take on their default values.
 
91
                </para>
 
92
 
 
93
                <para><!-- ext spec. p. 68, section 9.9.5 -->
 
94
                  If the extension
 
95
                  <citerefentry><refentrytitle>cl_khr_d3d10_sharing</refentrytitle></citerefentry>
 
96
                  is enabled, then <varname>properties</varname> specifies a list of context
 
97
                  property names and their corresponding values.  Each property is followed
 
98
                  immediately by the corresponding desired value.  The list is terminated
 
99
                  with zero.  if a property is not specified in <varname>properties</varname>,
 
100
                  then its default value is used (it is said to be specified implicitly). If
 
101
                  <varname>properties</varname> is NULL or empty (points to a list whose first
 
102
                  value is zero), all attributes take on their default value.
 
103
                </para>
 
104
 
 
105
                <para>
 
106
                  If the extension
 
107
                  <citerefentry><refentrytitle>cl_khr_gl_sharing</refentrytitle></citerefentry>
 
108
                  is enabled, then <varname>properties</varname> points to an attribute list,
 
109
                  which is a array of ordered &lt;attribute name, value> pairs terminated with
 
110
                  zero. If an attribute is not specified in <varname>properties</varname>,
 
111
                  then its default value is used (it is said to be specified implicitly). If
 
112
                  <varname>properties</varname> is NULL or empty (points to a list whose first
 
113
                  value is zero), all attributes take on their default values..
 
114
                </para>
 
115
 
 
116
                <!-- table 4.5 -->
 
117
                <informaltable frame="all">
 
118
                <tgroup cols="3" align="left" colsep="1" rowsep="1">
 
119
                    <colspec colname="col1" colnum="1" />
 
120
                    <colspec colname="col2" colnum="2" />
 
121
                    <colspec colname="col3" colnum="3" />
 
122
                    <thead>
 
123
                        <row>
 
124
                        <entry>cl_context_properties enum</entry>
 
125
                        <entry>Property value</entry>
 
126
                        <entry>Description</entry>
 
127
                        </row>
 
128
                    </thead>
 
129
 
 
130
                    <tbody>
 
131
                        <row>
 
132
                            <entry><constant>CL_CONTEXT_PLATFORM</constant></entry>
 
133
                            <entry><link xlink:href="abstractDataTypes.html">cl_platform_id</link></entry>
 
134
                            <entry>Specifies the platform to use.</entry>
 
135
                        </row>
 
136
 
 
137
                        <row>
 
138
                            <entry><constant>CL_CONTEXT_INTEROP_USER_SYNC</constant></entry>
 
139
                            <entry><link xlink:href="enums.html#cl_bool">cl_bool</link></entry>
 
140
                            <entry>
 
141
                                Specifies whether the user is responsible for synchronization between OpenCL
 
142
                                and other APIs. Please refer to the specific sections in the OpenCL 1.2 extension specification
 
143
                                that describe sharing with other APIs for restrictions on using this flag.
 
144
 
 
145
                                <para>
 
146
                                  If <constant>CL_CONTEXT_INTEROP_USER_</constant> SYNC is not
 
147
                                  specified, a default of <constant>CL_FALSE</constant> is assumed.
 
148
                                </para>
 
149
                            </entry>
 
150
                        </row>
 
151
 
 
152
                        <row>
 
153
                            <entry><constant>CL_CONTEXT_D3D10_DEVICE_KHR</constant></entry>
 
154
                            <entry>ID3D10Device*</entry>
 
155
                            <entry>
 
156
                              If the
 
157
                              <citerefentry><refentrytitle>cl_khr_d3d10_sharing</refentrytitle></citerefentry>
 
158
                              extension is enabled, specifies the <type>ID3D10Device</type>*
 
159
                              to use for Direct3D 10 interoperability. The default value is NULL.
 
160
                            </entry>
 
161
                        </row>
 
162
 
 
163
                        <row><!-- ext. spec p. 39, section 9.6.3 -->
 
164
                            <entry><constant>CL_GL_CONTEXT_KHR</constant></entry>
 
165
                            <entry>0, OpenGL context handle</entry>
 
166
                            <entry>
 
167
                              OpenGL context to associated
 
168
                              the OpenCL context with (available if the
 
169
                              <citerefentry><refentrytitle>cl_khr_gl_sharing</refentrytitle></citerefentry>
 
170
                              extension is enabled)
 
171
                            </entry>
 
172
                        </row>
 
173
 
 
174
                        <row><!-- ext. spec p. 39-40, section 9.6.3 -->
 
175
                            <entry><constant>CL_EGL_DISPLAY_KHR</constant></entry>
 
176
                            <entry> <constant>EGL_NO_DISPLAY</constant>, <type>EGLDisplay</type> handle </entry>
 
177
                            <entry>
 
178
                              EGLDisplay an OpenGL context was
 
179
                              created with respect to (available if the
 
180
                              <citerefentry><refentrytitle>cl_khr_gl_sharing</refentrytitle></citerefentry>
 
181
                              extension is enabled)
 
182
                            </entry>
 
183
                        </row>
 
184
 
 
185
                        <row><!-- ext. spec p. 39-40, section 9.6.3 -->
 
186
                            <entry><constant>CL_GLX_DISPLAY_KHR</constant></entry>
 
187
                            <entry>None, X handle</entry>
 
188
                            <entry>
 
189
                              X Display an OpenGL context was
 
190
                              created with respect to (available if the
 
191
                              <citerefentry><refentrytitle>cl_khr_gl_sharing</refentrytitle></citerefentry>
 
192
                              extension is enabled)
 
193
                            </entry>
 
194
                        </row>
 
195
 
 
196
                        <row><!-- ext. spec pp. 39-41, section 9.6.3 -->
 
197
                            <entry><constant>CL_CGL_SHAREGROUP_KHR</constant></entry>
 
198
                            <entry>0, CGL share group handle</entry>
 
199
                            <entry>
 
200
                              CGL share group to associate the OpenCL context with (available if the
 
201
                              <citerefentry><refentrytitle>cl_khr_gl_sharing</refentrytitle></citerefentry>
 
202
                              extension is enabled)
 
203
                            </entry>
 
204
                        </row>
 
205
 
 
206
                        <row><!-- ext. spec pp. 39-40, section 9.6.3 -->
 
207
                            <entry><constant>CL_WGL_HDC_KHR</constant></entry>
 
208
                            <entry>0, HDC handle</entry>
 
209
                            <entry>
 
210
                              HDC an OpenGL context was created with respect to (available if the
 
211
                              <citerefentry><refentrytitle>cl_khr_gl_sharing</refentrytitle></citerefentry>
 
212
                              extension is enabled)
 
213
                            </entry>
 
214
                        </row>
 
215
 
 
216
                        <row><!-- ext. spec p. 84, section 9.10.4; and p. 86, section 9.10.5 -->
 
217
                            <entry><constant>CL_CONTEXT_ADAPTER_D3D9_KHR</constant></entry>
 
218
                            <entry>IDirect3DDevice9 *</entry>
 
219
                            <entry>
 
220
                              Specifies an <type>IDirect3DDevice9</type>
 
221
                              to use for D3D9 interop (if the
 
222
                              <citerefentry><refentrytitle>cl_khr_dx9_media_sharing</refentrytitle></citerefentry>
 
223
                              extension is supported).
 
224
                            </entry>
 
225
                        </row>
 
226
 
 
227
                        <row><!-- ext. spec p. 84, section 9.10.4; and p. 86, section 9.10.5 -->
 
228
                            <entry><constant>CL_CONTEXT_ADAPTER_D3D9EX_KHR</constant></entry>
 
229
                            <entry>IDirect3DDeviceEx*</entry>
 
230
                            <entry>
 
231
                              Specifies an <type>IDirect3DDevice9Ex</type>
 
232
                              to use for D3D9 interop (if the
 
233
                              <citerefentry><refentrytitle>cl_khr_dx9_media_sharing</refentrytitle></citerefentry>
 
234
                              extension is supported).
 
235
                            </entry>
 
236
                        </row>
 
237
 
 
238
                        <row><!-- ext. spec p. 84, section 9.10.4; and p. 86, section 9.10.5 -->
 
239
                            <entry><constant>CL_CONTEXT_ADAPTER_DXVA_KHR</constant></entry>
 
240
                            <entry>IDXVAHD_Device *</entry>
 
241
                            <entry>
 
242
                              Specifies an <type>IDXVAHD_Device</type>
 
243
                              to use for DXVA interop (if the
 
244
                              <citerefentry><refentrytitle>cl_khr_dx9_media_sharing</refentrytitle></citerefentry>
 
245
                              extension is supported).
 
246
                            </entry>
 
247
                        </row>
 
248
 
 
249
                        <row><!-- ext. spec p. 98, section 9.11.4; and p. 99, section 9.11.5 -->
 
250
                            <entry><constant>CL_CONTEXT_D3D11_DEVICE_KHR</constant></entry>
 
251
                            <entry>ID3D11Device *</entry>
 
252
                            <entry>
 
253
                              Specifies the <type>ID3D11Device</type> * to use for Direct3D 11
 
254
                              interoperability. The default value is NULL.
 
255
                            </entry>
 
256
                        </row>
 
257
                    </tbody>
 
258
                </tgroup>
 
259
                </informaltable>
 
260
        </listitem>
 
261
    </varlistentry>
 
262
 
 
263
<!-- ================================ END PARAMETER TABLE  -->
 
264
 
 
265
        <varlistentry>
 
266
            <term><varname>num_devices</varname></term>
 
267
            <listitem>
 
268
                <para>
 
269
                    The number of devices specified in the <varname>devices</varname> argument.
 
270
                </para>
 
271
            </listitem>
 
272
        </varlistentry>
 
273
 
 
274
        <varlistentry>
 
275
            <term><varname>devices</varname></term>
 
276
            <listitem>
 
277
                <para>
 
278
                  A pointer to a list of unique devices returned by
 
279
                  <citerefentry><refentrytitle>clGetDeviceIDs</refentrytitle></citerefentry>
 
280
                  or sub-devices created by
 
281
                  <citerefentry><refentrytitle>clCreateSubDevices</refentrytitle></citerefentry>
 
282
                  for a platform.
 
283
                </para>
 
284
            </listitem>
 
285
        </varlistentry>
 
286
 
 
287
        <varlistentry>
 
288
            <term><varname>pfn_notify</varname></term>
 
289
            <listitem>
 
290
                <para>
 
291
                  A callback function that can be registered by the application. This callback
 
292
                  function will be used by the OpenCL implementation to report information
 
293
                  on errors during context creation as well as errors that occur at runtime
 
294
                  in this context.  This callback function may be called asynchronously by
 
295
                  the OpenCL implementation.  It is the application's responsibility to ensure
 
296
                  that the callback function is thread-safe. If <varname>pfn_notify</varname>
 
297
                  is NULL, no callback function is registered.  The parameters to this callback
 
298
                  function are:
 
299
                </para>
 
300
 
 
301
                <para><varname>errinfo</varname> is a pointer to an error string.</para>
 
302
 
 
303
                <para>
 
304
                  <varname>private_info</varname> and <varname>cb</varname> represent a pointer
 
305
                  to binary data that is returned by the OpenCL implementation that can be used
 
306
                  to log additional information helpful in debugging the error.
 
307
                </para>
 
308
 
 
309
                <para><varname>user_data</varname> is a pointer to user supplied data.</para>
 
310
 
 
311
                <para>
 
312
                  NOTE: There are a number of cases where error notifications need to be
 
313
                  delivered due to an error that occurs outside a context. Such notifications
 
314
                  may not be delivered through the <varname>pfn_notify</varname> callback. Where
 
315
                  these notifications go is implementation-defined.
 
316
                </para>
 
317
            </listitem>
 
318
        </varlistentry>
 
319
 
 
320
        <varlistentry>
 
321
            <term><varname>user_data</varname></term>
 
322
            <listitem>
 
323
                <para>
 
324
                  Passed as the <varname>user_data</varname> argument when
 
325
                  <varname>pfn_notify</varname> is called. <varname>user_data</varname> can
 
326
                  be NULL.
 
327
                </para>
 
328
            </listitem>
 
329
        </varlistentry>
 
330
 
 
331
        <varlistentry>
 
332
            <term><varname>errcode_ret</varname></term>
 
333
            <listitem>
 
334
                <para>
 
335
                  Returns an appropriate error code. If <varname>errcode_ret</varname> is NULL,
 
336
                  no error code is returned.
 
337
                </para>
 
338
            </listitem>
 
339
        </varlistentry>
 
340
 
 
341
        </variablelist>
 
342
    </refsect1>
 
343
 
 
344
<!-- ================================ NOTES  -->
 
345
 
 
346
    <refsect1 id="notes"><title>Notes</title>
 
347
        <para>
 
348
          <function>clCreateContext</function> and
 
349
          <citerefentry><refentrytitle>clCreateContextFromType</refentrytitle></citerefentry>
 
350
          perform an implicit retain. This is very helpful for 3rd party libraries, which
 
351
          typically get a context passed to them by the application.  However, it is possible
 
352
          that the application may delete the context without informing the library.  Allowing
 
353
          functions to attach to (i.e. retain) and release a context solves the problem of a
 
354
          context being used by a library no longer being valid.
 
355
        </para>
 
356
    </refsect1>
 
357
 
 
358
<!-- ================================ ERRORS  -->
 
359
 
 
360
    <refsect1 id="errors"><title>Errors</title>
 
361
      <para>
 
362
        <function>clCreateContext</function> returns a valid non-zero context and
 
363
        <varname>errcode_ret</varname> is set to <errorname>CL_SUCCESS</errorname> if the
 
364
        context is created  successfully. Otherwise, it returns NULL value with the following
 
365
        error values returned in <varname>errcode_ret</varname>:
 
366
      </para>
 
367
 
 
368
      <itemizedlist mark="disc">
 
369
        <listitem>
 
370
          <errorname>CL_INVALID_PLATFORM</errorname> if <varname>properties</varname>
 
371
          is NULL and no platform could be selected or if platform value specified
 
372
          in <varname>properties</varname> is not a valid platform. (If the extension
 
373
          <citerefentry><refentrytitle>cl_khr_gl_sharing</refentrytitle></citerefentry>
 
374
          is enabled, then this error is replaced with
 
375
          <constant>CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR</constant>; see below.)
 
376
        </listitem>
 
377
 
 
378
        <listitem><!-- core spec p. 55, section 4.4; and ext spec p. 42, section 9.6.4 -->
 
379
          <errorname>CL_INVALID_PROPERTY</errorname> if context property name in
 
380
          <varname>properties</varname> is not a supported property name, if the
 
381
          value specified for a supported property name is not valid, or if the
 
382
          same property name is specified more than once. However if the extension
 
383
          <citerefentry><refentrytitle>cl_khr_gl_sharing</refentrytitle></citerefentry> is
 
384
          enabled, then <constant>CL_INVALID_PROPERTY</constant> is returned if an attribute
 
385
          name other than those listed in the table for <varname>properties</varname>
 
386
          above or if <constant>CL_CONTEXT_INTEROP_USER_SYNC</constant> is specified in
 
387
          <varname>properties</varname>.
 
388
        </listitem>
 
389
 
 
390
        <listitem><!-- ext spec p. 42, section 9.6.4 -->
 
391
          <errorname>CL_INVALID_PROPERTY</errorname> if an attribute name other than those
 
392
          specified in table 4.5 or if <constant>CL_CONTEXT_INTEROP_USER_SYNC</constant> is
 
393
          specified in properties.
 
394
        </listitem>
 
395
 
 
396
        <listitem>
 
397
          <errorname>CL_INVALID_VALUE</errorname> if <varname>devices</varname> is NULL; if
 
398
          <varname>num_devices</varname> is equal to zero; or if <varname>pfn_notify</varname>
 
399
          is NULL but <varname>user_data</varname> is not NULL.
 
400
        </listitem>
 
401
 
 
402
        <listitem>
 
403
           <errorname>CL_INVALID_DEVICE</errorname> if <varname>devices</varname> contains an invalid device.
 
404
        </listitem>
 
405
 
 
406
        <listitem>
 
407
          <errorname>CL_INVALID_OPERATION</errorname> if Direct3D 10 interoperability is
 
408
          specified by setting <constant>CL_INVALID_D3D10_DEVICE_KHR</constant> to a non-NULL
 
409
          value, and interoperability with another graphics API is also specified (if the
 
410
          <citerefentry><refentrytitle>cl_khr_d3d10_sharing</refentrytitle></citerefentry>
 
411
          extension is enabled).
 
412
        </listitem>
 
413
 
 
414
        <listitem>
 
415
          <errorname>CL_DEVICE_NOT_AVAILABLE</errorname> if a device in <varname>devices</varname>
 
416
          is currently not available even though the device was returned by
 
417
          <citerefentry><refentrytitle>clGetDeviceIDs</refentrytitle></citerefentry>.
 
418
        </listitem>
 
419
 
 
420
        <listitem>
 
421
          <errorname>CL_OUT_OF_RESOURCES</errorname> if there is a failure to allocate resources
 
422
          required by the OpenCL implementation on the device.
 
423
        </listitem>
 
424
 
 
425
        <listitem>
 
426
          <errorname>CL_OUT_OF_HOST_MEMORY</errorname> if there is a failure to allocate
 
427
          resources required by the OpenCL implementation on the host.
 
428
        </listitem>
 
429
 
 
430
        <listitem>
 
431
          <errorname>CL_INVALID_D3D10_DEVICE_KHR</errorname> if the Direct3D
 
432
          10 device specified for interoperability is not compatible with
 
433
          the devices against which the context is to be created (if the
 
434
          <citerefentry><refentrytitle>cl_khr_d3d10_sharing</refentrytitle></citerefentry>
 
435
          extension is enabled).
 
436
        </listitem>
 
437
 
 
438
        <listitem>
 
439
          <errorname>CL_INVALID_D3D10_DEVICE_KHR</errorname> if the value of the property
 
440
          <constant>CL_CONTEXT_D3D10_DEVICE_KHR</constant> is non-NULL and does not specify
 
441
          a valid Direct3D 10 device with which the <varname>cl_device_ids</varname>
 
442
          against which this context is to be created may interoperate (if the
 
443
          <citerefentry><refentrytitle>cl_khr_d3d10_sharing</refentrytitle></citerefentry>
 
444
          extension is enabled).
 
445
        </listitem>
 
446
 
 
447
        <listitem><!-- ext. spec p. 39, section 9.6.3 -->
 
448
          <errorname>CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR</errorname> when an invalid OpenGL
 
449
          context or share group object handle is specified in <varname>properties</varname> (only
 
450
          if the <citerefentry><refentrytitle>cl_khr_gl_sharing</refentrytitle></citerefentry>
 
451
          extension is enabled).
 
452
        </listitem>
 
453
 
 
454
        <listitem>
 
455
          <!-- ext spec. p. 40, section 9.6.4 -->
 
456
          <errorname>CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR</errorname> if no OpenGL or
 
457
          OpenGL ES context or share group is specified in the attribute list given to
 
458
          <citerefentry><refentrytitle>clCreateContext</refentrytitle></citerefentry>
 
459
          and any of the commands in section 9.7 are called. (if the
 
460
          <citerefentry><refentrytitle>cl_khr_gl_sharing</refentrytitle></citerefentry> extension
 
461
          is enabled)
 
462
        </listitem>
 
463
 
 
464
        <listitem><!-- ext spec. p. 41, section 9.6.4 -->
 
465
            <errorname>CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR</errorname> if the
 
466
            <citerefentry><refentrytitle>cl_khr_gl_sharing</refentrytitle></citerefentry>
 
467
            extension is enabled and if a context was specified by any of the following means:
 
468
 
 
469
            <itemizedlist mark="disc">
 
470
                <listitem>
 
471
                  A context specified for an EGL-based OpenGL ES or OpenGL implementation
 
472
                  by setting the attributes <constant>CL_GL_CONTEXT_KHR</constant> and
 
473
                  <constant>CL_EGL_DISPLAY_KHR</constant>.
 
474
                </listitem>
 
475
 
 
476
                <listitem>
 
477
                  A context was specified for a GLX-based OpenGL implementation by
 
478
                  setting the attributes <constant>CL_GL_CONTEXT_KHR</constant> and
 
479
                  <constant>CL_GLX_DISPLAY_KHR</constant>.
 
480
                </listitem>
 
481
 
 
482
                <listitem>
 
483
                  A context was specified for a WGL-based OpenGL implementation by
 
484
                  setting the attributes <constant>CL_GL_CONTEXT_KHR</constant> and
 
485
                  <constant>CL_WGL_HDC_KHR</constant>.
 
486
                </listitem>
 
487
            </itemizedlist>
 
488
 
 
489
            and any of the following conditions hold:
 
490
 
 
491
            <itemizedlist mark="disc">
 
492
                <listitem>
 
493
                  The specified display and context attributes do not identify a valid
 
494
                  OpenGL or OpenGL ES context.
 
495
                </listitem>
 
496
 
 
497
                <listitem>
 
498
                   The specified context does not support buffer and renderbuffer objects.
 
499
                </listitem>
 
500
 
 
501
                <listitem>
 
502
                  The specified context is not compatible with the OpenCL context being
 
503
                  created (for example, it exists in a physically distinct address space,
 
504
                  such as another hardware device, or does not support sharing data with
 
505
                  OpenCL due to implementation restrictions).
 
506
                </listitem>
 
507
            </itemizedlist>
 
508
        </listitem>
 
509
 
 
510
        <listitem><!-- ext. spec p. 42, section 9.6.4 -->
 
511
          <errorname>CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR</errorname> if a
 
512
          share group was specified for a CGL-based OpenGL implementation by
 
513
          setting the attribute <constant>CL_CGL_SHAREGROUP_KHR</constant>, and the
 
514
          specified share group does not identify a valid CGL share group object (if the
 
515
          <citerefentry><refentrytitle>cl_khr_gl_sharing</refentrytitle></citerefentry> extension
 
516
          is enabled).
 
517
        </listitem>
 
518
 
 
519
        <listitem>
 
520
            <errorname>CL_INVALID_OPERATION</errorname> if a context was specified as described above 
 
521
            and any of the following conditions hold:
 
522
 
 
523
            <itemizedlist mark="disc">
 
524
                <listitem>
 
525
                  A context or share group object was specified for one of CGL, EGL, GLX, or WGL
 
526
                  and the OpenGL implementation does not support that window-system binding API.
 
527
                </listitem>
 
528
 
 
529
                <listitem>
 
530
                  More than one of the attributes <constant>CL_CGL_SHAREGROUP_KHR</constant>,
 
531
                  <constant>CL_EGL_DISPLAY_KHR</constant>, <constant>CL_GLX_DISPLAY_KHR</constant>,
 
532
                  and <constant>CL_WGL_HDC_KHR</constant> is set to a non-default value.
 
533
                </listitem>
 
534
 
 
535
                <listitem>
 
536
                  Both of the attributes <constant>CL_CGL_SHAREGROUP_KHR</constant> and
 
537
                  <constant>CL_GL_CONTEXT_KHR</constant> are set to non-default values.
 
538
                </listitem>
 
539
 
 
540
                <listitem>
 
541
                  Any of the devices specified in the devices argument cannot support OpenCL
 
542
                  objects which share the data store of an OpenGL object, as described in
 
543
                  section 9.7.
 
544
                </listitem>
 
545
            </itemizedlist>
 
546
        </listitem>
 
547
 
 
548
        <listitem>
 
549
          <errorname>CL_INVALID_DX9_MEDIA_ADAPTER_KHR</errorname> if the
 
550
          media adapter specified for interoperability is not compatible with
 
551
          the devices against which the context is to be created (only if the
 
552
          <citerefentry><refentrytitle>cl_khr_dx9_media_sharing</refentrytitle></citerefentry>
 
553
          extension is supported).
 
554
        </listitem>
 
555
 
 
556
        <listitem>
 
557
          <!-- ext. spec p. 86, section 9.10.5 --> <errorname>CL_INVALID_ADAPTER_KHR</errorname> if
 
558
          any of the values of the properties <constant>CL_CONTEXT_ADAPTER_D3D9_KHR</constant>,
 
559
          <constant>CL_CONTEXT_ADAPTER_D3D9EX_KHR</constant> or
 
560
          <constant>CL_CONTEXT_ADAPTER_DXVA_KHR</constant> is non-NULL and
 
561
          does not specify a valid media adapter with which the cl_device_ids
 
562
          against which this context  is to be created may interoperate (only if the
 
563
          <citerefentry><refentrytitle>cl_khr_dx9_media_sharing</refentrytitle></citerefentry>
 
564
          extension is supported).
 
565
        </listitem>
 
566
 
 
567
        <listitem>
 
568
          <!-- ext. spec p. 86, section 9.10.5 -->
 
569
          <errorname>CL_INVALID_OPERATION</errorname> if interoperability is
 
570
          specified by setting <constant>CL_CONTEXT_ADAPTER_D3D9_KHR</constant>,
 
571
          <constant>CL_CONTEXT_ADAPTER_D3D9EX_KHR</constant> or
 
572
          <constant>CL_CONTEXT_ADAPTER_DXVA_KHR</constant> to a non-NULL value, and
 
573
          interoperability with another graphics API is also specified (only if the
 
574
          <citerefentry><refentrytitle>cl_khr_dx9_media_sharing</refentrytitle></citerefentry>
 
575
          extension is supported).
 
576
        </listitem>
 
577
 
 
578
        <listitem>
 
579
          <!-- ext. spec p. 100, section 9.11.5 --> <errorname>CL_INVALID_OPERATION</errorname>
 
580
          if Direct3D 11 interoperability is specified by setting
 
581
          <constant>CL_INVALID_D3D11_DEVICE_KHR</constant> to a non-NULL value, and
 
582
          interoperability with another graphics API is also specified (only if the
 
583
          <citerefentry><refentrytitle>cl_khr_d3d11_sharing</refentrytitle></citerefentry>
 
584
          extension is supported).
 
585
        </listitem>
 
586
 
 
587
        <listitem>
 
588
          <!-- ext. spec p. 99, section 9.11.4; and p. 100, section 9.11.5 -->
 
589
          <errorname>CL_INVALID_D3D11_DEVICE_KHR</errorname> if the value of the property
 
590
          <constant>CL_CONTEXT_D3D11_DEVICE_KHR</constant> is non-NULL and does not specify
 
591
          a valid Direct3D 11 device with which the <varname>cl_device_ids</varname>
 
592
          against which this context is to be created may interoperate (only if the
 
593
          <citerefentry><refentrytitle>cl_khr_d3d11_sharing</refentrytitle></citerefentry>
 
594
          extension is supported).
 
595
        </listitem>
 
596
 
 
597
        <listitem>
 
598
          <!-- ext. spec p. 99, section 9.11.4 -->
 
599
          <errorname>CL_INVALID_D3D11_DEVICE_KHR</errorname> if the Direct3D
 
600
          11 device specified for interoperability is not compatible with
 
601
          the devices against which the context is to be created (only if the
 
602
          <citerefentry><refentrytitle>cl_khr_d3d11_sharing</refentrytitle></citerefentry>
 
603
          extension is supported).
 
604
        </listitem>
 
605
 
 
606
    </itemizedlist>
 
607
</refsect1>
 
608
 
 
609
<!-- ================================ EXAMPLE  -->
 
610
<!-- DO NOT DELETE IN CASE AN EXAMPLE IS ADDED IN THE FUTURE
 
611
 
 
612
    <refsect2 id="example1"><title>Example</title>
 
613
        <informaltable frame="none"><tgroup cols="1" align="left" colsep="0" rowsep="0">
 
614
        <colspec colname="col1" colnum="1" /><tbody><row>
 
615
        <entry>
 
616
cl_context <function>clCreateContext</function>
 
617
    <olink uri="enums.html#cl_context_properties">cl_context_properties</olink> <varname>*properties</varname>
 
618
    cl_uint <varname>num_devices</varname>
 
619
    const cl_device_id <varname>*devices</varname>
 
620
    void <varname>*pfn_notify</varname> (
 
621
        const char <varname>*errinfo</varname>,
 
622
        const void <varname>*private_info</varname>,
 
623
        size_t <varname>cb</varname>,
 
624
        void <varname>*user_data</varname>),
 
625
        void <varname>*user_data</varname>,
 
626
        cl_int <varname>*errcode_ret</varname>)
 
627
</entry></row>
 
628
        </tbody></tgroup></informaltable>
 
629
    </refsect2>
 
630
    -->
 
631
 
 
632
<!-- ================================ SPECIFICATION  -->
 
633
<!-- Set the "uri" attribute in the <olink /> element to the "named destination" for the PDF page
 
634
-->
 
635
    <refsect1 id="specification"><title>Specification</title>
 
636
        <para><imageobject><imagedata fileref="pdficon_small1.gif" format="gif" /></imageobject>
 
637
            <olink uri="clCreateContext">OpenCL Specification</olink>
 
638
        </para>
 
639
    </refsect1>
 
640
 
 
641
<!-- ================================ ALSO SEE  -->
 
642
 
 
643
    <refsect1 id="seealso"><title>Also see</title>
 
644
        <para>
 
645
            <citerefentry><refentrytitle>clGetDeviceIDs</refentrytitle></citerefentry>,
 
646
            <citerefentry><refentrytitle>clCreateContextFromType</refentrytitle></citerefentry>,
 
647
            <citerefentry><refentrytitle>clRetainContext</refentrytitle></citerefentry>,
 
648
            <citerefentry><refentrytitle>clReleaseContext</refentrytitle></citerefentry>,
 
649
            <citerefentry><refentrytitle>clGetContextInfo</refentrytitle></citerefentry>,
 
650
            <citerefentry href="classDiagram"><refentrytitle>Cardinality Diagram</refentrytitle></citerefentry>
 
651
        </para>
 
652
    </refsect1>
 
653
 
 
654
<!-- ============================== COPYRIGHT -->
 
655
<!-- Content included from copyright.inc.xsl -->
 
656
 
 
657
    <refsect3 id="Copyright"><title></title>
 
658
        <imageobject>
 
659
                <imagedata fileref="KhronosLogo.jpg" format="jpg" />
 
660
        </imageobject>
 
661
        <para />
 
662
    </refsect3>
 
663
 
 
664
 
 
665
<!-- 27-Oct-2011 -->
 
666
</refentry>
 
667