CBaseControlVideo Class

CBaseControlVideo class hierarchy

The CBaseControlVideo class implements the IBasicVideo dual interface and controls the video properties of a generic video window. Generally, a CBaseControlVideo object is a video renderer that draws video into a window on the display.

The CBaseControlVideo class supports both properties and methods. Properties are more easily accessible from many Automation controllers (such as the Microsoft® Visual Basic® programming system). However, some operations require applications to be able to change several properties simultaneously; for this reason, methods are provided that enable a number of related properties to be changed.

Many CBaseControlVideo member functions require only that the video renderer be connected to a filter graph. If it is not connected, member functions will return VFW_E_NOT_CONNECTED. Properties set on a video renderer persist between successive connections and disconnections. All applications should ensure that they reset the renderer properties before starting a presentation.

When working with video, the application can select a portion of the video to use. This portion is the source rectangle that the CBaseControlVideo object controls. CBaseControlVideo enables your application to set and retrieve the source rectangle. All the rectangles that CBaseControlVideo uses employ top, left, width, and height rather than top, left, right, and bottom, which is favored in Microsoft Win32® programming. When no source rectangle has been set, the properties of the source rectangle return the full, native video size.

Protected Data Members

m_pFilter Pointer to an owning media filter.
m_pInterfaceLock Externally defined critical section.
m_pPin Control of the media types for connection.

Member Functions

CBaseControlVideo Constructs a CBaseControlVideo object.
CopyImage Creates a memory copy of a video image.
GetImageSize Retrieves video image size information.
SetControlVideoPin Sets the pin with which this object should synchronize.

Overridable Member Functions

CheckSourceRect Determines if a source rectangle is valid.
CheckTargetRect Determines if a target rectangle is valid.
GetSourceRect Retrieves the current source video rectangle (pure virtual).
GetStaticImage Returns the current image in a memory buffer (pure virtual).
GetTargetRect Retrieves the current target video rectangle (pure virtual).
GetVideoFormat Retrieves the VIDEOINFOHEADER structure containing the video format.
IsDefaultSourceRect Determines if the renderer is using the default source rectangle (pure virtual).
IsDefaultTargetRect Determines if the renderer is using the default target rectangle (pure virtual).
OnUpdateRectangles Called when the source or target rectangle changes.
OnVideoSizeChange Passes EC_VIDEO_SIZE_CHANGED to the application.
SetDefaultSourceRect Sets the default source video rectangle (pure virtual).
SetDefaultTargetRect Sets the default target video rectangle (pure virtual).
SetSourceRect Sets the current source video rectangle (pure virtual).
SetTargetRect Sets the current target rectangle (pure virtual).

Implemented IBasicVideo Methods

get_AvgTimePerFrame Retrieves an approximate average time per frame.
get_BitErrorRate Retrieves an approximate bit error rate.
get_BitRate Retrieves an approximate bit rate for the video.
GetCurrentImage Retrieves a memory rendering of the current image.
get_DestinationHeight Retrieves the current destination rectangle's height.
get_DestinationLeft Retrieves the current destination rectangle's left coordinate.
GetDestinationPosition Retrieves the current destination position.
get_DestinationTop Retrieves the current destination rectangle's top coordinate.
get_DestinationWidth Retrieves the current destination rectangle's width.
get_SourceHeight Retrieves the current source rectangle's height.
get_SourceLeft Retrieves the current source rectangle's left coordinate.
GetSourcePosition Retrieves the current source position.
get_SourceTop Retrieves the current source rectangle's top coordinate.
get_SourceWidth Retrieves the current source rectangle's width.
get_VideoHeight Retrieves the native video height.
GetVideoPaletteEntries Retrieves a range of palette entries for the video.
GetVideoSize Retrieves the width and height of the native video.
get_VideoWidth Retrieves the native video width.
IsUsingDefaultDestination Determines if the renderer is using the default destination window.
IsUsingDefaultSource Determines if the renderer is using the default source window.
put_DestinationHeight Sets the destination rectangle's height.
put_DestinationLeft Sets the destination rectangle's left coordinate.
put_DestinationTop Sets the destination rectangle's top coordinate.
put_DestinationWidth Sets the destination rectangle's width.
put_SourceHeight Sets the source rectangle's height.
put_SourceLeft Sets the source rectangle's left coordinate.
put_SourceTop Sets the source rectangle's top coordinate.
put_SourceWidth Sets the source rectangle's width.
SetDefaultDestinationPosition Sets the default destination position again.
SetDefaultSourcePosition Sets the default source position again.
SetDestinationPosition Sets the destination rectangle position.
SetSourcePosition Sets the source rectangle position.

