This does not seem to be documented anywhere, so it makes sense to mention. A video decoder, wrapped by DMO Wrapper Filter, will receive preroll media samples with AM_SAMPLE_PREROLL flag (alternatively available using IMediaSample::IsPreroll), but it won’t even forward these samples to the underlying DMO, instead they are just ignored.

MSDN says:

Preroll samples are processed but not displayed. They are located in the media stream before the displayable samples.

However this behavoir of DMO Wrapper Filter does not seem to be correct. A DMO might require (in my case, maybe there are other scenarios) to initialize its decoding context from a splice point and then be able to decode further samples. The way the wrapper is skipping samples it appears that DMO is not receiving splice point data and won’t be able to start decoding of non-preroll samples until it receives a non-preroll splice point media sample…

Recently it was the time to sort out an issue with a video DMO, which outputs YV12 video and in the same time is capable of supporting extended video strides in order to efficiently make a direct connection to Video Mixing Renderer Filters.

From past experience, I already knew that some bugs are definitely involved but their effect was yet unexplored. For a testbed application, I took good old FrameRateSample02 application, which generates multiple video feeds and routes it to video renderers:

With new source video choices the application is capable of constructing filter graphs that use a private DMO (that is hosted inside the executable) wrapped with DMO Wrapper Filter, with a graph topology shown below:

The DMO does not do any processing, except support for extended strides while copying original data into buffer streamed to video renderer. Extended strides for a planar YUV format is a bit tricky. Are they supported at all? Yes, they are and video renderer might still request an extended stride and in which case origial MxN video needs to be copied into (M+P)xN buffer. Unlike packed pixel format, unused space is distributed in a bit different way but still very much similarly: output buffer is still a regular (M+P)xN rectangle, where the effective picture of size MxN should be copied into top left corner.

The problem I was aware of from past experience showed up immediately once the filters connected. After a dynamic format change initiated by the VMR, the filters report different connection media types. DMO Wrapper Filter still shows original connection time connection media type, while Video Mixing Renderer Filter shows media type it switched to.

This looks like DMO Wrapper Filter bug, but was yet to check if it still handles the new media type properly and passes the format change to the underlying DMO object. Taking into consideration the extent DMOs are used by Microsoft, it had to, thought I never met this in the MSDN documentation.

Further debugging revealed that DMO Wrapper Filter does handle the media type change and forward it to the DMO through IMediaObject::SetOutputType method. This happens when DMO already received its first input, and immediately before following IMediaObject::ProcessOutput method call:

rodmo.h(293) : CMediaObjectT<class CVideoDmo>::AllocateStreamingResources: ...
rodshow.h(2716) : CBaseFilterT<class CMainDialog::CSourceFilter>::Pause: ...
rodshow.h(2722) : CBaseFilterT<class CMainDialog::CSourceFilter>::Pause: m_State 0
rodshow.h(2730) : CBaseFilterT<class CMainDialog::CSourceFilter>::Pause: m_State 1
rodshow.h(2784) : CBaseFilterT<class CMainDialog::CSourceFilter>::GetState: nTimeout 0
rodmo.h(679) : CSimpleMediaObjectT<class CVideoDmo,1>::GetInputStatus: nInputStreamIndex 0
rodmo.h(702) : CSimpleMediaObjectT<class CVideoDmo,1>::ProcessInput: nInputStreamIndex 0, nFlags 0x1
rodmo.h(527) : CSimpleMediaObjectT<class CVideoDmo,1>::SetOutputType: nOutputStreamIndex 0, nFlags 0x0
rodmo.h(727) : CSimpleMediaObjectT<class CVideoDmo,1>::ProcessOutput: nFlags 0x1, nOutputBufferCount 1

So, the media type change is handled and the problem is only limited to reporting wrong (original) media type off the wrapper filter output pin.

Investigation of filter connection however brought up another interesting fact, memory allocator properties:

As the filters switched to a new media type, with extended strides, the memory allocator should obviously have been updated accordingly, in order to support larger buffer. However current memory allocator properties indicate old buffer size of 460,800 bytes, while new media type assumes 737,280 buffer size at the very least. The samples are however streamed fine, so the issue is also limited to incorrectly reported size.

This memory allocator is managed by the Video Mixing Renderer Filter, so the problem seems to be relating to it.

Good news however was that video was streamed and displayed correctly.

One thing that deserves special attention is making a DMO private. I already wrote another post on private DMOs some time ago, and this time the sample shows even a better way in case one does not need the DMO available for Intelligent Connect (in which case DMORegister call along with administrative privileges will be required),  just for a private instantiation. DMO is typically created by CoCreateInstance from inside the DMO Wrapper Filter, e.g. using IDMOWrapperFilter::Init method, so it is necessary to either register COM class, or… just register its class object for the process using CoRegisterClassObject.

