AmbiLED draft

---------------------------------------------------------------------------------------------------------
                       AmbiLED 2011, Mariusz Grzybacz - FREE Open Source software
---------------------------------------------------------------------------------------------------------
                                  to control any DIY AmbiLight system
								     writted for Windows 7 x64/x86
---------------------------------------------------------------------------------------------------------

1] Window handle finder (based on a spy++) for profile maker
   (TODO: Auto detection of surface capture method D3D9/10/11, OpenGL??, GDI)

2] Capture methods: D3D9/10/11 Hook (+Vertex Mode selection, for some people with lo-GPU,
   Software mode improves speed and LockableBackBuffer defaultly enabled =dramaticly speed improve),
   OpenGL??, .NET, GDI BitBlt + Reserved, Mirror Driver, Video Card capture??,
   External TCP Port: 32890? maybe faster way??=(Simple:Left,Right,Top,Bottom;
   Extended specified RGB channels must match unit channels)

   Web links:
   Blt+Reverse: http://stereopsis.com/blttest/
   Mirror Driver support? http://demoforge.com/dfmirage.htm
   Sharp SDK: http://www.demoforge.com/sdk/MirrSharp.zip
   Win7 .NET vs GDI: http://blog.bobcravens.com/2009/04/fastest-screen-capture-using-c-vista-vs-win7/
   Display>Video card: http://www.splitmedialabs.com/media-toolkits ]
   [ used this code for handle Finder: http://www.codeproject.com/KB/graphics/screen_capturing.aspx ]

3] Main display surface profile builder
   (eg. movie/surface size is 1920x800, 2.40:1 and it needs to match the led stripes positions.
   So solution is default for all inputs, surface in a size coresponding to the display device
   resolution 1920x1080, 16:9, with captured image inside in exactly same size & position
   as as original one.
   Note: Useful for multiple chanels for a side - this will prevent to light a stripe located
   on a black part of screen)

4] Auto-Run (Injection)Capturing(new Thread) from detected Process.Name in a system from Applications
   profiles list with custom settings for different applications
-- Two profile states: Normal, Exclusive
   (when enabled capturing in Normal state, then only new detected Process.Name with Exclusive flag set
   in profile will immediately pause Auto-Run timmer, then abort current working profile, Starts new
   and resume Auto-Run Timer. And for same flag state priority, capture switch to new profile depends
   on global settings [Profile triggering: Always, No-use])

5] User dynamic channels creation
   User creates channels dynamicly as a RECTs to scan X,Y,W,H in specified by a user order
   - MoMoLight v4 protocol - didn't confirmed this with Marc Nieuwenhuizen yet, who still helps
   on this. He mades an alternative with MoodLight support.

6] Colour-calculation:
-- TODO: Surface blur - didn't study how to do this and prefered to do this on DX Surface
** Get pixels through unsafe bitmap method to improve the speed and calculate average **
-- TODO: Intelligent Pixel Colour Threshold (NO IDEA HOW? When Surface blur does NOT solve desribed
   bellow issue, which is ONLY LAST ONE to make PERFECT AMBILIGHT SYSTEM, then need to find a way
   in some math maybe to eliminate:
+++) very low, but random colours blinking on darkness pictures - moving picture with shiny stars...
     ...on a dark sky - like a swimming colour dots
+++) fade in/out to white top/bottom side because of scrolled text at end of the movie)

7] Voodoo Modes: Simple, Game [Priority selection and Cycles count], True-Cinema +Expansion

8] Managed Colour-processing effects list for True-Cinema +Expansion mode (Add/Del, Move Up/Down)
a] Voodoo input settings
-- Expand individually/together *(Multiple)
   increase the lights level that can be used to adjust the brightness to match the one
   on a display device (*3), best solution for daytime watching (*10).
   IDEA: Useful with very cheap addon which is Foto-resistor that could be as extension for
   Ambi-module, which can perform room light measures for automatic lightning level adjustment!)
