Microsoft Windows Visual PC implements virtual machines and the application holds the entire machine state and virtual hard disk information in files. In a few large files in fact, so a question to move and/or backup the files is a question of periodic interest.

So what are the files it is using? First of all, the primary file a user clicks on to start virtual machine is a .VMCX file and it is located in “C:\Users\$(UserName)\Virtual Machines” directory. It is a shortcut to internal files and is holding very basic information about the machine, its state and location of other files.

<?xml version="1.0" encoding="UTF-16"?>
<!-- Microsoft Virtual Machine Description and Registration Settings -->
<vm_description>
    <ram_size type="string">512 MB</ram_size>
    <vmstate type="string">Hibernated</vmstate>
    <primary_disk1 type="string">C:\Users\Roman\AppData\Local\Microsoft\Windows Virtual PC\Virtual Machines\Windows XP Mode.vhd</primary_disk1>
    <secondary_disk1 type="string" />
    <notes type="string">Windows XP Professional in "XP Mode"
Username XPMUser, Password XPM User</notes>
    <vmc_path type="string">C:\Users\Roman\AppData\Local\Microsoft\Windows Virtual PC\Virtual Machines\Windows XP Mode.vmc</vmc_path>
</vm_description>

This directory has a special hidden desktop.ini file in it, which instruct the shell to treat the directory and the files in a special way, as Virtual PC files. This is also how Windows is providing user a link “Create virtual machine”.

The .VMCX file is editable (its format is based on XML) and it holds references to .VHD virtual disk files and .VMC virtual machine configuration files. However, .VMCX file is nothing but a shortcut only, and Windows Virtual PC will re-created those files once underlying .VMC file is double-clicked to be started, so there is no need to edit .VMCX files.

.VMC file is a virtual machine configuration file and it holds the settings a user provides for the virtual machine through settings dialog. The file is also using XML formatting, and is editable. While the file is small itself, its location is used as a base location for .VSV file, where software stores runtime state of virtual machine. The .VSV file size is stipulated by amount of RAM granted to the virtual machine, so the file may be pretty large itself and it might be desired to be moved to another location also. To achieve this, the small .VMC file needs to be moved to location of interest. A .VMC file can be double-clicked itself to start the virtual machine.

.VHD are the large files as they store data from virtual hard disks, so moving them may make sense. Additionally to the files themselves, if “Create Undo Disks” option is enabled, software will manage additional .VUD file with the name of format “VirtualPCUndo_$(VirtualMachineName)_$(Token).vud” file with changes that has not yet been applied. If moved, the .VUD files have to be thought of as a part of .VHD files.

By default a .VMC file holds both absolute and relative path refrences to .VHD and .VUD files, with relative reference as a priority. So if .VMC and .VHD (optionally with .VUD) files are moved together, no special path update/edit required. Software will be able to locate moved disk file automatically as soon as virtual machine is started. Still it is possible to edit the files manually and have files located in different directories. Also if disk file location is modified via GUI, software offers/attempts to strip undo disk .VUD file and cancel unapplied changes. If configuration file is edited manually, it is possible to keep undo disks without canceling the changes.

When moving files to a different location, make sure to check directory security so that Windows Virtual PC has sufficient privileges accessing files in the new location, or otherwise it would show ambiguous error messages “Could not register the virtual machine”.

See Also: Windows Virtual PC Tips on microsoft.com

Media Tools DirectShow Filters can be used to acquire, parse and decoder M-JPEG encoded video stream from an IP camera or a video server, however for a quick start it is necessary to properly register filters on system and create a DirectShow graph.

To register the filters, it is necessary to download DLLs from repository. While Acquisition.dll does not require special prerequisites installed, CodingI.dll is using Intel Integrated Performance Primitives (IPP) version 6.0.0 internally and requires its [at least] redistributables installed before DLLs are being registered using regsvr32.

Intel went further with new releases of IPP, which are incompatible with the version used to build CodingI.dll, so it is version 6.0.0 (in downloads on Intel website: version 6.0 build 0) has to be installed. Note that Intel DLLs from C:\Program Files\Intel\IPP\6.0.0.044\ia32\bin (version 6.0.0.062 is known to be also compatible) need to be on system search path, or copied to C:\Windows\system32 directory.

