ILMH263Encoder Interface

Documentation for  the interface of the LEAD H263 Encoder is broken down into the following sections:.

Data types

Interface Properties

Interface Methods

ITU-T Recommendation H.263 and LEAD H.263 Encoder

Data types:

 

eQUALITY enumeration

Value

Description

PERFECTQUALITY

[0] Very good quality.

Equivalent to a custom quality factor of 4.

QUALITYMOREIMPORTANTTHANSIZE

[1] Good quality, more compression than PERFECTQUALITY.

Equivalent to a custom quality factor of 5.

QUALITYSIZEEQUALLYIMPORTANT

[2] Good quality, more compression than QUALITYMOREIMPORTANTTHANSIZE.

Equivalent to a custom quality factor of 6.

SIZEMOREIMPORTANTTHANQUALITY

[3] Decent quality, more compression than QUALITYSIZEEQUALLYIMPORTANT.

Equivalent to a custom quality factor of 9.

HIGHESTCOMPRESSION

[4] Highest compression (lowest quality).

Equivalent to a custom quality factor of 31.

 

eBITRATE enumeration

Value

Description

MODEM_56K

[0] 56K modem. Equivalent to a bitrate of 56000.

ISDN_128K

[1] 128K ISDN line. Equivalent to a bitrate of 128000.

ISDN_256K

[2] 256K ISDN line. Equivalent to a bitrate of 256000.

DSL_384K

[3] 384K DSL line. Equivalent to a bitrate of 384000.

CABLE_768

[4] 768K Cable line. Equivalent to a bitrate of 768000.

T1_1500K

[5] T1 line. Equivalent to a bitrate of 1500000.

WIRELESS_802_11B_11M

[6] Wireless 801.11b network card. Equivalent to a bitrate of 11000000.

T3_45M

[7] T3 line. Equivalent to a bitrate of 45000000.

WIRELESS_802_11G_54M

[8] Wireless 801.11g network card. Equivalent to a bitrate of 54000000.

LAN_100M

[9] 100Mbps network card. Equivalent to a bitrate of 100000000.

LAN_1G

[10] 1Gbps network card. Equivalent to a bitrate of 1000000000.

 

eSPEED enumeration

Value

Description

HIGHQUALITY

[0] High quality option. Turn on all settings.

QUALITYMOREIMPORTANTTHANSPEED

[1] Good quality. Turn on all options except the deblocking filter.

QUALITYSPEEDEQUALLYIMPORTANT

[2] Compromise between quality and speed. Only the Unrestricted MV and Advanced Prediction modes are turned on.

SPEEDMOREIMPORTANTTHANQUALITY

[3] Favor speed at the expense of quality. Only Unrestricted MV is on.

HIGHSPEED

[4] Highest speed. No optional mode is turned on.

 

eIDISTANCEUNIT enumeration

Value

Description

UNIT_FRAMES

[0] The unit for the IDistance property is frames.

UNIT_SECONDS

[1] The unit for the IDistance property is seconds.

 

Constants   

Type

Value

Description

long

MINQUALITYFACTOR

[1] The minimum value for CustomQuality . This generates the highest quality video and the lowest compression.

long

MAXQUALITYFACTOR

[31] The maximum value for CustomQuality . This generates the lowest quality video and the highest compression.

 

eH263COMPATIBILITYMODE enumeration

Value

Description

H263COMPATIBILITY_DEFAULT

[0] Default mode: all encoder settings are enabled.

H263COMPATIBILITY_FLV

[1] Force the encoder to offer only Sorenson compression settings. Use this if you know you are creating FLV files.

 

eH263_APILEVEL enumeration

Value

Description

H263_APILEVEL_1

[0] Use the defaults from the previous version of the codec. This APILEVEL's defaults include setting the IDistanceUnit property to UNIT_SECONDS and the IDistance property value to the default value of 60, yielding 1 key frame every 60 seconds.

H263_APILEVEL_2

[1] Use the defaults from the current version of the codec. This APILEVEL's defaults have changed to use UNIT_FRAMES instead of UNIT_SECONDS for the IDistanceUnit property default.  Also, the IDistance property is set to the default value of 30, yielding a key frame every 30 frames.

 

Interface Properties:

 

 

Type

Name

Description

VARIANT_BOOL

UseQuality

Set to TRUE to use quality-based compression (VBR = variable bitrate). In this case, the quality is given by the UsePredefinedQuality, PredefinedQuality and QualityFactor properties.

Set to FALSE to use bitrate-based compression (CBR = constant bitrate). In this case, the bitrate is given by the PredefinedBitrate and BitrateValue properties.

VARIANT_BOOL

UsePredefinedQuality

(Used only if UseQuality is TRUE). Set to TRUE to use a predefined quality through PredefinedQuality .

