#ifndef _LADGUI_INCLUDED_
#define _LADGUI_INCLUDED_

#ifdef __cplusplus
extern "C" {
#endif

/*
 * LADGUI: A backwards-compatible Extension to LADSPA & DSSI allowing hosts to create simple yet more functional than current GUIs
 * Features:
 *  backwards and forwards compatible
 *  easy to use
 *  not tied to any host or platform
 *  strings for port values. eg. on a waveform selector describe_value() might return "SAW", "SQR", etc depending on the value
 *  grouping of ports. eg. creating a group such as "OSC1" containing ports "Tuning", "Waveform", "Volume", etc so that the gui can group these ports together
 *  display style of port. eg. Knob, Slider, Toggle. can be ignored by the host if it prefer to display all in a similar manner
 *
 *  LADGUI is an API for informing hosts or guis about LADSPA/DSSI parameters, not for creating the actual GUI, although i may create a reference host.
 *
 * To support it in a plugin simply make a function called ladgui_descriptor which returns a LADGUI_Descriptor,
 * for hosts just call dlsym(Handle, "ladgui_descriptor") and then call it if it exists to get the LADGUI_Descriptor.
*/

#define LADGUI_TYPE_HIDDEN			0x0000 /* not displayed */
#define LADGUI_TYPE_DONTCARE		0x0001 /* displays just as it normally would without LADGUI */
#define LADGUI_TYPE_NOTE			0x0002 /* eg. C-4 = 64 */
#define LADGUI_TYPE_SWITCH			0x0003 /* on/off, true/false, sin,sqr,saw,noise switch */
#define LADGUI_TYPE_HSLIDER			0x0004 /* horizontal slider */
#define LADGUI_TYPE_VSLIDER			0x0005 /* vertical slider */
#define LADGUI_TYPE_NUMBER			0x0006 /* numeric input */
#define LADGUI_TYPE_DIAL			0x0007 /* dial/knob input */
/* any unknown type is for future additions and hosts must fall back to dontcare */

typedef unsigned int LADGUI_DisplayType;

typedef struct _LADGUI_PortInfo {
	/* name of the port group. eg. "OSC 1", all ports in the same group will appear next to eachother and perhaps be indented or bordered like a HTML fieldset for example */
	char* group;

	/* controls how the port may be displayed */
	LADGUI_DisplayType type;

	/* increment or decrement by this value when adjusting */
	float precision;
} LADGUI_Param;

typedef struct _LADGUI_Descriptor {
	/* returns a null terminated string that describes the value of the port for the given value.
	 * returns NULL if there is no string, in which case fall back to pre LADGUI style.
	 */
	const char* (*describe_value)(const LADSPA_Handle Instance, const unsigned long port, const float value, const float sample_rate);

	/* returns a null terminated list of port groups.
	 * returns NULL if it should fall back to pre LADGUI style.
	 */
	LADGUI_PortInfo (*get_portinfo)(const LADSPA_Handle Instance, const unsigned long port);
} LADGUI_Descriptor;

const LADGUI_Descriptor * ladgui_descriptor(const unsigned long Index);

#ifdef __cplusplus
}
#endif

#endif