|
Indeo® Video Interactive Video for Windows* Programming Interface Specification Revision 1.9
THIS DOCUMENT IS PROVIDED "AS IS" WITH NO WARRANTIES WHATSOEVER, INCLUDING ANY
WARRANTY OF MERCHANTABILITY, FITNESS FOR ANY PARTICULAR PURPOSE, OR ANY WARRANTY
OTHERWISE ARISING OUT OF ANY PROPOSAL, SPECIFICATION OR SAMPLE.
A license is hereby granted to copy and reproduce this document for internal use only. No other license, express or implied, by
estoppel or otherwise, to any other intellectual property rights is granted herein. Intel disclaims all liability for infringement of any
proprietary rights, relating to implementation of information in this specification. Intel does not warrant or represent that such
implementation(s) will not infringe such rights.
The Features and Capabilities within this document are subject to change without notice.
Video for Windows Programming Interface
Specification
The Indeo® video interactive codec will provide access to new features using codec-specific ICM_SETCODECSTATE and
ICM_GETCODECSTATE messages. The following sections describe the new codec's SET and GET message interface.
The include file that contains this information is named "vfw_spec.h".
Codec Specific Messages
Indeo video interactive provides two new messages, ICM_GETCODECSTATE and ICM_SETCODECSTATE, for
communicating with the Indeo video interactive codec. The function ICSendMessage() is used to send these messages. Note
that these messages are specific to the Indeo video interactive codec; other codecs' responses to these messages are
unpredictable.
ICSendMessage
LRESULT ICSendMessage(HIC hic, UINT wMsg, DWORD dw1, DWORD dw2)
This function sends a message to a codec.
- Returns a message-specific result.
hic
Specifies the handle of the codec to receive the message. This must be the result of the ICM_OPEN message.
wMsg
Specifies the message to send. This must be set to either ICM_GETCODECSTATE or ICM_SETCODECSTATE.
dw1
Specifies additional message-specific information. This must be dwParam1 for ICM_GETCODECSTATE or
ICM_SETCODECSTATE.
dw2
Specifies additional message-specific information. This must be dwParam2 for ICM_GETCODECSTATE or
ICM_SETCODECSTATE.
ICM_GETCODECSTATE
This message is sent to a video compression driver to obtain driver state information. The definition of the
ICM_GETCODECSTATE parameters is codec-dependent. The following are the specifications used by the Indeo video
interactive codec:
- Returns ICERR_OK if successful. Otherwise, returns an error number. The following errors are defined:
ICERR_OK
No error.
ICERR_BADFORMAT
Either the parameter dwParam1 is NULL, the parameter dwParam2 is an incorrect size, or the type field has an
unsupported value.
ICERR_UNSUPPORTED
Either the version or the four-cc is unsupported.
ICERR_BADSIZE
The size field is incorrect for the specified type.
ICERR_BADFLAGS
The flags field is invalid. The valid flag and at least one other flag must be set.
ICERR_INTERNAL
A codec error - this will not happen.
dwParam1
Specifies a pointer to a block of memory to be filled with the current state.
dwParam2
Must be set to the length of the block of memory passed in dwParam1.
The data structure used to represent state information is defined by the mtType field. Additional information regarding the
effects of the mtType values is found below.
Use the ICSendMessage() function to send an ICM_GETCODECSTATE message.
ICM_SETCODECSTATE
This message is sent to a video compression driver to set driver state information. The definition of the
ICM_SETCODECSTATE parameters is codec-dependent. The following are the specifications used by the Indeo video
interactive codec:
- Returns ICERR_OK if successful. Otherwise, returns an error number. The following errors are defined:
ICERR_OK
No error.
ICERR_BADFORMAT
Either the parameter dwParam1 is NULL, the parameter dwParam2 is non-zero, or the type field has an unsupported
value.
ICERR_UNSUPPORTED
Either the version or the four-cc is unsupported.
ICERR_BADSIZE
The size field is incorrect for the specified type.
ICERR_BADFLAGS
The flags field is invalid. The valid flag and at least one other flag must be set.
ICERR_BADPARAM
One of the fields has a value that is out of range. The flags field will be set to indicate which field.
ICERR_INTERNAL
A codec error - this will not happen.
dwParam1
Specifies a pointer to a block of memory containing state information.
dwParam2
Must be set to the length of the block of memory passed in dwParam1.
The data structure used to represent state information is defined by the mtType field. Additional information regarding the
effects of the mtType values is found below.
Use the ICSendMessage() function to send an ICM_SETCODECSTATE message.
General Data Structures
The following general data structures are used by the Indeo video interactive codec when processing the
ICM_GETCODECSTATE and ICM_SETCODECSTATE messages.
Flags
A flag is either true (non-zero) or false (zero).
typedef DWORD R4_FLAG;
A pointer to a flag is used by the codec to write status information at a later time.
typedef R4_FLAG FAR * PTR_R4_FLAG;
Rectangle
The following structure is used to describe a rectangle.
typedef struct {
DWORD dwX;
DWORD dwY;
DWORD dwWidth;
DWORD dwHeight;
} R4_RECT, FAR * PTR_R4_RECT;
dwX
Specifies the 'X' value of the top left corner.
dw
Specifies the 'Y' value of the top left corner.
dwWidth
Specifies the width of the rectangle in pixels.
dwHeight
Specifies the height of the rectangle in pixels.
Transparency Bitmask
A transparency bitmask contains one bit for each pixel in the source image. If a bit is zero the data is transparent. The first bit in
each byte is identified by the mask 0x80. The last bit in each byte is identified by the mask 0x01. To allow faster access each
row must begin on a DWORD boundary and the total number of bytes must be rounded-up to a multiple of four.
typedef BYTE FAR * PTR_R4_BITMASK;
Transparency Range
A transparency range is specified using minimum and maximum values for R, G, and B. Any pixel with values within this range
(inclusive) is considered transparent.
typedef struct {
U16 u16Reserved;
U8 u8BlueLow;
U8 u8BlueHigh;
U8 u8GreenLow;
U8 u8GreenHigh;
U8 u8RedLow;
U8 u8RedHigh;
} R4_RANGE, FAR * PTR_R4_RANGE;
NOTE: The reserved field must be set to zero.
Decode Data Structures
Some parameters can be changed prior to either an ICM_DECOMPRESS or ICM_DECOMPRESSEX message. These are
found in the R4_DEC_FRAME_DATA structure. Use ICM_SETCODECSTATE to change these values. Use
ICM_GETCODECSTATE to obtain these values.
Other parameters can only be changed prior to either an ICM_DECOMPRESS_BEGIN or an
ICM_DECOMPRESSEX_BEGIN message. These are found in the R4_DEC_SEQ_DATA structure. Use
ICM_SETCODECSTATE to change these values. Use ICM_GETCODECSTATE to obtain these values.
The parameters defined in R4_DECODE_INIT_DATA can only be set, using ICM_SETCODECSTATE, prior to the first
ICM_DECOMPRESS_BEGIN or ICM_DECOMPRESSEX_BEGIN message. These values are valid for reading only after
at least one frame has been decoded. Use ICM_GETCODECSTATE to obtain these values.
R4_DEC_FRAME_DATA
The "DECFRAME" flags are used to identify the fields that are active. The "VALID" flag must be set to indicate that the flags variable has valid data.
#define DECFRAME_TIME_LIMIT (1UL<<0)
#define DECFRAME_DECODE_RECT (1UL<<1)
#define DECFRAME_VIEW_RECT (1UL<<2)
#define DECFRAME_BOUNDING_RECT (1UL<<3)
#define DECFRAME_TRANS_BITMASK (1UL<<4)
#define DECFRAME_BRIGHTNESS (1UL<<5)
#define DECFRAME_SATURATION (1UL<<6)
#define DECFRAME_CONTRAST (1UL<<7)
#define DECFRAME_FILL_COLOR (1UL<<9)
#define DECFRAME_8BIT_CONFIG_PALETTE(1UL<<10)
#define DECFRAME_8BIT_DITHER (1UL<<11)
#define DECFRAME_VIEW_RECT_ORIGIN (1UL<<12)
#define DECFRAME_INPUT_TRANS_MASK (1UL<<13)
#define DECFRAME_VALID (1UL<<31)
typedef struct {
DWORD dwSize;
DWORD dwFourCC;
DWORD dwVersion;
LONG mtType;
LONG oeEnvironment;
DWORD dwFlags;
DWORD dwTimeLimit;
R4_RECT rDecodeRect;
R4_RECT rViewRect;
PTR_R4_RECT prBoundingRect;
PTR_R4_BITMASK pbmTransparencyBitmask;
PTR_R4_FLAG pfUpdatedTransparencyBitmask;
LONG lBrightness;
LONG lSaturation;
LONG lContrast;
DWORD dwFillColor;
DWORD dwFirstPalIndex;
DWORD dwLastPalIndex;
RGBQUAD* prgbPalette;
R4_DITHER eDither;
R4_FLAG fViewRectOrigin;
PTR_R4_BITMASK pbmInputTransparencyBitmask;
} R4_DEC_FRAME_DATA, FAR * PTR_R4_DEC_FRAME_DATA;
The R4_DEC_FRAME_DATA structure contains the parameters that can be changed on a frame by frame basis. Any
changes affect decoding of the next frame.
dwSize
Must be set to the size of an R4_DEC_FRAME_DATA structure.
dwFourCC
Must be set to the codec four-cc.
dwVersion
Must be set to the interface version as specified in the "vfw_spec.h" include file.
mtType
Must be set to either MT_DECODE_FRAME_DEFAULT or MT_DECODE_FRAME_VALUE. This field identifies the
ICM_GETCODECSTATE or ICM_SETCODECSTATE operation type. Additional information on this field is found in the
sections "Messages for the Decoder using ICM_GETCODECSTATE" and "Messages for the Decoder using
ICM_SETCODECSTATE".
oeEnvironment
Must be set to OE_16 for 16-bit applications or OE_32 for 32-bit applications.
dwFlags
Must be set to indicate which variables are in use. There is a flag corresponding to each variable (or set of variables) in the
structure. See the "DECFRAME_*" definitions.
dwTimeLimit
Specifies the maximum number of milliseconds for the codec's decode and color conversion process. This is only used if
playback scalability is on. If this field has a value of zero, the number of milliseconds is estimated based on the frame rate. This
field is only used by the ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the
DECFRAME_TIME_LIMIT flag is true.
rDecodeRect
Specifies the decode rectangle (or local decode rectangle). Legal values for the 'X' value range from zero to the image width
minus one. Legal values for the 'Y' value range from zero to the image height minus one. The decode rectangle may not extend
outside the image. The decode rectangle may only be changed immediately before key frames. The decode rectangle defaults to
the entire frame if all four fields are zero. The decode rectangle specifies the portion of the rectangle that should be decoded.
This field is only used by the ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the
DECFRAME_DECODE_RECT flag is true.
rViewRect
Specifies the view rectangle (or clipping rectangle). The view rectangle may not extend beyond the current decode rectangle.
The view rectangle defaults to the decode rectangle if all four fields are zero. This field is only used by the
ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the DECFRAME_VIEW_RECT flag is true.
Notes:
- The view rectangle, rViewRect, may not extend beyond the current decode rectangle. This test will not be done until the
next ICM_DECOMPRESS or ICM_DECOMPRESSEX call. If the rectangle extends beyond the decode rectangle
ICERR_BADPARAM will be returned from the decompress call; the frame will not be decoded.
- The decode rectangle, rDecodeRect, may only change before key frames. This test will not be done until the next
ICM_DECOMPRESS or ICM_DECOMPRESSEX call. If the decode rectangle changes on a frame other than a key
frame ICERR_BADPARAM will be returned from the decompress call; the frame will not be decoded.
- The decode rectangle must contain the view rectangle. Although view rectangles may change on every frame decode
rectangles may only change on key frames. For that reason the decode rectangle must cover the area used by all the
view rectangles until the next key frame.
- The transparency information returned via the bounding rectangle and transparency bitmask describes the pixels in terms
of the original image dimensions and not the view rectangle.
prBoundingRect
Specifies a pointer to a bounding rectangle. The bounding rectangle outlines the pixels written to when transparency is on. A
bounding rectangle with all fields set to zero indicates that no pixels were written. The codec will write to this rectangle after
decoding a frame if both the decoder selectively wrote non-transparent pixels and this pointer is not NULL. The bounding
rectangle information is relative to the source image. This field is only used by the ICM_GETCODECSTATE and
ICM_SETCODECSTATE messages if the DECFRAME_BOUNDING_RECT flag is true.
pbmTransparencyBitmask
Specifies a pointer to a transparency bitmask. The codec will write to this buffer after decoding a frame if both the decoder
selectively wrote non-transparent pixels and this pointer is not NULL. The transparency bitmask is relative to the source
image. However, the data outside the view rectangle is undefined. This field is only used by the
ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the DECFRAME_TRANS_BITMASK flag is
true.
pfUpdatedTransparencyBitmask
Specifies a pointer to an R4_FLAG variable. After decoding each frame the codec will test this variable. If it is not NULL, the codec will set this flag to indicate if it has written a transparency bitmask using the pbmTransparencyBitmask pointer. This field is only used by the ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the
DECFRAME_TRANS_BITMASK flag is true.
An application can determine if a video is transparent through the pfUpdatedTransparencyBitmask pointer by requesting the
codec to return a transparency bitmask. If the video does not contain transparency, the value at
pfUpdatedTransparencyBitmask will be set to FALSE. If the video does contain transparency, the value at
pfUpdatedTransparencyBitmask will be set to TRUE.
lBrightness
Specifies the brightness value. Legal values range from -255 to 255. The value of zero represents the default brightness level.
Negative values have less brightness. Positive values have more brightness. This field is only used by the
ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the DECFRAME_BRIGHTNESS flag is true.
lSaturation
Specifies the saturation value. Legal values range from -255 to 255. The value of zero represents the default saturation level.
Negative values have less saturation. Positive values have more saturation. This field is only used by the
ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the DECFRAME_SATURATION flag is true.
lContrast
Specifies the contrast value. Legal values range from -255 to 255. The value of zero represents the default contrast level.
Negative values have less contrast. Positive values have more contrast. This field is only used by the
ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the DECFRAME_CONTRAST flag is true.
dwFillColor
This field allows the user to specify at decode-time a fill color to override the color specified in the bitstream. When setting the value, the variable must be in RGB24 format, with the high byte set to 0. To return to the default fill color in the bitstream, set the dwFillColor variable to DECFRAME_FILL_UNDEFINED. This field is only used by the ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the DECFRAME_FILL_COLOR flag is true.
NOTE: The color representation received by the ICM_GETCODECSTATE and the data sent with the
ICM_SETCODECSTATE messages are different. With the ICM_SETCODECSTATE message the dwFillColor variable
must be in RGB24 format. With the ICM_GETCODECSTATE message the value is provided in the current output
color mode (CLUT8, RGB16, RGB24).
For example (CLUT8 playback), to set the fill color, check the fill color, and return the fill color to its default value:
- Set the fill color:
Send the ICM_SETCODECSTATE message with the DECFRAME_FILL_COLOR flag set and dwFillColor =
0x000000FF (R=0, G=0, B=255). The fill color is changed to blue.
- Get the fill color:
Send the ICM_GETCODECSTATE message with the DECFRAME_FILL_COLOR flag set. The value of dwFillColor
is set to 0x000000FC, the index of the palette entry corresponding to blue.
- Set the fill color to the default fill color:
Send the ICM_SETCODECSTATE message with the DECFRAME_FILL_COLOR flag set and dwFillColor field set
to DECFRAME_FILL_UNDEFINED.
dwFirstPalIndex
dwLastPalIndex
prgbPalette
Specifies the palette and range of entries within the palette for the configurable palette color converter to use. dwFirstPalIndex
and dwLastPalIndex specify the range of entries in the palette provided in prgbPalette which will be examined/analyzed. These
fields are only used by the ICM_SETCODECSTATE message if the DECFRAME_8BIT_CONFIG_PALETTE flag is
true.
Notes:
- These fields are not used by the ICM_GETCODECSTATE message.
- The same palette must subsequently be sent with the ICM_DECOMPRESS_SET_PALETTE message before the
palette will be asserted.
- After performing the above steps all running instances of the IVI that were using either the configurable palette
or the default palette color converters will now start using the configurable palette color converter with the new
palette parameters. Those instances in active palette will stay that way, but they will use the new palette in its
entirety.
eDither
Specifies the dither level for the configurable palette color converter to use. Legal values are OFF, LOW, MEDIUM, and
HIGH. This field is only used by the ICM_SETCODECSTATE message if the DECFRAME_8BIT_DITHER flag is true.
Note
: This field is not used by the ICM_GETCODECSTATE message.
fViewRectOrigin
This field is reserved for future use.
pbmInputTransparencyBitmask
This field allows the application to supply a foreground transparency mask. When using foreground transparency, the codec’s
behavior depends upon whether the video clip actually contains transparency.
If the video clip does not contain transparency, the mask is used as a transparency bitmask: 1’s identify where video will be
drawn; 0’s identify where video will not be drawn.
If the mask provided is:
00000000000000000000000
00000000000000000000000
00111111111110000000000 videovideov
00111111111110000000000 videovideov
00111111111110000000000 -> videovideov
00111111111110000000000 videovideov
00111111111110000000000 videovideov
00000000000000000000000
00000000000000000000000
the codec will draw video where the mask contains 1’s, and either draw nothing or fill the 0’s, depending upon whether fill is on
If the video clip contains transparency, the mask is used in the opposite manner: 0’s identify where video will be drawn; 1’s
identify where video will not be drawn. The codec will draw the intersection of the input transparency bitmask and the internal
bitstream transparency bitmask:
00000000000000000000000
00000000000000000000000 video
00111111111110000000000 videov
00111111111110000000000 videovi
00111111111110000000000 -> videovid
00111111111110000000000 videovi
00111111111110000000000 videov
00000000000000000000000 video
00000000000000000000000
assuming that the following is the internal bitstream transparency mask for the frame:
00000000000000000000000
00000000000001111100000
00000000000011111110000
00000000000111111111000
00000000001111111111100
00000000000111111111000
00000000000011111110000
00000000000001111100000
00000000000000000000000
If the application requests the codec to return the transparency mask (through pfUpdatedTransparencyBitmask), the codec will return the mask corresponding to where pixels were drawn, which is the subset of the bitstream transparency that wasn't obscured by the foreground mask (object).
R4_DEC_SEQ_DATA
The "DECSEQ" flags are used to identify the sequence data fields that are active. The "VALID" flag must be set to indicate that
the flags variable has valid data.
#define DECSEQ_KEY (1UL<<0)
#define DECSEQ_SCALABILITY (1UL<<1)
#define DECSEQ_FILL_TRANSPARENT (1UL<<2)
#define DECSEQ_ALT_LINE (1UL<<3)
#define DECSEQ_VALID (1UL<<31)
typedef struct {
DWORD dwSize;
DWORD dwFourCC;
DWORD dwVersion;
LONG mtType;
LONG oeEnvironment;
DWORD dwFlags;
DWORD dwKey;
R4_FLAG fEnabledKey;
R4_FLAG fScalability;
R4_FLAG fAltLine;
R4_FLAG fFillTransparentPixels;
} R4_DEC_SEQ_DATA, FAR * PTR_R4_DEC_SEQ_DATA;
dwSize
Must be set to the size of an R4_DEC_SEQ_DATA structure.
dwFourCC
Must be set to the codec four-cc.
dwVersion
Must be set to the interface version as specified in the "vfw_spec.h" include file.
mtType
Must be set to either MT_DECODE_SEQ_DEFAULT or MT_DECODE_SEQ_VALUE. This field identifies the
ICM_GETCODECSTATE or ICM_SETCODECSTATE operation type. Additional information on this field is found in the
sections "Messages for the Decoder using ICM_GETCODECSTATE" and "Messages for the Decoder using
ICM_SETCODECSTATE".
oeEnvironment
Must be set to OE_16 for 16-bit applications or OE_32 for 32-bit applications.
dwFlags
Must be set to indicate which variables are in use. There is a flag corresponding to each variable in the structure. See the
"DECSEQ_*" definitions.
dwKey
Specifies a four-byte access key. This field is only valid if fEnabledKey is true. If the value does not match the value specified
at encode time the codec will not decode the frames. It will instead return an ICERR_ERROR value from the
ICM_DECOMPRESS and ICM_DECOMPRESSEX messages. This field is only used by the ICM_GETCODECSTATE
and ICM_SETCODECSTATE messages if the DECSEQ_KEY flag is true.
fEnabledKey
Specifies whether the dwKey field should be used.
fScalabilityeScalability
Specifies the current mode of decode scalability. Legal values are SC_ON, SC_OFF, SC_DONT_DROP_FRAMES, or
SC_DONT_DROP_QUALITY:
- SC_ON specifies full scalability, scalability of bands and of frames. This corresponds to a value of TRUE for the
fScalability flag.
- SC_OFF completely disables scalability. The decoder will entirely ignore the timer and decode every frame it receives to
full quality.
- SC_DONT_DROP_QUALITY has the same functionality as the value of FALSE for the fScalability flag. This option
does allow the codec to drop frames to meet time restrictions, but the quality on the decoded frames will be full.
- SC_DONT_DROP_FRAMES is the opposite of SC_DONT_DROP_QUALITY: it allows the decoder to reduce quality (bands) as much as is necessary to help with time constraints, but every frame must be decoded. This option is provided to assist with transparency. In addition, this scalability setting is used with the ICDECOMPRESS_HURRYUP flag for early bounding box exposure.
This field is only used by the ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the
DECSEQ_SCALABILITY flag is true.
fFillTransparentPixels
Specifies if transparent pixels should be displayed using a default color. The default color used is one of the transparency colors unless the sequence was created using TM_BITMASK transparency. In that case the default color is black. This field must be set to one to indicate that the transparent pixels be output in the default color. This field must be set to zero to indicate that the transparent pixels not be output (they will not be written). This field is only used by the ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the DECSEQ_FILL_TRANSPARENT flag is true.
fAltLine
Requests an alternate line display. In the zoom by 2 mode with this flag set to 0, every line is duplicated and written to the screen on every frame. With this flag set to 1, that duplicate information is replaced with black and written only once a sequence. This flag is a request only. Not all color depths or formats will support this feature. This field is only used by the ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the DECSEQ_ALT_LINE flag is true.
R4_DECODE_INIT_DATA
The "VALID" flag must be set to indicate that the flags variable has valid data.
#define DECINIT_VALID (3UL<<30)
typedef struct {
DWORD dwSize;
DWORD dwFourCC;
DWORD dwVersion;
LONG mtType;
LONG oeEnvironment;
DWORD dwFlags;
R4_FLAG fBidir;
R4_FLAG fDeltaFrames;
R4_FLAG fTransparency;
DWORD dwNLevels;
DWORD dwTileWidth;
DWORD dwTileHeight;
} R4_DECODE_INIT_DATA, FAR * PTR_R4_DECODE_INIT_DATA;
The R4_DECODE_INIT_DATA structure contains values which when used with ICM_SETCODECSTATE are hints for
initializing the decoder for the clip to be played; and when used with ICM_GETCODECSTATE after decoding are the
characteristics of the clip just played.
dwSize
Should be set to the size of an R4_ENC_SEQMust be set to the size of an R4_DECODE_INIT_DATA structure.
dwFourCC
ShouldMust be set to the codec four-cc.
dwVersion
Must be set to the interface version as specified in the "vfw_spec.h" include file.
mtType
Must be set to either MT_ENCODE_SEQ_DEFAULT or MT_ENCODE_SEQ_VALUE. This field identifies the
ICM_GETCODECSTATE or ICM_SETCODECSTATE operation type. Additional information on this field is found in the
sections "Messages for the Encoder using ICM_GETCODECSTATE" and "Messages for the Encoder using
ICM_SETCODECSTATE"Must be set to MT_DECODE_INIT_DATA.
oeEnvironment
Must be set to OE_16 for 16-bit applications or OE_32 for 32-bit applications.
dwFlags
Must be set to DECINIT_VALID.
fBidir
Boolean specifying whether the clip contains B frames (bidirectional prediction).
fDeltaFrames
Boolean specifying whether the clip contains P frames.
fTransparency
Boolean specifying whether the clip contains transparency information.
dwNLevels
Indicates scalability of the clip; 0=no scalability, 1=scalability on.
dwTileWidth
Zero unless the clip was encoded with minimum viewport size specified. If non-zero this must be the width of the viewports
encoded in the clip (not the minimum viewport specified during encoding). The viewport width for the clip can be found by
decoding the clip then either reading this value using ICM_GETCODECSTATE; or by examining the registry
(HKEY_CURRENT_USER\Software\Intel\Indeo\4.1\Decoder\Tile Width). If zero, dwTileHeight must also be zero.
dwTileHeight
Zero unless the clip was encoded with minimum viewport size specified. If non-zero this must be the height of the viewports
encoded in the clip (not the minimum viewport specified during encoding). The viewport height for the clip can be found by
decoding the clip then either reading this value using ICM_GETCODECSTATE; or by examining the registry
(HKEY_CURRENT_USER\Software\Intel\Indeo\4.1\Decoder\Tile Height). If zero. dwTileWidth must also be zero.
Notes:
- The purpose of this message type is to provide information about the clip to be decoded to the decoder earlier than it
would otherwise have the information, thereby allowing the decoder to correctly initialize for the clip; the result is reduced
decoder latency when it begins decoding frames.
- When this message type is not used (normal playback case) the decoder instead uses the characteristics of the most
recently decoded clip -- which it reads from the registry -- for early initialization
- The ICM_SETCODECSTATE message with this information must occur prior to the first
ICM_DECOMPRESS_BEGIN or ICM_DECOMPRESSEX_BEGIN message
- If the message is used and the parameters do not match the clip, the decoder will reinitialize to properly decode the clip
- The actual characteristics of the clip can be obtained by using the MT_DECODE_INIT_DATA message type with
ICM_GETCODECSTATE after frames have been decoded. The returned parameters will describe the most recently
decoded frame(s)
Encode Data Structures
Encode parameters can only be changed prior to an ICM_COMPRESS_BEGIN message. These are found in the
R4_ENC_SEQ_DATA structure (these include the items that can be set in the advanced compression parameters dialog box).
Use ICM_SETCODECSTATE to change these values. Use ICM_GETCODECSTATE to obtain these values.
ENC_SEQ_DATA
The "ENCSEQ" flags are used to identify the sequence data fields that are active. The "VALID" flag must be set to indicate that
the flags variable has valid data.
#define ENCSEQ_KEY (1UL<<0)
#define ENCSEQ_MINIMUM_VIEWPORT (1UL<<1)
#define ENCSEQ_TRANSPARENCY (1UL<<2)
#define ENCSEQ_SCALABILITY (1UL<<3)
#define ENCSEQ_BI_DIR_PREDICTION (1UL<<4)
#define ENCSEQ_PLAYBACK_PLATFORM (1UL<<5)
#define ENCSEQ_RANDOM_KEY_AND_BIDIR (1UL<<6)
#define ENCSEQ_FRAME_INFO (1UL<<7)
#define ENCSEQ_QUICK_COMPRESS (1UL<<8)
#define ENCSEQ_VALID (1UL<<31)
typedef struct {
DWORD dwSize;
DWORD dwFourCC;
DWORD dwVersion;
LONG mtType;
LONG oeEnvironment;
DWORD dwFlags;
DWORD dwKey;
DWORD dwMinViewportWidth;
DWORD dwMinViewportHeight;
R4_RANGE rngTransparencyRange;
PTR_R4_BITMASK pbmTransparencyBitmask;
LONG tmTransparencyMethod;
R4_FLAG fEnabledKey;
R4_FLAG fScalability;
R4_FLAG fBiDirPrediction;
R4_FLAG fRandomKeyAndBiDir;
DWORD dwPlaybackPlatform;
WORD wFrameLatency; /* Frame info flag */
WORD wDeadFrames; /* Frame info flag */
R4_FLAG fQuickCompress
} R4_ENC_SEQ_DATA, FAR * PTR_R4_ENC_SEQ_DATA;
dwSize
Must be set to the size of an R4_ENC_SEQ_DATA structure.
dwFourCC
Must be set to the codec four-cc.
dwVersion
Must be set to the interface version as specified in the "vfw_spec.h" include file.
mtType
Must be set to either MT_ENCODE_SEQ_DEFAULT or MT_ENCODE_SEQ_VALUE. This field identifies the
ICM_GETCODECSTATE or ICM_SETCODECSTATE operation type. Additional information on this field is found in the
sections "Messages for the Encoder using ICM_GETCODECSTATE" and "Messages for the Encoder using
ICM_SETCODECSTATE".
oeEnvironment
Must be set to OE_16 for 16-bit applications or OE_32 for 32-bit applications.
dwFlags
Must be set to indicate which variables are in use. There is a flag corresponding to each variable in the structure. See the
"ENCSEQ_*" definitions.
dwKey
Specifies a 4-byte key. This field is only valid if fEnabledKey is true. If the same key value is not also sent to the decoder at
decode time, the codec will not decode the frames. This field is only used by the ICM_GETCODECSTATE and
ICM_SETCODECSTATE messages if the ENCSEQ_KEY flag is true.
dwMinViewportWidth
Specifies the minimum viewport width. Legal values range from 0 to the image width. This field is only used by the
ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the ENCSEQ_MINIMUM_VIEWPORT flag is
true. The width may only be zero if the height is zero. The special zero,zero value is used to turn off the viewport.
dwMinViewportHeight
Specifies the minimum viewport height. Legal values range from 0 to the image height. This field is only used by the
ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the ENCSEQ_MINIMUM_VIEWPORT flag is
true. The height may only be zero if the width is zero. The special zero,zero value is used to turn off the viewport.
rngTransparencyRange
Specifies the transparency range if the tmTransparencyMethod field has a value of TM_RANGE. The transparency fields
are only used by the ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the
ENCSEQ_TRANSPARENCY flag is true.
pbmTransparencyBitmask
Specifies a pointer to a transparency bitmask buffer if the tmTransparencyMethod field has a value of TM_BITMASK.
The transparency fields are only used by the ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the
ENCSEQ_TRANSPARENCY flag is true.
tmTransparencyMethod
Specifies the transparency method. If the transparency method is TM_NONE the encoder will encode without transparency. If
the transparency method is TM_RANGE the encoder will use the rngTransparencyRange field to create the transparency
bitmask. If the transparency method is TM_BITMASK the encoder will read the transparency data from the bitmask buffer
pointed to by the pbmTransparencyBitmask field. It is the application's responsibility to update the buffer before calling to
compress the next frame. If the transparency method is TM_FRAME the encoder will use the first frame in the sequence to
create the transparency range. It will use that range to create the transparency bitmask when encoding later frames in the
sequence. If the transparency method is TM_ALPHA_CHANNEL, the encoder will extract the transparency bitmask from
the alpha channel. This method only has meaning on the XRGB32 color depth. On all other color depths, this method generates
no transparency. This field is only used by the ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the
ENCSEQ_TRANSPARENCY flag is true.
fEnabledKey
Specifies whether a key has been specified.
fScalability
Specifies whether to enable scalability. This feature is disabled if the flag is false (Zero). It is enabled if the flag is true
(non-zero). This field is only used by the ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the
ENCSEQ_SCALABILITY flag is true.
fBiDirPrediction
Specifies whether to enable bi-directional prediction. This feature is disabled if the flag is false (Zero). It is enabled if the flag is
true (non-zero). This field is only used by the ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the
ENCSEQ_BI_DIR_PREDICTION flag is true.
fRandomKeyAndBiDir
Specifies that the application understands the two frame latency associated with bi-directional prediction. Some applications
assert key frames to implement the key frame interval but do not understand that the requested key frame is returned two
frames later. To work-around the problems that result the Indeo video interactive codec ignores the random key frame flag if
bi-directional prediction is on. The application can override this behavior by setting this flag to true.
dwPlaybackPlatform
Specifies the playback platform. Legal values are zero ("Low-End"), one ("Medium"), and two ("High End"). This field is only
used by the ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if
ENCSEQ_PLAYBACK_PLATFORM is true.
wFrameLatency
Specifies the number of frames to pad at the end of a sequence. With Indeo video interactive this value will be 2 when
bi-directional prediction is enabled and 0 otherwise. This read-only field is only used by the ICM_GETCODECSTATE
message if ENCSEQ_FRAME_INFO is true.
wDeadFrames
Specifies the number of frames to discard at the beginning of the sequence in order to re-synchronize the audio to the video.
This read-only field is only used by the ICM_GETCODECSTATE message if ENCSEQ_FRAME_INFO is true.
fQuickCompress
Specifies whether to enable the Quick Compressor. This feature is disabled if the flag is false (Zero). It is enabled if the flag is
true (non-zero). This field is only used by the ICM_GETCODECSTATE and ICM_SETCODECSTATE messages if the
ENCSEQ_QUICK_COMPRESS flag is true.
Notes:
- If bi-directional prediction is enabled the encoder will repeat the first frame as the output of the first three encode
requests and will never return the last two frames. Thus, the application must provide two dummy frames at the end of
the sequence, remove the repeated frames from the beginning of the sequence, and re-synchronize the audio and video.
See wFrameLatency and wDeadFrames.
- The Quick Compressor can not be used in a 16-bit app.
Messages for the Decoder Using ICM_GETCODECSTATE
The ICM_GETCODECSTATE message is used to get either default or current values. The mtType field is used to specify
both the operation type and structure type.
MT_DECODE_FRAME_DEFAULT
When ICM_GETCODECSTATE is used with mtType set to MT_DECODE_FRAME_DEFAULT the codec assigns the
default frame values to the structure members without changing its current values. The ICM_GETCODECSTATE parameter
dwParam1 must point to an R4_DEC_FRAME_DATA structure, and dwParam2 must be the size of
R4_DEC_FRAME_DATA in bytes.
MT_DECODE_FRAME_VALUE
When ICM_GETCODECSTATE is used with mtType set to MT_DECODE_FRAME_VALUE the codec assigns the
current frame values to the structure members. The ICM_GETCODECSTATE parameter dwParam1 must point to an
R4_DEC_FRAME_DATA structure, and dwParam2 must be the size of R4_DEC_FRAME_DATA in bytes.
MT_DECODE_SEQ_DEFAULT
When ICM_GETCODECSTATE is used with mtType set to MT_DECODE_SEQ_DEFAULT the codec assigns the
default sequence values to the structure members without changing its current values. The ICM_GETCODECSTATE
parameter dwParam1 must point to an R4_DEC_SEQ_DATA structure, and dwParam2 must be the size of
R4_DEC_SEQ_DATA in bytes.
MT_DECODE_SEQ_VALUE
When ICM_GETCODECSTATE is used with mtType set to MT_DECODE_SEQ_VALUE the codec assigns the current
sequence values to the structure members. The ICM_GETCODECSTATE parameter dwParam1 must point to an
R4_DEC_SEQ_DATA structure, and dwParam2 must be the size of R4_DEC_SEQ_DATA in bytes.
MT_DECODE_INIT_DATA
When ICM_GETCODECSTATE is used with mtType set to MT_DECODE_INIT_DATA the codec assigns the current
sequence values to the structure members. The ICM_GETCODECSTATE parameter dwParam1 must point to an
R4_DECODE_INIT_DATA structure, and dwParam2 must be the size of R4_DECODE_INIT_DATA in bytes.
Messages for the Decoder Using ICM_SETCODECSTATE
The ICM_SETCODECSTATE message is used to set either default or current values. The mtType field is used to specify
both the operation type and structure type.
MT_DECODE_FRAME_DEFAULT
When ICM_SETCODECSTATE is used with mtType set to MT_DECODE_FRAME_DEFAULT the codec assigns the
default frame values to the structure members and changes its current values to these defaults. These changes do not take affect
until the next ICM_DECOMPRESS or ICM_DECOMPRESSEX. The ICM_GETCODECSTATE parameter dwParam1
must point to an R4_DEC_FRAME_DATA structure, and dwParam2 must be the size of R4_DEC_FRAME_DATA in
bytes.
MT_DECODE_FRAME_VALUE
When ICM_SETCODECSTATE is used with mtType set to MT_DECODE_FRAME_VALUE the codec changes its
current frame values to the values specified in the structure. These changes do not take affect until the next
ICM_DECOMPRESS or ICM_DECOMPRESSEX. The ICM_GETCODECSTATE parameter dwParam1 must point to an
R4_DEC_FRAME_DATA structure, and dwParam2 must be the size of R4_DEC_FRAME_DATA in bytes.
MT_DECODE_SEQ_DEFAULT
When ICM_SETCODECSTATE is used with mtType set to MT_DECODE_SEQ_DEFAULT the codec assigns the
default sequence values to the structure members and changes its current values to these defaults. These changes do not take
affect until the next ICM_DECOMPRESS_BEGIN or ICM_DECOMPRESSEX_BEGIN. The ICM_GETCODECSTATE
parameter dwParam1 must point to an R4_DEC_SEQ_DATA structure, and dwParam2 must be the size of
R4_DEC_SEQ_DATA in bytes.
MT_DECODE_SEQ_VALUE
When ICM_SETCODECSTATE is used with mtType set to MT_DECODE_SEQ_VALUE the codec changes its current
sequence values to the values specified in the structure. These changes do not take affect until the next
ICM_DECOMPRESS_BEGIN or ICM_DECOMPRESSEX_BEGIN. The ICM_GETCODECSTATE parameter
dwParam1 must point to an R4_DEC_SEQ_DATA structure, and dwParam2 must be the size of R4_DEC_SEQ_DATA in
bytes.
MT_DECODE_INIT_DATA
When ICM_SETCODECSTATE is used with mtType set to MT_DECODE_INIT_DATA the decoder stores the values of
the structure members, which are then used to initialize the decoder on the first ICM_DECOMPRESS_BEGIN or
ICM_DECOMPRESSEX_BEGIN. The ICM_SETCODECSTATE parameter dwParam1 must point to an
R4_DECODE_INIT_DATA structure, and dwParam2 must be the size of R4_DECODE_INIT_DATA in bytes.
Messages for the Encoder Using ICM_GETCODECSTATE
MT_ENCODE_SEQ_DEFAULT
When ICM_GETCODECSTATE is used with mtType set to MT_ENCODE_SEQ_DEFAULT the codec assigns the
default sequence values to the structure members without changing its current values. The ICM_GETCODECSTATE
parameter dwParam1 must point to an R4_ENC_SEQ_DATA structure, and dwParam2 must be the size of
R4_ENC_SEQ_DATA in bytes.
MT_ENCODE_SEQ_VALUE
When ICM_GETCODECSTATE is used with mtType set to MT_ENCODE_SEQ_VALUE the codec assigns the current
sequence values to the structure members. The ICM_GETCODECSTATE parameter dwParam1 must point to an
R4_ENC_SEQ_DATA structure, and dwParam2 must be the size of R4_ENC_SEQ_DATA in bytes.
Messages for the Encoder Using ICM_SETCODECSTATE
MT_ENCODE_SEQ_DEFAULT
When ICM_SETCODECSTATE is used with mtType set to MT_ENCODE_SEQ_DEFAULT the codec assigns the
default sequence values to the structure members and changes its current values to these defaults. These changes do not take
affect until the next ICM_COMPRESS_BEGIN. The ICM_GETCODECSTATE parameter dwParam1 must point to an
R4_ENC_SEQ_DATA structure, and dwParam2 must be the size of R4_ENC_SEQ_DATA in bytes.
MT_ENCODE_SEQ_VALUE
When ICM_SETCODECSTATE is used with mtType set to MT_ENCODE_SEQ_VALUE the codec changes its current
sequence values to the values specified in the structure. These changes do not take affect until the next
ICM_COMPRESS_BEGIN. The ICM_SETCODECSTATE parameter dwParam1 must point to an R4_ENC_SEQ_DATA
structure, and dwParam2 must be the size of R4_ENC_SEQ_DATA in bytes.
Functionality Notes
The following functionality is a possible using the above set of message.
Early Bounding Box Exposure
Early Bounding Box Exposure is the feature available to applications that would like to know where transparent video will be
drawn upon the frame buffer before the draw occurs. This is to minimize the data movement required by the calling application
in saving the background before the codec writes. To get this information, it is necessary to decode each frame twice. The first
decode does the internal work of decoding and returns the requested information, and the second decode just draws the
decoded frame to the screen.
To do this scalability must be set to SC_DONT_DROP_FRAMES (or SC_OFF) in the sequence setup. Then for each frame,
first send a decompress message with the HURRYUP flag and a request for the bounding box. Then send another decompress
message, without the HURRYUP flag, but with an UPDATE flag instead. The decoder will then draw (compose and color
convert) the partially decoded frame.
If your app is also requesting the transparency mask, it is recommended (for performance reasons only) that you only request
the mask on one of these calls, and not both.
Special Notes for 16-BIT Applications
There are special concerns for 16-bit applications that must use the extended features on a 32-bit operating system like
Window 95. Due to the thunking implementation of Video for Windows it is necessary to set up an ICM_GETCODECSTATE
message before performing it. The following code illustrates the method to use.
R4_ENC_SEQ_DATA FAR* pState;
pState->dwSize = sizeof(R4_ENC_SEQ_DATA);
pState->dwFourCC = mmioFOURCC('I', 'V', '4', '1');
pState->dwVersion = SPECIFIC_INTERFACE_VERSION;
pState->dwFlags = ENCSEQ_VALID | ENCSEQ_TRANSPARENCY;
// 16-bit operation requires that the request be
// setup. OR the MT_* code with MT_QUEUE.
pState->mtType = MT_ENCODE_SEQ_VALUE | MT_QUEUE;
pState->oeEnvironment = OE_16;
// Setup the desired structure with an ICM_SETCODECSTATE
ICSendMessage(hCodec, ICM_SETCODECSTATE, (DWORD) pState,
(DWORD)sizeof(R4_ENC_SEQ_DATA));
// Clear the FourCC for the queued 'get' operation
pState->dwFourCC = 0;
// Note that any non-negative return value is acceptable for 16-bit
// operation. For 32-bit operation, the return value must be 0.
iResult = ICSendMessage(hCodec, ICM_GETCODECSTATE,
(DWORD) pState, (DWORD) sizeof(R4_ENC_SEQ_DATA)));
It is a three step process. Setup the structure as usual. Issue an ICM_SETCODECSTATE message with its mtType field
ORed with MT_QUEUE. Then send an ICM_GETCODECSTATE message with its dwFourCC member set to zero.
This method is necessary for all three data structures.
If there is an error in the structure of either an ICM_GETCODECSTATE or ICM_SETCODECSTATE message, an error
code will be returned, but the dwFlags field will not indicate which structure member caused the error.
|
![[INTEL NAVIGATION HEADER]](../../../DESIGN/PIX/HEADER.GIF){kind=small}