There is no need for direct usage of API since ATL already wrapped the calls and we are to take advantage of what is already available. First of all, the DMO class requires certain CLSID, because we don’t have one typically declared in IDL. A good place for attaching CLSID is class declaration and __declspec keyword:

class __declspec(uuid("88B976BE-EEE6-45b1-A21B-42A941DF8819")) ATL_NO_VTABLE CVideoDmo :
    public CComObjectRootEx<CComMultiThreadModelNoCS>,
    public CComCoClass<CVideoDmo>,
    public CSimpleMediaObjectT<CVideoDmo, 1>
{

Further a COM class is typically referenced into module’s object map byan OBJECT_ENTRY_AUTO macro:

//OBJECT_ENTRY_AUTO(__uuidof(VideoDmo), CVideoDmo)

But we don’t need this this time as we don’t need standard COM registration for the class. We will register its class object manually and temporarily, at the time of DMO initialization:

CComQIPtr<IBaseFilter> pBaseFilter;
CVideoDmo* pVideoDmo;
{
    BEGIN_OBJECT_MAP(g_pObjectMap)
        OBJECT_ENTRY(__uuidof(CVideoDmo), CVideoDmo)
    END_OBJECT_MAP()
    ATLASSERT(DIM(g_pObjectMap) == 2 && !g_pObjectMap[1].pclsid);
    ATLENSURE_SUCCEEDED(g_pObjectMap[0].RegisterClassObject(CLSCTX_INPROC_SERVER, REGCLS_SINGLEUSE));
    _ATLTRY
    {
        CComPtr<IDMOWrapperFilter> pDmoWrapperFilter = ConstructDmoWrappedFilter(__uuidof(CVideoDmo), CVideoDmo::GetCategory());
        pBaseFilter = pDmoWrapperFilter;
        ATLENSURE_THROW(pBaseFilter, E_NOINTERFACE);
        CComQIPtr<IMediaObject> pMediaObject = pDmoWrapperFilter;
        ATLENSURE_THROW(pMediaObject, E_NOINTERFACE);
        pVideoDmo = static_cast<CVideoDmo*>((IMediaObject*) pMediaObject);
    }
    _ATLCATCHALL()
    {
        ATLVERIFY(SUCCEEDED(g_pObjectMap[0].RevokeClassObject()));
        _ATLRETHROW;
    }
    ATLVERIFY(SUCCEEDED(g_pObjectMap[0].RevokeClassObject()));
}
pVideoDmo->Initialize(CDmoMediaType(m_pMediaType), CopyYv12MediaBuffer);
ATLENSURE_SUCCEEDED(pGraphBuilder->AddFilter(pBaseFilter, CStringW(_T("Pass-Through DMO"))));
ATLENSURE_SUCCEEDED(pGraphBuilder->Connect(pOutputPin, _FilterGraphHelper::GetFilterPin(pBaseFilter, PINDIR_INPUT)));
pOutputPin = _FilterGraphHelper::GetFilterPin(pBaseFilter, PINDIR_OUTPUT)

What is being done in the code snippet above is:

• local object map with a single OBJECT_ENTRY item to have ATL manage class object registration/revokation for us
• registration of a private class/CLSID
• instantiation and initialization of a DMO Wrapper Filter which is to pick up our class
• cast back to native C++ pointer for easy further access (a private interface would be more accurate here)
• revokation for CLSID

For information, the interfaces queried from the DMO:

Find all "CVideoDmo::InternalQueryInterface", Hidden, Find Results 1, Current Document
CVideoDmo::InternalQueryInterface: Interface IMediaObject, Result 0x00000000
CVideoDmo::InternalQueryInterface: Interface IDMOQualityControl, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IDMOVideoOutputOptimizations, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IMediaObject, Result 0x00000000
CVideoDmo::InternalQueryInterface: Interface IWMGetSecureChannel, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IAMOpenProgress, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IAMDeviceRemoval, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IDirectVobSub, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IDirectVobSub, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IWMCodecAMVideoAccelerator, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IDirectVobSub, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IWMCodecAMVideoAccelerator, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IWMCodecAMVideoAccelerator, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IMediaSeeking, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IMediaPosition, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IAMFilterMiscFlags, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IVideoWindow, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IBasicAudio, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IAMFilterMiscFlags, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IKsPropertySet, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IReferenceClock, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IWMCodecAMVideoAccelerator, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IAMDeviceRemoval, Result 0x80004002
CVideoDmo::InternalQueryInterface: Interface IAMOpenProgress, Result 0x80004002
Matching lines: 24

A Visual C++ .NET 2008 source code is available from SVN. Additional files will be required to compile, but binary is also incuded.

Started as Is it possible to use local component in DLL? on microsoft.public.vc.atl newsgroup. The question is to embed a custom DirectX Media Object (DMO) into executable so that it is only available to proprietary application and not to entire system and could be reused in other applications. If in particular this DMO should be available to intelligent connect, e.g. used by embedded Windows Media Player control, the solution requires that private DMO appears fully registered as full featured regular DMO.

A while ago I proposed a solution on getting COM Class/DMO embedded into executable and temporarily exposed as availble without registry registration through CoRegisterClassObject/RegisterClassObject, however in addition to COM class registration, a DMO needs to also be specifically listed as a DMO, through DMORegister API.

In order to expose private DMO to DirectShow subsystem the following steps has to be performed:

• register COM class object as a COM class (CoRegisterClassObject) to enable its instantiation by its CLSID
• use DMORegister API to list DMO in global list (warning, seems to be requiring write permission on HKEY_CLASSES_ROOT key)
• have the filter graph of interest created
• use DMOUnregister API as early as possible to unlist private DMO from global list

ATLENSURE_SUCCEEDED(__objMap_CPrivateMediaObject.RegisterClassObject(CLSCTX_INPROC_SERVER, REGCLS_MULTI_SEPARATE));
DMO_PARTIAL_MEDIATYPE pInputMediaTypes[] = { { MEDIATYPE_Video, CPrivateMediaObject::GetXxxxSubtype() } };
ATLENSURE_SUCCEEDED(DMORegister(L"Private DMO", CLSID_PrivateMediaObject, DMOCATEGORY_VIDEO_DECODER, 0, _countof(pInputMediaTypes), pInputMediaTypes, 0, NULL));
...
ATLVERIFY(SUCCEEDED(DMOUnregister(CLSID_PrivateMediaObject, DMOCATEGORY_VIDEO_DECODER)));

The sample code/project takes an .AVI file which is a XVID video file with a FOURCC compression code changed from XVID to XXXX. The file is unplayable but there is a private DMO which accepts XXXX video and copies data as is into XVID format on its output.

A Visual C++ .NET 2008 source code is available from SVN.

Previously on the topic:

• Part 1: Starting the Project
• Part 2: Video Processing
• Part 3: Persistence, Automation and Property Pages
• Part 4: Merit

Due to the nature of the brightness and constract correction processing, it would make sense to combine and simplify processing to apply correction “in-place”, that is without copying data from input to output buffer, but instead processing the same buffer before it is passed further downstream.

DMO API offers additional optional IMediaObjectInPlace interface to be implemented on the DMO which the hosting object might prefer to regular IMediaObject.

The interface itself is simple with basically the only Process method to actually handle the processing:

// IMediaObjectInPlace
	STDMETHOD(Process)(ULONG nSize, BYTE* pnData, REFERENCE_TIME nStartTime, DWORD nFlags)
	STDMETHOD(Clone)(IMediaObjectInPlace** ppMediaObject)
	STDMETHOD(GetLatency)(REFERENCE_TIME* pnLatencyTime)

Still the interest in in-place processing in DMO is more abstract because current DMO Wrapper Filter implementation does not take advantage of in-place processing and chooses to always work through IMediaObject.

However if the object is hosted directly, in-place processing might make sense and be important.

To support in-place processing in the DMO it is required to inherit from interface and add it to the COM map:

class ATL_NO_VTABLE CBrightnessContrastObject :
	public CComObjectRootEx<CComMultiThreadModel>,
	...
	public IMediaObjectInPlace
...
BEGIN_COM_MAP(CBrightnessContrastObject)
	...
	COM_INTERFACE_ENTRY(IMediaObjectInPlace)
END_COM_MAP()

And implement the IMediaObjectInPlace methods, of which IMediaObjectInPlace::Process is the essential.

Source code: DmoBrightnessContrastSample.05.zip (note that Release build binary is included)

Previously on the topic:

• Part 1: Starting the Project
• Part 2: Video Processing
• Part 3: Persistence, Automation and Property Pages

The implemented so far filter/DMO shown a problem related to its unexpectedly high “importance” in the system with the symptom of “auto-insertion” the filter when it is not necessary. For example, let us render an AVI file through Infinite Tee Pin Filter:

The problem is that DirectShow auto-inserts our Brightness/Contrast filter into the graph while it is obviously not expected, wanted or necessary:

The problem is high filter/DMO merit value and a popular YUY2 video format the filter is advertised to accept on input during DMO registration.

The merit is 0×00600800 and defined values are:

enum
{
    MERIT_PREFERRED     = 0x800000,
    MERIT_NORMAL        = 0x600000,
    MERIT_UNLIKELY      = 0x400000,
    MERIT_DO_NOT_USE    = 0x200000,
    MERIT_SW_COMPRESSOR = 0x100000,
    MERIT_HW_COMPRESSOR = 0x100050
};

So the filter’s merit is MERIT_NORMAL plus 0×800 DMO API adds to give DMOs an advantage over regular filters. If we followed merit choice guidelines (“A filter that should never be considered for ordinary playback should have a merit of MERIT_DO_NOT_USE or less“), we would have taken MERIT_DO_NOT_USE value or MERIT_UNLIKELY at the very most, because the nature of this filter is to provide additional processing feature when it is explicitly requested by the graph creator.

So in order to resolve the problem we need to override DMO’s default merit and review the registration step. To provide our own merit value for the filter, we need to create a REG_DWORD Merit value in advance under coclass registry key in HKEY_CLASSES_ROOT:

OLECHAR pszClassIdentifier[64] = { 0 };
ATLVERIFY(StringFromGUID2(GetObjectCLSID(), pszClassIdentifier, _countof(pszClassIdentifier)));
CRegKey Key;
CString sKeyName;
sKeyName.Format(_T("CLSID\\%ls"), pszClassIdentifier);
__C(HRESULT_FROM_WIN32(Key.Create(HKEY_CLASSES_ROOT, sKeyName)));
static const DWORD g_nMerit = MERIT_DO_NOT_USE;
__C(HRESULT_FROM_WIN32(Key.SetDWORDValue(_T("Merit"), g_nMerit)));

Note that another (even easier) way to pre-create this registry value is putting it into .RGS registration script file (MERIT_DO_NOT_USE = 0×00200000 = 2097152):

HKCR
{
	...
	NoRemove CLSID
	{
		ForceRemove {334BE85B-9DE4-4405-8EEE-9CBB2650F83D} = s 'BrightnessContrastObject Class'
		{
			...
			val Merit = d '2097152'

Source code: DmoBrightnessContrastSample.04.zip (note that Release build binary is included)

See also:

• Registering a DMO

Continued by:

• Part 5: In-Place Processing
  

See topic on MSDN Forums about coloring issue.

This is a demo of YUY2 to YV12 conversion as suggested copying Y values and averaging U and V.

Original image is on the right.

Code snippet to perform the transformation:

ATLASSERT(pInputBitmapInfoHeader->biCompression == FOURCC_YUY2);
const CSize Extent = pInputVideoInfoHeader->GetExtent();
ATLASSERT(Extent == pOutputVideoInfoHeader->GetExtent());
const BYTE* pnInputData = InputMediaBuffer.m_pnData;
SSIZE_T nFirstInputRowOffset, nNextInputRowOffset;
pInputVideoInfoHeader->GetData(nFirstInputRowOffset, nNextInputRowOffset);
ATLASSERT(!nFirstInputRowOffset);
BYTE* pnOutputData = OutputMediaBuffer.m_pnData;
SSIZE_T nFirstOutputRowOffset, nNextOutputRowOffset;
pOutputVideoInfoHeader->GetData(nFirstOutputRowOffset, nNextOutputRowOffset);
ATLASSERT(!nFirstOutputRowOffset);
BYTE* pnOutputDataY = pnOutputData;
BYTE* pnOutputDataV = pnOutputDataY + Extent.cy * nNextOutputRowOffset;
BYTE* pnOutputDataU = pnOutputDataV + (Extent.cy * nNextOutputRowOffset) / 4;
ATLTRACE2(atlTraceGeneral, 5, _T("pnInputData 0x%08x - 0x%08x, Extent { %d, %d }, pnOutputData 0x%08x - 0x%08x\n"), pnInputData, pnInputData + pInputBitmapInfoHeader->biSizeImage, Extent.cx, Extent.cy, pnOutputData, pnOutputData + pOutputBitmapInfoHeader->biSizeImage);
ATLTRACE2(atlTraceGeneral, 5, _T("nFirstInputRowOffset %d, nNextInputRowOffset %d, nFirstOutputRowOffset %d, nNextOutputRowOffset %d\n"), nFirstInputRowOffset, nNextInputRowOffset, nFirstOutputRowOffset, nNextOutputRowOffset);
ATLTRACE2(atlTraceGeneral, 5, _T("pnOutputDataY 0x%08x, pnOutputDataV 0x%08x, pnOutputDataU 0x%08x\n"), pnOutputDataY, pnOutputDataV, pnOutputDataU);
SSIZE_T nInputRowOffset = nFirstInputRowOffset;
for(LONG nY = 0; nY < Extent.cy; nY += 2)
{
    SSIZE_T nInputOffset = nInputRowOffset;
    for(LONG nX = 0; nX < Extent.cx; nX += 2)
    {
        pnOutputDataY[0] = pnInputData[nInputOffset + 0];
        const BYTE nU0 = pnInputData[nInputOffset + 1];
        pnOutputDataY[1] = pnInputData[nInputOffset + 2];
        const BYTE nV0 = pnInputData[nInputOffset + 3];
        pnOutputDataY[nNextOutputRowOffset + 0] = pnInputData[nInputOffset + nNextInputRowOffset + 0];
        const BYTE nU1 = pnInputData[nInputOffset + nNextInputRowOffset + 1];
        pnOutputDataY[nNextOutputRowOffset + 1] = pnInputData[nInputOffset + nNextInputRowOffset + 2];
        const BYTE nV1 = pnInputData[nInputOffset + nNextInputRowOffset + 3];
        pnOutputDataU[0] = (nU0 + nU1) / 2;
        pnOutputDataV[0] = (nV0 + nV1) / 2;
        nInputOffset += 4;
        pnOutputDataY += 2;
        pnOutputDataV += 1;
        pnOutputDataU += 1;
    }
    nInputRowOffset += 2 * nNextInputRowOffset;
    pnOutputDataY += 2 * nNextOutputRowOffset - Extent.cx;
    pnOutputDataV += nNextOutputRowOffset / 2 - Extent.cx / 2;
    pnOutputDataU += nNextOutputRowOffset / 2 - Extent.cx / 2;
}
ATLTRACE2(atlTraceGeneral, 5, _T("pnOutputDataY 0x%08x, pnOutputDataV 0x%08x, pnOutputDataU 0x%08x\n"), pnOutputDataY, pnOutputDataV, pnOutputDataU)

See also:

• Video Rendering with 8-Bit YUV Formats
• Colorspaces, YUY2 and YV12
• IYUV or YV12 colorspace?, YUV colorspaces SMPTE vs 601 vs 709
• Feeding Y’CbCr (“YUV”/”YV12″) data to TMPGEnc

Previously on the topic:

• Part 1: Starting the Project
• Part 2: Video Processing

The principal task of video processing is done but there are still things mandatory for the filter to be usable. First of all, a custom interface is required to be able to control the filter from higher level application and to adjust brightness and constract correction values on the run time. Additionally, persistence would not hurt at all to be able to store correction settings along with other graph settings in GraphEdit graph file or anywhere else. Additionally, it would also be convenient to have a property page for the filter to be able to adjust the correction settings through GUI, both on graph composition and while the graph is running.

All the mentioned tasks are interconnected and ATL has an answer in implementation of:

• IDispatch-derived automation interface through IDispatchImpl class to implement custom interface to be used for external control over the filter/DMO and also to be used to access persistent properties
• IPersistStream/IPersistStreamInit interfaces through IPersistStreamInitImpl class and PROP_MAP macro map to implement persistence capabilities
• ISpecifyPropertyPages interface through ISpecifyPropertyPagesImpl class to provide custom property page

Also note that DMO Minimum Requirements mention IPersistStream and ISpecifyPropertyPages as not required but recommended as useful, and these interfaces will be used by DirectShow.

We start with custom IDispatch-derived interface to be used to control filter and for persistence. ATL Project Wizard already prepared empty IBrightnessContrastObject interface as a part of project creation, where we are adding Brightness and Contrast properties (in the IDL definition) and adding implementation of corresponding methods to the filter/DMO class:

interface IBrightnessContrastObject : IDispatch
{
	[propget, id(1)] HRESULT Brightness([out, retval] LONG* pnBrightness);
	[propput, id(1)] HRESULT Brightness([in] LONG nBrightness);
	[propget, id(2)] HRESULT Contrast([out, retval] LONG* pnContrast);
	[propput, id(2)] HRESULT Contrast([in] LONG nContrast);
};

// IBrightnessContrastObject
	STDMETHOD(get_Brightness)(LONG* pnBrightness) throw()
	STDMETHOD(put_Brightness)(LONG nBrightness) throw()
	STDMETHOD(get_Contrast)(LONG* pnContrast) throw()
	STDMETHOD(put_Contrast)(LONG nContrast) throw()

To complete implemetnation of persistence we are to inherit from IPersistStreamInitImpl and also add a property map:

class ATL_NO_VTABLE CBrightnessContrastObject :
	...
	public IPersistStreamInitImpl<CBrightnessContrastObject>,
...
BEGIN_COM_MAP(CBrightnessContrastObject)
	COM_INTERFACE_ENTRY(IPersistStreamInit)
	COM_INTERFACE_ENTRY_IID(IID_IPersistStream, IPersistStreamInit)
...
BEGIN_PROP_MAP(CBrightnessContrastObject)
	PROP_ENTRY_TYPE_EX("Brightness", 1, CLSID_NULL, __uuidof(IBrightnessContrastObject), VT_I4)
	PROP_ENTRY_TYPE_EX("Contrast", 2, CLSID_NULL, __uuidof(IBrightnessContrastObject), VT_I4)
END_PROP_MAP()
...
public:
	BOOL m_bRequiresSave;

In the property map we enumerate the persistent properties using PROP_ENTRY_TYPE_EX (a successor of PROP_ENTRY_EX, which is deprecated starting Visual Studio .NET 2008).

Note that ATL implements IPersistStreamInit, however IPersistStream is compatible in method declaration so we can quick-implement this interface through declaring COM_INTERFACE_ENTRY_IID and thus casting IPersistStreamInit to IPersistStream.

Note CLSID_NULL which is a class identifier of the corresponding property page, if any, which we will replace with a non-NULL identifier below as soon as property page is ready.

We also need a m_bRequiresSave variable which is used by IPersist*Impl classes and for this reason it has to be either public or instead we should friend the classes to allow access to the variable.

To ensure automation interface property put accessors are working as expected, let us re-work debug pre-initialization of the correction variables through FinalConstruct method:

#if defined(_DEBUG)
	HRESULT FinalConstruct() throw()
	{
		_ATLTRY
		{
			__C(put_Brightness(-0x0010));
			__C(put_Contrast(0x2000));
		}
		_ATLCATCH(Exception)
		{
			return Exception;
		}
		return S_OK;
	}
#endif // defined(_DEBUG)

The only things remained is a property page, for which we create a new COM object class CGeneralPropertyPage. Luckily, ATL has a wizard-based creation helper for property pages:

We will start needing WTL for convenient GUI implementation. Please refer to Example: Implementing a Property Page on how property page is implemented. Once implementation is complete, we need to inherit from IPersistStreamInitImpl and reference the property page from filter/DMO property map:

class ATL_NO_VTABLE CBrightnessContrastObject :
	...
	public ISpecifyPropertyPagesImpl<CBrightnessContrastObject>,
...
BEGIN_COM_MAP(CBrightnessContrastObject)
	...
	COM_INTERFACE_ENTRY(ISpecifyPropertyPages)
...
BEGIN_PROP_MAP(CBrightnessContrastObject)
	PROP_PAGE(CLSID_GeneralPropertyPage)

Filter’s run time:

Source code: DmoBrightnessContrastSample.03.zip (note that Release build binary is included)

Continued by:

• Part 4: Merit

Previously on the topic:

• Part 1: Starting the Project

We have the DMO filter project compilable and registered with the system and it is right time to start putting code in that allows connecting the filter to other DirectShow filters, such as video capture or video file source on the input and video renderer on the output.

IMediaObject implementation includes the following groups of functions:

• object capabilities:

  STDMETHOD(GetStreamCount)(DWORD* pnInputStreamCount, DWORD* pnOutputStreamCount)
  STDMETHOD(GetInputStreamInfo)(DWORD nInputStreamIndex, DWORD* pnFlags)
  STDMETHOD(GetOutputStreamInfo)(DWORD nOutputStreamIndex, DWORD* pnFlags)
  STDMETHOD(GetInputType)(DWORD nInputStreamIndex, DWORD nTypeIndex, DMO_MEDIA_TYPE* pMediaType)
  STDMETHOD(GetOutputType)(DWORD nOutputStreamIndex, DWORD nTypeIndex, DMO_MEDIA_TYPE* pMediaType)

• current media types:

  STDMETHOD(SetInputType)(DWORD nInputStreamIndex, const DMO_MEDIA_TYPE* pMediaType, DWORD nFlags)
  STDMETHOD(SetOutputType)(DWORD nOutputStreamIndex, const DMO_MEDIA_TYPE* pMediaType, DWORD nFlags)
  STDMETHOD(GetInputCurrentType)(DWORD nInputStreamIndex, DMO_MEDIA_TYPE* pMediaType)
  STDMETHOD(GetOutputCurrentType)(DWORD nOutputStreamIndex, DMO_MEDIA_TYPE* pMediaType)
  STDMETHOD(GetInputSizeInfo)(DWORD nInputStreamIndex, DWORD* pnBufferSize, DWORD* pnMaximalLookAheadBufferSize, DWORD* pnAlignment)
  STDMETHOD(GetOutputSizeInfo)(DWORD nOutputStreamIndex, DWORD* pnBufferSize, DWORD* pnAlignment)

• streaming:

  STDMETHOD(GetInputMaxLatency)(DWORD nInputStreamIndex, REFERENCE_TIME* pnMaximalLatency)
  STDMETHOD(SetInputMaxLatency)(DWORD nInputStreamIndex, REFERENCE_TIME nMaximalLatency)
  STDMETHOD(Flush)()
  STDMETHOD(Discontinuity)(DWORD nInputStreamIndex)
  STDMETHOD(AllocateStreamingResources)()

• data processing:

  STDMETHOD(GetInputStatus)(DWORD nInputStreamIndex, DWORD* pnFlags)
  STDMETHOD(Lock)(LONG bLock)
  STDMETHOD(ProcessInput)(DWORD nInputStreamIndex, IMediaBuffer* pMediaBuffer, DWORD nFlags, REFERENCE_TIME nTime, REFERENCE_TIME nLength)
  STDMETHOD(ProcessOutput)(DWORD nFlags, DWORD nOutputBufferCount, DMO_OUTPUT_DATA_BUFFER* pOutputBuffers, DWORD* pnStatus)

For a very basic filter/DMO we will need to implement:

• GetStreamCount to indicate number of streams and number of pins on the corresponding filter
• GetInputStreamInfo and GetInputType to indicate acceptable input media type
• GetOutputStreamInfo and GetOutputType to indicate acceptable output media type; we will be ready to suggest output media type as soon as input media type is already agreed since media types should match
• SetInputType, SetOutputType, GetInputCurrentType, GetOutputCurrentType are simple get/put accessors with a check on setting current media type to be used
• GetInputSizeInfo and GetOutputSizeInfo will indicate buffer requirements
• GetInputStatus and ProcessInput will deal with accepting input data
• ProcessOutput is the method to actually perform brightness and contrast conversion

The object will have one input and one output pin with similar fixed side buffers on both ends – the simplest case possible.

Starting with GetInputType method we are dealing with DMO_MEDIA_TYPE structure, which describes format of the data used. It is a struct member twin of DirectShow AM_MEDIA_TYPE with DMO API management functions Mo*MediaType. For easy and reliable manipulation with this type we will need a ATL/WTL-like wrapper class “template < BOOL t_bManaged > class CDmoMediaTypeT”, which will take care of allocating and freeing the media types.

m_pInputMediaType and m_pOutputMediaType variables will hold media types accepted and agreed for object streams (and thus, filter pins). m_DataCriticalSection is a critical section to ensure thread safe operation.

ProcessInput method will be receiving input buffers for further processing, however this method is not expected to write any outputs. The filter/DMO is expected to pre-process the input and copy save pre-processing outputs in member variables or private buffers. Or instead, the filter can leave a reference to the input buffer and perform the entire processing in the following ProcessOutput call.

Other methods SetInputType, SetOutputType, Flush, Discontinuity and GetInputStatus are also dependent on current input status, so to ease further life we are making CInput class to hold all input data provided with ProcessInput call until required by ProcessOutput and other implementation methods. m_Input member variable will hold latest input buffer.

ProcessOutput is the last method to implement and it has the real data processing. The method is called when both streams/pins are connected, media types agreed and the graph is not stopped. At the moment of the call we should have input data already available through a reference to IMediaBuffer held by m_Input variable and received through ProcessInput call. ProcessOutput is to full output buffer with processed data.

Initially we decided to use YUY2 pixel format for input and output data. The choice of YUV format is stipulated by ease of processing in YUV color space. Brightness and contrast correction affects only Y component of the pixel:

The following equation summarizes the steps described in the previous paragraph. C is the contrast value and B is the brightness value.
Y’ = ((Y – 16) x C) + B + 16

YUY2 format has pixels united into macropixel structure, one macropixel for two horizontally neighboring pixels:

That is, input and output buffers are arrays of macropixels, where we need to update Y component using brightness and contrast correction coefficients. At the very moment we define constant member variables m_nBrightness and m_nContrast and initialize them to predefeined values of -0×0010 and 0×2000 respectively. Let brightness value range be -0x00FF (unbright) through 0x00FF (bright), with a value of 0×0000 leaving original brightness intact. The contrast value range will be 0×0000 (full fade out) through 0xFFFF, with a value of 0×4000 leaving original contrast intact. So taken constants will slightly decrease brightness and apply 50%. contrast reduction. The actual correction for one Y value is performed by function Adjust.

It is important to support non-standard video strides in order to be compatible to Video Mixing Renderer Filter. Video Mixing Renderer Filter can request an image with extended strides by providing respective media type on the output pin of the DMO Wrapper Filter, which is passed to the DMO output stream. ProcessOutput should be prepared to the changed media type and extended strides by checking biWidth field of the BITMAPINFOHEADER structure embedded into media type.

Once the processing is ready, we can easily check the operation using Infinite Pin Tee Filter duplicating video stream into two streams and rendering the first through designed filter and rendering the other (original) stream as is:

Once the graph is started, video renderers pop up their windows:

Source code: DmoBrightnessContrastSample.02.zip (note that Release build binary is included)

Additional notes:

• YUV Formats
• Processing in the 8-bit YUV Color Space
• Brightness and Contrast
• Using the Video Mixing Renderer
• BITMAPINFOHEADER Structure – see Remarks on calculating stride

Continued by:

• Part 3: Persistence, Automation and Property Pages

This post is starting a step by step tutorial on writing a simple DirectShow filter using a simplified DirectX Media Objects (DMO) API. From the very scratch, the goal is to make a DirectShow/DMO video processing filter which implements video brightness and contrast correction.

DirectX Media Objects are COM-based components. To implement a COM object we will use Visual Studio .NET 2008 and Active Template Library (ATL).

We are starting creating a no thrills ATL DLL project following by adding a no thrills ATL Simple Object Class:

The only thing to make sure is to choose “Both” Threading Model since DirectX Media Object must function correctly in a free-threaded environment:

Visual Studio wizard creates a class which implements custom IDispatch-derived dual interface. We will not need it until we get to persistence and property pages.

First of all, we need to reference relevant SDK headers to be able to use DirectShow and DMO API:

#include < dshow.h >
#include < dmo.h >
#include < dmodshow.h >
...
#pragma comment(lib, "strmiids.lib")
#pragma comment(lib, "dmoguids.lib")
#pragma comment(lib, "msdmo.lib")

We reference header files and immediately leave a comment to linker to link library files (to avoid specifying them explicitly in project settings.

From the minimum requirements for every DMO we implemented aggregation (ATL provides implementation by default) and threading model:

Every DMO should meet the following minimum requirements:
- It must support aggregation.
- It must expose the IMediaObject interface.
- The threading model must be ‘both’. DMOs must function correctly in a free-threaded environment.

We yet need to expose IMediaObject interface and add registration code to expose the object/filter to DirectShow-enabled applications and software components. While registration step is not necessary, it still allows visual graph construction with the filter being developed using GraphEdit utility.

To implement IMediaObject, we inherit from it the media object class:

class ATL_NO_VTABLE CBrightnessContrastObject :
    public CComObjectRootEx< CComMultiThreadModel >,
    public CComCoClass< CBrightnessContrastObject, &CLSID_BrightnessContrastObject >,
    public IDispatchImpl< IBrightnessContrastObject >,
    public IMediaObject

then add the interface into COM MAP:

BEGIN_COM_MAP(CBrightnessContrastObject)
    COM_INTERFACE_ENTRY(IMediaObject)

and add IMediaObject methods to the class.

Since IMediaObject contains Lock method, it is confused with CComObjectRootEx‘s Lock and breaks project from compilation. To resolve this ambiguity, we add another method to the media object class:

// CComObjectRootEx
    VOID Lock()
    {
        CComObjectRootEx::Lock();
    }

To enable automatic registration of the media object with DirectShow/DMO infrastructure, we are putting registration as a part of COM registration of the DLL module. This way the object will be automatically exposed to DirectShow software once the DLL is installed and registered with the system.

First of all, we are adding GetObjectFriendlyName method to provide a friendly name for the object, to be used by both ATL to register the class as COM class and the same name will be available to DirectShow software:

static LPCTSTR GetObjectFriendlyName() throw()
{
    return _T("Alax.Info BrightnessContrast Sample");
}

To intercept COM registration and register the object as DMO we are overriding UpdateRegistry method. The implementation for this method is added to th class through DECLARE_REGISTRY_RESOURCEID macro. We comment this out and add implementation for this method explicitly:

Except for default handling through CAtlModule::UpdateRegistryFromResource, we will add calls to our RegisterMediaObject and UnregisterMediaObject functions which in their turn will use DMORegister and DMOUnregister API.

static HRESULT WINAPI UpdateRegistry(BOOL bRegister) throw()
{
    _ATLTRY
    {
        if(!bRegister)
            UnregisterMediaObject();
        ATLASSERT(_pAtlModule);
        _pAtlModule->UpdateRegistryFromResource(IDR_BRIGHTNESSCONTRASTOBJECT, bRegister);
        if(bRegister)
            RegisterMediaObject();
    }
    _ATLCATCH(Exception)
    {
        return Exception;
    }
    return S_OK;
}

Our media object will expose one input and one output stream/pin both with media type MEDIATYPE_Video, MEDIASUBTYPE_YUY2.

Once the project is compiled, COM registration is performed as a part of build task and DMO registration is a subtask. So, the object is already exposed to DirectShow software and applications:

The framework part is done, we are ready to add real implementation for IMediaObject interface and video processing methods.

Source code: DmoBrightnessContrastSample.01.zip

Additional Notes:

• Platform SDK provides IMediaObjectImpl template class (dmoimpl.h) to inherit from instead of IMediaObject, which offer base implementation for IMediaObject interface.
• See also similar tutorial on vnet.uh.edu

Continued by:

• Part 2: Video Processing
• Part 3: Persistence, Automation and Property Pages