CBaseControlVideo::CBaseControlVideo

CBaseControlVideo Class

Constructs a CBaseControlVideo object.

Syntax

CBaseControlVideo(
    CBaseFilter *pFilter,
    CCritSec *pInterfaceLock,
    TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr
    );

Parameters

pFilter
Pointer to the owning media filter object.
pInterfaceLock
Pointer to the critical section to use for locking.
pName
Pointer to the object description.
pUnk
Typical COM ownership.
phr
Pointer to the COM return value.

Return Value

No return value.

Remarks

The object implements the IBasicVideo control interface.

All the interface methods from IBasicVideo that this class implements require that the filter be connected correctly. For this reason, the class is passed a pin with which it should synchronize with. Whenever an interface method is called, the object determines that the pin is still connected.

CBaseControlVideo::CheckSourceRect

CBaseControlVideo Class

Determines if a source rectangle is valid.

Syntax

virtual HRESULT CheckSourceRect(
    RECT *pSourceRect
    );

Parameters

pSourceRect
Pointer to the source rectangle to check.

Return Value

Returns E_INVALIDARG if not valid; otherwise, returns NOERROR (S_OK).

Remarks

This member function checks that the source rectangle requested does not exceed the available source video. The left and top coordinates cannot be negative, and the width and height cannot exceed the right and bottom of the video.

CBaseControlVideo::CheckTargetRect

CBaseControlVideo Class

Determines if a target rectangle is valid.

Syntax

virtual HRESULT CheckTargetRect(
    RECT *pTargetRect
    );

Parameters

pTargetRect
Pointer to the target rectangle to check.

Return Value

Returns E_INVALIDARG if not valid; otherwise, returns NOERROR (S_OK).

Remarks

This member function determines if the target rectangle requested is valid. Because the destination rectangle specifies a position in the logical client of the window, the coordinates can be negative, although the overall width and height cannot be zero or a negative value.

CBaseControlVideo::CopyImage

CBaseControlVideo Class

Creates a memory copy of an image.

Syntax

HRESULT CopyImage(
    IMediaSample *pMediaSample,
    VIDEOINFOHEADER *pVideoInfo,
    LONG *pBufferSize,
    BYTE *pVideoImage,
    RECT *pSourceRect
    );

Parameters

pMediaSample
Pointer to the sample containing the video image.
pVideoInfo
Pointer to the format representing the video image.
pBufferSize
Pointer to the size of the output buffer.
pVideoImage
Pointer to the output buffer.
pSourceRect
Pointer to the source video rectangle.

Return Value

If the pVideoImage parameter is NULL, the pBufferSize parameter is filled in with the number of bytes the output buffer requires to store the image. If the buffer passed in is too small or the member function fails to allocate sufficient memory, the member function returns E_OUTOFMEMORY.

Remarks

The member function retrieves the image from the sample and copies it into the output buffer. The section of video copied into the output buffer reflects the source rectangle that is set through the IBasicVideo interface (although it does not reflect the destination rectangle).

CBaseControlVideo::get_AvgTimePerFrame

CBaseControlVideo Class

Retrieves the average time per frame.

Syntax

HRESULT get_AvgTimePerFrame(
    REFTIME *pAvgTimePerFrame
    );

Parameters

pAvgTimePerFrame
Pointer to the average time per frame.

Return Value

Returns NOERROR if successful or E_OUTOFMEMORY if there is not enough memory available.

Remarks

This member function implements the IBasicVideo::get_AvgTimePerFrame method. It calls the pure virtual CBaseControlVideo::GetVideoFormat member function to retrieve the VIDEOINFOHEADER structure from the derived class.

CBaseControlVideo::get_BitErrorRate

CBaseControlVideo Class

Retrieves an approximate bit error rate for the video.

Syntax

HRESULT get_BitErrorRate(
    long *pBitErrorRate
    );

Parameters

