DfMirage SDK v1.2 Developer’s Guide

DfMirage SDK v1.2 Developer’s Guide

Introduction DfMirage is “cutting edge" video driver mirroring technology for the Windows NT OS family. It is a driver for a virtual video device managed at the DDML level of the graphics system that exactly mirrors the drawing operations of one or more physical display devices. A detailed explanation of how a mirroring video driver works may be found in the Windows DDK. Display mirroring technology is widely employed by remote desktop applications such as: NetMeeting, PC Anywhere, VNC, Webex, etc. Mirroring is a technically superior method when compared to primitive primitive screen grabbing, grabbing, because because it allows the capture capture of only the minimally minimally updated regions and retrieves the data directly, bypassing the intermediate copy. Using the DfMirage driver solves the problem of reliably and efficiently detecting modified areas on the screen. This driver may be used transparently with office, CAD and other types of business and utility applications. An example is the open-source TightVNC application which uses the DfMirage driver with great success.

Operating environment and setup The DfMirage driver is targeted to the Microsoft Windows NT OS family, which includes Windows NT4, Windows 2000, Windows XP/2003 and future versions of Windows as well. It has been tested on Windows 2000 service packs 0-4, and Windows XP service packs 1 and 2. Windows NT4 service pack 6 is also supported (driver package available upon request).

Installation To setup the DfMirage driver, run MirageSetup.exe. The underlying virtual display device uses plug-n-play technology, so the installation requires no reboot. When the driver is installed, it appears in device manager as shown in the following picture: http://www.demoforge.com/support/dfmirror-devmgr.png To ensure that the installation was successfull run dfstudio-mirage.exe (this is a special build of DemoForge Studio 2 which uses DfMirage driver internally) and the press the Record button. You may then locate the file just recorded in your %TEMP% folder. This file may be played back. It is rather large because it contains only raw, uncompressed data. If you compress it using any modern archival software, you will see a considerable difference in size. You may also save the recorded file to DML format to see the image data which has been captured by the mirage driver.

Uninstallation The uninst uninstall allatio ation n of DfMirag DfMiragee is fully fully suppor supported ted.. The uninst uninstall aller er is regist registere ered d with with the “Add/Remove Programs” applet of Control Panel. Removing the device is a two-phase process. This is due to shortcomings within the Windows system video port driver. Microsoft has promised to resolve this issue with the release of Windows Vista. When the first phase is finished, the system must be rebooted. The 2nd phase will automatically begin following the reboot, when any member of the local Administrators group logs in. For a more detailed explanation of DfMirage setup considerations see the file “Mirage\Setup\Installer\Guide.en.doc”.

Operating principles The DfMirage driver tracks the minimal areas of screen update and enables the client software to retrieve those updates directly (by means of the screen memory shared between the driver and application). This method provides excellent results in terms of traffic and CPU usage, while still maintaining its ease of use features. The Mirror driver follows the standard bi-component model

The world’s largest digital library

Try Scribd FREE for 30 days to access over 125 million titles without ads or interruptions! Start Free Trial Cancel Anytime.





of NT video drivers. That is, it uses miniport and display driver modules. Miniport is a low-level component. It represents a virtual video device. It is loaded by the OS IO manager and remains in memory until the OS is terminated. The miniport device is inaccessible to user-mode code. The display driver is loaded and unloaded on demand by changes in video mode. Basically, when it is loaded and running, video mirroring takes place. The DfMirage driver maps its screen surface into the user-mode application’s virtual memory space. Normally, the format and size of the buffer corresponds exactly to the format and size of the primary screen surface. This is not the case when its color format is overridden – (there is available, a registry-based switch for the driver to enforce the fixed color depth of the mirrored screen surface). The mapping of memory is performed via a file mapping object (or a “Section” using NT kernel slang). In this way an application “ sees” everything that’s being drawn on the mirrored screen surface, resulting in the application’s ability to perform a direct copy of the modified screen area. It has but read-only access to this buffer. The driver provides an application with the ability to retrieve ONLY those areas, which are modified, modified, in spite of this, the entire screen buffer is always available to the application application for read access. The user-m user-mode ode applic applicati ation on commun communicat icates es with with the DfMirag DfMiragee driver driver via the ExtEscape() Windows Windows API function. function. ExtEscape serv serves es the the role role of an exte extens nsib ible le escap escapee hatch hatch for for the the Windows GDI as it allows the passing of custom or non-standard requests to the video driver. There are a number of private escape codes defined by DfMirage. Escape function codes and input/output structures are declared in display-esc.h (This is an interface header shared among the driver and application code modules).

