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.

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
   - linespec.dll                 LineSpec library
   - linespec (virtual).dll       Virtual version of the LineSpec library
   - LineSpec.txt                 Documentation etc.
   - Source.zip                   Source code (PureBasic) and related files;
   - LineSpec Demo *.*            Demo applications, source and related files;
   - *.lib & *.exp                Additional include files you may need for some
                                  compilers

  Wavedata to spectrum data conversation is based on a free Visual Basic 6
  example by Ulli "Mühlenweg" <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), 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 version includes a 95%
  assembly version which 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

Usage
-----

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

  - If Startup() has failed, do not call GetSpectrum() or Shutdown().
  - If Startup() has failed or after using Shutdown(), you may try Startup()
    again.
  - 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.
  - 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 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. There is no need to restart the demo
  application to apply changes.

  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.

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

  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.