Overview
--------

Libwaveform attempts to provide versatile easy-to-use display
of audio waveforms for Gtk+-2 applications.

Efficiency:

* audio and peak data is handled in blocks to get reasonable performance with large files.
* opengl hardware features are used where available.
* multi-level caching.
* in many cases drawing can be done repeatedly with virtually no cpu load.

Multi-level caching is provided:

* peak files are saved to disk roughly following freedeskop.org standards. (Ardour session peak files are also supported.)
* peak files are cached in ram at multiple resolutions.
* audio is cached in ram for use at high resolutions.
* peaks are stored as OpenGl 2D textures in graphics hardware.
* peaks are stored as OpenGl 1D textures for use with shader programs.
* rendered and filtered images are stored as OpenGl FBO's.

There are 4 main ways of using libwaveform:

1. the WaveformView Gtk widget
2. with GtkGLExt using the WaveformActor interface
3. rendering to a GdkPixbuf
4. rendering to an Alphabuf

Requirements:

- Gtk2
- GtkGLExt
- Libsndfile
- OpenGl (recomended)


Status
------

Basic functionality is now in place, but many areas need improving. There are
no known serious bugs so please report any you find. Feedback is also needed
on api, documentation, visuals etc.

An API review needs to be undertaken before a release is made.

Testing:
Has been fully tested with Gallium 0.4 on Radeon RV530, RV620 and Cedar and Intel 945.
Radeon HD 5000 has issues at very hi res which look like driver bugs though this is not confirmed.
Nvidia 8400 has been found to mostly work (Nouveau), though some issues are being investigated.
Wider testing is needed.

If you are able to help testing, please start with running test/view_test.
To compile the test programs you need to run configure with '--enable-test'.


WaveformView
------------

The easiest way to use libwaveform is via the WaveformView Gtk widget.

The widget will show the complete audio file and can be panned and zoomed
down to sample level.

To use the widget:
```c
	WaveformView* waveform = waveform_view_new(NULL);
	waveform_view_load_file(waveform, "myfile.wav");
```
(then pack and show the widget as normal)	

For a demonstration of usage, see: test/view_test.c


WaveformActor
-------------

The WaveformActor interface can be used to show a waveform on an
existing GtkGLExt drawing area. It is designed for use in editors
and audio production tools.

OpenGl shaders will be used if available, otherwise it will fallback
to using 8 bit textures.

WaveformActor's share a common WfCanvas object.
The canvas has the following directly setable properties:
```c
	uint32_t sample_rate
```

In order to remain versatile, the WfCanvas is very minimal.
For example it has no concept of time or tempo (positions are
specified in x y coordinates).

For a demonstration of usage, see: test/actor_test.c

Support for different peak formats is provided by 'loaders'. As
well as the default peak file loader, an Ardour session loader is
provided:
```c
	waveform_set_peak_loader(wf_load_ardour_peak);
```
or you can specify your own loader.


GdkPixbuf
---------

libwaveform provides the function waveform_render_peak_to_pixbuf().
Support for splitting the audio into blocks is not explicitly provided
and has to be done manually.

GdkPixbuf is useful as an intermediate step to producing PNG output.


AlphaBuf
--------

Alphabufs are useful in low level OpenGl applications.
They do not use much texture memory but are not as efficient
as using shaders.

eg to create a texture for use with Clutter:
```c
	Waveform* waveform = waveform_load_new("myfile.wav");
	AlphaBuf* a = waveform_alphabuf_new(waveform, -1, FALSE);
	texture = cogl_texture_new_from_data(a->width, a->height, COGL_TEXTURE_NONE, COGL_PIXEL_FORMAT_A_8, COGL_PIXEL_FORMAT_ANY, a->width, a->buf);
```

The above creates a texture for the whole file.
This is not appropriate for large files.

It is planned to add better support for Clutter in the near future.


Peak file cache
---------------

A cache of peak files is stored in XDG_CACHE_HOME (default ~/.cache/).
Files are removed if older than 30 days.
They are stored with standard WAV headers and contain alternating 16bit integer values for plus and minus peak values.
One pair of values (for each channel) is stored for every 256 frames of the original audio file.


Zoom levels
-----------

There are four distinct drawing modes depending on the zoom level.
Each mode has 16 times the resolution of the previous.

- Low res uses a 256 pixel texture per 256^3 audio frames.
- Std res uses a 256 pixel texture per 256^2 audio frames.
- Hi res draws individual lines, one per 16 audio frames.
- V Hi res draws at full resolution, ie using all audio frames.