The API Following is a brief description of this API:

ESCAPE CODE: INPUT: OUTPUT: FUNCTION: process. RETURN VALUES: VALUES:

dmf_esc_usm_pipe_map

None struct GETCHANGESBUF GETCHANGESBUF

Creates a mirror screen and updates queue mappings for the calling If the function succeeds, the return value is greater than zero.

The buffers are mapped upon receiving this escape request. The output buffer format for the request is GETCHANGESBUF. GETCHANGESBUF::Userbuffer is actually a pointer to the mirror mirror screen screen surface surface view. view. GETCHANGESBUF::buffer poin points ts to the the queu queuee of modi modifie fied d rectangles. The screen surface is “top to bottom, so the 1st line of pixels in the screen surface commences with the 1st byte of screen memory. For example, you can address the 2nd line of pixels by adding a fixed positive value (stride, also known as a pitch or delta) to the address of the 1st line. The userbuffer value actually points to the line 0. Surface dimensions correspond to the dimensions of the primary display. The stride of the surface is DWORD-aligned upwards. (The stride is calculated as follows: (screen_width*(screen_bits_per_pel>>3)+3)&-4.) ESCAPE CODE: INPUT:

dmf_esc_usm_pipe_unmap struct GETCHANGESBUF GETCHANGESBUF





There is a reciprocal unmap API - dmf_esc_usm_pipe_unmap. It is recommended that this API be used to terminate the capture under normal conditions. Under abnormal conditions it is best to unmap the shared memory buffe ffers by calling UnmapViewOfFile(). The dmf_esc_usm_pipe_unmap/UnmapViewOfFile() call should always be accompanied by the DeleteDC() call for a previously-obtained mirror-device DC to release an instance of the driver. (NOTE: this function is new, available in driver version 1.1+ ) dmf_esc_qry_ver_info ESCAPE CODE: INPUT: struct Esc_dmf_Qvi_IN struct Esc_dmf_Qvi_OUT OUTPUT: FUNCTION: Queries for driver’s version and determines if driver and application versions are compatible. RETURN VALUES: VALUES: If the function succeeds, the return value is greater than zero. If the function succeeds, this means that driver and application are version compatible.

In Esc_dmf_Qvi_IN application passes it’s version information. See dmf-proto-version.h: set to and Esc_dmf_Qvi_IN:: app_actual_version DMF_PROTO_VER_CURRENT , Esc_dmf_Qvi_IN:: display_minreq_ver display_minreq_version sion to DMF_PROTO_VER_MINCOMPAT version number constants from SDK version it was built with. In Esc_dmf_Qvi_OUT driver returns information about its version. Esc_dmf_Qvi_OUT:: display_actual_version is the driver’s app_minreq_version is a minimum application version version number. Esc_dmf_Qvi_OUT:: app_minreq_version number which is supported by the driver. CHANGES_BUF is a circular queue of modified rect records (CHANGES_RECORD ) (the current

capacity setting is 20,000 records, which is normally far more than enough). The structure is defined as follows: struct CHANGES_RECORD CHANGES_RECORD { ULONG type; RECT rect; RECT origrect; origrect; POINTpoint; ULONG color; ULONG refcolor; };

This definition is governed by historical reasons (legacy software compatibility). Not all fields in this structure are actually used with Mirage driver. CHANGES_RECORD:: CHANGES_RECORD:: type takes the following values: typedef enum { dmf_ dmf_d dfo_S fo_SCR CREE EEN_ N_SC SCRE REEN EN = 11 11,, dmf_dfo_BLIT = 12, dmf_dfo_TEXTOUT = 18, dmf_ dmf_d dfo_P fo_Ptr tr_E _Eng ngag age e = 48 48,, dmf_d f_dfo_ fo_Ptr_ tr_Avert = 49, dmf_d f_dfn_ fn_asse ssert_on = 64, dmf_d f_dfn_ fn_asse ssert_off off = 65, }





