epoc32/include/mmf/devvideo/mpeg4visual.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     1 // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
     2 // All rights reserved.
     3 // This component and the accompanying materials are made available
     4 // under the terms of "Eclipse Public License v1.0"
     5 // which accompanies this distribution, and is available
     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
     7 //
     8 // Initial Contributors:
     9 // Nokia Corporation - initial contribution.
    10 //
    11 // Contributors:
    12 //
    13 // Description:
    14 // Constants and structs specific to Mpeg4 Visual.  See the DevVideo specs for more details.
    15 // 
    16 //
    17 
    18 #ifndef __DEVVIDEO_MPEG4VISUAL_H__
    19 #define __DEVVIDEO_MPEG4VISUAL_H__
    20 
    21 #include <e32base.h>
    22 #include <mmf/devvideo/h263.h>
    23 
    24 /**
    25 Specifies the picture type.
    26 @publishedAll
    27 @released
    28 */
    29 enum TMPEG4VisualVOPType
    30     {
    31 	/**
    32 	An Intra-coded (I) VOP is coded using information only from itself.
    33 	*/
    34     EMPEG4VisualVOPTypeI = 0x01,
    35 
    36 	/**
    37 	A Predictive-coded (P) VOP is a VOP which is coded using motion compensated prediction from a 
    38 	past reference VOP.
    39 	*/
    40     EMPEG4VisualVOPTypeP = 0x02,
    41 
    42 	/**
    43 	A Bidirectionally predictive-coded (B) VOP is a VOP which is coded using motion compensated 
    44 	prediction from a past and/or future reference VOP(s).
    45 	*/
    46     EMPEG4VisualVOPTypeB = 0x04,
    47 
    48 	/**
    49 	A sprite (S) VOP is a VOP for a sprite object or a VOP which is coded using prediction based on
    50 	global motion compensation from a past reference VOP.
    51 	*/
    52     EMPEG4VisualVOPTypeS = 0x08
    53     };
    54 
    55 /**
    56 Specifies the MPEG-4 Visual header types.
    57 @publishedAll
    58 @released
    59 */
    60 enum TMPEG4VisualHeaderType
    61     {
    62 	/**
    63 	Visual Object Sequence Header.
    64 	*/
    65     EMPEG4VisualHeaderSequence = 0x01,
    66 
    67 	/**
    68 	Visual Object Header.
    69 	*/
    70     EMPEG4VisualHeaderObject   = 0x02,
    71 
    72 	/**
    73 	Video Object Layer Header.
    74 	*/
    75     EMPEG4VisualHeaderVOL      = 0x04,
    76 
    77 	/**
    78 	Group of Video Object Plane Header.
    79 	*/
    80     EMPEG4VisualHeaderGOV      = 0x08,
    81 
    82 	/**
    83 	Video Object Plane Header.
    84 	*/
    85     EMPEG4VisualHeaderVOP      = 0x10
    86     };
    87 
    88 
    89 /**
    90 Object sequence header.
    91 @publishedAll
    92 @released
    93 */
    94 class TMPEG4VisualObjectSequenceHeader
    95     {
    96 public:
    97 	/**
    98 	Used to signal the profile and level identification according to Table G-1 of MPEG-4 Visual.
    99 	*/
   100     TUint iProfileLevel;
   101 
   102 	/**
   103 	Contains the user_data bytes, if any, that are directly included in the VideoObjectSequence() 
   104 	syntax structure (subclause 6.2.2 of MPEG-4 Visual), in bitstream order. The pointer must remain
   105 	valid as long as the object it belongs to is being processed by the client (for playback) or MSL
   106 	video subsystem (for recording).
   107 	*/
   108     TPtrC8 iUserData;
   109     };
   110 
   111 /**
   112 Object header.
   113 @publishedAll
   114 @released
   115 */
   116 class TMPEG4VisualObjectHeader
   117     {
   118 public:
   119 	/**
   120 	Identifies the version number of the visual object as specified in the semantics of 
   121 	visual_object_verid syntax element of MPEG-4 Visual.
   122 	*/
   123     TUint iVisualObjectVerid;
   124 
   125 	/**
   126 	Specifies the priority of the visual object as specified in the semantics of 
   127 	visual_object_priority syntax element of MPEG-4 Visual. If the visual_object_priority syntax 
   128 	element is not present in the bitstream, iVisualObjectPriority shall be equal to 0.
   129 	*/
   130     TUint iVisualObjectPriority;
   131 
   132 	/**
   133 	Identifies the type of the visual object as specified in the semantics of 
   134 	visual_object_type syntax element of MPEG-4 Visual. HW devices according to this specification 
   135 	are required to set iVisualObjectType to 1 (to indicate "video ID").
   136 	*/
   137     TUint iVisualObjectType;
   138 
   139 	/**
   140 	Uniquely identifies the video object. The value of iVideoObjectId shall be the same as the 
   141 	value of the video_object_id syntax element specified in MPEG-4 Visual.
   142 	*/
   143     TUint iVideoObjectId;
   144 
   145 	/**
   146 	Contains the user_data bytes, if any, that are directly included in the VideoObject() syntax 
   147 	structure (subclause 6.2.2 of MPEG-4 Visual), in bitstream order. The pointer must remain valid
   148 	as long as the object it belongs to is being processed by the client (for playback) or MSL video
   149 	subsystem (for recording).
   150 	*/
   151     TPtrC8 iUserData;
   152     };
   153 
   154 /**
   155 Mpeg4 Visual VBV parameters.
   156 
   157 If the syntax elements that are used to derive the values of the class member variables are not 
   158 present in the bitstream, the variable values shall be set to default values as specified in 
   159 Annex D of MPEG-4 Visual.
   160 @publishedAll
   161 @released
   162 */
   163 class TMPEG4VisualVbvParams
   164     {
   165 public:
   166 	/**
   167 	Specifies the instantaneous video object layer channel bit rate in bits per second. Shall be set
   168 	to ((first_half_bit_rate << 15) + latter_half_bit_rate) * 400, where the values of 
   169 	first_half_bit_rate and latter_half_bit_rate are conveyed in the VideoObjectLayer syntax 
   170 	structure of MPEG-4 Visual.
   171 	*/
   172     TInt64 iBitRate;
   173 
   174 	/**
   175 	Specifies the VBV buffer size in bytes. Shall be set to 
   176 	((first_half_vbv_buffer_size) << 3) + latter_half_vbv_buffer_size) * 2048, 
   177 	where the values of first_half_vbv_buffer_size and latter_half_vbv_buffer_size are conveyed in 
   178 	the VideoObjectLayer syntax structure of MPEG-4 Visual.
   179 	*/
   180     TUint32 iVbvBufferSize;
   181 
   182 	/**
   183 	Specifies VBV occupancy in bytes just before the removal of the first VOP following the VOL 
   184 	header. The purpose for the quantity is to provide the initial condition for VBV buffer fullness. 
   185 	Shall be set to ((first_half_vbv_occupancy) << 15) + latter_half_vbv_occupancy) * 2048, where
   186 	the values of first_half_vbv_occupancy and latter_half_vbv_occupancy are conveyed in the 
   187 	VideoObjectLayer syntax structure of MPEG-4 Visual.
   188 	*/
   189     TUint32 iVbvOccupancy;
   190     };
   191 
   192 
   193 /**
   194 Video object layer header.
   195 @publishedAll
   196 @released
   197 */
   198 class TMPEG4VisualVOLHeader
   199     {
   200 public:
   201 	/**
   202 	Uniquely identifies the video object layer. The value of iVideoObjectLayerId shall be the same
   203 	as the value of the video_object_layer_id syntax element specified in MPEG-4 Visual.
   204 	*/
   205     TUint iVideoObjectLayerId;
   206 
   207 	/**
   208 	iShortVideoHeader equal to ETrue indicates that the associated elementary stream conforms to
   209 	ITU-T Recommendation H.263 (without optional coding modes).  The value of iShortVideoHeader 
   210 	shall be equal to the value of the short_video_header flag of MPEG-4 Visual. 
   211 	*/
   212     TBool iShortVideoHeader;
   213 
   214 	/**
   215 	iRandomAccessibleVOL equal to ETrue indicates that every VOP in this VOL is individually
   216 	decodable. The value of iRandomAccessibleVOL shall be equal to the value of the 
   217 	random_accessible_vol flag of MPEG-4 Visual.
   218 	*/
   219     TBool iRandomAccessibleVOL;
   220 
   221 	/**
   222 	Indicates the object type as specified in Table 6-10 of MPEG-4 Visual and constrains the 
   223 	associated elementary stream to use tools from the indicated object type. HW devices according
   224 	to this specification are required to set iVideoObjectTypeIndication to 1 (to indicate Simple
   225 	Object Type).
   226 	*/
   227     TUint iVideoObjectTypeIndication;
   228 
   229 	/**
   230 	Identifies the version number of the video object layer as specified in the semantics of 
   231 	video_object_layer_verid syntax element of MPEG-4 Visual.
   232 	*/
   233     TUint iVideoObjectLayerVerid;
   234 
   235 	/**
   236 	*/
   237     TUint iVideoObjectLayerPriority;
   238 
   239 	/**
   240 	Specifies the priority of the video object layer as specified in the semantics of 
   241 	video_object_layer_priority syntax element of MPEG-4 Visual. If the video_object_layer_priority
   242 	syntax element is not present in the bitstream, iVideoObjectLayerPriority shall be equal to 0.
   243 	*/
   244     TUint iAspectRatioNum;
   245 
   246 	/**
   247 	Pixel aspect ratio numerator and denominator respectively. The pixel aspect ratio is defined as 
   248 	iAspectRatioNum/iAspectRatioDenom, where the values are positive integers and relatively prime. 
   249 	These values shall be set according to the value of aspect_ratio_info, par_width (if present), 
   250 	and par_height (if present) syntax elements in the VideoObjectLayer() syntax structure of MPEG-4
   251 	Visual.
   252 	*/
   253     TUint iAspectRatioDenom;
   254 
   255 	/**
   256 	Specifies the VBV parameters in use for the VOL. The values in iVbvParams are valid if 
   257 	iShortVideoHeader equals to EFalse. If iShortVideoHeader equals to ETrue, the VBV operation and 
   258 	parameters are specified in Annex D of MPEG-4 Visual.
   259 	*/
   260     TMPEG4VisualVbvParams iVbvParams;
   261 
   262 	/**
   263 	Indicates the number of evenly spaced subintervals, called ticks, within one modulo time. One
   264 	modulo time represents the fixed interval of one second. Shall be set equal to the value of 
   265 	vop_time_increment_resolution of the VideoObjectLayer() syntax structure of MPEG-4 Visual.
   266 	*/
   267     TUint16 iVOPTimeIncrementResolution;
   268 
   269 	/**
   270 	iFixedVOPRate equal to ETrue indicates that all VOPs are coded with a fixed VOP rate. 
   271 	iFixedVOPRate equal to EFalse indicates that some VOPs may not be coded with a fixed VOP rate. 
   272 	Shall be set equal to the value of fixed_vop_rate of the VideoObjectLayer() syntax structure
   273 	of MPEG-4 Visual.
   274 	*/
   275     TBool iFixedVOPRate;
   276 
   277 	/**
   278 	The number of ticks between two successive VOPs in the display order. Valid only if 
   279 	iFixedVOPRate is equal to ETrue. Shall be set equal to the value of fixed_vop_time_increment 
   280 	of the VideoObjectLayer() syntax structure of MPEG-4 Visual.
   281 	*/
   282     TUint16 iFixedVOPTimeIncrement;
   283 
   284 	/**
   285 	iDataPartitioning equal to ETrue indicates that slices are organized in data partitions within 
   286 	the associated elementary bitstream. Shall be set equal to the value of the data_partitioned 
   287 	syntax element of the VideoObjectLayer() syntax structure of MPEG-4 Visual.
   288 	*/
   289     TBool iDataPartitioning;
   290 
   291 	/**
   292 	iReversibleVLC equal to ETrue indicates that the reversible variable length tables of MPEG-4 
   293 	Visual are in use in the associated elementary bistream. Shall be set equal to the value of the
   294 	reversible_vlc syntax element of the VideoObjectLayer() syntax structure of MPEG-4 Visual. If 
   295 	reversible_vlc is not present in the bitstream, the value of iReversibleVLC shall be set to 
   296 	EFalse.
   297 	*/
   298     TBool iReversibleVLC;
   299 
   300 	/**
   301 	Contains the user_data bytes, if any, that are directly included in the VideoObjectLayer()
   302 	syntax structure, in bitstream order. The pointer must remain valid as long as the object it 
   303 	belongs to is being processed by the client (for playback) or MSL video subsystem (for 
   304 	recording).
   305 	*/
   306     TPtrC8 iUserData;
   307     };
   308 
   309 
   310 /**
   311 Mpeg4 visual GOV header.
   312 @publishedAll
   313 @released
   314 */
   315 class TMPEG4VisualGOVHeader
   316     {
   317 public:
   318 	/**
   319 	iTimeCodeHours, iTimeCodeMinutes and iTimeCodeSeconds together specify the modulo part (i.e. the 
   320 	full second units) of the time base for the first object plane (in display order) after the GOV 
   321 	header according to the semantics of the time_code syntax element of MPEG-4 Visual.
   322 	*/
   323     TUint iTimeCodeHours;
   324 
   325 	/**
   326 	iTimeCodeHours, iTimeCodeMinutes and iTimeCodeSeconds together specify the modulo part (i.e. the 
   327 	full second units) of the time base for the first object plane (in display order) after the GOV 
   328 	header according to the semantics of the time_code syntax element of MPEG-4 Visual.
   329 	*/
   330     TUint iTimeCodeMinutes;
   331 
   332 	/**
   333 	iTimeCodeHours, iTimeCodeMinutes and iTimeCodeSeconds together specify the modulo part (i.e. the 
   334 	full second units) of the time base for the first object plane (in display order) after the GOV 
   335 	header according to the semantics of the time_code syntax element of MPEG-4 Visual.
   336 	*/
   337     TUint iTimeCodeSeconds;
   338 
   339 	/**
   340 	Indicates the nature of the predictions used in the first consecutive B-VOPs (if any) 
   341 	immediately following the first coded I-VOP after the GOV header. iClosedGOV equal to ETrue
   342 	indicates that there are no such B-VOPs or that these B-VOPs have been encoded using only 
   343 	backward prediction or intra coding. The value of iClosedGOV shall be set equal to the value of
   344 	closed_gov syntax element of MPEG-4 Visual.
   345 	*/
   346     TBool iClosedGOV;
   347 
   348 	/**
   349 	iBrokenLink equal to ETrue indicates that the first consecutive B-VOPs (if any) immediately 
   350 	following the first coded I-VOP following the GOV header may not be correctly decoded because
   351 	the reference frame which is used for prediction is not available (e.g., due to result of 
   352 	editing in compressed domain). A decoder may use this flag to avoid displaying frames that 
   353 	cannot be correctly decoded. The value of iBrokenLink shall be set equal to the value of 
   354 	broken_link syntax element of MPEG-4 Visual.
   355 	*/
   356     TBool iBrokenLink;
   357     };
   358 
   359 
   360 /**
   361 Mpeg4 visual VOP header.
   362 @publishedAll
   363 @released
   364 */
   365 class TMPEG4VisualVOPHeader
   366     {
   367 public:
   368 	/**
   369 	Indicates the coding type of the VOP.
   370 	*/
   371     TMPEG4VisualVOPType iVOPCodingType;
   372 
   373 	/**
   374 	Indicates the number of seconds elapsed since the previous GOV header or since the previous
   375 	picture in display order, whichever is closer in display order. The value of iModuloTimeBase 
   376 	shall be set equal to the decoded value derived from a series of modulo_time_base fields as 
   377 	specified in MPEG-4 Visual.
   378 	*/
   379     TUint iModuloTimeBase;
   380 
   381 	/**
   382 	VOP display time relative to iModuloTimeBase in clock ticks. The value of iVOPTimeIncrement 
   383 	shall be set equal to the value of the vop_time_increment syntax element of MPEG-4 Visual.
   384 	*/
   385     TUint16 iVOPTimeIncrement;
   386 
   387 	/**
   388 	iVOPCoded equal to EFalse indicates that the VOP is a copy of the previous VOP in display order.
   389 	The value of iVOPCoded shall be set equal to the value of the vop_coded syntax element of MPEG-4
   390 	Visual.
   391 	*/
   392     TBool iVOPCoded;
   393 
   394 	/**
   395 	Indicates the initial value of the quantization parameter. iVOPQuant shall be set equal to the
   396 	value of the vop_quant syntax element.
   397 	*/
   398     TUint iVOPQuant;
   399 
   400 	/**
   401 	Indicates the VOP ID. iVOPId shall be set equal to the value of the vop_id syntax element. Valid
   402 	only if the flag newpred_enable is equal to 1.
   403 	*/
   404     TUint16 iVOPId;
   405 
   406 	/**
   407 	When equal to ETrue indicates the following iVOPIdForPrediction is valid. Valid only if the flag
   408 	newpred_enable is equal to 1.
   409 	*/
   410     TBool iVOPIdForPredictionValid;
   411 
   412 	/**
   413 	Indicates VOP ID of the VOP that is used as the reference VOP for the current VOP. 
   414 	iVOPIdForPrediction shall be set equal to the value of the vop_id_for_prediction if the syntax 
   415 	element is present (i.e. the ). Valid only if iVOPIdForPredictionValid is equal to ETrue.
   416 	*/
   417     TUint16 iVOPIdForPrediction;
   418     };
   419 
   420 
   421 /**
   422 This class is used to convey information of Visual Object Sequence, Visual Object, VOL, GOV, and VOP 
   423 headers that are consecutive in decoding order without any intervening syntax structures.
   424 @publishedAll
   425 @released
   426 */
   427 class TMPEG4VisualHeader
   428     {
   429 public:
   430 	/**
   431 	A binary OR of values specified in TMPEG4VisualHeaderType:
   432 		* EMPEG4VisualHeaderSequence - set if the visual object sequence header is present and 
   433 		  iVisualObjectSequenceHeader is set accordingly. Otherwise, iVisualObjectSequenceHeader 
   434 		  shall be set to NULL.
   435 		* EMPEG4VisualHeaderObject - set if the visual object header is present and 
   436 		  iVisualObjectHeader is set accordingly. Otherwise, iVisualObjectHeader shall be set
   437 		  to NULL.
   438 		* EMPEG4VisualHeaderVOL - set if the VOL header is present and iVOLHeader is set accordingly.
   439 		  Otherwise, iVOLHeader shall be set to NULL.
   440 		* EMPEG4VisualHeaderGOV - set if the GOV header is present and iGOVHeader is set accordingly.
   441 		  Otherwise, iGOVHeader shall be set to NULL.
   442 		* EMPEG4VisualHeaderVOP - set if the VOP header is present and iVOPHeader is set accordingly.
   443 		  Otherwise, iVOPHeader shall be set to NULL
   444 	*/
   445     TUint32 iConsecutiveHeaders;
   446 
   447 	/**
   448 	The visual object sequence header.
   449 	*/
   450     const TMPEG4VisualObjectSequenceHeader* iVisualObjectSequenceHeader;
   451 
   452 	/**
   453 	The visual object header.
   454 	*/
   455     const TMPEG4VisualObjectHeader* iVisualObjectHeader;
   456 
   457 	/**
   458 	The VOL header.
   459 	*/
   460     const TMPEG4VisualVOLHeader* iVOLHeader;
   461 
   462 	/**
   463 	The GOV header.
   464 	*/
   465     const TMPEG4VisualGOVHeader* iGOVHeader;
   466 
   467 	/**
   468 	The VOP header.
   469 	*/
   470     const TMPEG4VisualVOPHeader* iVOPHeader;
   471     };
   472 
   473 
   474 
   475 /**
   476 This class is used to signal decoder or encoder capabilities.
   477 @publishedAll
   478 @released
   479 */
   480 class TMPEG4VisualCapability
   481     {
   482 public:
   483 	/*
   484 	iProfileLevel[ i ] indicates a supported combination of profile and level, i.e., 
   485 	profile_and_level_indication, according to Table G-1 of MPEG-4 Visual. The values of i from 62 
   486 	to 255 are reserved (the MPEG-4 Visual standard referenced in the present document has 62 
   487 	combinations of profile and level). 
   488 	*/
   489     TUint8 iProfileLevel[256];
   490     };
   491 
   492 
   493 /**
   494 This class is used to set the encoder operation mode.
   495 @publishedAll
   496 @released
   497 */
   498 class TMPEG4VisualNormalMPEG4Mode
   499     {
   500 public:
   501 	/**
   502 	Specifies the picture types allowed in the bitstream. The value is a binary OR of values from
   503 	TMPEG4VisualVOPType. Signaled picture types that are not included in the prevailing coding 
   504 	profile are ignored.
   505 	*/
   506     TMPEG4VisualVOPType iAllowedVOPTypes;
   507 	
   508 	/**
   509 	Specifies the number of consecutive video packet headers within a VOP, starting from the first
   510 	video packet header in decoding order, where the value of header_extension_code shall be set to 1. 
   511 	*/
   512     TUint iHeaderExtension;
   513 
   514 	/**
   515 	Specifies whether data partitioning is in use. When equal to ETrue, data partitioning is in use.
   516 	When equal to EFalse, data partitioning is not in use. If data partitioning is in use, the 
   517 	SetErrorProtectionLevelsL method, if used, should set the number of unequal error protection
   518 	levels to be larger than one. 
   519 	*/
   520     TBool iDataPartitioning;
   521 	
   522 	/**
   523 	Specifies whether reversible variable length coding is in use. When equal to ETrue, reversible 
   524 	variable length coding is in use. When equal to EFalse, reversible variable length coding is 
   525 	not in use. Valid only if iDataPartitioned is equal to ETrue.
   526 	*/
   527     TBool iReversibleVLC;
   528 	
   529 	/**
   530 	Specifies which headers are included in the first output buffer of each intra VOP. (Note: Video
   531 	Object Sequence and Video Object Headers can be repeated for error resiliency. VOL Header 
   532 	includes the initial buffer occupancy level. GOV header includes an update on display times.)
   533 	*/
   534     TMPEG4VisualHeaderType iHeadersBeforeIntraVOP;
   535     };
   536 
   537 /**
   538 This class is used to set the encoder operation mode.
   539 @publishedAll
   540 @released
   541 */
   542 class TMPEG4VisualMode
   543     {
   544 public:
   545 	/**
   546 	Indicates whether the short header mode of MPEG-4 Visual is used. If iShortHeaderMode is 
   547 	equal to ETrue, then iH263VideoMode is valid and all other parameter values are invalid. If 
   548 	iShortHeaderMode is equal to EFalse, then iH263VideoMode is invalid and all other parameter 
   549 	values are valid. 
   550 	*/
   551     TBool iShortHeaderMode;
   552 	
   553 	/**
   554 	Contains the encoding modes to use when iShortHeaderMode is EFalse.
   555 	*/
   556     TMPEG4VisualNormalMPEG4Mode iMPEG4VisualNormalMPEG4Mode;
   557 
   558 	/**
   559 	Contains the encoding modes to use when iShortHeaderMode is ETrue.
   560 	*/
   561     TH263VideoMode iH263VideoMode;
   562     };
   563 
   564 	
   565 
   566 #endif