a few extra comments for MSVC 2008 (or prior) projects.

updated fail guard explanation and performance tests included an additional usage hint (regarding yielding the rendering thread after each frame draw).

Signed-off-by: Marcos Paulo Berteli Slomp <[email protected]>

Author: slomp

platform/windows/README.TXT

@@ -5,7 +5,7 @@ SUMMARY
 
 1) libfreenect: incompatibilities with Visual C++
    This section is here merely for historical reasons. All of the issues documented
-   there were already fixed in the libfreenect repository and CMake should be able to
+   here were already fixed in the libfreenect repository and CMake should be able to
    produce a project that is ready to build libfreenect in Windows with Visual Studio.
    Consider browsing this section if experiencing compilation issues under different
    platforms, compilers and/or IDEs.
@@ -15,7 +15,7 @@ SUMMARY
    a proper port of libusb-1.0 for Windows is not yet available. Such emulation layer
    allows Windows development to keep in sync with the official development branch of
    libfreenect, without the need of dedicated drivers/implementations. This section
-   discusses how and why the current libfreenect Windows port moved in this direction.
+   discusses why and how the current libfreenect Windows port moved in this direction.
 
 3) libusbemu: Tips, Hints and Best Practices
    The current status of libusbemu is quite reliable under normal usage circumstances,
@@ -40,8 +40,8 @@ Language issues: The Microsoft C compiler does not implement all the C99 standar
 ----------------------------------------------------------------------------------
 
 An attempt to compile the current libfreenect with Visual C++ will trigger a lot
-of errors. A simple workaround is to tell Visual Studio to force compilation all .c
-files within the project using the C++ compiler:
+of errors. A simple workaround is to tell Visual Studio to force compilation all the
+".c" files within the project using the C++ compiler:
   Project >> Properties >> C/C++ >> Advanced >> Compile As: Compile as C++ Code (/TP)
 
 This will get rid of most errors, except those regarding implicit pointer casts.
@@ -168,36 +168,22 @@ libusbemu exists.
 3) libusbemu: Tips, Hints and Best Practices
    *****************************************
 
-----------------------------------------------------------------------------
-TIP: Configure your project to build your application with a console window!
-----------------------------------------------------------------------------
+---------------------------------------------------------------
+TIP: Trigger the Fail Guard if the system becomes unresponsive.
+---------------------------------------------------------------
 
-Since libusbemu is quite experimental, There is a fail guard within it. If for some
-reason your system renders unresponsive, try to focus the console window of your
-application and press [ESC].
+Since libusbemu is quite experimental, there is a fail guard within it. If for some
+reason your system renders unresponsive, try focusing any window of the application
+and hold [CTRL] + [ALT] for a while.
 
 This will trigger a special synchronization event within the libusbemu which will
 interrupt the execution of any internal thread of libusbemu and prompt a message box
 to the user asking for action. You can either resume execution (if you unintentionally
-pressed [ESC] in the console window) or abort the libusbemu. The recent fixes in the
-libusbemu don not seem to be causing any unresponsiveness, but is hard to assert...
+pressed [CTRL] + [ALT] in the console window) or abort libusbemu. The fail guard will
+never trigger if there is no incoming video or depth streams.
 
-Note that this key check will only have effect if the console window is focused. The
-application is still free to capture the [ESC] key normally within the application
-window (unless the application window happens to be the console, but then it is very
-likely that no stream is being captured and no call to freenect_process_events() is
-being made, thus preventing the fail guard to be ever trigged).
-
---------------------------------------------------
-TIP: Do not change the default state of libusbemu.
---------------------------------------------------
-
-The default libusbemu setup embraces the best performance currently found so far:
-multi-threaded stream reaping.
-
-If one feels curious/adventurous, the USB isochronous reap strategy can be modified
-within the emulator code but don't expect good results; the default ReapThreaded()
-strategy is the most reliable and stable, while the others are very experimental.
+The Fail Guard is important since in such situations one would most likely be forced
+to shutdown the computer (in a not so graceful way, by holding the power button!).
 
 ----------------------------------------
 TIP: Only use a single freenect context.
