rsc3/doc-schelp/HelpSource/Reference/default_group.scrbl

#lang scribble/manual
@(require (for-label racket))

@title{default_group}
 The default Group@section{categories}
  Server>Nodes
@section{related}
  Classes/Group, Classes/RootNode, Classes/Node, Guides/NodeMessaging, Guides/Order-of-execution

@section{tree}
 
## root node (id:0)
@section{tree}
 
## default group (id:1)
::
::

When a Server is booted there is a top level group with an ID of 0 that defines the root of the node tree. (This is represented by a subclass of Group: link::Classes/RootNode::.)
If the Server was booted from within SCLang (as opposed to from the command line) a default group with an ID of 1 will be automatically created. @section{footnote}
 
When booting the server from the command line, you can create the default group manually with:

@racketblock[
s.initTree;
::
::
This is the default target for all Nodes when using object style and is what you will get if you supply a link::Classes/Server:: as a target. If you don't specify a target or pass in nil, you will get the default group of the default Server.
]

@racketblock[
s.boot;
a = Synth.new(\default); // creates a synth in the default group of the default Server
a.group; // note the Group ID
::
The default group serves an important purpose: It provides a predictable basic Node tree so that methods such as Server-scope, Server-record, etc. can function without running into order of execution problems. In the example below the scoping node will come after the default group.
]

@racketblock[
s.boot;

{ SinOsc.ar(mul: 0.2) }.scope(1);

// watch the post window;
s.queryAllNodes;

// our SinOsc synth is within the default group (ID 1)
// the scope node comes after the default group, so no problems

s.quit;
::
Note that the default group is persistent: It is created in Server's ]

@racketblock[init]
@section{Tree}
  method (executed along with any code stored in its tree instance variable; see Server for more detail) and is recreated upon reboot, after pressing Cmd-., and after all nodes are freed. When using osc messages this means that a target node of id 1 can always be used:

@racketblock[
s.sendMsg("/s_new", "snd", 1832,0,1); // add to head of group 1
::
The default group can be specifically freed, but there is generally no reason that one would want to do so.

In general one should add nodes to the default group rather than the RootNode unless one has a specific reason to do so (i.e. adding some new functionality such as recording and scoping which is dependent upon a predictable basic node order). When using object style the default group is the default target for all new nodes, so nodes will normally not be added to the RootNode unless that is explicitly specified. It is of course possible to do so, but it should only be done with a proper understanding of the issues involved.

For instance, if one were to place an 'effects' synth after the default group and call Server-record or Server-scope, the resulting recording or scope synths may not be correctly ordered:
]
@section{tree}
 
## default group
@section{tree}
 
## source synth1
## source synth2
::
## recording synth
## effects synth
::
In the above example the recording synth might not capture the output of the effects synth since it comes later in the node order.

A better method in this case is to create a group within the default group and place the effects synth after that.
@section{tree}
 
## default group
@section{tree}
 
## source group
@section{tree}
 
## source synth1
## source synth2
::
## effects synth
::
## recording synth
::