Once Intel IPP is prepared, it is required to register CodingI.dll using regsvr32. This registers filters and they are available in GraphEdit and for applications. It is important that on the way of constructing graph which renders video using standard video renderers it is required to specify correct resolution for video, or otherwise graph might fail to start with a message “The graph could not change state”, caused by video renderer failure to dynamically change to different (effective) resolution.

To create rendering graph, add Alax.Info HTTP Stream Source Filter from the filter list and provide camera URL in properties, e.g. http://cam15001.miemasu.net/nphMotionJPEG?Kind=1

Add more filters and provide proper resolution for video:

Complete graph construction with resolution set up:

Being run, the graph shows video:

Dynamic handling of resolution selection, configuration and change is also illustrated in sample application RenderHttpMjpegVideo01.

NOTE: The constructed graph .GRF file is available for download.

A simple question being asked all over again. Given IBasicVideo, IBasicVideo2, IVMRWindowlessControl or IVMRWindowlessControl9, how to save image to file? It is easy. It is a bit easier with IBasicVideo because it is possible to query this interface directly from graph’s interface, such as IGraphBuilder, and the call will be forwarded to video renderer. This code assumes internal bitmap format is non-paletted, which I believe is always the case.

LONG nBufferSize = 0;
ATLENSURE_SUCCEEDED(pBasicVideo->GetCurrentImage(&nBufferSize, NULL));
CHeapPtr<BITMAPINFO> pBitmapInfo;
ATLENSURE_THROW(pBitmapInfo.AllocateBytes(nBufferSize), E_OUTOFMEMORY);
ATLENSURE_SUCCEEDED(pBasicVideo->GetCurrentImage(&nBufferSize, (LONG*) (BITMAPINFO*) pBitmapInfo));
const BYTE* pnData = (const BYTE*) (&pBitmapInfo->bmiHeader + 1);
// NOTE: You might wish to handle <=8 bpp bitmaps here
ATLASSERT(pBitmapInfo->bmiHeader.biBitCount > 8);
ATLASSERT(pBitmapInfo->bmiHeader.biCompression == BI_RGB);
ATLASSERT(pBitmapInfo->bmiHeader.biSizeImage);
BITMAPFILEHEADER BitmapFileHeader;
ZeroMemory(&BitmapFileHeader, sizeof BitmapFileHeader);
BitmapFileHeader.bfType = 'MB';
BitmapFileHeader.bfSize = (DWORD) (sizeof (BITMAPFILEHEADER) + pBitmapInfo->bmiHeader.biSize + pBitmapInfo->bmiHeader.biSizeImage);
BitmapFileHeader.bfOffBits = (DWORD) (sizeof (BITMAPFILEHEADER) + pBitmapInfo->bmiHeader.biSize);
ATLENSURE_SUCCEEDED(File.Write(&BitmapFileHeader, sizeof BitmapFileHeader));
ATLENSURE_SUCCEEDED(File.Write(&pBitmapInfo->bmiHeader, pBitmapInfo->bmiHeader.biSize));
ATLENSURE_SUCCEEDED(File.Write(pnData, (DWORD) pBitmapInfo->bmiHeader.biSizeImage));

ATL regular expression code adds dump/debug capabilities with ATL_REGEXP_DUMP preprocessor definition defined (undocumented). Dump output is directed to stdout, so if the application is not console, it has to be redirected in advance, e.g. into a $(BinaryPath)$(BinaryName)-atlrx.h file.

	CAtlRegExp<> Expression; LPCTSTR pszPattern; BOOL bCaseSensitive;
#if defined(ATL_REGEXP_DUMP)
	REParseError Error = Expression.Parse(pszPattern, bCaseSensitive);
	if(Error != REPARSE_ERROR_OK)
	{
		FILE* pStream = NULL;
		if(!GetStdHandle(STD_OUTPUT_HANDLE))
		{
			TCHAR pszPath[MAX_PATH] = { 0 };
			ATLVERIFY(GetModuleFileName(_AtlBaseModule.GetModuleInstance(), pszPath, _countof(pszPath)));
			RemoveExtension(pszPath); // ATLPath::
			_tcscat_s(pszPath, _countof(pszPath), _T("-atlrx.txt"));
			ATLVERIFY(freopen_s(&pStream, CStringA(pszPath), "w", stdout) == 0);
		}
		_tprintf(_T("Error %d\n"), Error);
		Expression.Dump();
		if(pStream)
			ATLVERIFY(fclose(pStream) == 0);
		ATLASSERT(FALSE); // Break into debugger
	}