pBitErrorRate
Pointer to the bit error rate (one error for approximately this many bits).

Return Value

Returns NOERROR if successful or E_OUTOFMEMORY if there is not enough memory available.

Remarks

This member function implements the IBasicVideo::get_BitErrorRate method. It calls the pure virtual CBaseControlVideo::GetVideoFormat to retrieve the VIDEOINFOHEADER structure from the derived class.

CBaseControlVideo::get_BitRate

CBaseControlVideo Class

Retrieves an approximate bit rate for the video.

Syntax

HRESULT get_BitRate(
    long *pBitRate
    );

Parameters

pBitRate
Pointer to the bit rate, in bits per second.

Return Value

Returns NOERROR if successful or E_OUTOFMEMORY if not enough memory is available.

Remarks

This member function implements the IBasicVideo::get_BitRate method. It calls the pure virtual CBaseControlVideo::GetVideoFormat to retrieve the VIDEOINFOHEADER structure from the derived class.

CBaseControlVideo::GetCurrentImage

CBaseControlVideo Class

Retrieves a copy of the current image at the renderer.

Syntax

HRESULT GetCurrentImage(
    long *pBufferSize,
    long *pVideoImage
    );

Parameters

pBufferSize
Pointer to the size of the output buffer.
pVideoImage
Pointer to the output buffer for the image.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_INVALIDARG Invalid argument.
E_OUTOFMEMORY Out of memory. Returned when the pVideoInfo parameter is NULL.
NOERROR Success.
VFW_E_NOT_PAUSED The operation could not be performed because the filter is not paused.

Remarks

This member function retrieves the image from the sample and copies it into the output buffer. The section of video copied into the output buffer reflects the source rectangle set through the IBasicVideo interface. It does not reflect the destination rectangle.

CBaseControlVideo::get_DestinationHeight

CBaseControlVideo Class

Retrieves the current destination rectangle height.

Syntax

HRESULT get_DestinationHeight(
    long *pDestinationHeight
    );

Parameters

pDestinationHeight
Pointer to the destination height.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_POINTER Null pointer argument.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.
NOERROR Success.

Remarks

This member function implements the IBasicVideo::get_DestinationHeight method.

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where it will be played. The destination rectangle is relative to the client area of the window that it is playing in. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::get_DestinationLeft

CBaseControlVideo Class

Retrieves the left coordinate of the current destination rectangle.

Syntax

HRESULT get_DestinationLeft(
    long *pDestinationLeft
    );

Parameters

pDestinationLeft
Pointer to the left coordinate of the destination rectangle.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_POINTER Null pointer argument.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.
NOERROR Success.

Remarks

This member function implements the IBasicVideo::get_DestinationLeft method.

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::GetDestinationPosition

CBaseControlVideo Class

Retrieves the destination rectangle in one atomic operation.

Syntax

HRESULT GetDestinationPosition(
    long *pLeft,
    long *pTop,
    long *pWidth,
    long *pHeight
    );

Parameters

pLeft
Pointer to the left coordinate of the destination rectangle.
pTop
Pointer to the top coordinate of the destination rectangle.
pWidth
Pointer to the width of the destination rectangle.
pHeight
Pointer to the height of the destination rectangle.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_POINTER Null pointer argument.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.
NOERROR Success.

Remarks

This member function can be used in place of separate calls to the CBaseControlVideo::get_DestinationLeft, CBaseControlVideo::get_DestinationTop, CBaseControlVideo::get_DestinationWidth, and CBaseControlVideo::get_DestinationHeight member functions. An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::get_DestinationTop

CBaseControlVideo Class

Retrieves the top coordinate of the current destination rectangle.

Syntax

HRESULT get_DestinationTop(
    long *pDestinationTop
    );

Parameters

pDestinationTop
Pointer to the top coordinate of the destination rectangle.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_POINTER Null pointer argument.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.
NOERROR Success.

Remarks

This member function implements the IBasicVideo::get_DestinationTop method.

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::get_DestinationWidth

CBaseControlVideo Class

Retrieves the width of the current destination rectangle.

Syntax

HRESULT get_DestinationWidth(
    long *pDestinationWidth
    );

Parameters

pDestinationWidth
Pointer to the destination width.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_POINTER Null pointer argument.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.
NOERROR Success.