@@ -206,6 +192,23 @@ TIP: Only use a single freenect context.
 Multiple freenect contexts should be no problem in the future. Having more than one
 device attached to the same context should work fine, but no tests were made so far.
 
+-----------------------------------------------------
+TIP: Yield the rendering thread after each iteration.
+-----------------------------------------------------
+
+In case your application performs direct rendering (OpenGL, Direct3D), it is highly
+recommended to yield the rendering thread after finishing rendering each frame. This
+can alleviate a lot of CPU usage. The ideal place for this yield is right after the
+swap-buffers call (SwapBuffers(), glutSwapBuffers(), Present(), etc). The best way to
+yield is by calling Sleep(1). Note that Sleep(0) is also possible, but the former is
+more "democratic".
+
+Note that some graphics drivers or platforms may already yield after swap-buffers.
+This seems to be the case with OpenGL NVIDIA drivers for Linux. In Windows, however,
+the same driver (version) does not yield. Maybe in Linux the "yielder" is not the
+driver itself, but the underlying implementation of glXSwapBuffers()... Anyway, when
+in doubt, it will not hurt to explicitly yield again.
+
 --------------------------------------------------------------------------------------
 TIP: Perform stream operations only in the thread that calls freenect_process_events()
 --------------------------------------------------------------------------------------
@@ -242,77 +245,84 @@ and if such behavior is really to be expected is a hard task to determine.
 4) Overall performance of libfreenect in Windows
    *********************************************
 
+---------------------------------------------
+THIS SECTION IS OUTDATED, GOTTA REDO IT SOON!
+---------------------------------------------
+
 Hardware:
 * Notebook 
 * CPU: Intel Core2 Duo 32bit [T7250] @ 2.0GHz
 * RAM: 4GB RAM
 * GPU: GeForce 8600M GT 256MB VRAM
 
+
+
 Task: display of simultaneous RGB (Bayer-to-RGB) and depth streams (16bit unpadded) on
 the screen through OpenGL textures. Application source code is identical for all tests
 (except for the Zephod's version that required some interface adaptation).
 
-The performance results below refer to the average frame time (one loop iteration).
 
-Linux: Ubuntu Notebook 10.10
-* compiler: gcc 4.4.5
-* time measured via POSIX gettime()
-  * Debug:   1.22ms (libfreenect also built in debug mode)
-  * Release: 1.15ms
 
-Win32: Windows 7 Enterprise 32bit
+Results: performance measurements refer to the average frame time (one loop iteration).
+
+Linux: Ubuntu Notebook 10.10 -- gcc 4.4.5
+* Debug:   1.22ms | CPU @ 77% | video @ 30Hz | depth @ 30Hz
+* Release: 1.15ms | CPU @ 72% | video @ 30Hz | depth @ 30Hz
+
+Win32: Windows 7 Enterprise 32bit -- VC++ (Professional) 2010
 1) libfreenect with libusbemu:
