About / What is LineSpec
------------------------

  LineSpec is a library to simplify the process of getting spectrum data from
  the (default) recording device;

  The latest official version(s) can be found at http://www.ctuser.net. For
  suggestions, questions, requests or bug reports, send eMail to
  info@ctuser.net.

Requirements
------------

  Not yet tested that much yet, but any PC capable of recording sound should do.
  However, I've already encounter a computer with good hardware where playback
  (using QuickPlayer) began stuttering when LineSpec demo applications ran, and
  on another recording stops after a few seconds when 'Stereo Mix' is choosen.

Copying / License / ...
-----------------------

  LineSpec and Demo applications are free software; you can redistribute them
  and/or modify them under the terms of the GNU General Public License as
  published by the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

  You should have received a copy of the GNU General Public License along with
  this program; if not, write to the Free Software Foundation, Inc., 59 Temple
  Place, Suite 330, Boston, MA  02111-1307  USA

  If you have any questions, suggestions or bug reports about this product,
  contact me: info@ctuser.net; Please do not contact me about general B.A.S.I.C.
  language or A.P.I. issues.

  Files (depending on the package you downloaded, not all files may be included)
   - License.txt                  GNU General Public License
   - *.dll                        LineSpec library(ies)
   - LineSpec.txt                 Documentation etc.
   - API & Includes\*.*           API declarations and/or include files
   - Demo applications\*.*        Demo applications, source and related files;
   - Examples\*.*                 Some test applications
   - Source\*.*                   Source code and related files

  Wavedata to spectrum data conversation is based on a free Visual Basic 6
  example by Ulli "Mhlenweg" <umgedv@yahoo.com>, which can be found at
http://www.planetsourcecode.com/vb/scripts/ShowCode.asp?txtCodeId=65007&lngWId=1
  
