Carla/source/includes/vst3sdk/pluginterfaces/vst/ivstunits.h

//------------------------------------------------------------------------
// Project     : VST SDK
//
// Category    : Interfaces
// Filename    : pluginterfaces/vst/ivstunits.h
// Created by  : Steinberg, 2005
// Description : VST Units Interfaces
//
//-----------------------------------------------------------------------------
// This file is part of a Steinberg SDK. It is subject to the license terms
// in the LICENSE file found in the top-level directory of this distribution
// and at www.steinberg.net/sdklicenses. 
// No part of the SDK, including this file, may be copied, modified, propagated,
// or distributed except according to the terms contained in the LICENSE file.
//-----------------------------------------------------------------------------

#pragma once

#include "pluginterfaces/base/funknown.h"
#include "vsttypes.h"

//------------------------------------------------------------------------
#include "pluginterfaces/base/falignpush.h"
//------------------------------------------------------------------------

namespace Steinberg {
class IBStream;

//------------------------------------------------------------------------
namespace Vst {
//------------------------------------------------------------------------
/** Special UnitIDs for UnitInfo */
static const UnitID kRootUnitId	= 0;        ///< identifier for the top level unit (root)
static const UnitID kNoParentUnitId = -1;	///< used for the root unit which doesn't have a parent.

//------------------------------------------------------------------------
/** Special ProgramListIDs for UnitInfo */
static const ProgramListID kNoProgramListId = -1;	///< no programs are used in the unit.

//------------------------------------------------------------------------
/** Basic Unit Description.
\see IUnitInfo */
//------------------------------------------------------------------------
struct UnitInfo
{
	UnitID id;						///< unit identifier
	UnitID parentUnitId;			///< identifier of parent unit (kNoParentUnitId: does not apply, this unit is the root)
	String128 name;					///< name, optional for the root component, required otherwise
	ProgramListID programListId;	///< id of program list used in unit (kNoProgramListId = no programs used in this unit)
};

//------------------------------------------------------------------------
/** Basic Program List Description.
\see IUnitInfo */
//------------------------------------------------------------------------
struct ProgramListInfo
{
	ProgramListID id;				///< program list identifier
	String128 name;					///< name of program list
	int32 programCount;				///< number of programs in this list
};

//------------------------------------------------------------------------
/** Special programIndex value for IUnitHandler::notifyProgramListChange */
static const int32 kAllProgramInvalid =	-1;		///< all program information is invalid

//------------------------------------------------------------------------
/** Host callback for unit support.
\ingroup vstIHost vst300
- [host imp]
- [extends IComponentHandler]
- [released: 3.0.0]
- [optional]

Host callback interface, used with IUnitInfo.
Retrieve via queryInterface from IComponentHandler.

\see \ref vst3Units, IUnitInfo */
//------------------------------------------------------------------------
class IUnitHandler: public FUnknown
{
public:
//------------------------------------------------------------------------
	/** Notify host when a module is selected in Plug-in GUI. */
	virtual tresult PLUGIN_API notifyUnitSelection (UnitID unitId) = 0;

	/** Tell host that the Plug-in controller changed a program list (rename, load, PitchName changes).
	    \param listId is the specified program list ID to inform.
		\param programIndex : when kAllProgramInvalid, all program information is invalid, otherwise only the program of given index. */
	virtual tresult PLUGIN_API notifyProgramListChange (ProgramListID listId, int32 programIndex) = 0;

//------------------------------------------------------------------------
	static const FUID iid;
};

DECLARE_CLASS_IID (IUnitHandler, 0x4B5147F8, 0x4654486B, 0x8DAB30BA, 0x163A3C56)


//------------------------------------------------------------------------
/** Host callback for extended unit support.
\ingroup vstIHost vst365
- [host imp]
- [extends IUnitHandler]
- [released: 3.6.5]
- [optional]

Host callback interface, used with IUnitInfo.
Retrieve via queryInterface from IComponentHandler.

\see \ref vst3Units, IUnitHandler */
//------------------------------------------------------------------------
class IUnitHandler2 : public FUnknown
{
public:
	//------------------------------------------------------------------------
	/** Tell host that assignment Unit-Bus defined by IUnitInfo::getUnitByBus has changed. */
	virtual tresult PLUGIN_API notifyUnitByBusChange () = 0;

	//------------------------------------------------------------------------
	static const FUID iid;
};

DECLARE_CLASS_IID (IUnitHandler2, 0xF89F8CDF, 0x699E4BA5, 0x96AAC9A4, 0x81452B01)


//------------------------------------------------------------------------
/** Edit controller extension to describe the Plug-in structure.
\ingroup vstIPlug vst300
- [plug imp]
- [extends IEditController]
- [released: 3.0.0]
- [optional]

IUnitInfo describes the internal structure of the Plug-in.
- The root unit is the component itself, so getUnitCount must return 1 at least.
- The root unit id has to be 0 (kRootUnitId).
- Each unit can reference one program list - this reference must not change.
- Each unit using a program list, references one program of the list.

\see \ref vst3Units, IUnitHandler */
//------------------------------------------------------------------------
class IUnitInfo: public FUnknown
{
public:
//------------------------------------------------------------------------
	/** Returns the flat count of units. */
	virtual int32 PLUGIN_API getUnitCount () = 0;