-   * compiler: VC++ 2010
-   * time measured via QueryPerformanceFrequency() / QueryPerformanceCounter()
-     * Debug:   4.01ms (libfreenect also built in debug mode)
-     * Release: 2.75ms (run without debug)
-2) Zephod's dedicated driver V16:
-   * compiler: VC++ 2010
-   * time measured via QueryPerformanceFrequency() / QueryPerformanceCounter()
-     * Debug:   2.91ms (Zephod's driver also built in debug mode)
-     * Release: 2.57ms (run without debug)
-
-A Win32 MinGW-based (gcc/g++ 3.4.5) build of libfreenect with libusbemu using POSIX
+   * Debug:   2.44ms | CPU @ 75% | video @ 30Hz | depth @ 30Hz
+   * Release: 1.93ms | CPU @ 63% | video @ 30Hz | depth @ 30Hz
+2) Zephod's dedicated driver (V16):
+   * Debug:   2.87ms | CPU @ 82% | video @ 30Hz | depth @ 30Hz
+   * Release: 2.55ms | CPU @ 77% | video @ 30Hz | depth @ 30Hz
+
+
+
+Remarks:
+
+Debug builds account for the library itself being built in Debug mode (libfreenect or
+Zaphod's driver, whichever applies). Release builds also imply that the program was
+started without any debug information embedded.
+
+In Windows, time was measured through the Win32 exclusive QueryPerformanceFrequency()
+and QueryPerformanceCounter() routines. In Linux, the measurement was performed via
+POSIX gettime() function.
+
+A Win32 MinGW-based (gcc/g++ 4.5.0) build of libfreenect with libusbemu using POSIX
 gettime() also yielded to nearly identical performance results than VC++ 2010 with
-Performance Counters. All of the Win32 performance results were also double-checked
-with Fraps.
+Performance Counters.
+
+All of the Win32 performance results were also double-checked with Fraps.
+
+In Windows, a single thread yield call was placed after rendering each screen frame
+(as recommended in Item 3-3). In Linux, the graphics driver - possibly glXSwapBuffers
+itself - seems to be already yielding the rendering thread, and forcing it in the code
+did not incur into any extra impact on performance.
+
 
-In all platforms and build configurations, video and depth were streamed at 30Hz,
-which seems to be the maximum throughput available from Kinect.
 
 Discussion:
 
 Even though there are no streaming frequency discrepancies between platforms, one may
 infer, just from the frame times, that Windows clearly has an overhead disadvantage.
 However, this does not hold true: there is still plenty of time for the application
-logic to run. For a steady 60FPS (16.66ms per frame) real-time performance, a Release
-build in Windows would still have about 14ms per frame available for the application,
-while in Linux the available time would be around 15.5ms, a 1.5ms overhead difference
+logic to run.
+
+For a steady 60FPS (~16.66ms per frame) real-time performance, a Release build using
+libusbemu in Windows would still have about 14.70ms per frame available for the client
+code, while in Linux the available time would be around 15.50ms, a 0.8ms overhead
 between the platforms. Such a small difference should not impose any special design
 considerations for the client code.
 
-The overhead between libusbemu and Zephod's code is due the fact that libusbemu has
-to inspect the usb packages before forwarding them to libfreenect which will then be
-checked again within libfreenect. Another performance consideration is the fact that
-Zephod's Bayer-to-RGB and bit-unpacking seem to be faster than the stream conversion
-procedures provided by libfreenect.
-
-Another performance impact between libusbemu and Zephod's code, is due the fact that
-libusbemu makes heavy use of STL containers which in Debug mode tend to introduce a
-significative overhead; such overhead disappears in Release mode since STL containers
-are prone to be "inlined" and further optimized, besides the fact that many security
-checks of the STL are disabled in Release builds. Moreover, libusbemu also uses lots
-of synchronization directives, such as mutexes and conditional variables (events),
-that impose extra overhead. Anyway, the overall overhead between the libusbemu and the
-Zephod's dedicated Win32 driver is negligible (1.1ms for Debug builds and 0.2ms for
-Release builds).
-
-TODO:
-* CPU consumption: CPU should be at 100% in either Linux or Windows
-  But in Windows, there are two critical-time threads inside the libusbemu which will
-  compete for CPU resources with the main program (and the freenect_process_events()
-  thread) which may also explain the overhead.
-* Memory consumption: no known leaks in the libusbemu; double checked with VC++ memory
-  leak detection tools.
+Furthermore, note that the CPU usage in Windows tend to be lower than in Linux. The
+reason behind this difference is quite difficult to summarize here, but it is probably
+related to the way Windows and Linux perform asynchronous I/O in USB-mapped files.
+The interested reader is encouraged to refer to the following links:
+  > http://www.unwesen.de/articles/waitformultipleobjects_considered_expensive
+  > http://softwarecommunity.intel.com/articles/eng/2807.htm
+  > http://software.intel.com/en-us/blogs/2006/10/19/why-windows-threads-are-better-than-posix-threads/
+The memory consumption overhead of libusbemu in Windows is negligible, and as far as
+the VC++ memory leak detection goes, libusbemu has no memory leaks.
 
 ======================================================================================