Background
----------

  It initially started with a non-public QuickPlayer version which rendered a
  simple spectrum on about 1/5 screen height, which was ocassionally shown with
  a beamer during the "Summernight Party" 2004 in Exing (Germany) by
  Partyservice Falk (http://www.partyservica-falk.de).

  Some time later I excluded the rendering stuff to a seperate executable,
  using fmodex for recording and slightly delayed virtual playback to get the
  spectrum.

  In 2007, I helped including "sound support" for "Lights player", a Jukebox for
  external LED boards (http://www.freewebs.com/artdecojukebox), which resulted
  the LineSpec library (3.x). Due the sync problem (to keep the playback
  slightly behind recording), and invalid spectrum data after some time, I
  continued working on a example using waveIn api to "record" and displayed a
  spectrum.
  Also using native waveIn APIs, there was still invalid spectrum data after
  some time; to fix this, recording totally reinitializes after each processed
  spectrum.

  Designed as standalone library, it is officially published in fall 2007, with
  version 3.10 (build 2007.09.30)

  LineSpec is open source since spring/summer 2008, with version 3.10 (build
  2008.04.16)

  With version 3.20 (published sprint 2009), the source was rewritting to
  assembly (Flat Assembler / http://www.flatassembler.net ), resulting in about
  3 times faster waveform to spectrum conversation; Multithread support is also
  included in the main dll instead of having a seperate dll. (The purebasic demo
  applications use a wrapper with almost no speed disadvantages)

API
---

  The Startup api has changed with version 3.20!!!

  bool Startup(
    UINT Flags       // See Flags
    ); // If the function succeeds, the return value is not NULL;
    
    Flags:
      0x00000000 Default;
      0x01000000 Use multithread; If the function succeeds, the return value is
                 the handle to the new thread; This handle is valid until
                 ShutDown(), and you should not close (CloseHandle()) it.



  UINT Shutdown(); // currently no specific return value



  UINT GetSpectrum(
    UINT ptrFloatArray, // pointer to an array of floats for the spectrum
    UINT ArraySize,     // Number of floats (per channel!)
    UINT Channels,      // Channels to grab: 0=mixed, 1=left, 2=right, 3=stereo
    UINT Flags,         // See Flags
    UINT ptrBoost       // pointer to a float with the boost value, or NULL
    ); // returns the GetTickCount() windows api value from the last finished
       // spectrum data, or NULL / 0

    Flags:
      0x1 = get previous spectrum;
      0x2 = average values;
            this flag is useless when combined with 0x1 (get previous spectrum)

Usage
-----

  To use LineSpec, call the Startup function. If the function succeeds, you can
  use GetSpectrum; When finished, call Shutdown();

  PureBasic:
    you can 'IncludeFile "LineSpec (PureBasic assembly).pb"'; However you have
    to additionally call LineSpec_PBLoader(), which must return successfull (not
    null) before using the other functions; This way linespec.dll is not needed.
  Visual Basic 6:
    add 'LineSpec (Visual Basic 6 declarations).bas' to the project, and copy
    linespec.dll to a folder where Visual Basic can find it.

Remarks
-------

  - If Startup() has failed, do not call GetSpectrum() or Shutdown().
  - If Startup() has failed or after using Shutdown(), you may try Startup()
    again.
  - You must not initialize twice, but you can initialize again after Shutdown()
  - GetSpectrum always delivers the last used / latest available spectrum data,
    and the return value is the GetTickCount() windows api value the affected
    spectrum data was delivered.
    If no spectrum data is ready after Startup() yet, it delivers zero floats,
    and the return value is NULL / 0 (may not be true when reinitializing).
  - The boost value is applied internally whenever a new spectrum data is to be
    used; Calling GetSpectrum() with flag 1 or no new data available, the
    ptrBoost parameter is currently ignored; If ptrBoost is NULL, no boost is
    applied.

Demo applications
-----------------

  Images used for LineSpec demos:
  At the moment, there are no recent demos using any wallpapers/images yet.

  The demos don't need the dll because it's compiled into (included) the binary.

  When launching, Linespec will start foreground, and change to background as
  soon as user input occurs

  There is a systray-icon in case you are not familiar with the keyboard
  shortcuts

  You have to setup recording device. On most systems there is no need to
  restart the demo application to apply changes (may be needed on Windows
  Vista?).

  Demos will automatically use a non-primary monitor, or even the full "virtual
  desktop".

  When having QuickPlayer (beta 60+), Apollo, Foobar2000 or Winamp running, the
  demos will display the current playing song


  Shortcuts:
    Ctrl + Shift + Alt + D:   toggles visibility (but still running!)
    Ctrl + Shift + Alt + F:   return to foreground-mode
    Ctrl + Shift + Alt + L:   quit
    Ctrl + Shift + Alt + V:   open Windows volume controls

  Some usefull windows shortcuts:
               Windows + M:   Minimize (most) Windows
               Windows + D:   Brings the Desktop to the foreground (requires
                              Windows 98/ME, NT?/2000?/XP/Vista/+; You may have
                              to swap to another application first to restore
                              the demo application)

  TrayIcon behavior:
                Left click:   toggles visibility (but still fully running!)
          Left doubleclick:   quit
               Right click:   show menu

  For completeness, source for the released demo applications is provided;
  I know it's a (coding) disaster, especially all this compiler directives.
  It's a demo application, so I didn't care a bit except speed and size of the
  final binary, and sharing code.

Compiling
---------

  - Use flat assembler ( http://www.flatassembler.net ) to compile
    LineSpec.fasm
  - For the speed measurement version, copy (overwrite) files from
    Source\Meassure to Source
  - The virtual version needs PureBasic to compile
  - The demo applications need PureBasic to compile
  - The version info resource I use some specific values so that they can be
    updated with a tool during batch compiling. Don't forget to update this info

Version history
---------------

  3.23 build 2010.05.24
   General changes/library:
    - MirrorData and BoostData is now unitialized/reserved data, and calculated
      on startup; Calculation code is shared with hMemRec, which is now partly
      initialized (code), partly uninitialized (additional bytes)
    - Even less code between EnterCriticalSection and LeaveCriticalSection; The
      Multithreaded recording stuff is also slightly optimized for speed (/size)
   Demo applications:
    - Wallpaper demos alignment issue, esp. when resizing alot
    - New 'Encircle' demo
    - Starfield (and Encircle) demo now renders below text area

  3.22 build 2009.11.17
   General changes/library:
    - Removed UninitializeCriticalSection import (not present on XP; was not
      actually used and so ignored by the assembler)
    - GetSpectrum did not return GetTickCount() windows api value from the last
      finished spectrum data if not multithreaded.
    - waveInAddBuffer now performed before waveInStart
    - Buffer is now unitialized/reserved data, so uncompressed size is much
      smaller

  3.21 build 2009.05.20
   General changes/library:
    - Minor arrangements so the assembly can be easier used for PureBasic
    - When multithreading, current/new wavedata memory was switched even if no
      new data was available, resulting in switching between old/current data.
      (Demos are not affected)
   Demo applications:
    - Device setup starts mixer in recording mode

  3.20 build 2009.02.15
   General changes:
    - Startup() has now a flag
    - GetSpectrum() is now ~ 95% assembly and way faster:
       ~ 4.4x Wavedata preperation
       ~ 3.4x FFT generation
       ~ 3.6x Postprocessing, calculating and boosting
       ~ 1.7x Array processing / copying
      Total improvement is ~ 3.4x speed
      (using elapsed times for 32 calls with new spectrum data; 5 tries each,
      comparing best value(s) of the (slightly modified) old version with the
      worst value(s) of the new version)
   Demo applications:
    - Basic native support to gather titles from Apollo, Winamp and latest
      Foobar 2000
    - Rewritten and enhanced stretching/alignment for Wallpaper demos
    - Fixed GDI leak when size changes (Wallpaper demos only)
    - When entering foreground mode (due keypress or elapsed time) visibility is
      automatically restored
    - Lot's of Windows XP workarounds
    - Menu for tray icon click with right mouse button
    - New icons; Vista png icon (untested)
    - SetStretchBltMode left HALFTONE so eye stretching is no longer corrupted
      on Windows NT series.
    - Systray icon reloading
    - Semitransparent title bar (optionally / requires msimg32.dll)
    - When main window is hidden, spectrum is rendered in the systray (icon)
      instead

  3.11 build 2008.07.24
   Demo applications:
    - Proper background erasing (wallpaper / starfield demos unaffected)
    - Global hotkeys working properly on Windows XP

  3.11 build 2008.06.20
   General changes:
    - GetSpectrum() returns GetTickCount() windows api value of the affected
      spectrum data, or NULL / 0
    - ptrBoost parameter for GetSpectrum() may be NULL
    - Using channel 0 in GetSpectrum() delivers mixed left/right channel data
   Multithread version:
    - Thread always stoppes recording properly now on Shutdown()
   Virtual version:
    - Flags and Channels parameters processed (correctly)
   Demo applications:
    - Recording thread always stoppes recording properly when quitting
    - New demo: LSDemo - Wallpaper - LaFee
    - Animation when title changes

  3.10 build 2008.04.16
   Virtual version:
    - Generates spectrum values for all channels correctly
   Demo applications:
    - Removed stuff to detect wether screensavers etc. are permitted, because
      provided information is unreliable. Quit or hide manually instead.