hides hides the pointe pointerr from screen screen.. Pointe Pointerr coordi coordinat nates es go throug through h CHANGES_RECORD::point field. Records dmf_dfn_assert_on and dmf_dfn_assert_off noti notify fy the the appl applic icati ation on abou aboutt the the driver’s status. results dmf_dfo_BLIT event is the most common update event type. dmf_dfo_TEXTOUT is results from text output. dmf_dfo_SCREEN_SCREEN is a screen-to-screen copy BitBlt . Applications should disregard origrect , color , refcolor fields. All update types (range dmf_dfo_SCREEN_SC dmf_dfo_SCREEN_SCREEN.. REEN.. dmf_dfo_TEXTOUT ) may ultimately be treat treated ed as BitBlt . The only rele elevant ant and valid field of CHANGES_RECORD is then then CHANGES_RECORD::rect . It is the screen destination update rectangle (a rectangular boundary of an actual update region) of the above-mentioned graphic operations. dmf_dfo_SCREEN_SCREEN event type is supported in Mirage driver version 1.2+. To allow this new event type it must be enabled (see below). dmf_dfo_SCREEN_SCREEN may be used

as an additional optimization option (it may be useful in cases of window drag, scroll, etc.) In addition to CHANGES_RECORD::rect it has valid CHANGES_RECORD::point field – the source point of screen copy c opy operation. The screen of Mirage driver is not divided into a fixed set of predefined rectangles. The update rectangles are placed, sized and ordered exactly in the same manner that the underlying graphic operations were. The update rect coordinates are relative to the driver’s attach point on the desktop. If the driver is attached at (0, 0) (as usual), rects are in a desktop coordinate space. The head of the buffer is moved moved cyclic cyclically ally forward forward when when a newly-m newly-modi odified fied rect arrives arrives (the (the queue queue consta constantl ntly y wraps wraps through its end to the beginning). There is an ever-increasing counter of records: The ULONG Using g this this coun counter ter,, one one may may dete determ rmin inee whet whethe herr ther theree are any any CHANGES_BUF::counter . Usin newly-modi newly-modified fied rects available. When the application application detects the newly-modi newly-modified fied rectangles, rectangles, it has an opportunity to retrieve those rectangles directly from the mapped screen buffer memory. The application then makes copies of these modified rects and performs the required process on them (for example, sending them over wire). If an application detects that it has lost one or more modified rects, (possible when the system is sorely over-taxed) nothing is really broken. The application should simply skip any unprocessed rects and then perform an update of the entire screen . The entire contents of the modified modified rects buffer is available for read from the application at any time. It is important to understand understand that shared memory memory structures structures remain available to the application application despite any change to the video mode when the driver is unloaded completely or just disabled temporarily. The shared memory objects are managed by 2 references: from the driver and from the application. These are unavailable when, and only when, both the driver and application release them. This is by design, design, to ensure ensure reliability in the case of an unexpected unexpected disconnection disconnection with with the the clie client nt appl applic icati ation on.. This This is why why it is impo importa rtant nt to perfo perform rm the the clean cleanup up befo before re reconnection. To start working with the driver, the application must first activate it. The driver is set to enabled (“Attach.ToDesktop” value in system registry). The video mode change is then performed and the new activation setting for the driver takes effect.





While there is no technical limit on the number of applications which may simultaneously read the mirror screen, only one of them them should attempt to manage the driver. The Mirage driver has a boot-time checker that ensures that the driver is deactivated even when the managing application has failed to deactivate it (for example, when the application has crashed). The driver is never loaded (and can’t be activated) in the Safe (or VGA) boot mode of Windows.

Options There are some registry-based switches that affect the driver’s behavior. All switches are derived from the values located in one of the following registry keys: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\dfmirage\Device0] or [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\dfmirage\Device0] [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Hardware [HKEY_LOCAL_MACHINE\S YSTEM\CurrentControlSet\Hardware Profiles\Current\ System\CurrentControlSet\SERVICES\dfmirage\DEVICE0] These supported switches are: “Pointer.Enabled”=dword: 0 (default) or 1. First First (simpl (simple) e) mode mode (Point (Pointer. er.Ena Enable bled=1 d=1)) just just render renderss the mouse mouse pointe pointerr moveme movements nts and ani animati ation and produces only simple update event ents from rom these. Second mode (Pointer.Enabled=0) excludes the mouse from the screen buffer, posting only position and status events. There are 2 types of events that bypass the “update buffer” regarding the mouse pointer capture: 48 (dmf_dfo_Ptr_Engage): show the pointer (cursor) [in a position specified] 49 (dmf_dfo_Ptr_Avert ): ): hide the pointer. • The current pointer shape is queried via a special call. An application can disable mouse pointer rendering if it wants to draw it on its own. •

