summaryrefslogtreecommitdiff
path: root/engine-ocean/External/glew/auto/EGL-Registry/sdk/docs/man/eglCreateImage.xml
blob: 8072ec32a80c16d5eb8381dd21ef60d7ad8ac37c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:base="" xml:id="eglCreateImage">
    <info>
         <copyright>
             <year>2018</year>
             <holder>The Khronos Group Inc.</holder>
         </copyright>
    </info>
    <refmeta>
        <refentrytitle>eglCreateImage</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>eglCreateImage</refname>
        <refpurpose>
            Create a new <type>EGLImage</type> object
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
            <funcdef>EGLImage <function>eglCreateImage</function></funcdef>
            <paramdef>(EGLDisplay <parameter>display</parameter></paramdef>
            <paramdef>EGLContext <parameter>context</parameter></paramdef>
            <paramdef>EGLenum <parameter>target</parameter></paramdef>
            <paramdef>EGLClientBuffer <parameter>buffer</parameter></paramdef>
            <paramdef>const EGLAttrib *<parameter>attrib_list</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1 xml:id="parameters"><title>Parameters</title>
        <variablelist>
            <varlistentry>
                <term><parameter>display</parameter></term>
                <listitem><para>
                    Specifies the <acronym>EGL</acronym> display connection.
                </para></listitem>
            </varlistentry>
            <varlistentry>
                <term><parameter>context</parameter></term>
                <listitem><para>
                    Specifies the client API context for which the image is
                    created.
                </para></listitem>
            </varlistentry>
            <varlistentry>
                <term><parameter>target</parameter></term>
                <listitem><para>
                    Specifies the type of resource used as the image source.
                </para></listitem>
            </varlistentry>
            <varlistentry>
                <term><parameter>buffer</parameter></term>
                <listitem><para>
                    Specifies the resource to be used as the image source.
                </para></listitem>
            </varlistentry>
            <varlistentry>
                <term><parameter>attrib_list</parameter></term>
                <listitem><para>
                    Specifies attributes used to select sub-sections of the
                    resource to be used as the image source.
                </para></listitem>
            </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 xml:id="description"><title>Description</title>
        <para>
            <function>eglCreateImage</function> is used to create an
            <type>EGLImage</type> object from an existing image resource
            <parameter>buffer</parameter>. <parameter>display</parameter>
            specifies the EGL display used for this operation.
            <parameter>context</parameter> specifies the EGL client API
            context used for this operation, or
            <constant>EGL_NO_CONTEXT</constant> if a client API context is
            not required. <parameter>target</parameter> specifies the type
            of resource being used as the <type>EGLImage</type> source
            (examples include two-dimensional textures in OpenGL ES contexts
            and <type>VGImage</type> objects in OpenVG contexts).
            <parameter>buffer</parameter> is the name (or handle) of a
            resource to be used as the <type>EGLImage</type> source, cast
            into the type <type>EGLClientBuffer</type>.
            <parameter>attrib_list</parameter> is a list of attribute-value
            pairs which is used to select sub-sections of
            <parameter>buffer</parameter> for use as the
            <type>EGLImage</type> source, such as mipmap levels for OpenGL
            ES texture map resources, as well as behavioral options, such as
            whether to preserve pixel data during creation. If
            <parameter>attrib_list</parameter> is
            non-<constant>NULL</constant>, the last attribute specified in
            the list must be <constant>EGL_NONE</constant>.
        </para>
        <para>
            The resource specified by <parameter>display</parameter>,
            <parameter>context</parameter>, <parameter>target</parameter>,
            <parameter>buffer</parameter>, and
            <parameter>attrib_list</parameter> must not itself be an
            <type>EGLImage</type> sibling, or bound to a pbuffer
            <type>EGLSurface</type> resource
            (<function>eglBindTexImage</function>,
            <function>eglCreatePbufferFromClientBuffer</function>).
        </para>
        <para>
            Values accepted for <parameter>target</parameter> are shown in
            table <xref linkend="tab-imagetarget"/>.
        </para>
        <table frame="all" xml:id="tab-imagetarget">
            <title>
                Legal values for <function>eglCreateImage</function> <parameter>target</parameter>
            </title>
            <tgroup cols="2" align="left" colsep="1" rowsep="1">
                <thead>
                    <row>
                        <entry><parameter>target</parameter></entry>
                        <entry>Notes</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry><constant>EGL_GL_TEXTURE_2D</constant></entry>
                        <entry>Used for GL 2D texture images</entry>
                    </row>
                    <row>
                        <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant></entry>
                        <entry>Used for the +X face of GL cubemap texture images</entry>
                    </row>
                    <row>
                        <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant></entry>
                        <entry>Used for the -X face of GL cubemap texture images</entry>
                    </row>
                    <row>
                        <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant></entry>
                        <entry>Used for the +Y face of GL cubemap texture images</entry>
                    </row>
                    <row>
                        <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant></entry>
                        <entry>Used for the -Y face of GL cubemap texture images</entry>
                    </row>
                    <row>
                        <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant></entry>
                        <entry>Used for the +Z face of GL cubemap texture images</entry>
                    </row>
                    <row>
                        <entry><constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant></entry>
                        <entry>Used for the -Z face of GL cubemap texture images</entry>
                    </row>
                    <row>
                        <entry><constant>EGL_GL_TEXTURE_3D</constant></entry>
                        <entry>Used for OpenGL and OpenGL ES 3D texture images</entry>
                    </row>
                    <row>
                        <entry><constant>EGL_GL_RENDERBUFFER</constant></entry>
                        <entry>Used for OpenGL and OpenGL ES renderbuffer images</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        <para>
            Attribute names accepted in <parameter>attrib_list</parameter>
            are shown in table <xref linkend="tab-imageattr"/>, together
            with the <parameter>target</parameter> for which each attribute
            name is valid, and the default value used for each attribute if
            it is not included in <parameter>attrib_list</parameter>.
        </para>
        <table frame="all" xml:id="tab-imageattr">
            <title>
                Legal attributes for <function>eglCreateImage</function>
                <parameter>attrib_list</parameter> parameter
            </title>
            <tgroup cols="4" align="left" colsep="1" rowsep="1">
                <thead>
                    <row>
                        <entry><parameter>target</parameter></entry>
                        <entry>Notes</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>Attribute</entry>
                        <entry>Description</entry>
                        <entry>Valid <parameter>target</parameter>s</entry>
                        <entry>Default Value</entry>
                    </row>
                    <row>
                        <entry><constant>EGL_NONE</constant></entry>
                        <entry>Marks the end of the attribute-value list</entry>
                        <entry>All</entry>
                        <entry>N/A</entry>
                    </row>
                    <row>
                        <entry><constant>EGL_GL_TEXTURE_LEVEL</constant></entry>
                        <entry>
                            Specifies the mipmap level used as the
                            <type>EGLImage</type> source. Must be part of
                            the complete texture object
                            <parameter>buffer</parameter>
                        </entry>
                        <entry>
                            <constant>EGL_GL_TEXTURE_2D</constant>,
                            <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, or
                            <constant>EGL_GL_TEXTURE_3D</constant>
                        </entry>
                        <entry>0</entry>
                    </row>
                    <row>
                        <entry><constant>EGL_GL_TEXTURE_ZOFFSET</constant></entry>
                        <entry>
                            Specifies the depth offset of the image to use
                            as the <type>EGLImage</type> source. Must be
                            part of the complete texture object
                            <parameter>buffer</parameter>
                        </entry>
                        <entry><constant>EGL_GL_TEXTURE_3D</constant></entry>
                        <entry>0</entry>
                    </row>
                    <row>
                        <entry><constant>EGL_IMAGE_PRESERVED</constant></entry>
                        <entry>Whether to preserve pixel data</entry>
                        <entry>All</entry>
                        <entry><constant>EGL_FALSE</constant></entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        <para>
            <function>eglCreateImage</function> returns an
            <type>EGLImage</type> object corresponding to the image data
            specified by <parameter>display</parameter>,
            <parameter>context</parameter>, <parameter>target</parameter>,
            <parameter>buffer</parameter> and
            <parameter>attrib_list</parameter> which may be referenced by
            client API operations.
        </para>
        <para>
            If <parameter>target</parameter> is
            <constant>EGL_GL_TEXTURE_2D</constant>,
            <constant>EGL_GL_TEXTURE_3D</constant>,
            <constant>EGL_GL_RENDERBUFFER</constant>,
            <constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
            <constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
            <constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
            <constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
            <constant>EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or
            <constant>EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>,
            <parameter>display</parameter> must be a valid
            <type>EGLDisplay</type>, and <parameter>context</parameter> must
            be a valid OpenGL or OpenGL ES API context on that display.
        </para>
        <para>
            If <parameter>target</parameter> is
            <constant>EGL_GL_TEXTURE_2D</constant>,
            <parameter>buffer</parameter> must be the name of a nonzero,
            <constant>GL_TEXTURE_2D</constant> target texture object, cast
            into the type <type>EGLClientBuffer</type>.
        </para>
        <para>
            If <parameter>target</parameter> is one of the
            <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant> enumerants,
            <parameter>buffer</parameter> must be the name of a nonzero,
            <constant>GL_TEXTURE_CUBE_MAP</constant> (or equivalent in GL
            extensions) target texture object, cast into the type
            <type>EGLClientBuffer</type>.
        </para>
        <para>
            If <parameter>target</parameter> is
            <constant>EGL_GL_TEXTURE_3D</constant>,
            <parameter>buffer</parameter> must be the name of a nonzero,
            <constant>GL_TEXTURE_3D</constant> (or equivalent in GL
            extensions) target texture object, cast into the type
            <type>EGLClientBuffer</type>.
        </para>
        <para>
            <parameter>attrib_list</parameter> should specify the mipmap
            level (<constant>EGL_GL_TEXTURE_LEVEL</constant>) and, where
            applicable, z-offset
            (<constant>EGL_GL_TEXTURE_ZOFFSET</constant>) which will be used
            as the <type>EGLImage</type> source; If not specified, the
            default values listed in table <xref linkend="tab-imageattr"/>
            will be used instead. Additional values specified in are
            ignored.
        </para>
        <para>
            There must exist some levels <emphasis>x</emphasis> and
            <emphasis>y</emphasis> such that the mipmap level requested lies
            between <emphasis>x</emphasis> and <emphasis>y</emphasis>
            (inclusive), the texture would be mipmap complete were
            <emphasis>x</emphasis> substituted for the base level and
            <emphasis>y</emphasis> substituted for the max level, and all
            levels less than <emphasis>x</emphasis> or greater than
            <emphasis>y</emphasis> are unspecified. For cubemaps a single
            pair <emphasis>x</emphasis> and <emphasis>y</emphasis> must
            apply to all faces. For three-dimensional textures, the
            specified z-offset must be smaller than the depth of the
            specified mipmap level.
        </para>
        <para>
            If <parameter>target</parameter> is
            <constant>EGL_GL_RENDERBUFFER</constant>,
            <parameter>buffer</parameter> must be the name of a complete,
            nonzero, non-multisampled <constant>GL_RENDERBUFFER</constant>
            (or equivalent in extensions) target object, cast into the type
            <type>EGLClientBuffer</type>. Values specified in
            <parameter>attrib_list</parameter> are ignored.
        </para>
        <para>
            If the value of attribute
            <constant>EGL_IMAGE_PRESERVED</constant> is
            <constant>EGL_FALSE</constant> (the default), then all pixel
            data values associated with <parameter>buffer</parameter> will
            be undefined after <function>eglCreateImage</function> returns.
        </para>
        <para>
            If the value of attribute
            <constant>EGL_IMAGE_PRESERVED</constant> is
            <constant>EGL_TRUE</constant>, then all pixel data values
            associated with <parameter>buffer</parameter> are preserved.
        </para>
    </refsect1>
    <refsect1 xml:id="errors"><title>Errors</title>
        <para>
            <function>eglCreateImage</function> returns
            <constant>EGL_NO_IMAGE</constant> on failure. The contents of
            <parameter>buffer</parameter> will be unaffected.
        </para>
        <para>
            If <parameter>display</parameter> is not the handle of a valid
            <type>EGLDisplay</type> object, the error
            <constant>EGL_BAD_DISPLAY</constant> is generated.
        </para>
        <para>
            If <parameter>context</parameter> is neither the handle of a
            valid <type>EGLContext</type> object on
            <parameter>display</parameter> nor
            <constant>EGL_NO_CONTEXT</constant>, the error
            <constant>EGL_BAD_CONTEXT</constant> is generated.
        </para>
        <para>
            If <parameter>target</parameter> is not one of the values in
            table <xref linkend="tab-imagetarget"/>, the error
            <constant>EGL_BAD_PARAMETER</constant> is generated.
        </para>
        <para>
            If <parameter>target</parameter> is
            <constant>EGL_GL_TEXTURE_2D</constant>,
            <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>,
            <constant>EGL_GL_RENDERBUFFER</constant> or
            <constant>EGL_GL_TEXTURE_3D</constant>, and
            <parameter>display</parameter> is not a valid
            <type>EGLDisplay</type>, the error
            <constant>EGL_BAD_DISPLAY</constant> is generated.
        </para>
        <para>
            If <parameter>target</parameter> is
            <constant>EGL_GL_TEXTURE_2D</constant>,
            <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>,
            <constant>EGL_GL_RENDERBUFFER</constant> or
            <constant>EGL_GL_TEXTURE_3D</constant>, and
            <parameter>context</parameter> is not a valid
            <type>EGLContext</type>, the error
            <constant>EGL_BAD_CONTEXT</constant> is generated.
        </para>
        <para>
            If <parameter>target</parameter> is
            <constant>EGL_GL_TEXTURE_2D</constant>,
            <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>,
            <constant>EGL_GL_RENDERBUFFER</constant> or
            <constant>EGL_GL_TEXTURE_3D</constant>, and
            <parameter>context</parameter> is not a valid GL context, or
            does not match the <parameter>display</parameter>, the error
            <constant>EGL_BAD_MATCH</constant> is generated.
        </para>
        <para>
            If <parameter>target</parameter> is
            <constant>EGL_GL_TEXTURE_2D</constant>,
            <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant> or
            <constant>EGL_GL_TEXTURE_3D</constant> and
            <parameter>buffer</parameter> is not the name of a texture
            object of type <parameter>target</parameter>, the error
            <constant>EGL_BAD_PARAMETER</constant> is generated.
        </para>
        <para>
            If <parameter>target</parameter> is
            <constant>EGL_GL_RENDERBUFFER</constant> and
            <parameter>buffer</parameter> is not the name of a renderbuffer
            object, or if <parameter>buffer</parameter> is the name of a
            multisampled renderbuffer object, the error
            <constant>EGL_BAD_PARAMETER</constant> is generated.
        </para>
        <para>
            If <constant>EGL_GL_TEXTURE_LEVEL</constant> is nonzero,
            <parameter>target</parameter> is
            <constant>EGL_GL_TEXTURE_2D</constant>,
            <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant> or
            <constant>EGL_GL_TEXTURE_3D</constant>, and
            <parameter>buffer</parameter> is not the name of a complete GL
            texture object, the error <constant>EGL_BAD_PARAMETER</constant>
            is generated.
        </para>
        <para>
            If <constant>EGL_GL_TEXTURE_LEVEL</constant> is 0,
            <parameter>target</parameter> is
            <constant>EGL_GL_TEXTURE_2D</constant>,
            <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant> or
            <constant>EGL_GL_TEXTURE_3D</constant>,
            <parameter>buffer</parameter> is the name of an incomplete GL
            texture object, and any mipmap levels other than mipmap level 0
            are specified, the error <constant>EGL_BAD_PARAMETER</constant>
            is generated.
        </para>
        <para>
            If <constant>EGL_GL_TEXTURE_LEVEL</constant> is 0,
            <parameter>target</parameter> is
            <constant>EGL_GL_TEXTURE_2D</constant> or
            <constant>EGL_GL_TEXTURE_3D</constant>,
            <parameter>buffer</parameter> is not the name of a complete GL
            texture object, and mipmap level 0 is not specified, the error
            <constant>EGL_BAD_PARAMETER</constant> is generated.
        </para>
        <para>
            If <constant>EGL_GL_TEXTURE_LEVEL</constant> is 0,
            <parameter>target</parameter> is
            <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>,
            <parameter>buffer</parameter> is not the name of a complete GL
            texture object, and one or more faces do not have mipmap level 0
            specified, the error <constant>EGL_BAD_PARAMETER</constant> is
            generated.
        </para>
        <para>
            If <parameter>target</parameter> is
            <constant>EGL_GL_TEXTURE_2D</constant>,
            <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>,
            <constant>EGL_GL_RENDERBUFFER</constant> or
            <constant>EGL_GL_TEXTURE_3D</constant> and
            <parameter>buffer</parameter> refers to the default GL texture
            object (0) for the corresponding GL target, the error
            <constant>EGL_BAD_PARAMETER</constant> is generated.
        </para>
        <para>
            If <parameter>target</parameter> is
            <constant>EGL_GL_TEXTURE_2D</constant>,
            <constant>EGL_GL_TEXTURE_CUBE_MAP_*</constant>, or
            <constant>EGL_GL_TEXTURE_3D</constant>, and the value specified
            in <parameter>attrib_list</parameter> for
            <constant>EGL_GL_TEXTURE_LEVEL</constant> is not a valid mipmap
            level for the specified GL texture object
            <parameter>buffer</parameter>, the error
            <constant>EGL_BAD_MATCH</constant> is generated.
        </para>
        <para>
            If <parameter>target</parameter> is
            <constant>EGL_GL_TEXTURE_3D</constant>, and the value specified
            in <parameter>attrib_list</parameter> for
            <constant>EGL_GL_TEXTURE_ZOFFSET</constant> exceeds the depth of
            the specified mipmap level-of-detail in
            <parameter>buffer</parameter>, the error
            <constant>EGL_BAD_PARAMETER</constant> is generated.
        </para>
        <para>
            If an attribute specified in <parameter>attrib_list</parameter>
            is not one of the attributes shown in table <xref
            linkend="tab-imageattr"/>, the error
            <constant>EGL_BAD_PARAMETER</constant> is generated.
        </para>
        <para>
            If an attribute specified in <parameter>attrib_list</parameter>
            is not a valid attribute for <parameter>target</parameter>, as
            shown in table <xref linkend="tab-imageattr"/>, the error
            <constant>EGL_BAD_MATCH</constant> is generated.
        </para>
        <para>
            If the resource specified by <parameter>display</parameter>,
            <parameter>context</parameter>, <parameter>target</parameter>,
            <parameter>buffer</parameter> and
            <parameter>attrib_list</parameter> has an off-screen buffer
            bound to it (e.g., by a previous call to
            <function>eglBindTexImage</function>), the error
            <constant>EGL_BAD_ACCESS</constant> is generated.
        </para>
        <para>
            If the resource specified by <parameter>display</parameter>,
            <parameter>context</parameter>, <parameter>target</parameter>,
            <parameter>buffer</parameter> and
            <parameter>attrib_list</parameter> is bound to an off-screen
            buffer (e.g., by a previous call to
            <function>eglCreatePbufferFromClientBuffer</function>), the
            error <constant>EGL_BAD_ACCESS</constant> is generated.
        </para>
        <para>
            If the resource specified by <parameter>display</parameter>,
            <parameter>context</parameter>, <parameter>target</parameter>,
            <parameter>buffer</parameter> and
            <parameter>attrib_list</parameter> is itself an
            <type>EGLImage</type> sibling, the error
            <constant>EGL_BAD_ACCESS</constant> is generated.
        </para>
        <para>
            If insufficient memory is available to complete the specified
            operation, the error <constant>EGL_BAD_ALLOC</constant> is
            generated.
        </para>
        <para>
            If the value specified in <parameter>attrib_list</parameter> for
            <constant>EGL_IMAGE_PRESERVED</constant> is
            <constant>EGL_TRUE</constant>, and an <type>EGLImage</type>
            handle cannot be created from the specified resource such that
            the pixel data values in <parameter>buffer</parameter> are
            preserved, the error <constant>EGL_BAD_ACCESS</constant> is
            generated.
        </para>
        <para>
            Note that the success or failure of
            <function>eglCreateImage</function> should not affect the
            ability to use <parameter>buffer</parameter> in its original API
            context (or context share group) (although the pixel data values
            will be undefined if the command succeeds and the value of
            <constant>EGL_IMAGE_PRESERVED</constant> is not
            <constant>EGL_TRUE</constant>).
        </para>
    </refsect1>
    <refsect1 xml:id="lifetime"><title>Lifetime and Usage of <type>EGLImage</type>s</title>
        <para>
            Once an <type>EGLImage</type> is created from an
            <type>EGLImage</type> source, the memory associated with the
            <type>EGLImage</type> source will remain allocated (and all
            <type>EGLImage</type> siblings in all client API contexts will
            be useable) as long as either of the following conditions is
            true:
        </para>
        <para>
            <itemizedlist>
            <listitem>
                <para>
                     Any <type>EGLImage</type> siblings exist in any client
                     API context
                </para>
            </listitem>
            <listitem>
                <para>
                    The <type>EGLImage</type> object exists inside EGL
                </para>
            </listitem>
            </itemizedlist>
        </para>
        <para>
            The semantics for specifying, deleting and using
            <type>EGLImage</type> siblings are client API-specific, and are
            described in the appropriate API specifications.
        </para>
        <para>
            If an application specifies an <type>EGLImage</type> sibling as
            the destination for rendering and/or pixel download operations
            (e.g., as an OpenGL or OpenGL ES framebuffer object,
            <function>glTexSubImage2D</function>, etc.), the modified image
            results will be observed by all <type>EGLImage</type> siblings
            in all client API contexts. If multiple client API contexts
            access <type>EGLImage</type> sibling resources simultaneously,
            with one or more context modifying the image data, rendering
            results in all contexts accessing <type>EGLImage</type> siblings
            are undefined.
        </para>
        <para>
            Respecification and/or deletion of any <type>EGLImage</type>
            sibling (i.e., both <type>EGLImage</type> source and
            <type>EGLImage</type> target resources) inside a client API
            context (by issuing a subsequent call to commands such as
            <function>glTexImage*</function> or
            <function>glDeleteTextures</function>, with the
            <type>EGLImage</type> sibling resource as the target of the
            operation) affects only that client API context and other
            contexts within its share group. For an OpenGL or OpenGL ES
            context, respecification always results in
            <firstterm>orphaning</firstterm> of the <type>EGLImage</type>,
            and may also include allocation of additional memory for the
            respecified resource and/or copying of the <type>EGLImage</type>
            pixel data.
        </para>
        <para>
            Note: Behavior of other types of client APIs generally follows
            the OpenGL and OpenGL ES behavior described here, although this
            is not mandated yet.
        </para>
        <para>
            Operations inside EGL or any client API context which may affect
            the lifetime of an <type>EGLImage</type> (or the memory
            allocated for the <type>EGLImage</type>), such as respecifying
            and/or deleting an <type>EGLImage</type> sibling inside a client
            API context, must be atomic.
        </para>
        <para>
            Applications may create client API resources from an
            <type>EGLImage</type> using client API extensions outside the
            scope of this document (such as
            <constant>GL_OES_EGL_image</constant>, which creates OpenGL ES
            texture and renderbuffer objects). If the <type>EGLImage</type>
            used to create the client resource was created with the
            <constant>EGL_IMAGE_PRESERVED</constant> attribute set to
            <constant>EGL_TRUE</constant>, then the pixel data values
            associated with the image will be preserved after creating the
            client resource; otherwise, the pixel data values will be
            undefined. If the <type>EGLImage</type> was created with the
            <constant>EGL_IMAGE_PRESERVED</constant> attribute set to
            <constant>EGL_TRUE</constant>, and EGL is unable to create the
            client resource without modifying the pixel values, then
            creation will fail and the pixel data values will be preserved.
        </para>
    </refsect1>
    <refsect1 xml:id="notes"><title>Notes</title>
        <para>
            <function>eglCreateImage</function> is available only if the EGL
            version is 1.5 or greater.
        </para>
    </refsect1>
    <refsect1 xml:id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>eglBindTexImage</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>eglCreatePbufferFromClientBuffer</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>eglDestroyImage</refentrytitle></citerefentry>,
            <function>glDeleteTextures</function>,
            <function>glTexImage*</function>,
            <function>glTexSubImage2D</function>
        </para>
    </refsect1>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/>
</refentry>