Remarks

This member function implements the IBasicVideo::get_DestinationWidth method.

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::GetImageSize

CBaseControlVideo Class

Retrieves video image size information.

Syntax

HRESULT GetImageSize(
    VIDEOINFOHEADER *pVideoInfo,
    long *pBufferSize,
    RECT *pSourceRect
    );

Parameters

pVideoInfo
Pointer to a VIDEOINFOHEADER structure to be filled in.
pBufferSize
Pointer to the size of the video buffer.
pSourceRect
Pointer to the rectangle dimensions of the source video.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_INVALIDARG Invalid argument. The data format is not compatible.
E_UNEXPECTED Unexpected error occurred. One or more arguments are NULL.
NOERROR Success.

Remarks

This member function is a helper function used for creating memory image renderings of DIB images. It is called from the base class implementation of CBaseControlVideo::GetCurrentImage when a null pVideoImage parameter is passed to that member function. As a result, this member function constructs and returns a VIDEOINFOHEADER structure, using the information in pBufferSize and pSourceRect.

CBaseControlVideo::get_SourceHeight

CBaseControlVideo Class

Retrieves the height of the current source rectangle.

Syntax

HRESULT get_SourceHeight(
    long *pSourceHeight
    );

Parameters

pSourceHeight
Pointer to the height of the source rectangle.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_POINTER Null pointer argument.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.
NOERROR Success.

Remarks

This member function implements the IBasicVideo::get_SourceHeight method.

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::get_SourceLeft

CBaseControlVideo Class

Retrieves the left coordinate of the current source rectangle.

Syntax

HRESULT get_SourceLeft(
    long *pSourceLeft
    );

Parameters

pSourceLeft
Pointer to the left coordinate of the current source rectangle.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_POINTER Null pointer argument.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.
NOERROR Success.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::GetSourcePosition

CBaseControlVideo Class

Retrieves the position and dimensions of the source rectangle in one atomic operation.

Syntax

HRESULT GetSourcePosition(
    long *pLeft,
    long *pTop,
    long *pWidth,
    long *pHeight
    );

Parameters

pLeft
Pointer to the left coordinate of the source rectangle.
pTop
Pointer to the top coordinate of the source rectangle.
pWidth
Pointer to the width of the source rectangle.
pHeight
Pointer to the height of the source rectangle.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_POINTER Null pointer argument.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.
NOERROR Success.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::GetSourceRect

CBaseControlVideo Class

Retrieves the source rectangle. This is an internal method.

Syntax

virtual HRESULT GetSourceRect(
    RECT *pSourceRect
    ) PURE;

Parameters

pSourceRect
Pointer to the retrieved source rectangle.

Return Value

Returns an HRESULT value.

Remarks

This member function must be overridden in the derived class to return the source rectangle held by the video renderer. It is called from the following CBaseControlVideo member functions.

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class. 

// Return the current source rectangle