“Screen.ForcedBpp”=dword: 0 (default), 16, 24 or 32. This switch forces the mirror screen color depth. 0 enables the native color depth of a primary display device to be used for a mirror screen. There are 3 valid values of color depth that may be enforced – 16, 24 and 32 bits per pixel. No values other than 0, 16, 24 and 32 are allowed. NOTE that 16 bits per pixel forced color depth option is available only in driver version 1.2+. Colo Colorr dept depth h enfo enforce rceme ment nt may may some someti time mess be usef useful ul.. Thro Throug ugh h the the use use of this this feat featur ure, e, an application may implement only true color encoding, resulting in its not having to deal with palettes or worry about color depth switching. Nevertheless, it should still be noted that native 8 bit or 16-bit screen images are more compact. “Cap.DfbBackingMode”=dword: 0, 2, or 3 (default). This is the powerful switch of screen memory backing mode. Backing mode 3 (the default and recommended option) results in an “opaque” mirror screen. That is -- a screen that cannot be accessed by GDI directly. This means nothing drawn on the mirror screen escapes the notice of the driver. This option guarantees the maximum mirroring consistency possible in the Windows GDI.





rendering is performed. The driver in this mode only collects update regions. This mode may be useful for applications that bypass the driver when retrieving the screen image. Backing mode 2 is somewhat experimental. The mirror screen is transparent to the GDI in this mode. Rendering is on and screen image is acce ssible. When the screen is transparent, the GDI is not always always accura accurate te when when using using the driver driver’s ’s hooks hooks to perfor perform m the render rendering ing,, and screen screen mirroring consistency may become compromised under certain circumstances. Still, some customers claim that certain graphic-intensive applications such as video players perform significantly faster in this mode. This mode is not recommended unless you know exactly what you’re doing. The following options are new to Mirage driver version 1.2+: “Order.BltCopyBits.Enabled” = dword: 0 (default) or 1. Enables or disables generation of dmf_dfo_SCREEN_SCREEN update events in case of screen2-screen BitBlt . “Cap.Bootup” = dword: 0 (default), 1 or 2. Controls “boot-time checker” which normally checks if the driver is unintentionally attached to screen screen during during the syste system m boot boot and disabl disables es the attach attachmen ment. t. Value Value 0 corres correspon ponds ds to usual usual behavior. Value 1 enables for 1-time (this boot only) driver attach from system boot. Value 2 (and higher) suppresses the check at all, thus the driver will always be attached to screen right from the system startup. This switch is generally useless with modern (Windows 2000+) OSes because applications should load and unload the driver dynamically. If it is anyway needed (for instance, on NT4), use it with caution.

Performance considerations Screen grabbing with the DfMirage driver is as simple as performing a direct memory copy of the modifications modifications made to the framebuffer. framebuffer. The driver provides direct read access to the screen framebuffer for the client application. The DfMirage driver enables a far more efficient screen capture method when compared to the usual way of blitting from the screen DC. Using BitBlt from the screen requires at least one syscall ( BitBlt ), ), a global screen update lock performed internally by BitBlt plus an extra memory copy operation. The DfMirage driver requires no syscalls or screen locks. In principle, you can grab the screen, or any part of it when you need or want to, resulting in flexible performance and instant on-the-fly tuning, for example, to accommodate high-stress conditions). The application receives prompt notifications of regions which have been modified, but they may be allowed to accumulate if the updates are occurring faster than desired. They also may be accumulated for short periods simply to minimize the traffic. You are not compelled to keep up with the real screen video driver, but you can. It is very flexible. Updates are often small, such as those resulting from a single mouse pointer motion. The application only needs to grab and update the small area behind the pointer. In this case there is very little CPU consumption. But from time to time of course, there will be major updates which