	/** Gets UnitInfo for a given index in the flat list of unit. */
	virtual tresult PLUGIN_API getUnitInfo (int32 unitIndex, UnitInfo& info /*out*/) = 0;

	/** Component intern program structure. */
	/** Gets the count of Program List. */
	virtual int32 PLUGIN_API getProgramListCount () = 0;

	/** Gets for a given index the Program List Info. */
	virtual tresult PLUGIN_API getProgramListInfo (int32 listIndex, ProgramListInfo& info /*out*/) = 0;

	/** Gets for a given program list ID and program index its program name. */
	virtual tresult PLUGIN_API getProgramName (ProgramListID listId, int32 programIndex, String128 name /*out*/) = 0;

	/** Gets for a given program list ID, program index and attributeId the associated attribute value. */
	virtual tresult PLUGIN_API getProgramInfo (ProgramListID listId, int32 programIndex,
		CString attributeId /*in*/, String128 attributeValue /*out*/) = 0;

	/** Returns kResultTrue if the given program index of a given program list ID supports PitchNames. */
	virtual tresult PLUGIN_API hasProgramPitchNames (ProgramListID listId, int32 programIndex) = 0;

	/** Gets the PitchName for a given program list ID, program index and pitch.
		If PitchNames are changed the Plug-in should inform the host with IUnitHandler::notifyProgramListChange. */
	virtual tresult PLUGIN_API getProgramPitchName (ProgramListID listId, int32 programIndex,
		int16 midiPitch, String128 name /*out*/) = 0;

	// units selection --------------------
	/** Gets the current selected unit. */
	virtual UnitID PLUGIN_API getSelectedUnit () = 0;

	/** Sets a new selected unit. */
	virtual tresult PLUGIN_API selectUnit (UnitID unitId) = 0;

	/** Gets the according unit if there is an unambiguous relation between a channel or a bus and a unit.
	    This method mainly is intended to find out which unit is related to a given MIDI input channel. */
	virtual tresult PLUGIN_API getUnitByBus (MediaType type, BusDirection dir, int32 busIndex,
		int32 channel, UnitID& unitId /*out*/) = 0;

	/** Receives a preset data stream.
	    - If the component supports program list data (IProgramListData), the destination of the data
		  stream is the program specified by list-Id and program index (first and second parameter)
		- If the component supports unit data (IUnitData), the destination is the unit specified by the first
		  parameter - in this case parameter programIndex is < 0). */
	virtual tresult PLUGIN_API setUnitProgramData (int32 listOrUnitId, int32 programIndex, IBStream* data) = 0;

//------------------------------------------------------------------------
	static const FUID iid;
};

DECLARE_CLASS_IID (IUnitInfo, 0x3D4BD6B5, 0x913A4FD2, 0xA886E768, 0xA5EB92C1)

//------------------------------------------------------------------------
/** Component extension to access program list data.
\ingroup vstIPlug vst300
- [plug imp]
- [extends IComponent]
- [released: 3.0.0]
- [optional]

A component can either support program list data via this interface or
unit preset data (IUnitData), but not both!

\see \ref vst3UnitPrograms */
//------------------------------------------------------------------------
class IProgramListData: public FUnknown
{
public:
//------------------------------------------------------------------------
	/** Returns kResultTrue if the given Program List ID supports Program Data. */
	virtual tresult PLUGIN_API programDataSupported (ProgramListID listId) = 0;

	/** Gets for a given program list ID and program index the program Data. */
	virtual tresult PLUGIN_API getProgramData (ProgramListID listId, int32 programIndex, IBStream* data) = 0;

	/** Sets for a given program list ID and program index a program Data. */
	virtual tresult PLUGIN_API setProgramData (ProgramListID listId, int32 programIndex, IBStream* data) = 0;

//------------------------------------------------------------------------
	static const FUID iid;
};

DECLARE_CLASS_IID (IProgramListData, 0x8683B01F, 0x7B354F70, 0xA2651DEC, 0x353AF4FF)

//------------------------------------------------------------------------
/** Component extension to access unit data.
\ingroup vstIPlug vst300
- [plug imp]
- [extends IComponent]
- [released: 3.0.0]
- [optional]

A component can either support unit preset data via this interface or
program list data (IProgramListData), but not both!

\see \ref vst3UnitPrograms */
//------------------------------------------------------------------------
class IUnitData: public FUnknown
{
public:
//------------------------------------------------------------------------
	/** Returns kResultTrue if the specified unit supports export and import of preset data. */
	virtual tresult PLUGIN_API unitDataSupported (UnitID unitID) = 0;

	/** Gets the preset data for the specified unit. */
	virtual tresult PLUGIN_API getUnitData (UnitID unitId, IBStream* data) = 0;

	/** Sets the preset data for the specified unit. */
	virtual tresult PLUGIN_API setUnitData (UnitID unitId, IBStream* data) = 0;

//------------------------------------------------------------------------
	static const FUID iid;
};

DECLARE_CLASS_IID (IUnitData, 0x6C389611, 0xD391455D, 0xB870B833, 0x94A0EFDD)

//------------------------------------------------------------------------
} // namespace Vst
} // namespace Steinberg

//------------------------------------------------------------------------
#include "pluginterfaces/base/falignpop.h"
//------------------------------------------------------------------------