HRESULT CVideoText::GetSourceRect(RECT *pSourceRect)
{
    ASSERT(pSourceRect);
    m_pRenderer->m_DrawImage.GetSourceRect(pSourceRect);
    return NOERROR;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object.

CBaseControlVideo::get_SourceTop

CBaseControlVideo Class

Retrieves the top coordinate of the current source rectangle.

Syntax

HRESULT get_SourceTop(
    long *pSourceTop
    );

Parameters

pSourceTop
Pointer to the top coordinate of the source rectangle.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_POINTER Null pointer argument.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.
NOERROR Success.

Remarks

This member function implements the IBasicVideo::get_SourceTop method.

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::get_SourceWidth

CBaseControlVideo Class

Retrieves the width of the current source rectangle.

Syntax

HRESULT get_SourceWidth(
    long *pSourceWidth
    );

Parameters

pSourceWidth
Pointer to the width of the current source rectangle.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_POINTER Null pointer argument.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.
NOERROR Success.

Remarks

This member function implements the IBasicVideo::get_SourceWidth method.

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::GetStaticImage

CBaseControlVideo Class

Pure virtual method that derived classes override.

Syntax

virtual HRESULT GetStaticImage(
    long *pBufferSize,
    long *pDIBImage
    ) PURE;

Parameters

pBufferSize
Pointer to the size of the output buffer.
pDIBImage
Pointer to the output buffer.

Return Value

Returns an HRESULT value.

Remarks

Through the IBasicVideo interface, an application can request that it be given a copy of the current image in a memory buffer (some renderers can return E_NOTIMPL to this if they do not support it). The derived class determines how to retrieve the image. When the application calls CBaseControlVideo::GetStaticImage, it calls this pure virtual method that the derived class should override to implement it. This is also called by the CBaseControlVideo::GetCurrentImage member function.

The class provides a helper member function, CBaseControlVideo::CopyImage, that can be given a sample that contains an image, and the member function will copy the relevant section of it (based on the current source rectangle) into the output buffer supplied by the application.

The following example from the video renderer sample, SampVid, demonstrates an implementation of this member function in a derived class. In this example, m_pRenderer holds an object of a class derived from CBaseVideoRenderer. 

// Return a copy of the current image in the video renderer

HRESULT CVideoText::GetStaticImage(long *pBufferSize,long *pDIBImage)
{
    // Get any sample the renderer may be holding.

    IMediaSample *pMediaSample = m_pRenderer->GetCurrentSample();
    if (pMediaSample == NULL) {
        return E_UNEXPECTED;
    }

    // Call the base class helper method to do the work.

    HRESULT hr = CopyImage(pMediaSample,          // Buffer containing image
                           &m_pRenderer->m_mtIn,                // Type representing bitmap
                           pBufferSize,                                     // Size of buffer for DIB
                           (BYTE*) pDIBImage);                   // Data buffer for output

    pMediaSample->Release();
    return hr;
}

CBaseControlVideo::GetTargetRect

CBaseControlVideo Class

Retrieves the destination rectangle. This is an internal helper member function.

Syntax

virtual HRESULT GetTargetRect(
    RECT *pTargetRect
    ) PURE;

Parameters

pTargetRect
Pointer to the destination rectangle.

Return Value

Returns an HRESULT value.

Remarks

This member function must be overridden in the derived class to return the target rectangle held by the video renderer. It is called from the following CBaseControlVideo member functions.

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class. 

// Return the current destination rectangle.

HRESULT CVideoText::GetTargetRect(RECT *pTargetRect)
{
    ASSERT(pTargetRect);
    m_pRenderer->m_DrawImage.GetTargetRect(pTargetRect);
    return NOERROR;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object.

CBaseControlVideo::GetVideoFormat

CBaseControlVideo Class

Retrieves a video sample that represents the current video format.

Syntax

virtual VIDEOINFOHEADER * GetVideoFormat(void) PURE;

Return Value

Returns a pointer to a VIDEOINFOHEADER structure that contains the current video format.

Remarks

To return and check certain information through IBasicVideo, the object must know the current video format. It gets this information by calling this pure virtual method that derived classes must override. This member function is called by the following CBaseControlVideo member functions.

CBaseControlVideo::get_VideoHeight

CBaseControlVideo Class

Retrieves the height of the native video.

Syntax

HRESULT get_VideoHeight(
    long *pVideoHeight
    );

Parameters

pVideoHeight
Pointer to the height of the native video, in pixels.

Return Value

Returns NOERROR if successful or E_OUTOFMEMORY if there is not enough memory available.

Remarks

This member function implements the IBasicVideo::get_VideoHeight method. It calls the pure virtual CBaseControlVideo::GetVideoFormat to retrieve the VIDEOINFOHEADER structure from the derived class.

CBaseControlVideo::GetVideoPaletteEntries

CBaseControlVideo Class

Retrieves a range of palette entries for the video.

Syntax

HRESULT GetVideoPaletteEntries(
    long StartIndex,
    long Entries,
    long *pRetrieved,
    long *pPalette
    );

Parameters

StartIndex
Zero-based start palette entry.
Entries
Number of entries required.
pRetrieved
Pointer to the number of colors obtained.
pPalette
Pointer to output buffer for colors.

Return Value

Returns NOERROR if successful, VFW_E_NO_PALETTE_AVAILABLE if the video samples has no color palette, E_OUTOFMEMORY if there is not enough memory available, E_INVALIDARG if StartIndex is invalid, or S_FALSE if there are no colors in the palette.

Remarks

This member function returns the current palette of the video as an array allocated by the user. To remain consistent, use the members in the Win32 PALETTEENTRY structure to return the colors, rather than the members in the RGBQUAD structure (although the parameter is a LONG). The memory is allocated by the caller, so simply copy each in turn. Determine that the number of entries requested and the start position offset are both valid. If the number of entries evaluates to zero, return an S_FALSE code.

CBaseControlVideo::GetVideoSize

CBaseControlVideo Class

Retrieves the native video's width and height.

Syntax

HRESULT GetVideoSize(
    long *pWidth,
    long *pHeight
    );

Parameters

pWidth
Pointer to the video width.
pHeight
Pointer to the video height.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_OUTOFMEMORY Out of memory.
E_POINTER Null pointer argument.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.
NOERROR Success.

CBaseControlVideo::get_VideoWidth

CBaseControlVideo Class

Retrieves the width of the native video.

Syntax

HRESULT get_VideoWidth(
    long *pVideoWidth
    );

Parameters

pVideoWidth
Pointer to the width of the native video, in pixels.

Return Value

Returns NOERROR if successful or E_OUTOFMEMORY if there is not enough memory available.

Remarks

This member function implements the IBasicVideo::get_VideoWidth method. It calls the pure virtual CBaseControlVideo::GetVideoFormat to retrieve the VIDEOINFOHEADER structure from the derived class.

CBaseControlVideo::IsDefaultSourceRect

CBaseControlVideo Class

Determines if the renderer is using the default source rectangle (pure virtual).

Syntax

virtual HRESULT IsDefaultSourceRect(void) PURE;

Return Value

Returns an HRESULT value. Returns S_OK if the renderer is using the default source; otherwise, returns S_FALSE.

Remarks

This member function must be implemented in the derived class. It is called by the CBaseControlVideo::IsUsingDefaultSource member function.

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class. 

// Return S_OK if using the default source; otherwise, S_FALSE.

HRESULT CVideoText::IsDefaultSourceRect()
{
    RECT SourceRect;

    VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
    BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
    m_pRenderer->m_DrawImage.GetSourceRect(&SourceRect);

    // Check the coordinates that match the video dimensions.

    if (SourceRect.left != 0 || SourceRect.top != 0 ||
            SourceRect.right != pHeader->biWidth ||
                SourceRect.bottom != pHeader->biHeight) {
                    return S_FALSE;
    }
    return S_OK;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object. The m_mtIn data member, also defined in the derived class, holds a CMediaType object with the media type of the input pin.

CBaseControlVideo::IsDefaultTargetRect

CBaseControlVideo Class

Determines if the renderer is using the default target rectangle (pure virtual).

Syntax

virtual HRESULT IsDefaultTargetRect(void) PURE;

Return Value

Returns an HRESULT value. Returns S_OK if the renderer is using the default target; otherwise, returns S_FALSE.

Remarks

This member function must be implemented in the derived class. It is called by the CBaseControlVideo::IsUsingDefaultDestination member function.

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class. 

// Return S_OK if using the default target; otherwise, S_FALSE.

HRESULT CVideoText::IsDefaultTargetRect()
{
    RECT TargetRect;

    VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
    BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
    m_pRenderer->m_DrawImage.GetTargetRect(&TargetRect);

    // Check the destination that matches the initial client area.

    if (TargetRect.left != 0 || TargetRect.top != 0 ||
            TargetRect.right != m_Size.cx ||
                TargetRect.bottom != m_Size.cy) {
                    return S_FALSE;
    }
    return S_OK;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object. The m_mtIn data member, also defined in the derived class, holds a CMediaType object with media type of the input pin.

CBaseControlVideo::IsUsingDefaultSource

CBaseControlVideo Class

Determines if the renderer is using the default source window.

Syntax

virtual HRESULT IsUsingDefaultSource(void);

Return Value

Returns an HRESULT value. Returns S_OK if the renderer is using the default source; otherwise, returns S_FALSE.

CBaseControlVideo::IsUsingDefaultDestination

CBaseControlVideo Class

Determines if the renderer is using the default destination window.

Syntax

virtual HRESULT IsUsingDefaultDestination(void);

Return Value

Returns an HRESULT value. Returns S_OK if using the default destination; otherwise, returns S_FALSE.

CBaseControlVideo::OnUpdateRectangles

CBaseControlVideo Class

Called when either the source or destination rectangle changes.

Syntax

virtual HRESULT OnUpdateRectangles(void);

Return Value

Returns NOERROR.

CBaseControlVideo::OnVideoSizeChange

CBaseControlVideo Class

Passes an EC_VIDEO_SIZE_CHANGED message to the filter graph manager.

Syntax

virtual HRESULT OnVideoSizeChange(void);

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_OUTOFMEMORY Out of memory.

Remarks

A video renderer should call this member function each time the video size is changed; this will typically be called once after initial connection. If the renderer can support dynamic format changes (from 320 x 240 to 160 x 120), it should also call it after each change.

CBaseControlVideo::put_DestinationHeight

CBaseControlVideo Class

Sets the destination rectangle height.

Syntax

HRESULT put_DestinationHeight(
    long DestinationHeight
    );

Parameters

DestinationHeight
New destination height.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_INVALIDARG Invalid argument.
E_POINTER Null pointer argument.
NOERROR Success.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::put_DestinationLeft

CBaseControlVideo Class

Sets the left coordinate of the destination rectangle.

Syntax

HRESULT put_DestinationLeft(
    long DestinationLeft
    );

Parameters

DestinationLeft
New left coordinate of destination rectangle.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_INVALIDARG Invalid argument.
E_POINTER Null pointer argument.
NOERROR Success.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::put_DestinationTop

CBaseControlVideo Class

Sets the top coordinate of the destination rectangle.

Syntax

HRESULT put_DestinationTop(
    long DestinationTop
    );

Parameters

DestinationTop
New top coordinate of the destination rectangle.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_INVALIDARG Invalid argument.
E_POINTER Null pointer argument.
NOERROR Success.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::put_DestinationWidth

CBaseControlVideo Class

Sets the width of the destination rectangle.

Syntax

HRESULT put_DestinationWidth(
    long DestinationWidth
    );

Parameters

DestinationWidth
New destination width.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_INVALIDARG Invalid argument.
E_POINTER Null pointer argument.
NOERROR Success.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::put_SourceHeight

CBaseControlVideo Class

Sets the source rectangle height.

Syntax

HRESULT put_SourceHeight(
    long SourceHeight
    );

Parameters

SourceHeight
Source height.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_INVALIDARG Invalid argument.
E_POINTER Null pointer argument.
NOERROR Success.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::put_SourceLeft

CBaseControlVideo Class

Sets the source rectangle left coordinate.

Syntax

HRESULT put_SourceLeft(
    long SourceLeft
    );

Parameters

SourceLeft
New left coordinate of the source rectangle.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_INVALIDARG Invalid argument.
E_POINTER Null pointer argument.
NOERROR Success.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::put_SourceTop

CBaseControlVideo Class

Sets the top coordinate of the source rectangle.

Syntax

HRESULT put_SourceTop(
    long SourceTop
    );

Parameters

SourceTop
New top coordinate of the source rectangle.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_INVALIDARG Invalid argument.
E_POINTER Null pointer argument.
NOERROR Success.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::put_SourceWidth

CBaseControlVideo Class

Sets the width of the source rectangle.

Syntax

HRESULT put_SourceWidth(
    long SourceWidth
    );

Parameters

SourceWidth
New width of the source rectangle.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_INVALIDARG Invalid argument.
E_POINTER Null pointer argument.
NOERROR Success.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::SetControlVideoPin

CBaseControlVideo Class

Sets the pin used by the filter.

Syntax

void SetControlVideoPin(
    CBasePin *pPin
    );

Parameters

pPin
Pointer to the pin with which the interface is synchronized.

Return Value

No return value.

Remarks

The interface can be called only when the filter has been connected successfully. The object is passed through this method to the pin with which it is synchronized; in most cases it will determine if the pin is connected when it has an interface method called and will return VFW_E_NOT_CONNECTED if it fails.

CBaseControlVideo::SetDefaultDestinationPosition

CBaseControlVideo Class

Sets the renderer back to using the default destination position (typically the entire window client area).

Syntax

HRESULT SetDefaultDestinationPosition(void);

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
NOERROR Success.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::SetDefaultSourcePosition

CBaseControlVideo Class

Sets the renderer back to using the default source position (typically all the native video).

Syntax

HRESULT SetDefaultSourcePosition(void);

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
NOERROR Success.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::SetDefaultSourceRect

CBaseControlVideo Class

Sets the default source video rectangle (pure virtual). This in an internal member function that gets called when the source rectangle is reset.

Syntax

virtual HRESULT SetDefaultSourceRect(void) PURE;

Return Value

Returns an HRESULT value.

Remarks

Derived classes should override this to reset the source rectangle. It is called from CBaseControlVideo::SetDefaultSourcePosition.

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class. 

// This is called when you reset the default source rectangle.

HRESULT CVideoText::SetDefaultSourceRect()
{
    VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
    BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
    RECT SourceRect = {0,0,pHeader->biWidth,pHeader->biHeight};
    m_pRenderer->m_DrawImage.SetSourceRect(&SourceRect);
    return NOERROR;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object. The m_mtIn data member, also defined in the derived class, holds a CMediaType object with media type of the input pin.

CBaseControlVideo::SetDefaultTargetRect

CBaseControlVideo Class

Sets the default target video rectangle (pure virtual). This is an internal member function that gets called when the source rectangle is reset.

Syntax

virtual HRESULT SetDefaultTargetRect(void) PURE;

Return Value

Returns an HRESULT value.

Remarks

Derived classes should override this to reset the destination video rectangle. It is called from the CBaseControlVideo::SetDefaultDestinationPosition member function.

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class. 

// This is called when you reset the default target rectangle.

HRESULT CVideoText::SetDefaultTargetRect()
{
    VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
    BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
    RECT TargetRect = {0,0,m_Size.cx,m_Size.cy};
    m_pRenderer->m_DrawImage.SetTargetRect(&TargetRect);
    return NOERROR;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object. The m_mtIn data member, also defined in the derived class, holds a CMediaType object with the media type of the input pin.

CBaseControlVideo::SetDestinationPosition

CBaseControlVideo Class

Sets the destination rectangle for the video.

Syntax

HRESULT SetDestinationPosition(
    long Left,
    long Top,
    long Width,
    long Height
    );

Parameters

Left
New left coordinate.
Top
New top coordinate.
Width
New width.
Height
New height.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_INVALIDARG Invalid argument.
E_POINTER Null pointer argument.
NOERROR Success.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::SetSourcePosition

CBaseControlVideo Class

Sets a new source position for the video.

Syntax

HRESULT SetSourcePosition(
    long Left,
    long Top,
    long Width,
    long Height
    );

Parameters

Left
New left coordinate.
Top
New top coordinate.
Width
New width.
Height
New height.

Return Value

Returns an HRESULT value that depends on the implementation; can be one of the following values, or other values not listed.
E_FAIL Failure.
E_INVALIDARG Invalid argument.
E_POINTER Null pointer argument.
NOERROR Success.
VFW_E_NOT_CONNECTED The operation cannot be performed because the pins are not connected.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::SetSourceRect

CBaseControlVideo Class

Sets the current source video rectangle (pure virtual). This is an internal member function that gets called when the source rectangle changes.

Syntax

virtual HRESULT SetSourceRect(
    RECT *pSourceRect
    ) PURE;

Parameters

pSourceRect
Pointer to the source rectangle.

Return Value

Returns an HRESULT value.

Remarks

Derived classes should override this member function to know when the source rectangle changes. It is called from the following member functions.

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class. 

HRESULT CVideoText::SetSourceRect(RECT *pSourceRect)
{
    m_pRenderer->m_DrawImage.SetSourceRect(pSourceRect);
    return NOERROR;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object.

CBaseControlVideo::SetTargetRect

CBaseControlVideo Class

Sets the current target rectangle (pure virtual). This is an internal member function that gets called when the destination rectangle changes.

Syntax

virtual HRESULT SetTargetRect(
    RECT *pTargetRect
    ) PURE;

Parameters

pTargetRect
Pointer to the destination rectangle.

Return Value

Returns an HRESULT value.

Remarks

Derived classes should override this to know when the destination rectangle changes. It is called from the following member functions.

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class. 

HRESULT CVideoText::SetTargetRect(RECT *pTargetRect)
{
    m_pRenderer->m_DrawImage.SetTargetRect(pTargetRect);
    return NOERROR;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object.

Top of Page Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.