Set to FALSE to use a custom quality factor through CustomQuality .

eQUALITY

PredefinedQuality

(Used only if UseQuality is TRUE and UsePredefinedQuality is TRUE). Use this property to choose one of the predefined quality options. See the eQUALITY enumeration for possible values.

long

CustomQuality

(Used only if UseQuality is TRUE and UsePredefinedQuality is FALSE). Use a custom quality factor. The value ranges from 1 (best quality, lowest compression) to 31 (worst quality, highest compression).

VARIANT_BOOL

UsePredefinedBitrate

(Used only if UseQuality is FALSE). Set to TRUE to use a predefined bitrate through PredefinedBitrate .

Set to FALSE to use a custom bitrate through CustomBitrate .

eBITRATE

PredefinedBitrate

(Used only if UseQuality is FALSE and UsePredefinedBitrate is TRUE). Use this value to set the desired compressed video rate to one of the predefined bitrates. See the eBITRATE enumeration for possible values.

long

CustomBitRate

(Used only if UseQuality is FALSE and UsePredefinedBitrate is FALSE). Use this value to set the desired compressed video rate in bits per second.

VARIANT_BOOL

UsePredefinedSpeed

Set to TRUE to use a predefined speed through PredefinedSpeed .

Set to FALSE to control the speed using the UseUnrestrictedMotionVector , UseAdvancedIntraCoding , UseAdvancedPredictionMode , UseDeblockingFilter properties.

eSPEED

PredefinedSpeed

(Used only if UsePredefinedSpeed is TRUE). Use this property to set the speed to one of the predefined values. See the eBITRATE enumeration for possible values.

VARIANT_BOOL

UseUnrestrictedMotionVector

(Used only if UsePredefinedSpeed is FALSE). If TRUE, motion vectors are allowed to point outside the picture. The edge pixels are used as prediction for the "not existing" pixels. With this mode, a significant gain is achieved if there is movement across the edges of the picture, especially for the smaller movies. Implements (Annex D) Unrestricted Motion Vector mode of the ITU-T Recommendation H.263 and LEAD H.263 Encoder.

VARIANT_BOOL

UseDeblockingFilter

(Used only if UsePredefinedSpeed is FALSE). If TRUE, the blocky artifacts generated at higher compression are reduced by using an adaptive filter across block boundaries. Use this option to improve the video quality at low bit rate (high compression). Implements (Annex J) Deblocking Filter mode of the ITU-T Recommendation H.263 and LEAD H.263 Encoder.

VARIANT_BOOL

UseAdvancedIntraCoding

(Used only if UsePredefinedSpeed is FALSE). If TRUE, the compression efficiency for INTRA macroblock encoding is improved by using spatial prediction for DCT (Discrete Cosine Transform) coefficient values. Implements (Annex I) Advanced INTRA Coding mode of the ITU-T Recommendation H.263 and LEAD H.263 Encoder.

VARIANT_BOOL

UseAdvancedPredictionMode

(Used only if UsePredefinedSpeed is FALSE). If TRUE, Overlapped Block Motion Compensation (OBMC) is used for the luminance part of P-pictures. Four 8x8 vectors instead of one 16x16 vector are used for some of the macroblocks in the picture. The encoder Also known as compressor, this is a module or algorithm to compress data. Playing that data back requires a decompressor, or decoder. has to decide which type of vectors to use. Four vectors use more bits, but give better prediction (compression). Implements (Annex T) Modified Quantization mode of the ITU-T Recommendation H.263 and LEAD H.263 Encoder. Implements (Annex F) Advanced Prediction mode of the ITU-T Recommendation H.263 and LEAD H.263 Encoder.

long

InputFrameRate

(Read-only). Use this property to obtain input frame rate in frame/sec, which can be used to determine how to set the OutputFrameRate property.

float

OutputFrameRate

Use this property to control the output frame rate. You can set the output frame rate to be the same as the input frame rate (-1) or you can set it to particular output frame rate (if > 0). Note that you should set the output frame rate to be less than the input frame rate (to get better compression). It is not very useful to set the output frame rate to the less than the input frame rate.

VARIANT_BOOL

UseRTP

If TRUE, the encoder packetizes an H.263 video stream The portion of the file holding the video data. The video data might be compressed to save disk space. The data has to be decompressed using a video decompressor before you can play (see) it. with Real-Time Transport Protocol (RTP) headers. This option should be used when transmitting H.263 video streams over the Internet.

VARIANT_BOOL

UseSuperCompression

Set to TRUE, to enable the high compression mode, which is a non-standard extension introduced by LEAD Technologies, Inc. to the H.263 compression algorithm. This generates a smaller video, but only the LEAD H.263 Decoder Also known as a decompressor, this is a module or algorithm to decompress data. can decode this video. The video generated in this mode has a small quality degradation (especially when there is text), but the compression gain is significant. This mode is very useful for achieving lower bitrates.