VNC applications typically prefer to accumulate the modifications every, 100 ms or so or even for a longer period. It may simply use a 100ms timer and process all of the modifications discovered (which may overlap each other) at once. The poll scenario therefore, requires no dire direct ct inte intera racti ction on with with the the driv driver er at all. all. Now Now imag imagin inee the the extr extrem emely ely taxi taxing ng dema demand ndss of synchronous notification when an event object is used. The application is interrupted for every single update! For example, a mere mouse pointer motion may produce tens or even hundreds of events per second. More importantly, each update event must be individually confirmed to reset the raised notification event object. This is rarely considered desirable behavior! Note that we now have an extra confirmation “syscall” from the application to the driver. This may introduce notable notable latency under high load condition conditions. s. This also makes it more difficult to accumulate accumulate the updates. According to our own observations, we have concluded that the poll method is typically more CPU efficient than event-based synchronization whether under low or high load conditions. If there is someone who would like to test the method, an event-based sync (with the ability to accumulate the confirmations) may be implemented upon customer request. CPU consumpt consumption ion of the client client applic applicati ation on can result result from either either of two things. things. First, First, the rendering (or mirroring) of the graphics commands in the mirrored framebuffer (which takes place in the driver). This is always commensurate with the same CPU consumption in the real screen video driver. Graphics acceleration for the DfMirage driver are managed by the Windows graphics engine. The driver, with the assistance of Windows, renders the complete image to the framebu framebuffer ffer surfac surface, e, thus thus minimi minimizin zing g CPU consum consumpti ption. on. Second Second,, (this (this takes takes place place in the application itself,) the overhead of copying of and sending/storing the updates. It depends on the application whether it does data processing, compression, etc. This technology may certainly be used for VNC applications, even on older machines (in fact, the performance of a slow machine will greatly depend on the data compression and network operation).

Known problems When the video mirroring driver is active, all DirectDraw capabilities of the system are temporarily disabled. DirectDraw applications, especially full-screen 3D games are affected by this. It is a known problem of all mirror drivers, due to DirectDraw DDI’s design which did not have mirror drivers in mind at design-time. In spite of this, most office DirectDraw applications (including Windows Media Player) are able to work with the driver in a manner similar to their operation in Terminal Server sessions, with NetMeeting, or other remote desktop systems. When DfMirage is not runnin running g (i.e. (i.e. the driver driver is unload unloaded) ed) Direct DirectDraw Draw capabi capabiliti lities es are fully fully availab available. le. We have have





case, the driver will simply refuse to load. (The ChangeDisplaySettingsEx() call will fail with the DISP_CHANGE_BADMODE code). The solution recommended by Microsoft (hiding a list of unsupported video modes) does not work with PowerStrip at all. In fact, PowerStrip is driven crazy by it. This is a problem common to all mirror drivers. A universal solution is currently under development. A change of Video mode, especially when the display resolution or color depth is changed will likely result in the DfMirage driver being reloaded. This is normal and is by design of the Windows NT graphics system. An application may examine the stream of events it receives for the dmf_dfn_assert_off event. This event appears when the driver is deactivated unexpectedly. It usually indicates a change of video mode. When the driver is deactivated, it terminates the capture and begins preparation for unload. The driver is not aware whether the deactivation is temporary or permanent, so it errs on the side of preparing for the permanent scenario. When the application detects this situation, it should clean up the memory mapping (as usual) and simply reconnect the driver again (i.e., unmap --> DeleteDC --> CreateDC --> map). Changing to fullscreen text mode (for example, a DOS box) will cause the driver (as well as hardware video drivers) to be suspended. The driver is restored as soon as this mode is terminated. In principle, an application may treat this situation as a general video mode change. We have plans to implement a solution similar to the one from Terminal Server, by simply disabling fullscreen text mode (subject to the user’s preference, of course).

The Project’s files and tree structure The SDK contains a complete driver setup package (a single exe) as well as a set of separate driver files: dfmirage.sys -- miniport driver binary dfmirage.dll -- display driver binary dfmirage.inf -- setup INF file for the driver Our installer/uninstaller for mirror drivers is also included: MirrInst.exe (the source code may be included depending on the terms of license).

•

The SDK also includes: •

the driver developer’s guide (this document),





\Client – this is the user-mode driver API, driver control sample code, and a special build of DfStudio for the DfMirage driver \Mirage – these are driver components: \Mirage\MirageMini – contains the miniport driver, \Mirage\MirageDisplay – the display driver that communicates with the kernel graphic engine and the client application, \Mir \Mirag age\ e\Se Setu tup p - setu setup p engi engine ne dll dll usag usagee samp sample les. s. See See a brie brieff desc descri ript ptio ion n in the the file file Mirage\Setup\Installer\Guide.en.doc. \Mirror \MirrorIns Instal taller ler - our uninst uninstall aller er engine engine (coden (codename amed d KZhwdi KZhwdi)) and a simple simple setup setup utilit utility y (MirrInstExe) just for the video drivers. Windows 2000 or XP DDK headers and libraries are required to build the driver. The following tools are used to build the entire project: •

•

MSFT Visual C++ .NET 7.1 (MSFT Visual C++ 6.0 compiler or the Windows XP DDK (2600) compiler also may be used), InnoSetup installer (version 4 or later).

The client samples (driver management code) are in C/C++ and Object Pascal languages, but this code can easily be adapted for C# or other modern platform. platform.

Frequently asked questions Q1: Need I do any mutex locking/thread synchronization with the mirror driver, or do I just read direct out of CHANGESBUF? Won't that lead to race conditions? In first, let’s consider a race condition with CHANGESBUF itself. You get the actual sequence number number (let’s call it N1) of the last update. This operation operation is atomic and you only get a number number less or equal to the actual (most recent) number. Then you just process records from N0+1 up to N1, where N0 is your previous record sequence counter (N1 from the previous pass turns to N0 on the next pass). In theory, here you may detect if you had lost the track of the changes. Say, there is more than MAXCHANGES_BUF/2 since the last update. Then you simply discard any update update records records and repost the entire screen without any harm except for possibly added excess traffic. Note that fatal lag behind occurs only under the hardest stress conditions since buffer capacity (MAXCHANGES_BUF) is large enough. Most products that use Mirage driver simply





1. Application processes the rect R1 for update N, but there already is another update M>N which overlaps R1. Nothing is wrong. The same already correct image for rect R1 will be simply transferred twice. This happens from time to time. 2. Application processes the rect R1 for update N, and in the same time driver renders another update M>N which overlaps R1. The update is not completed when application grabs the image. Again nothing nothing is particularly particularly bad. Incomplete Incomplete image will be posted posted for R1. And then promptly will be posted the complete image. This artifact occurs rarely and as a rule comes unnoticed at all (being perceived normally as a stage of developing the resulting image as it really is). So out of sync state, if only it appears, occurs in the application's view of the screen and is trans transie ient nt by natu nature. re. When When a seri series es of upda update tess is fini finish shed ed and and comp comple lete tely ly proc proces esse sed d by application, there is always a perfect sync.

Q2: In 16 bit per pixel mode my captured screen colors appear corrupt. Mirage driver always uses the same bitmasks for 16 bit color mode, known as 565 format color mask. Most likely, your application tries to interpret the Mirage screen in 555 color mask. Please set the correct bitmasks explicitly. 565 color format has the following masks: RED: 0xf800 GREEN: 0x07e0 BLUE: 0x001f, whereas 555 color format has these masks: RED: 0x7c00 GREEN: 0x03e0 BLUE: 0x001f.

Q3: What happens should my application suddenly crash while working with driver. When application dies preliminarily, the driver disconnects from application, and the shared memory view is released by Windows memory manager. Though, the driver remains loaded. It will stay loaded until another application stops/reloads it or until system shutdown. Driver that is loaded by one application (and is not connected to it now) is usable by another application, and even has not to be reloaded. Though, reload may be useful in order to activate different settings.

DfMirage SDK v1.2 Developer’s Guide

Recommend Documents