-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathgdl.h
1755 lines (1404 loc) · 52.8 KB
/
gdl.h
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
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
//-----------------------------------------------------------------------------
// Copyright 2006-2011 Intel Corporation
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//-----------------------------------------------------------------------------
#ifndef _GDL_H_
#define _GDL_H_
#include "gdl_types.h"
#include "gdl_pd.h"
#if defined(__cplusplus)
extern "C" {
#endif
/*------------------------------------------------------------------------------
* IMPORTANT!
*
* Change of a structure/type or a function prototype requires rolling of an
* appropriate version number. For more information see gdl_version.h
*----------------------------------------------------------------------------*/
/**@mainpage
* This document is applicable to all Intel(R) CE Media Processors.
* Where functional differences exist between individual processors,
* applicability to platform/silicon will be delineated.
*/
/**@defgroup general General */
/**@defgroup disp_mode Display Mode*/
/**@defgroup post_blend Post Blender*/
/**@defgroup plane_management Plane Management
A plane is a unit of hardware that can supply pixel data to be composited
with the pixel data of other planes for output to the display. Different
kinds of planes have different capabilities. The Intel(R) CE Media Processors
contain two kinds of planes:
- Universal Pixel Planes (UPPs)
- Indexed/Alpha Planes (IAPs)
The Plane Management API provides a generic way to configure a plane and
populate it with pixel data. The main components of the API are:
- <b>A predefined set of plane attributes.</b> Attributes are specified as
name/value pairs. The enumeration #gdl_plane_attr_t defines the attribute
names. The documentation of this data type describes each attribute
including:
- the plane capability controlled by the attribute.
- the data type of the attribute's value.
- the range of valid values that can be assigned to the attribute.
- the default value of the attribute.
- <b>The ability to query a plane for its capabilities.</b> Each plane type
may support a different subset of the defined attributes and different
set of pixel formats. gdl_plane_capabilities() returns a description of
the attributes and pixel formats supported by a specified plane.
- <b>A set of attribute query functions.</b> These functions return the
current hardware setting of the specified attribute on the specified plane.
The only difference between the functions is the data type returned.
- gdl_plane_get_attr()
- gdl_plane_get_int()
- gdl_plane_get_uint()
- gdl_plane_get_rect()
- <b>A set of attribute configuration functions.</b> For each of the query
functions there is a corresponding set function. All attribute set
function calls must be bracketed by calls to configuration begin/end
functions. The specified attributes values are "batched" and executed
only when the end function is called. Batching provides atomicity of
configuration changes and avoids getting into invalid states when related
attributes must be changed at the same time. The sequence of calls made
to configure a plane is as follows:
- gdl_plane_config_begin()
- one or more calls to:
- gdl_plane_set_attr()
- gdl_plane_set_int()
- gdl_plane_set_uint()
- gdl_plane_set_rect()
- gdl_plane_config_end()
- <b>A surface flip function.</b> A surface is a memory buffer containing
pixel information. See @ref surface for more information. The gdl_flip()
function "flips" a surface onto a plane, making the pixels in that surface
visible.
@warning Plane defaults (including if they are enabled or disabled) are
set when the display driver is loaded, and when
@ref gdl_plane_reset() and @ref gdl_plane_reset_all() are called.
They are <b>not</b> set by @ref gdl_init().
*/
/**@defgroup surface Surface Management
A surface is a memory buffer containing pixel data.
*/
/**@defgroup disp_vbi VBI and Polarity */
/**@defgroup disp_pd Port Drivers */
/**@defgroup debug Debug helpers
The majority of the functions in this group dump the contents of data
structures to stdout or return string representations (that can be used in
messages) for the values of various GDL enumerations.
*/
#ifndef DOXYGEN_SKIP
#define GDL_API __attribute__ ((visibility ("default")))
#else
#define GDL_API " "
#endif
GDL_API gdl_ret_t
gdl_init(
gdl_void * reserved0
);
/**< @ingroup general
This routine initializes the session and initiates communication with
the display driver server daemon. Calls to any other GDL functions will
fail until this call is made. It must be called once per process. All
threads in a process are then able to use the GDL API.
Subsequent calls to gdl_init() (without an intervening call to gdl_close())
will return #GDL_SUCCESS and increment an internal reference count.
@param [in] reserved0
This parameter is reserved for future use and should be set to 0.
@note This routine does not restore plane or port driver defaults
that may have been changed by a previously running GDL
application. Plane defaults can be restored by using
@ref gdl_plane_reset() and @ref gdl_plane_reset_all(). No
restoration functionality exists for port drivers.
*/
#ifndef DOXYGEN_SKIP /* DOXYGEN_SKIP only defined when docs are generated */
GDL_API gdl_ret_t _gdl_init(gdl_uint32 version);
#define gdl_init(reserved0) _gdl_init((GDL_HEADER_VERSION_MAJOR << 16) \
| GDL_HEADER_VERSION_MINOR)
#endif
GDL_API gdl_ret_t
gdl_close(
void
);
/**< @ingroup general
This function decrements the internal reference count that gdl_open()
increments. Once the reference count goes to zero, communication with the
display driver server daemon is closed and the session is terminated.
Subsequent calls to the GDL API from within the same process will fail until
gdl_init() is called again.
The use of a reference account allows pairs of gdl_open()/gdl_close() calls
to be used, for instance, in separate threads in the same process without
interference.
When the session is terminated, any unfreed surfaces that were allocated by
the calling process are freed, and warnings are printed to the console. If
a surface freed in this manner is currently being displayed, the plane it is
displayed on is first disabled. No other hardware settings are changed;
applications launched subsequently will inherit the hardware configuration
left behind by the closing process.
*/
GDL_API gdl_ret_t
gdl_get_driver_info(
gdl_driver_info_t * driver_info
);
/**< @ingroup general
This routine returns driver information to the caller. This information
can be used to verify the version of the gdl driver.
@param [out] driver_info
This parameter is of type #gdl_driver_info_t. This info contains the
driver version as well as other info.
*/
GDL_API gdl_ret_t
gdl_closed_caption_source(
gdl_plane_id_t plane_id
);
/**< @ingroup general
This function allows specification of the video stream to be used as the
source for closed caption data.
The vbd_flip() function (of the VBD interface) allows the caller to flip a
field/frame from a video stream onto a specified Universal Pixel Plane.
Closed caption data associated with the frame is passed along in the same
call.
However, it is possible for multiple video streams to be displayed at the
same time, on different planes. The internal TV encoder(s) can only process
one CC stream at a time -- intermixing streams will result in garbage being
displayed for CC text.
The plane ID passed to this function determines which CC stream will be
passed along to the internal TV encoder(s). CC data passed for streams
flipped onto any other planes will be discarded.
By default, the CC source is GDL_PLANE_ID_UNDEFINED, which causes *all* CC
data passed to vbd_flip() to be ignored.
@param [in] plane_id
The ID of the Universal Pixel Plane to which the currently selected CC
stream will be directed. If the value is GDL_PLANE_ID_UNDEFINED, all CC
data passed via vbd_flip() calls will be ignored.
*/
GDL_API gdl_ret_t
gdl_set_blending_model(
gdl_blending_model_t blending_model
);
/**< @ingroup general
This function sets a new blending model. Blending model controls the
configuration of the VDC blender, and hence the number of displays/planes
available to be programmed by applications.
@param [in] blending_model
The new blending model to use.
@b NOTE:
Before changing the blending model, all planes must be disabled (see
#gdl_flip).
Changing blending model will:
- Bring all planes to their default/reset configurations.
- Reset both displays/pipes (#gdl_set_display_info is required on relevant
pipes).
- Set a UPP z-order to the default one.
*/
GDL_API gdl_ret_t
gdl_get_blending_model(
gdl_blending_model_t * blending_model
);
/**< @ingroup general
This function gets the current blending model.
@param [out] blending_model
A pointer to a #gdl_blending_model_t enum that will hold the current blending model
*/
GDL_API gdl_ret_t
gdl_get_display_info(
gdl_display_id_t display_id,
gdl_display_info_t * display_info
);
/**< @ingroup disp_mode
This routine returns the current display settings including resolution,
refresh rate, and so on.
@param [in] display_id
The ID of the display whose settings should be retrieved.
@param [out] display_info
A pointer to a #gdl_display_info_t structure that will receive the current
display settings.
*/
GDL_API gdl_ret_t
gdl_set_display_info(
gdl_display_info_t * display_info
);
/**< @ingroup disp_mode
This routine sets the display to the configuration specified by the
display_info parameter.
@param [in] display_info
The desired display configuration. The 'id' field of the structure
indicates the display that is to be configured.
<b>WARNING !!!!!!!!!!!!!!!!!!</b>
- Changing display mode requires port drivers to reset internal state,
and glitches are unavoidable.
- Since HDMI audio signals are carried within the video signals,
resetting the state of the HDMI port driver with active audio can
result in an audio pipeline stall. To avoid this, the application
must use the audio API to stop HDMI audio prior to changing the
display mode and reconfigure/restart HDMI audio afterwards. See
the Intel(R) CE Media Processors SMD C-API Programmer's Guide for
details on the SMD audio API.
@b NOTE:
Changing display mode will disable all planes that were programmed with
#gdl_flip_stereo call.
*/
GDL_API gdl_ret_t
gdl_check_tvmode(
gdl_display_id_t id,
gdl_tvmode_t * mode
);
/**< @ingroup disp_mode
Returns #GDL_SUCCESS if and only if the specified display mode is supported
on all of the port drivers currently active on the specified display.
@param [in] id
Display of interest.
@param [in] mode
Mode of interest.
*/
GDL_API gdl_ret_t
gdl_get_port_tvmode_by_index(
gdl_pd_id_t id,
gdl_uint32 index,
gdl_tvmode_t * mode
);
/**< @ingroup disp_mode
This routine can be used to enumerate the display modes supported by a
given port driver. The supported modes are indexed by 0-based consecutive
integer values. Calling this function with index==0 will return
information about the first supported mode; calling it with index==1
will return information about the second supported mode; and so on.
The function returns GDL_SUCCESS as long as 'index' < N, where N is the
number of modes supported by the port driver.
@param [in] id
Port driver of interest.
@param [in] index
Mode index.
@param [out] mode
Display mode information is returned here if the return value is
GDL_SUCCESS; otherwise, the contents of this structure are meaningless.
*/
GDL_API gdl_ret_t
gdl_display_wait_for_vblank(
gdl_display_id_t display_id,
gdl_polarity_t * polarity
);
/**< @ingroup disp_vbi
This routine will block until the next Vertical Blanking Interval (VBI) has
begun on the specified display_id, as indicated by the VBlank signal.
Return value other than GDL_SUCCESS indicates that no VBI occurred during
the expected timeinterval. This may indicate that specified pipe/display is
not enabled.
@b NOTE: The latency between VBI and return from this call can be affected
by a system load.
@param [in] display_id
Display/Pipe on which to wait for the next VBI.
@param [out] polarity
If this argument is NULL it is ignored. Otherwise, the polarity of the
video image currently being scanned out is returned via this pointer. E.g.,
a return value of #GDL_POLARITY_FIELD_TOP indicates that a top field is now
being scanned out (the VBlank came at the conclusion of the scanout of a
bottom field).
*/
GDL_API gdl_ret_t
gdl_display_get_polarity(
gdl_display_id_t display_id,
gdl_polarity_t * polarity
);
/**< @ingroup disp_vbi
This routine immediately returns the polarity of the display image that is
currently being scanned out on the specified Display ID. E.g., a return
value of #GDL_POLARITY_FIELD_TOP indicates that a top field is now being
scanned out; its scanout will conclude at the next VBlank.
@param [in] display_id
Display ID on which polarity is queried.
@param [out] polarity
The polarity is returned here. See #gdl_polarity_t.
*/
GDL_API gdl_ret_t
gdl_wait_for_vblank(
gdl_polarity_t * polarity
);
/**< @ingroup disp_vbi
This routine will block until the next Vertical Blanking Interval (VBI) has
begun, as indicated by the VBlank signal. Return value other than
GDL_SUCCESS indicates that no VBI occurred during the expected time
interval. This may indicate that PIPE A is not enabled.
@b NOTE: The latency between VBI and return from this call can be affected
by a system load.
@param [out] polarity
If this argument is NULL it is ignored. Otherwise, the polarity of the
video image currently being scanned out is returned via this pointer. E.g.,
a return value of #GDL_POLARITY_FIELD_TOP indicates that a top field is now
being scanned out (the VBlank came at the conclusion of the scanout of a
bottom field).
@b NOTE: Deprecated function. Use #gdl_display_wait_for_vblank instead.
*/
GDL_API gdl_ret_t
gdl_get_display_polarity(
gdl_polarity_t * polarity
);
/**< @ingroup disp_vbi
This routine immediately returns the polarity of the display image that is
currently being scanned out. E.g., a return value of
#GDL_POLARITY_FIELD_TOP indicates that a top field is now being scanned
out; its scanout will conclude at the next VBlank.
@param [out] polarity
The polarity is returned here. See #gdl_polarity_t.
@b NOTE: Deprecated function. Use #gdl_display_get_polarity instead.
*/
GDL_API gdl_ret_t
gdl_alloc_surface(
gdl_pixel_format_t pixel_format,
gdl_uint32 width,
gdl_uint32 height,
gdl_uint32 flags,
gdl_surface_info_t * surface_info
);
/**< @ingroup surface
This routine allocates a surface with the specified characteristics. The
driver will determine the required alignment and validate the requested
surface attributes, and may alter them according to the device status.
@param [in] pixel_format
The pixel format of the surface.
@param [in] width
The width of the surface in pixels.
@param [in] height
The height of the surface in pixels.
@param [in] flags
Any number of flags of type #gdl_surface_flag_t OR'd together that
describe the type of surface and the intended usage.
@param [out] surface_info
This parameter is returned to the caller and contains information about the
surface that was just created.
@b NOTE
Exiting the application or terminating the GDL session via a call to
gdl_close() without freeing the surface will result in its automatic
deallocation. A warning message will be printed to the system console and
log.
*/
GDL_API gdl_ret_t
gdl_get_surface_info(
gdl_surface_id_t surface_id,
gdl_surface_info_t * surface_info
);
/**< @ingroup surface
This routine returns the gdl_surface_info_t data structure for the requested
surface.
@param [in] surface_id
The ID of the surface for which information is requested.
@param [out] surface_info
A pointer to a #gdl_surface_info_t structure to be filled with information
about the specified surface.
*/
GDL_API gdl_ret_t
gdl_flush_surface(
gdl_surface_id_t surface_id
);
/**< @ingroup surface
This routine flushes cached memory used by the surface. Flushing only has any
effect when surface is allocated with #GDL_SURFACE_CACHED flag.
@param [in] surface_id
The ID of the surface to be flushed.
*/
GDL_API gdl_ret_t
gdl_map_surface(
gdl_surface_id_t surface_id,
gdl_uint8 ** pointer,
gdl_uint32 * pitch
);
/**< @ingroup surface
This routine provides a direct pointer to the surface's buffer mapped into
the caller's address space. Synchronization of any graphics operations
pending on that surface must be handled by the caller before using the
pointer.
A surface may be mapped by more than one thread.
The surface must be unmapped prior to freeing it; an attempt to free a
mapped surface will fail.
@param [in] surface_id
The ID of the surface that to be mapped.
@param [out] pointer
CPU accessible address of the surface.
@param [out] pitch
The pitch of the mapped surface in bytes. This is an optional output
parameter and will be ignored if it is NULL. In the case of a YUV
planar or pseudo-planar surface, this is the pitch of the Y surface.
*/
GDL_API gdl_ret_t
gdl_unmap_surface(
gdl_surface_id_t surface_id
);
/**< @ingroup surface
This routine unmaps the surface's buffer from the callers address space.
All surfaces should be unmapped when the pointer is no longer needed.
An attempt to free a mapped surface will fail.
@param [in] surface_id
The ID of the surface that is to be unmapped.
*/
GDL_API gdl_ret_t
gdl_free_surface(
gdl_surface_id_t surface_id
);
/**< @ingroup surface
This routine destroys the memory associated with the specified surface.
@param [in] surface_id
The ID of the surface that to be destroyed.
@b NOTE
- Freeing a surface that is currently being displayed on a plane, will cause
the plane to be disabled. A warning will be printed to the system console
and log.
- Attempting to free a surface that is currently mapped by anyone will
result in a #GDL_ERR_MAPPED error.
- Passing an invalid surface ID or the ID GDL_SURFACE_INVALID will result in
an error return.
*/
GDL_API gdl_ret_t
gdl_get_palette(
gdl_surface_id_t surface_id,
gdl_palette_t * palette
);
/**< @ingroup surface
This routine returns the palette entries for the specified surface.
@param [in] surface_id
The ID of the surface whose palette entries are to be returned.
@param [in,out] palette
The length field of the palette structure contains the number of palette
entries requested by the user. Upon completion of this call it may be
updated with the actual number of palette entries (if less than the
specified length) or with zero(if there is no palette associated with the
surface). The data field will be filled with palette entries.
*/
GDL_API gdl_ret_t
gdl_set_palette(
gdl_surface_id_t surface_id,
gdl_palette_t * palette
);
/**< @ingroup surface
This routine assigns the specified palette to the specified surface.
An error will be returned if the pixel format of the surface is not a
palettized format.
Note that the palette info is copied into the driver: changing entries in
a palette has no effect until the next time gdl_set_palette() is called.
Also note that changing the palette of a surface that is currently flipped
onto a plane does <b>not</b> change the displayed colors: the surface
must be flipped onto the plane again after the palette is set.
@param [in] surface_id
The ID of the surface whose palette entries will be set.
@param [in] palette
A pointer to a palette structure containing color data as well as number
of active palette elements
*/
GDL_API gdl_ret_t
gdl_get(
gdl_surface_id_t surface_id,
gdl_rectangle_t * rect,
gdl_uint32 pitch,
gdl_void * data,
gdl_uint32 flags
);
/**< @ingroup surface
This routine copies a rectangular region of pixel data out of a surface to
a buffer.
@param [in] surface_id
The ID of the surface from which the pixel data is read. This function is
currently only implemented for the following pixel formats, and will return
an error code if the surface has any other pixel format:
- GDL_PF_ARGB_32
- GDL_PF_RGB_32
- GDL_PF_RGB_24
- GDL_PF_ARGB_16_4444
- GDL_PF_RGB_16
- GDL_PF_RGB_15
@param [in] rect
The rectangle within the surface from which the data is to be read.
The origin is relative to the origin of the surface. Both the origin
coordinates and the dimensions of the rectangle are specified in pixels.
A NULL pointer indicates that the rectangle is the entire surface.
@param [in] pitch
The pitch of the output data buffer. It must be greater than or equal to
@code
rect->width * <bytes-per-pixel>
@endcode
@param [out] data
The address of the buffer to which the pixel data should be copied.
The size of the buffer must be greater than or equal to
@code
rect->height * pitch
@endcode
@param [in] flags
None currently defined -- pass as 0.
*/
GDL_API gdl_ret_t
gdl_put(
gdl_surface_id_t surface_id,
gdl_rectangle_t * rect,
gdl_uint32 pitch,
gdl_void* data,
gdl_uint32 flags
);
/**< @ingroup surface
This routine copies a rectangular region of pixel data into a surface from
a buffer.
@param [in] surface_id
The ID of the surface to which the pixel data will be written. This
function is currently only implemented for the following pixel formats, and
will return an error code if the surface has any other pixel format:
- GDL_PF_ARGB_32
- GDL_PF_RGB_32
- GDL_PF_RGB_24
- GDL_PF_ARGB_16_4444
- GDL_PF_RGB_16
- GDL_PF_RGB_15
@param [in] rect
The rectangle within the surface to which the data is to be written.
The origin is relative to the origin of the surface. Both the origin
coordinates and the dimensions of the rectangle are specified in pixels.
A NULL pointer indicates that the rectangle is the entire surface.
@param [in] pitch
The pitch of the input data buffer. It must be greater than or equal to
@code
rect->width * <bytes-per-pixel>
@endcode
@param [in] data
The address of the buffer from which the pixel data should be copied.
The pixel format of the data is assumed to be that of the surface.
The size of the buffer must be greater than or equal to
@code
rect->height * pitch
@endcode
@param [in] flags
None currently defined -- pass as 0.
*/
GDL_API gdl_ret_t
gdl_clear_surface(
gdl_surface_id_t surface_id,
gdl_color_t * color
);
/**< @ingroup surface
This routine clears a surface by setting all of its pixels to the specified
color.
@param [in] surface_id
The ID of the surface to be cleared. Only packed pixel formats are
supported by this function; if the surface has a pseudo-planar video pixel
format, the call will fail.
@param [in] color
The input color for the operation. Note that:
- The pixel format of the surface will determine which fields and bits
of the gdl_color_t item are used. For example, if the pixel format is
GDL_PF_RGB_16, then:
- none of the alpha_index field will be used.
- the low-order 5 bits of the r_y field will be used.
- the low-order 6 bits of the g_u field will be used.
- the low-order 5 bits of the b-v field will be used.
.
- If the surface is supposed to contain pixels with premultiplied alpha
it is the programmer's responsibility to pass a color whose components
have been premultiplied.
*/
GDL_API gdl_ret_t
gdl_plane_capabilities(
gdl_plane_id_t plane_id,
gdl_plane_info_t * info
);
/**< @ingroup plane_management
This function returns information about the hardware capabilities of the
specified display plane.
The returned data structure will report the plane name, the
programmer-configurable attributes, and the pixel formats supported by the
plane. See #gdl_plane_info_t to determine how to interpret the returned
information.
@param [in] plane_id
The ID of the plane for which information should be returned.
@param [out] info
Plane information is returned here.
*/
GDL_API gdl_ret_t
gdl_plane_config_begin(
gdl_plane_id_t plane_id
);
/**< @ingroup plane_management
This function begins a configuration transaction for the specified plane.
After making this call, the application program can call the gdl_plane_set_*
functions to change the attributes of interest. No new attribute values
are actually set in the hardware until a call is made to
gdl_plane_config_end().
The "batching" of attribute settings reduces the number of round trips
made to the driver and helps avoid invalid intermediate states when
interrelated attributes are being changed.
Only one transaction can be open at a time. If a corresponding call to
gdl_plane_config_end() is not made before the next call to
gdl_plane_config_begin(), an error will be returned.
@param [in] plane_id
The ID of the plane for which a configuration transaction should be
begun.
@see gdl_plane_config_end(), gdl_plane_set_uint(), gdl_plane_set_int(),
gdl_plane_set_rect(), gdl_plane_set_attr(),
*/
GDL_API gdl_ret_t
gdl_plane_config_end(
gdl_boolean_t abort
);
/**< @ingroup plane_management
This function delimits the end of a configuration transaction. All
attributes specified via gdl_plane_set_* calls since the last call to
gdl_plane_config_begin() are validated and applied.
The 'abort' argument causes all pending configuration settings to be
discarded without being applied.
It is an error to call this function without a preceding call to
gdl_plane_config_begin(). If this function is called with abort=#GDL_TRUE,
the return value can be safely ignored and the caller is guaranteed that
there are no configuration operations pending or in progress for the calling
application.
@param [in] abort
If #GDL_FALSE, all plane attributes set since the last call to
gdl_plane_config_begin() are validated and applied. Otherwise, all
pending settings are discarded and the transaction is terminated
without any change to the hardware.
@see gdl_plane_config_begin()
*/
GDL_API gdl_ret_t
gdl_plane_set_int(
gdl_plane_attr_t name,
gdl_int32 value
);
/**< @ingroup plane_management
See gdl_plane_set_attr()
*/
GDL_API gdl_ret_t
gdl_plane_set_uint(
gdl_plane_attr_t name,
gdl_uint32 value
);
/**< @ingroup plane_management
See gdl_plane_set_attr()
*/
GDL_API gdl_ret_t
gdl_plane_set_float(
gdl_plane_attr_t name,
gdl_f32 value
);
/**< @ingroup plane_management
See gdl_plane_set_attr()
*/
GDL_API gdl_ret_t
gdl_plane_set_rect(
gdl_plane_attr_t name,
gdl_rectangle_t * value
);
/**< @ingroup plane_management
See gdl_plane_set_attr()
*/
GDL_API gdl_ret_t
gdl_plane_set_attr(
gdl_plane_attr_t name,
void * value
);
/**< @ingroup plane_management
These functions queue the specified attribute setting for execution in the
currently open configuration transaction. They vary from each other only
in the type of value they accept, which must be appropriate for the
specified attribute.
It is an error to call any of these functions with the "name" of an
attribute that has a type different from that of the function.
It is an error to call any of these functions without a preceding call to
gdl_plane_config_begin().
The plane is not actually reconfigured until the next call to
gdl_plane_config_end(). It is possible that an error caused by passing
erroneous or conflicting values to the "set" functions will not be
detected until then.
Note that data values passed to these routines are cached -- the
application does @b not need to preserve the data or pointers until the
gdl_plane_config_end() is called.
@param [in] name
The attribute to be changed.
@param [in] value
The new setting (or, for multi-word values, pointer to the new setting)
for the attribute.
@see gdl_plane_config_begin(), gdl_plane_config_end()
*/
GDL_API gdl_ret_t
gdl_plane_get_int(
gdl_plane_id_t plane,
gdl_plane_attr_t name,
gdl_int32 * value
);
/**< @ingroup plane_management
See gdl_plane_get_attr()
*/
GDL_API gdl_ret_t
gdl_plane_get_uint(
gdl_plane_id_t plane,
gdl_plane_attr_t name,
gdl_uint32 * value
);
/**< @ingroup plane_management
See gdl_plane_get_attr()
*/
GDL_API gdl_ret_t
gdl_plane_get_float(
gdl_plane_id_t plane,
gdl_plane_attr_t name,
gdl_f32 * value
);
/**< @ingroup plane_management
See gdl_plane_get_attr()
*/
GDL_API gdl_ret_t
gdl_plane_get_rect(
gdl_plane_id_t plane,
gdl_plane_attr_t name,
gdl_rectangle_t * value
);
/**< @ingroup plane_management
See gdl_plane_get_attr()
*/
GDL_API gdl_ret_t
gdl_plane_get_attr(
gdl_plane_id_t plane,
gdl_plane_attr_t name,
void * value
);
/**< @ingroup plane_management
These functions retrieve the current value of the specified attribute
for the specified plane. These functions vary from each other only in the
type of value they return.
It is an error to call any of these functions with the "name" of an
attribute that has a type different from that of the function.
@param [in] plane
The plane to be queried.
@param [in] name
The attribute whose value is to be retrieved.
@param [out] value
The current value of the attribute is returned here.
*/
GDL_API gdl_ret_t
gdl_plane_reset(
gdl_plane_id_t plane
);
/**< @ingroup plane_management
Disables the specified plane and resets its attributes to their defaults.
@param [in] plane
The plane to be reset.
*/
GDL_API gdl_ret_t
gdl_plane_reset_all(
void
);
/**< @ingroup plane_management
Disables all planes and reset their attributes to their defaults.
*/
GDL_API gdl_ret_t
gdl_flip_stereo(
gdl_plane_id_t left_plane_id,
gdl_surface_id_t left_surface_id,
gdl_surface_id_t right_surface_id,
gdl_int32 shift,
gdl_flip_t type);
/**< @ingroup plane_management
This function makes the specified left/right surfaces visible on
the left/right views during stereo video modes.
This function should only be called when a stereo display mode is in effect.
@param [in] left_plane_id