Set to FALSE to disable this mode. The default is FALSE.

eIDISTANCEUNIT

IDistanceUnit

If set to UNIT_FRAMES, the IDistance property sets the distance between I frames in frames.

If set to UNIT_SECONDS, the IDistance property sets the distance between I frames in seconds.

long

IDistance

Use this to set the interval for I frames. The IDistanceUnit property contains the unit for this property (seconds or frames). The distance between two consecutive I frames is sometimes referred to as the Key Frame interval. I (Intraframe) frames are encoded independently without any reference to a previous frame or forward frame. All the frames between I frames are P and B frames. P (Predictive) frames are encoded using the previous frame as reference. P frames are compressed more than I frames. B (Bi-directional) frames are encoded using both the previous and the next frames as reference and they are compressed better than I and P frames.

If the distance between I frames increases, the compression ratio increases. However, a large distance between I frames has its disadvantages:

  • If an I frame is lost before reaching the decoder (typically due to a noisy or an unreliable channel), the decoder has to wait a long time without displaying anything until the next I frame comes.

  • A large key frame interval makes seeking (searching through the video data) slower.

long

PDistance

Use this to set the number of B frames between two consecutive P frames. The unit for this property is always frames. If set to 0, the compressor Also known as an encoder, this is a module or algorithm to compress data. Playing that data back requires a decompressor, or decoder. generates only I and P frames.

VARIANT_BOOL

SorensonOutput

Set to TRUE, to generate Sorenson video used by Flash ( FLV Flash format. ) files. This video is a modified form of H.263 compression. Set to FALSE to generate regular H.263 video. The default value is FALSE.

eH263COMPATIBILITYMODE

CompatibilityMode

Use this property to determine which settings will be available in the property page.
Set to H263COMPATIBILITY_DEFAULT to make all settings available.
Set to H263COMPATIBILITY_FLV to force the encoder to offer only settings compatible with the FLV format. This option forces the following settings:

  • SorensonOutput = VARIANT_TRUE

  • UseRTP = VARIANT_FALSE

  • UseSuperCompression = VARIANT_FALSE

 

Interface Methods:

 

HRESULT ResetToDefaultsEx(eH263_APILEVEL ApiLevel);

Parameters

eH263_APILEVEL ApiLevel

Which version of the codec to set the defaults to.

Description

Resets the encoder to default values. The ApiLevel determines which default values to use. Current applications should set the ApiLevel to H263_APILEVEL_2 = 1.

The encoder might change in the future and have different properties or default behavior. Calling this method ensures the encoder will have the same default values as they were at the time you developed your application.

It is best to call ResetToDefaultsEx(H263_APILEVEL_2) before beginning to set properties and to call other methods for this interface.

 

HRESULT StartChangingAttributes();

Parameters

None

 

Description

Start changing attributes, but don't use the new settings until StopChangingAttributes is called.

To change more than one encoder setting, it is best to call StartChangingAttributes before making the first change and StopChangingAttributes after making the last change. This way, the encoder does not make any checks on the validity of the settings until all the changes have been made. Also, some changes might require a reconnection of the output pin and making all the changes between a StartChangingAttributes and StopChangingAttributes pair ensures there is only one reconnection of the output pin.

 

HRESULT StopChangingAttributes(VARIANT_BOOL bCancelChanges);

Parameters

VARIANT_BOOL bCancelChanges

Determines whether the changes should be kept (VARIANT_FALSE) or canceled (VARIANT_TRUE).

Description

Stop changing the attributes. Call this method after changes to the interface are complete.

Set bCancelChanges to VARIANT_FALSE to apply all the changes that have been made. Set bCancelChanges to VARIANT_TRUE to revert the encoder to the settings that were used prior to calling StartChangingAttributes.

ITU-T Recommendation H.263 and LEAD H.263 Encoder

Enable and disable h.263 options in terms of ITU-T Recommendation H.263 as follows:

-(Annex I) Advanced INTRA Coding mode

Implemented

To turn it on or off use the UseAdvancedIntraCoding property.

-(Annex J) Deblocking Filter mode

Implemented

To turn it on or off use the UseDeblockingFilter property.

-(Annex T) Modified Quantization mode

Implemented

To turn it on or off use the UseAdvancedPredictionMode method (it is associated with the Advanced Prediction Mode).

-( Annex D) Unrestricted Motion Vector

Implemented

To turn it on or off use the UseUnrestrictedMotionVector property.

-(Annex F) Advanced Prediction mode

Implemented

To turn it on or off use the UseAdvancedPredictionMode method.

-(Annex S) Alternative Inter VLC mode

Not implemented in the encoder. But it is implemented in the decoder.

-(Annex K) Slice Structured mode

Not implemented.