-- Colour Quantize
-- Colour Threshold (TODO: Like a curve in Photoshop or Sony Sound Forge)
-- Progressive GreyScale *(_level_Brightness)
b] True-Cinema calculations
-- Dynamic Colour Smoother *(_cycles_Smooth; _level_Aggression) [modes: Individual/Together]
   Normally movie has have something around, let's say 25fps and while using classic MoMoLight
   controller v1/v2 with 3 RGB channels at baud rate 9600, software is able to transfer ~133,33
   colour arrays. So why do not make colour changes more smooth and protect in same time from
   unwanted and bad looking flickering on small picture changes?
   Smooth colours calculates difference between two last colours on a channels and determinate
   dynamicly smooth cycle length. While doing smooth cycle, even longer then few retreive cycles
   it always reads current colour values and speeds up or down if necessary to attack aggressively,
   faster or slower if needed - depends on a colour difference. It's a like a "Colour Smooth Slider"
   to bring user "True-Cinema" AmbiLight. Anyway works fine! :)
   Cycles count number depends on Cycle Interval which depends on interface.speed+transmit.protocol
   with some reserve upto 20% for Aggressive Events attacks.
   ev1 if buffer for one data shot to the AmbiLED module is NOT empty then drop new data
       to allow current buffer data flyout =this protects buffer from overload and delays
	   send notify to log window: "Increase cycle interval to prevent buffer overloads
	   and data drops."
	   useful for first configuration and slow connection interface.speed eg. 9600 bauds
   note: Aggression Level for each Expand multipler needs to be set manually
         because of unknown LED intensity, room lightness, ...
		 my settings: (day-light)var.multiplier=10, _level_Aggression=128
		              (night)var.multiplier=4, _level_Aggression=96
c] Voodoo output settings
- Dynamic Color Increasing (not needed when users needs correct Gamma settings) - like a Smoother
  gets reset to Increase=10 (no increasing) from trigger Aggressive and works only when
  Aggressive set Together (All RGB channels) (NOT RECOMENDANTED)
- Gamma (important to calibrate LEDs to match light from display device)
- Colour compensation for each R, G, B colour - green wall behind a TV? reduce it!

------------------------------------------------------------------------------------------
   How True-Cinema works? Described in few steps on preferred mode Individual Smoother.
   Thread.1--] Init Capture method

   Thread.1a1] DoRequest capture method, copy to unsafe Bitmap and extract average colours
               for all specified RGB channels into _data_tempReceivedRGB

   Thread.1a2] Apply Voodoo Input filters on _data_tempReceivedRGB

   Thread.1a3] Copy temp array to _data_ReceivedRGB array and sets _trg_Received=true
               // NOTE: cannot start new Thread.2 from this point because this abort can
			   cause in damage settings, broken data in arrays and cycles drops

   Thread.1a4] if capture method != D3Dx then Thread.Sleep (Interval - (Start-Stop))

   Thread.1a5] Start new Thread.1


   Thread.2--] Init True-Cinema cycle, _chX_cycle_count++
   Thread.2a1] When triggered that new data arrives, then:
              *make Array copy of data from _data_CurrentRGB to _data_PreviousRGB
			  *and from _data_ReceivedRGB into _data_CurrentRGB
			  *also reset _trg_Received
			  (Note: steps bellow are executed on each channel in one cycle)

   Thread.2a2] check colour difference between
               __data_CurrentRGB[chX][c] and _data_PreviousRGB[chX][c].

   Thread.2a3] When _chX_colour_diff is >_level_Aggression then sets _chX_state_Aggressive flag
			   to enabled for chX, apply new colous, reset all states and QUIT
			   // check for new cycles count

   Thread.2a4] When _chX_colour_diff <= _level_Aggression then
			  *calculate new smooth cycle count progressively. Example results:
			    _chX_colour_diff=0                   then _tmp_cycles_Smooth=_max_smooth   (32)
			    _chX_colour_diff=_level_Aggression/2 then _tmp_cycles_Smooth=_max_smooth/2 (16)
			    _chX_colour_diff=_level_Aggression-1 then _tmp_cycles_Smooth=1 (no smooth)

   Thread.2a5]*if _tmp_cycles_smooth < _chX_cycles_smooth then
              *execute _reset_cycle_state(X)
               - calculate colour from previous cycle and save in working buffers
			     *execute getColorFromSmoothCycle(_chX_cycle_count, _chX_cycles_smooth,
				            _data_CurrentRGB[chX][c], _data_PreviousRGB[chX][c]) : _data_OutputRGB
			   - reset cycle count for this channel set _chX_cycle_count = 0
			   otherwise do the same, but global flag _smooth.LikeOldPlatformGame must be DISABLED?
              *execute _reset_cycle_state(X)

			   NOTE: standard smooth cycle calculation
   Thread.2a6]*execute getColorFromSmoothCycle(_chX_cycle_count, _chX_cycles_smooth,
				         _data_CurrentRGB[chX][c], _data_PreviousRGB[chX][c]) : _data_OutputRGB

   Thread.2a7]*if _chX_cycle_count = _chX_cycles_smooth then _chX_cycle_count = -1
   Thread.2a8]*Apply Voodoo Output filters on _data_OutputRGB and execute Send on new Thread
   Thread.2a9]*Thread.Sleep (Interval - (Start-Stop)) +abort triggered from _trg_Received
   Thread.2aA]*Start new Thread.2

   Thread.3a] Data send thread (Previous != Current) then Send
------------------------------------------------------------------------------------------