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 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293
|
X-Video Motion Compensation - API specification v. 1.0
Mark Vojkovich <markv@xfree86.org>
/* history */
first draft (9/6/00)
second draft (10/31/00) - Changed to allow acceleration at both
the motion compensation and IDCT level.
third draft (1/21/01) - Some refinements and subpicture support.
fourth draft (5/2/01) - Dual Prime clarification, add
XvMCSetAttribute.
fifth draft (6/26/01) - Change definition of XvMCCompositeSubpicture
plus some clarifications and fixed typographical errors.
sixth draft (9/24/01) - Added XVMC_SECOND_FIELD and removed
XVMC_PROGRESSIVE_FRAME and XVMC_TOP_FIELD_FIRST flags.
seventh draft (10/26/01) - Added XVMC_INTRA_UNSIGNED option.
eighth draft (11/13/02) - Removed IQ level acceleration and
changed some structures to remove unused fields.
/* acknowledgements */
Thanks to Matthew J. Sottek from Intel for lots of input.
/********************************************************************/
OVERVIEW
/********************************************************************/
XvMC extends the X-Video extension (Xv) and makes use of the
familar concept of the XvPort. Ports have attributes that can be set
and queried through Xv. In XvMC ports can also have hardware motion
compensation contexts created for use with them. Ports which support
XvImages (ie. they have an "XV_IMAGE" port encoding as described in
the Xv version 2.2 API addendum) can be queried for the list of XvMCSurface
types they support. If they support any XvMCSurface types an
XvMCContext can be created for that port.
An XvMCContext describes the state of the motion compensation
pipeline. An individual XvMCContext can be created for use with
a single port, surface type, motion compensation type, width and
height combination. For example, a context might be created for a
particular port that does MPEG-2 motion compensation on 720 x 480
4:2:0 surfaces. Once the context is created, referencing it implies
the port, surface type, size and the motion compensation type. Contexts
may be "direct" or "indirect". For indirect contexts the X server
renders all video using the data passed to it by the client. For
direct contexts the client libraries render the video with little
or no interaction with the X server.
XvMCSurfaces are buffers into which the motion compensation
hardware can render. The data in the buffers themselves are not client
accessible and may be stored in a hardware-specific format. Any
number of buffers can be created for use with a particular context
(resources permitting).
XvMC provides video acceleration starting at one of two places
in the video pipeline. Acceleration starting at the first point,
which we shall call the "Motion Compensation" level, begins after the
the inverse quantization and IDCT at the place where motion compensation
is to be applied. The second point, which we shall call the "IDCT"
level, begins before the IDCT just after the inverse quantization.
Rendering is done by presenting the library with a target XvMCSurface
and up to two reference XvMCSurfaces for the motion compensation, a
buffer of 8x8 blocks and a command buffer which describes how to
use the 8x8 blocks along with motion compensation vectors to construct
the data in the target XvMCSurface. When the pipeline starts at the
IDCT level, Xv will perform the IDCT on the blocks before performing
the motion compensation. A function is provided to copy/overlay a
portion of the XvMCSurface to a drawable with arbitrary scaling.
XvMCSubpictures are separate surfaces that may be blended with the
target surface. Any number of XvMCSubpictures may be created for use
with a context (resources permitting). Both "backend" and "frontend"
subpicture behavior are supported.
/********************************************************************/
QUERYING THE EXTENSION
/********************************************************************/
/* Errors */
#define XvMCBadContext 0
#define XvMCBadSurface 1
#define XvMCBadSubpicture 2
Bool XvMCQueryExtension (Display *display, int *eventBase, int *errBase)
Returns True if the extension exists, False otherwise. Also returns
the error and event bases.
display - The connection to the server.
eventBase -
errBase - The returned event and error bases. Currently there
are no events defined.
Status XvMCQueryVersion (Display *display, int *major, int *minor)
Query the major and minor version numbers of the extension.
display - The connection to the server.
major -
minor - The returned major and minor version numbers.
/********************************************************************/
QUERYING SURFACE TYPES
/********************************************************************/
/* Chroma formats */
#define XVMC_CHROMA_FORMAT_420 0x00000001
#define XVMC_CHROMA_FORMAT_422 0x00000002
#define XVMC_CHROMA_FORMAT_444 0x00000003
/* XvMCSurfaceInfo Flags */
#define XVMC_OVERLAID_SURFACE 0x00000001
#define XVMC_BACKEND_SUBPICTURE 0x00000002
#define XVMC_SUBPICTURE_INDEPENDENT_SCALING 0x00000004
#define XVMC_INTRA_UNSIGNED 0x00000008
/* Motion Compensation types */
#define XVMC_MOCOMP 0x00000000
#define XVMC_IDCT 0x00010000
#define XVMC_MPEG_1 0x00000001
#define XVMC_MPEG_2 0x00000002
#define XVMC_H263 0x00000003
#define XVMC_MPEG_4 0x00000004
typedef struct {
int surface_type_id;
int chroma_format;
unsigned short max_width;
unsigned short max_height;
unsigned short subpicture_max_width;
unsigned short subpicture_max_height;
int mc_type;
int flags;
} XvMCSurfaceInfo;
surface_type_id - Unique descriptor for this surface type.
chroma_format - Chroma format of this surface (eg. XVMC_CHROMA_FORMAT_420,
XVMC_CHROMA_FORMAT_422, XVMC_CHROMA_FORMAT_444).
max_width -
max_height - Maximum dimensions of the luma data in pixels.
subpicture_max_width -
subpicture_max_height - The Maximum dimensions of the subpicture
that can be created for use with this surface
Both fields are zero if subpictures are not
supported.
mc_type - The type of motion compensation available for this
surface. This consists of XVMC_MPEG_1, XVMC_MPEG_2, XVMC_H263
or XVMC_MPEG_4 OR'd together with any of the following:
XVMC_MOCOMP - Acceleration starts at the motion compensation
level;
XVMC_IDCT - Acceleration starts at the IDCT level.
flags - Any combination of the following may be OR'd together.
XVMC_OVERLAID_SURFACE - Displayed data is overlaid and not
physically in the visible framebuffer.
When this is set the client is responsible
for painting the colorkey.
XVMC_BACKEND_SUBPICTURE - The supicture is of the "backend"
variety. It is "frontend" otherwise.
There is more information on this in the
section on subpictures below.
XVMC_SUBPICTURE_INDEPENDENT_SCALING - The subpicture can be scaled
independently of the video
surface. See the section on
subpictures below.
XVMC_INTRA_UNSIGNED - When this flag is set, the motion compenstation
level Intra macroblock data should be in an
unsigned format rather than the signed format
present in the mpeg stream. This flag applies
only to motion compensation level acceleration.
XvMCSurfaceInfo * XvMCListSurfaceTypes(Display *dpy, XvPortID port, int *num)
Returns the number of surface types supported by the XvPort and an array
of XvMCSurfaceInfo describing each surface type. The returned array
should be freed with XFree().
dpy - The connection to the server.
port - The port we want to get the XvMCSurfaceInfo array for.
num - The number of elements returned in the array.
Errors:
XvBadPort - The requested port does not exist.
BadAlloc - There are insufficient resources to complete this request.
/********************************************************************/
CREATING A CONTEXT
/********************************************************************/
/* XvMCContext flags */
#define XVMC_DIRECT 0x00000001
typedef struct {
XID context_id;
int surface_type_id;
unsigned short width;
unsigned short height;
XVPortID port;
int flags;
void * privData; /* private to the library */
} XvMCContext;
context_id - An XID associated with the context.
surface_type_id - This refers to the XvMCSurfaceInfo that describes
the surface characteristics.
width -
height - The dimensions (of the luma data) this context supports.
port - The port that this context supports.
flags - Any combination may be OR'd together.
XVMC_DIRECT - This context is direct rendered.
Status XvMCCreateContext (
Display display,
XVPortID port,
int surface_type_id,
int width,
int height,
int flags,
XvMCContext * context
);
This creates a context by filling out the XvMCContext structure passed
to it and returning Success.
display - Specifies the connection to the server.
port - Specifies the port to create the context for.
surface_type_id -
width -
height - Specifies the surface type and dimensions that this
context will be used for. The surface_type_id corresponds
to the surface_type_id referenced by the XvMCSurfaceInfo.
The surface returned may be larger than the surface requested
(usually the next larger multiple of 16x16 pixels).
flags - Any of the following may by OR'd together:
XVMC_DIRECT - A direct context is requested.
If a direct context cannot be created the request
will not fail, rather, an indirect context will
be created instead.
context - Pointer to the pre-allocated XvMCContext structure.
Errors:
XvBadPort - The requested port does not exist.
BadValue - The dimensions requested are not supported by the
surface type.
BadMatch - The surface_type_id is not supported by the port.
BadAlloc - There are not sufficient resources to fulfill this
request.
Status XvMCDestroyContext (Display display, XvMCContext * context)
Destroys the specified context.
display - Specifies the connection to the server.
context - The context to be destroyed.
Errors:
XvMCBadContext - The XvMCContext is not valid.
/*********************************************************************/
SURFACE CREATION
/*********************************************************************/
typedef struct {
XID surface_id;
XID context_id;
int surface_type_id;
unsigned short width;
unsigned short height;
void *privData; /* private to the library */
} XvMCSurface;
surface_id - An XID associated with the surface.
context_id - The XID of the context for which the surface was created.
surface_type_id - Derived from the context_id, it specifies the
XvMCSurfaceInfo describing the surface.
width -
height - The width and height of the luma data.
Status
XvMCCreateSurface(
Display *display,
XvMCContext * context;
XvMCSurface * surface;
);
Creates a surface (Frame) for use with the specified context.
The surface structure is filled out and Success is returned if no
error occured.
context - pointer to a valid context. The context implies
the surface type to be created, and its dimensions.
surface - pointer to a pre-allocated XvMCSurface structure.
Errors:
XvMCBadContext - the context is not valid.
BadAlloc - there are insufficient resources to complete
this operation.
Status XvMCDestroySurface(Display *display, XvMCSurface *surface);
Destroys the given surface.
display - Specifies the connection to the server.
surface - The surface to be destroyed.
Errors:
XvMCBadSurface - The XvMCSurface is not valid.
/*********************************************************************/
RENDERING A FRAME
/*********************************************************************/
typedef struct {
XID context_id;
unsigned int num_blocks;
short *blocks;
void *privData; /* private to the library */
} XvMCBlockArray;
num_blocks - Number of 64 element blocks in the blocks array.
context_id - XID of the context these blocks were allocated for.
blocks - Pointer to an array of (64 * num_blocks) shorts.
Status XvMCCreateBlocks (
Display *display,
XvMCContext *context,
unsigned int num_blocks,
XvMCBlockArray * block
);
This allocates an array of DCT blocks in the XvMCBlockArray
structure passed to it. Success is returned if no error occured.
display - The connection to the server.
context - The context the block array is being created for.
num_blocks - The number of 64 element short blocks to be allocated.
This number must be non-zero.
block - A pointer to a pre-allocated XvMCBlockArray structure.
Errors:
XvMCBadContext - the context is invalid.
BadAlloc - There are insufficient resources to complete the
operation.
BadValue - num_blocks was zero.
Status XvMCDestroyBlocks (Display *display, XvMCBlockArray * block)
Frees the given array.
display - The connection to the server.
block - The block array to be freed.
----------------------------------------------------------
#define XVMC_MB_TYPE_MOTION_FORWARD 0x02
#define XVMC_MB_TYPE_MOTION_BACKWARD 0x04
#define XVMC_MB_TYPE_PATTERN 0x08
#define XVMC_MB_TYPE_INTRA 0x10
#define XVMC_PREDICTION_FIELD 0x01
#define XVMC_PREDICTION_FRAME 0x02
#define XVMC_PREDICTION_DUAL_PRIME 0x03
#define XVMC_PREDICTION_16x8 0x02
#define XVMC_PREDICTION_4MV 0x04
#define XVMC_SELECT_FIRST_FORWARD 0x01
#define XVMC_SELECT_FIRST_BACKWARD 0x02
#define XVMC_SELECT_SECOND_FORWARD 0x04
#define XVMC_SELECT_SECOND_BACKWARD 0x08
#define XVMC_DCT_TYPE_FRAME 0x00
#define XVMC_DCT_TYPE_FIELD 0x01
typedef struct {
unsigned short x;
unsigned short y;
unsigned char macroblock_type;
unsigned char motion_type;
unsigned char motion_vertical_field_select;
unsigned char dct_type;
short PMV[2][2][2];
unsigned int index;
unsigned short coded_block_pattern;
unsigned short pad0;
} XvMCMacroBlock;
x, y - location of the macroblock on the surface in units of macroblocks.
macroblock_type - can be any of the following flags OR'd together:
XVMC_MB_TYPE_MOTION_FORWARD - Forward motion prediction should
be done. This flag is ignored for
Intra frames.
XVMC_MB_TYPE_MOTION_BACKWARD - Backward motion prediction should
be done. This flag is ignored when
the frame is not bidirectionally
predicted.
XVMC_MB_TYPE_PATTERN - Blocks are referenced and they contain
differentials. The coded_block_pattern will
indicate the number of blocks and index will
note their locations in the block array.
XVMC_MB_TYPE_INTRA - Blocks are referenced and they are intra blocks.
The coded_block_pattern will indicate the number
of blocks and index will note their locations in
the block array. XVMC_MB_TYPE_PATTERN and
XVMC_MB_TYPE_INTRA are mutually exclusive. If
both are specified, XVMC_MB_TYPE_INTRA takes
precedence.
motion_type - If the surface is a field, the following are valid:
XVMC_PREDICTION_FIELD
XVMC_PREDICTION_16x8
XVMC_PREDICTION_DUAL_PRIME
If the surface is a frame, the following are valid:
XVMC_PREDICTION_FIELD
XVMC_PREDICTION_FRAME
XVMC_PREDICTION_DUAL_PRIME
motion_vertical_field_select - The following flags may be OR'd together
XVMC_SELECT_FIRST_FORWARD
XVMC_SELECT_FIRST_BACKWARD
XVMC_SELECT_SECOND_FORWARD
XVMC_SELECT_SECOND_BACKWARD
If the bit is set the bottom field is indicated.
If the bit is clear the top field is indicated.
X X X X D C B A
------- | | | |_ First vector forward
| | | |___ First vector backward
unused | |_____ Second vector forward
|_______ Second vector backward
PMV - The motion vector(s)
PMV[c][b][a]
a - This holds the vector. 0 = horizontal, 1 = vertical.
b - 0 = forward, 1 = backward.
c - 0 = first vector, 1 = second vector.
The motion vectors are used only when XVMC_MB_TYPE_MOTION_FORWARD
or XVMC_MB_TYPE_MOTION_BACKWARD are set.
DualPrime vectors must be fully decoded and placed in the PMV
array as follows.
Field structure:
PMV[0][0][1:0] from same parity
PMV[0][1][1:0] from opposite parity
Frame structure:
PMV[0][0][1:0] top from top
PMV[0][1][1:0] bottom from bottom
PMV[1][0][1:0] top from bottom
PMV[1][1][1:0] bottom from top
index - The offset in units of (64 * sizeof(short)) from the start of
the block array where this macroblock's DCT blocks, as indicated
by the coded_block_pattern, are stored.
coded_block_pattern - Indicates the blocks to be updated. The bitplanes
are specific to the mc_type of the surface. This
field is valid only if XVMC_MB_TYPE_PATTERN or
XVMC_MB_TYPE_INTRA are set. In that case the blocks
are differential or intra blocks respectively.
The bitplanes are described in ISO/IEC 13818-2
Figures 6.10-12.
dct_type - This field indicates whether frame pictures are frame DCT
coded or field DCT coded. ie XVMC_DCT_TYPE_FIELD or
XVMC_DCT_TYPE_FRAME.
typedef struct {
unsigned int num_blocks;
XID context_id;
XvMCMacroBlock *macro_blocks;
void *privData; /* private to the library */
} XvMCMacroBlockArray;
num_blocks - Number of XvMCMacroBlocks in the macro_blocks array.
context_id - XID of the context these macroblocks were allocated for.
macro_blocks - Pointer to an array of num_blocks XvMCMacroBlocks.
Status XvMCCreateMacroBlocks (
Display *display,
XvMCContext *context,
unsigned int num_blocks,
XvMCMacroBlockArray * blocks
);
This allocates an array of XvMCMacroBlocks in the XvMCMacroBlockArray
structure passed to it. Success is returned if no error occured.
display - The connection to the server.
context - The context the macroblock array is being created for.
num_blocks - The number of XvMCMacroBlocks to be allocated.
This number must be non-zero.
blocks - A pointer to a pre-allocated XvMCMacroBlockArray structure.
Errors:
XvMCBadContext - the context is invalid.
BadAlloc - There are insufficient resources to complete the
operation.
BadValue - num_blocks was zero.
Status XvMCDestroyMacroBlocks (Display *display, XvMCMacroBlockArray * block)
Frees the given array.
display - The connection to the server.
block - The macro block array to be freed.
------------------------------------------------------------
#define XVMC_TOP_FIELD 0x00000001
#define XVMC_BOTTOM_FIELD 0x00000002
#define XVMC_FRAME_PICTURE (XVMC_TOP_FIELD | XVMC_BOTTOM_FIELD)
#define XVMC_SECOND_FIELD 0x00000004
Status XvMCRenderSurface(
Display *display,
XvMCContext *context,
unsigned int picture_structure,
Surface *target_surface,
Surface *past_surface,
Surface *future_surface,
unsigned int flags,
unsigned int num_macroblocks,
unsigned int first_macroblock,
XvMCMacroBlockArray *macroblock_array,
XvMCBlockArray *blocks
);
This function renders the macroblocks passed to it. It will not
return until it has read all of the macroblocks, however, rendering
will usually not be completed by that time. The return of this
function means it is safe to touch the blocks and macroblock_array.
To synchronize rendering see the section on sychronization below.
display - The connection to the server.
context - The context used to render.
target_surface -
past_surface -
furture_surface -
The target_surface is required. If the future and past
surfaces are NULL, the target_surface is an "Intra" frame.
If the past surface is provided but not the future surface,
the target_surface is a "Predicted Inter" frame.
If both past and future surfaces are provided, the
target_surface is a "Bidirectionally-predicted Inter" frame.
Specifying a future surface without a past surface results
in a BadMatch.
All surfaces must belong to the same context.
picture_structure - XVMC_TOP_FIELD, XVMC_BOTTOM_FIELD or
XVMC_FRAME_PICTURE.
flags - Flags may include:
XVMC_SECOND_FIELD - For field pictures this indicates whether
the current field (top or bottom) is first
or second in the sequence.
num_macroblocks - The number of XvMCMacroBlock structures to execute in
the macroblock_array.
first_macroblock - The index of the first XvMCMacroBlock to process in the
macroblock_array.
blocks - The array of XvMCBlocks to be referenced by the XvMCMacroBlocks.
The data in the individual blocks are in raster scan order and
should be clamped to the limits specific to the acceleration
level. For motion compensation level acceleration this is 8
bits for Intra and 9 bits for non-Intra data. At the IDCT level
this is 12 bits.
Errors:
XvMCBadContext - The context is not valid.
XvMCBadSurface - Any of the surfaces are not valid.
BadMatch - Any of the surfaces do not belong to the specified
context or a future surface was specified without
a past surface.
BadValue - Unrecognized data for the picture_structure.
/***********************************************************************/
DISPLAYING THE SURFACE
/***********************************************************************/
Status
XvMCPutSurface(
Display *display,
XvMCSurface *surface,
Drawable draw,
short srcx,
short srcy,
unsigned short srcw,
unsigned short srch,
short destx,
short desty,
unsigned short destw,
unsigned short desth,
int flags
);
Display the rectangle from the source defined by srcx/y/w/h scaled
to destw by desth and placed at (destx, desty) on the given drawable.
This function is not guaranteed to be pipelined with previous rendering
commands and may display the surface immediately. Therefore, the client
must query that the surface has finished rendering before calling this
function.
display - The connection to the server.
surface - The surface to copy/overlay from.
draw - The drawable to copy/overlay the video on.
srcx -
srcy -
srcw -
srch - The rectangle in the source area from the surface that is
to be displayed.
destx -
desty -
destw -
desth - The rectangle in the destination drawable where the scaled
source rectangle should be displayed.
flags - this indicates the field to be displayed and can be XVMC_TOP_FIELD,
XVMC_BOTTOM_FIELD or XVMC_FRAME_PICTURE. XVMC_FRAME_PICTURE
displays both fields (weave).
Errors:
XvMCBadSurface - The surface is not valid.
BadDrawable - The drawable does not exist.
Status XvMCHideSurface(Display *display, XvMCSurface *surface)
Stops display of a surface. This is only needed if the surface is an
overlaid surface as indicated in the XvMCSurfaceInfo - it is a no-op
otherwise.
display - The connection to the server.
surface - The surface to be hidden.
Errors:
XvMCBadSurface - The surface is not valid.
/***********************************************************************/
COMPOSITING THE SUBPICTURE
/***********************************************************************/
XvImageFormatValues * XvMCListSubpictureTypes (
Display * display,
XvPortID port,
int surface_type_id,
int *count_return
)
Returns an array of XvImageFormatValues supported by the surface_type_id
describing the surface. The surface_type_id is acquired from the
XvMCSurfaceInfo. This list should be freed with XFree().
display - Specifies the connection to the X-server.
port - Specifies the port we are interested in.
surface_type_id - Specifies the surface type for which we want to
query the supported subpicture types.
count_return - the size of the returned array.
Errors:
BadPort - The port doesn't exist.
BadAlloc - There are insufficient resources to complete this request.
BadMatch - The surface type is not supported on that port.
typedef struct {
XID subpicture_id;
XID context_id;
int xvimage_id;
unsigned short width;
unsigned short height;
int num_palette_entries;
int entry_bytes;
char component_order[4];
void *privData; /* private to the library */
} XvMCSubpicture;
subpicture_id - An XID associated with this subpicture.
context_id - The XID of the context this subpicture was created for.
xvimage_id - The id descriptor of the XvImage format that may be used
with this subpicture.
width -
height - The dimensions of the subpicture.
num_palette_entries - For paletted formats only. This is the number
of palette entries. It is zero for XvImages
without palettes.
entry_bytes - Each component is one byte and entry_bytes indicates
the number of components in each entry (eg. 3 for
YUV palette entries). This field is zero when
palettes are not used.
component_order - Is an array of ascii characters describing the order
of the components within the bytes. Only entry_bytes
characters of the string are used.
Status
XvMCCreateSubpicture (
Display *display,
XvMCContext *context,
XvMCSubpicture *subpicture,
unsigned short width,
unsigned short height,
int xvimage_id
)
This creates a subpicture by filling out the XvMCSubpicture structure
passed to it and returning Success.
display - Specifies the connection to the X-Server.
context - The context to create the subpicture for.
subpicture - Pre-allocated XvMCSubpicture structure to be filled
out by this function.
width -
height - The dimensions of the subpicture.
xvimage_id - The id describing the XvImage format.
Errors:
BadAlloc - There are insufficient resources to complete this request.
XvMCBadContext - The specified context does not exist.
BadMatch - The XvImage format id specified is not supported by
the context.
BadValue - If the size requested is larger than the max size reported
in the XvMCSurfaceInfo.
Status
XvMCClearSubpicture (
Display *display,
XvMCSubpicture *subpicture,
short x,
short y,
unsigned short width,
unsigned short height,
unsigned int color
)
Clear the area of the given subpicture to "color".
display - The connection to the server.
subpicture - The subpicture to clear.
x -
y -
width -
height - The rectangle in the subpicture to be cleared.
color - The data to fill the rectangle with.
Errors:
XvMCBadSubpicture - The subpicture is invalid.
Status
XvMCCompositeSubpicture (
Display *display,
XvMCSubpicture *subpicture,
XvImage *image,
short srcx,
short srcy,
unsigned short width,
unsigned short height,
short dstx,
short dsty
)
Copies the XvImage to the XvMCSubpicture.
display - The connection to the server.
subpicture - The subpicture used as the destination of the copy.
image - The XvImage to be used as the source of the copy.
XvImages should be of the shared memory variety for
indirect contexts.
srcx -
srcy -
width -
height - The rectangle from the image to be composited.
dstx -
dsty - The location in the subpicture where the source rectangle
should be composited.
Errors:
XvMCBadSubpicture - The subpicture is invalid.
BadMatch - The subpicture does not support the type of XvImage
passed to this function.
Status
XvMCDestroySubpicture (Display *display, XvMCSubpicture *subpicture)
Destroys the specified subpicture.
display - Specifies the connection to the X-server.
subpicture - The subpicture to be destroyed.
Errors:
XvMCBadSubpicture - The subpicture specified does not exist.
Status
XvMCSetSubpicturePalette (
Display *display,
XvMCSubpicture *subpicture,
unsigned char *palette
)
Set the subpicture's palette. This applies to paletted subpictures
only.
display - The connection to the server.
subpicture - The subpicture on which to change the palette.
palette - A pointer to an array holding the palette data. The
size of this array is
num_palette_entries * entry_bytes
in size. The order of the components in the palette
is described by the component_order in the XvMCSubpicture
structure.
Errors:
XvMCBadSubpicture - The subpicture specified does not exist.
BadMatch - The specified subpicture does not use palettes.
Status
XvMCBlendSubpicture (
Display *display,
XvMCSurface *target_surface,
XvMCSubpicture *subpicture,
short subx,
short suby,
unsigned short subw,
unsigned short subh,
short surfx,
short surfy,
unsigned short surfw,
unsigned short surfh
)
Status
XvMCBlendSubpicture2 (
Display *display,
XvMCSurface *source_surface,
XvMCSurface *target_surface,
XvMCSubpicture *subpicture,
short subx,
short suby,
unsigned short subw,
unsigned short subh,
short surfx,
short surfy,
unsigned short surfw,
unsigned short surfh
)
The behavior of these two functions is different depending on whether
or not the XVMC_BACKEND_SUBPICTURE flag is set in the XvMCSurfaceInfo.
XVMC_BACKEND_SUBPICTURE set:
XvMCBlendSubpicture associates the subpicture with the target_surface.
Both will be displayed at the next call to XvMCPutSurface. Additional
blends before the call to XvMCPutSurface simply overrides the association.
Both the target_surface and subpicture will query XVMC_DISPLAYING from
the call to XvMCPutSurface until they are no longer displaying. It is
safe to associate the subpicture and target_surface before rendering has
completed (while they still query XVMC_RENDERING) but it is not safe to
call XvMCPutSurface at that time.
XvMCBlendSubpicture2 copies the source_surface to the target_surface
and associates the subpicture with the target_surface. This essentially
calls XvMCBlendSubpicture on the target_surface after the copy. Both
the subpicture and target_surface will query XVMC_DISPLAYING from the
call to XvMCPutSurface until they are no longer displaying. The
source_surface will not query XVMC_DISPLAYING as a result of this function.
The copy is pipelined with the rendering and will cause XVMC_RENDERING
to be queried until the copy is done.
XVMC_BACKEND_SUBPICTURE not set ("frontend" behavior):
XvMCBlendSubpicture is a no-op in this case.
XvMCBlendSubpicture2 blends the source_surface and subpicture and
puts it in the target_surface. This does not effect the status of
the source surface but will cause the target_surface to query
XVMC_RENDERING until the blend is completed.
display - The connection to the server.
subpicture - The subpicture to be blended into the video.
target_surface - The surface to be displayed with the blended subpicture.
source_surface - Source surface prior to blending.
subx -
suby -
subw -
subh - The rectangle from the subpicture to be blended.
surfx -
surfy -
surfw -
surfh - The rectangle in the XvMCSurface to blend the subpicture rectangle
into. If XVMC_SUBPICTURE_INDEPENDENT_SCALING is not set in the
XvMCSurfaceInfo subw must be equal to surfw and subh must be
equal to surfh height or else a BadValue error occurs.
Errors:
XvMCBadSurface - Any of the surfaces are invalid.
XvMCBadSubpicture - The subpicture is invalid.
BadMatch - The subpicture or any of the surfaces do not belong to the
same context.
BadValue - XVMC_SUBPICTURE_INDEPENDENT_SCALING is set and the source
and destination rectangles are different sizes.
/***********************************************************************/
SURFACE SYNCHRONIZATION
/***********************************************************************/
#define XVMC_RENDERING 0x00000001
#define XVMC_DISPLAYING 0x00000002
Status
XvMCSyncSurface (Display *display, XvMCSurface *surface)
This function blocks until all rendering requests on the surface
have been completed.
display - The connection to the server.
surface - The surface to synchronize.
Errors:
XvMCBadSurface - The surface is not valid.
Status
XvMCFlushSurface (Display *display, XvMCSurface *surface)
This function commits pending rendering requests to ensure that
they will be completed in a finite amount of time.
display - The connnection to the server.
surface - The surface whos rendering requests should be flushed.
Errors:
XvMCBadSurface - The surface is not valid.
Status
XvMCGetSurfaceStatus (Display *display, XvMCSurface *surface, int *stat)
display - The connection to the server.
surface - The surface whos status is being queried.
stat - May be any of the following OR'd together:
XVMC_RENDERING - The last XvMCRenderSurface request has not completed
yet.
XVMC_DISPLAYING - The surface is currently being displayed or a
display is pending (ie. it is not safe to render
to it).
Errors:
XvMCBadSurface - The surface is not valid.
/***********************************************************************/
SUBPICTURE SYNCHRONIZATION
/***********************************************************************/
Status
XvMCSyncSubpicture (Display *display, XvMCSubpicture *subpicture)
This function blocks until all composite/clear requests on the supicture
have been completed.
display - The connection to the server.
subpicture - The subpicture to synchronize.
Errors:
XvMCBadSubpicture - The subpicture is not valid.
Status
XvMCFlushSubpicture (Display *display, XvMCSubpicture *subpicture)
This function commits pending composite/clear requests to ensure that
they will be completed in a finite amount of time.
display - The connection to the server.
subpicture - The subpicture whos compositing should be flushed.
Errors:
XvMCBadSubpicture - The surface is not valid.
Status
XvMCGetSubpictureStatus (Display *display, XvMCSubpicture *subpic, int *stat)
display - The connection to the server.
subpic - The subpicture whos status is being queried.
stat - may be any of the following OR'd together:
XVMC_RENDERING - The last XvMCCompositeSubpicture or XvMCClearSubpicture
request has not completed yet.
XVMC_DISPLAYING - The subpicture is currently being displayed or a
display is pending (ie. it is not safe to render
to it).
Errors:
XvMCBadSubpicture - The surface is not valid.
/********************************************************************/
ATTRIBUTES
/********************************************************************/
Context specific attribute functions are provided. These are
similar to their Xv Counterparts XvQueryPortAttributes, XvSetPortAttribute
and XvGetPortAttribute but their state is specific to the context.
XvAttribute *
XvMCQueryAttributes (
Display *display,
XvMCContext *context,
int *number
)
An array of XvAttributes of size "number" is returned by this function.
If there are no attributes, NULL is returned and number is set to 0.
The array may be freed with XFree().
display - The connection to the server.
context - The context whos attributes we are querying.
number - The returned number of recognized atoms.
Errors:
XvMCBadContext - The context is invalid.
Status
XvMCSetAttribute (
Display *display,
XvMCContext *context,
Atom attribute,
int value
)
This function sets a context-specific attribute and returns Success
if no error has occurred.
display - The connection to the server.
context - The context for which the attribute change is to go into effect.
attribute - The X Atom of the attribute to be changed.
value - The new value of the attribute.
Errors:
XvMCBadContext - The context is not valid.
BadValue - An invalid value was specified.
BadMatch - This attribute is not defined for this context.
Status
XvMCGetAttribute (
Display *display,
XvMCContext *context,
Atom attribute,
int *value
)
This function queries a context-specific attribute and return
Success and the value if no error has occurred.
display - The connection to the server.
context - The context whos attribute we are querying.
attribute - The X Atom of the attribute to be retrieved.
value - The returned attribute value.
Errors:
XvMCBadContext - The context is not valid.
BadMatch - This attribute is not defined for this context.
|