#else
	ATLVERIFY(Expression.Parse(pszPattern, bCaseSensitive) == REPARSE_ERROR_OK);
#endif // defined(ATL_REGEXP_DUMP)

There is also ATLRX_DEBUG definition, which enables other debug capabilities. CAtlRegExp object is given a virtual function OnDebugEvent through which it prints comments on CAtlRegExp::Match process, which can be also redirected to file similar way.

Given a DirectShow filter graph, what media samples are being sent through particular graph point? DumpMediaSamples utility gives a fast answer to this question. It prints out connection media type details (with details of VIDEOINFOHEADER, VIDEOINFOHEADER2 and WAVEFORMATEX structures corresponding to FORMAT_VideoInfo, FORMAT_VideoInfo2 and FORMAT_WaveFormatEx format types) and IMediaSample details obtained through AM_SAMPLE2_PROPERTIES structure. First of all, it is necessary to create a graph of interest using GraphEdit utility. At the point of interest it is necessary to insert [an uninitialized] Sample Grabber Filter with the filter name “SampleGrabber” (this is the default name but if you add second filter which will be given a different name and remove first filter then, the utility would fail). The graph may look like this:

Save the graph into a file and start utility providing filter graph path as a command line argument. The utility will load the graph, locate the inserted Sample Grabber Filter and run the graph. Any sample passing through will be printed:

Microsoft Windows XP [Version 5.1.2600]
(C) Copyright 1985-2001 Microsoft Corp.

C:\>DumpMediaSamples Test.grf
Media Type:

majortype {73646976-0000-0010-8000-00AA00389B71}, subtype {44495658-0000-0010-8000-00AA00389B71}, pUnk 0x00000000
bFixedSizeSamples 1, bTemporalCompression 0, lSampleSize 23443
formattype {05589F80-C356-11CE-BF01-00AA0055595A}, cbFormat 88, pbFormat 0x0017a7b0
pbFormat as VIDEOINFOHEADER:
  rcSource { 0, 0, 0, 0 ), rcTarget { 0, 0, 0, 0 }
  dwBitRate 372125, dwBitErrorRate 0, AvgTimePerFrame 400,000.00
  bmiHeader.biSize 40, bmiHeader.biWidth 400, bmiHeader.biHeight 320, bmiHeader.biPlanes 1, bmiHeader.biBitCount 16, bmiHeader.biCom
pression XVID
  bmiHeader.biSizeImage 768000, bmiHeader.biXPelsPerMeter 0, bmiHeader.biYPelsPerMeter 0, bmiHeader.biClrUsed 0, bmiHeader.biClrImpo
rtant 0

Media Samples:

fSampleTime 0.000, .dwTypeSpecificFlags 0x00000000, .dwSampleFlags 0x00000115, .tStart 000000000, .tStop 000400000, .dwStreamId 0
.cbBuffer 23443, .lActual 15621, pbBuffer 00 00 01 B0 F5 00 00 01 B5 09 00 00 01 00 00 00 01 20 08 86 84 00 67 0C 32 10 A0 51 8F 00 00 01 B2 44 69 76 58 35 30 33 62 31 33 39 33 70 00 00

fSampleTime 0.040, .dwTypeSpecificFlags 0x00000000, .dwSampleFlags 0x00000110, .tStart 000400000, .tStop 000800000, .dwStreamId 0
.cbBuffer 23443, .lActual 1, pbBuffer 7F

fSampleTime 0.080, .dwTypeSpecificFlags 0x00000000, .dwSampleFlags 0x00000110, .tStart 000800000, .tStop 001200000, .dwStreamId 0
.cbBuffer 23443, .lActual 1, pbBuffer 7F

A pre-built binary (Win32) and reference Visual C++ project source code (will require additional headers to compile) are 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
  

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