You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
305 lines
10 KiB
305 lines
10 KiB
Environments:
|
|
=============
|
|
|
|
1. What is an Environment?
|
|
2. How do the interfaces look?
|
|
3. How do I create/use one?
|
|
4. How do I implement items?
|
|
|
|
/*
|
|
Documentation TODO: add more details:
|
|
- Guis and aRts (probably seperate document), GuiFactory, GenericGuiFactory,...
|
|
- the dataDirectory (sections 2,3,4)
|
|
- how items react on changes of active (section 4)
|
|
*/
|
|
|
|
1. What is an Environment?
|
|
--------------------------
|
|
|
|
Programs like sequencers often require complex structures with lots of
|
|
parameters to configure running inside aRts, to create music. For instance
|
|
for composing a song, you might require
|
|
|
|
- several effects
|
|
- several synthetic instruments
|
|
- several audio tracks
|
|
- a mixer
|
|
|
|
While with artscontrol, the user can setup much of this himself manually, the
|
|
problem is that this has to be done over and over again. That is, if he saves
|
|
the song, the settings of his effects, instruments and the mixer will not be
|
|
saved with it.
|
|
|
|
The main idea of the new interfaces in Arts::Environment is that the sequencer
|
|
can save the environment required to create a song along with the the song, so
|
|
that the user will find himself surrounded by the same effects, instruments,...
|
|
with the same settings again, once he loads the song again.
|
|
|
|
So, conceptually, we can imagine the environment as a "room", where the user
|
|
works in to create a song. He needs to install the things inside the room he
|
|
needs. Initially, the room will be empty. Now, the user things: oh, I am going
|
|
to need this nice 24 channel mixer. *plop* - it appears in the room. Now he
|
|
thinks I need some sampler which can play my piano. *plop* - it appears in
|
|
the room.
|
|
|
|
Now he starts working, and adds the "items" he needs. Finally, if he stops
|
|
working on the song, he can pack all what is in the environment in a little
|
|
box, and whenever he starts working on the song again, he can start where he
|
|
left off. He can even take the environment to a friend, and continue working
|
|
on the song there.
|
|
|
|
Note that there might be other tasks (such as creating a film, playing an
|
|
mp3 with noatun,...) which will have similar requirements of saving the
|
|
current state, so the concept of environments is not limited to songs.
|
|
|
|
2. How do the interfaces look?
|
|
------------------------------
|
|
|
|
There are two main things in the Environment, that is
|
|
|
|
Arts::Environment::Container this interface is where you put all your stuff
|
|
you need to create a song
|
|
|
|
Arts::Environment::Item this is an item that works inside an
|
|
environment
|
|
|
|
2.1 The Container interface:
|
|
----------------------------
|
|
|
|
Initially "Container"s are empty when created. If you create items, you need
|
|
to tell the container about it.
|
|
|
|
void addItem(Item item);
|
|
Item createItem(string name);
|
|
|
|
You can create the Item yourself and use addItem afterwards, or you can tell
|
|
the container to create an Item (by name), and return it to you. Then it will
|
|
automatically be put into the environment.
|
|
|
|
You can list the items that are currently inside an environment with the
|
|
attribute
|
|
|
|
readonly attribute sequence<Item> items;
|
|
|
|
and remove them with
|
|
|
|
void removeItem(Item item);
|
|
|
|
Finally, the more interesting aspect is that you can save the whole
|
|
environment to a list of strings, and restore it from there.
|
|
|
|
sequence<string> saveToList();
|
|
void loadFromList(sequence<string> strlist);
|
|
|
|
If you load it, all items will be created that were created in the environment
|
|
you saved.
|
|
|
|
|
|
There are two more special items. Here are two remaining problems to explain
|
|
you the purpose of these (you can skip these explaination if you want get
|
|
the basic idea first):
|
|
|
|
* the "sample data problem"
|
|
|
|
Consider you have a song where you use these spectacular "boom" sound you just
|
|
sampled. Now you save it to a list of strings, and take it to a friend. There
|
|
are two things that could happen up to now:
|
|
|
|
1. the "boom" sound doesn't get put into that list of strings, so when you play
|
|
the song on your friends computer it might be missing
|
|
|
|
2. the "boom" sound gets saved as string list - this would probably be really
|
|
really inefficient for both, loading and saving
|
|
|
|
So we introduce a
|
|
|
|
attribute string dataDirectory;
|
|
|
|
where song specific data can be saved. The general idea is that items should
|
|
access data from anywhere on your harddisc. However, if you execute a special
|
|
operation (such as "pack the environment"), all data used in the environment
|
|
should get copied into the dataDirectory, and the data should be used from
|
|
there in the future.
|
|
|
|
The details of this are not quite done yet.
|
|
|
|
* the "outside world object" problem
|
|
|
|
Suppose you use an environment and some items use objects that are not items
|
|
of the environment. A typical example might be objects which refer to an
|
|
Arts::StereoEffectStack outside the environment. Such objects could be saved,
|
|
but they need to know how to restore themselves to "the same" StereoEffectStack
|
|
again (which will not be restored by the environment).
|
|
|
|
The general idea to solve this is the context. In the context the user can
|
|
name non-environment objects and say: "well, here is a StereoEffectStack my
|
|
items will refer to, and it is named 'OutputEffectStack'". Upon serialization,
|
|
the environment would not care about the OutputEffectStack, and each item
|
|
which needs to refer to it would only save that it needs to put the items
|
|
in something called 'OutputEffectStack' again.
|
|
|
|
The same way, up on restore, items could lookup the 'OutputEffectStack' again
|
|
and insert StereoEffects in there.
|
|
|
|
The details of this are not quite done yet.
|
|
|
|
2.2 The Item interface:
|
|
-----------------------
|
|
|
|
Most functions in the Item interface are not too relevant for users. Upon
|
|
insertion, the environment uses
|
|
|
|
void setContainer(Container container);
|
|
|
|
to tell the Item in which environment it lives. It also uses setContainer(
|
|
Container::null()) once the Item gets removed. Which container the Item
|
|
is in can be seen in the
|
|
|
|
readonly attribute Container parent;
|
|
|
|
Upon serialization, the container uses
|
|
|
|
sequence<string> saveToList();
|
|
void loadFromList(sequence<string> strlist);
|
|
|
|
to save or restore the data. Finally, you can see if the item is currently
|
|
inside a Container with the
|
|
|
|
readonly attribute boolean active;
|
|
|
|
There is some trick here: the problem is that you will probably want to hold
|
|
references to items (or parts of items) in some situations. But if you do so,
|
|
and for instance display the item on the GUI, you will still display the item
|
|
if it was removed from the environment. And you will (by reference counting)
|
|
prevent it from disappearing.
|
|
|
|
So... if you hold a reference, watch whether the item is still active, using
|
|
|
|
connect(item, "active_changed", ...)
|
|
|
|
and do release the references you hold if it is not. I.e. if you have a mixer
|
|
window on the screen, and the mixer gets inactive, close it. (See also: change
|
|
notification documentation).
|
|
|
|
3. How do I create/use one?
|
|
---------------------------
|
|
|
|
First of all, creation. Usually, you will hold your environments on the
|
|
sound server. So creating will look like:
|
|
|
|
/* lookup sound server (use an existing one, if you have one) */
|
|
Arts::SoundServer server = Reference("global:Arts_SoundServer");
|
|
if(server.isNull())
|
|
/* error handling -> no sound server running */;
|
|
|
|
/* create the object on the server */
|
|
Arts::Environment::Container container =
|
|
Arts::DynamicCast(server.createObject("Arts::Environment::Container"));
|
|
if(container.isNull())
|
|
/* error handling -> environment container could not be created */;
|
|
|
|
Good, now we have an environment. What to do now? We could add a mixer. This
|
|
would work like
|
|
|
|
Arts::Environment::MixerItem mixer =
|
|
Arts::DynamicCast(container.createItem("Arts::Environment::MixerItem"));
|
|
if(mixer.isNull())
|
|
/* error handling -> no mixer */;
|
|
|
|
Cool. A mixer. What do we do with that. Hm... setting the channel count would
|
|
be nice, for instance.
|
|
|
|
mixer.channelCount(8); /* an eight channel mixer */
|
|
|
|
And finally, we could display a GUI for it, using the KDE gui embedding thing.
|
|
|
|
Arts::GenericGuiFactory guiFactory;
|
|
Arts::Widget widget = guiFactory.createGui(mixer);
|
|
if(!widget.isNull())
|
|
{
|
|
KArtsWidget *kartswidget = new KArtsWidget(widget);
|
|
kartswidget->show();
|
|
}
|
|
else
|
|
{
|
|
/* error handling -> no gui available for this item */
|
|
}
|
|
|
|
NOTE: for GenericGuiFactory to work, it needs to know what toolkit you are
|
|
using. For KDE, you need to add the line
|
|
|
|
ObjectManager::the()->provideCapability("kdegui");
|
|
|
|
somewhere in your application (only do this once).
|
|
|
|
You can try using saveToList or loadFromList on the container, too. A classical
|
|
piece of code which does this is, copied from artscontrol:
|
|
|
|
void EnvironmentView::load() /* load from file DEFAULT_ENV_FILENAME */
|
|
{
|
|
ifstream infile(DEFAULT_ENV_FILENAME);
|
|
string line;
|
|
vector<string> strseq;
|
|
|
|
while(getline(infile,line))
|
|
strseq.push_back(line);
|
|
|
|
defaultEnvironment().loadFromList(strseq); /* we'd use "container" here */
|
|
}
|
|
|
|
void EnvironmentView::save()
|
|
{
|
|
vector<string> *strseq;
|
|
strseq = defaultEnvironment().saveToList(); /* we'd use "container" here */
|
|
|
|
ofstream outfile(DEFAULT_ENV_FILENAME);
|
|
for(vector<string>::iterator i = strseq->begin(); i != strseq->end(); i++)
|
|
outfile << *i << endl;
|
|
delete strseq;
|
|
}
|
|
|
|
/* remark about loading:
|
|
Of course, after loading the environment, you might want to look at
|
|
container.items, to be able to display the guis again. To find out if an
|
|
item is a mixer, you can do Arts::Environment::MixerItem m =
|
|
Arts::DynamicCast(item); - or if you want to get the type in a generic
|
|
way, you can use string typename = item._interfaceName(); */
|
|
|
|
Finally, if we're tired of using our mixer, we can remove it again, using
|
|
|
|
container.removeItem(mixer);
|
|
|
|
4. How do I implement items?
|
|
----------------------------
|
|
|
|
Basically, you derive an interface from Arts::Environment::Item, like this:
|
|
|
|
// this code is in the .idl file:
|
|
interface MyItem : Arts::Environment::Item {
|
|
/* methods/attributes here */
|
|
};
|
|
|
|
and your implementation from Arts::Environment::Item_impl, like this:
|
|
|
|
// this code is in the .cc file:
|
|
#include "artsmodules.h"
|
|
#include "env_item_impl.h"
|
|
|
|
class MyItem_impl : virtual public MyItem_skel,
|
|
virtual public Arts::Environment::Item_impl
|
|
{
|
|
public:
|
|
void loadFromList(const vector<string>& list)
|
|
{
|
|
/* you need to implement this... */
|
|
}
|
|
vector<string> *saveToList()
|
|
{
|
|
/* ... and that */
|
|
}
|
|
};
|
|
REGISTER_IMPLEMENTATION(MyItem_impl); /* register your implementation */
|
|
|
|
If you want your item to have a Gui, implement a GuiFactory that can create
|
|
a gui for the item.
|