Sound.Sc3.Ugen.Graph

U_Graph and related types.

The Ugen type is recursive, inputs to Ugens are Ugens.

This makes writing Ugen graphs simple, but manipulating them awkward.

Ugen equality is structural, and can be slow to determine for some Ugen graph structures.

A U_Node is a non-recursive notation for a Ugen, all U_Nodes have unique identifiers.

A U_Graph is constructed by a stateful traversal of a Ugen.

A U_Graph is represented as a partioned (by type) set of U_Nodes, edges are implicit.

Types

type Port_Index = Int

Port index.

data From_Port

Type to represent the left hand side of an edge in a unit generator graph. C = constant, K = control, U = ugen.

Constructors

From_Port_C

Fields

• from_port_nid :: Id

From_Port_K

Fields

• from_port_nid :: Id
• from_port_kt :: K_Type

From_Port_U

Fields

• from_port_nid :: Id
• from_port_idx :: Maybe Port_Index

Instances

Show From_Port

Defined in Sound.Sc3.Ugen.Graph

Methods

showsPrec :: Int -> From_Port -> ShowS

show :: From_Port -> String

showList :: [From_Port] -> ShowS

Eq From_Port

Defined in Sound.Sc3.Ugen.Graph

Methods

(==) :: From_Port -> From_Port -> Bool

(/=) :: From_Port -> From_Port -> Bool

data To_Port

A destination port.

Constructors

To_Port

Fields

• to_port_nid :: Id
• to_port_idx :: Port_Index

Instances

Show To_Port

Defined in Sound.Sc3.Ugen.Graph

Methods

showsPrec :: Int -> To_Port -> ShowS

show :: To_Port -> String

showList :: [To_Port] -> ShowS

Eq To_Port

Defined in Sound.Sc3.Ugen.Graph

Methods

(==) :: To_Port -> To_Port -> Bool

(/=) :: To_Port -> To_Port -> Bool

type U_Edge = (From_Port, To_Port)

A connection from From_Port to To_Port.

data U_Node

Sum-type to represent nodes in unit generator graph. _C = constant, _K = control, _U = ugen, _P = proxy.

Constructors

U_Node_C

Fields

• u_node_id :: Id
• u_node_c_value :: Sample

U_Node_K

Fields

• u_node_id :: Id
• u_node_k_rate :: Rate
• u_node_k_index :: Maybe Int
• u_node_k_name :: String
• u_node_k_default :: Sample
• u_node_k_type :: K_Type
• u_node_k_meta :: Maybe (Control_Meta Sample)

U_Node_U

Fields

• u_node_id :: Id
• u_node_u_rate :: Rate
• u_node_u_name :: String
• u_node_u_inputs :: [From_Port]
• u_node_u_outputs :: [Output]
• u_node_u_special :: Special
• u_node_u_ugenid :: UgenId

U_Node_P

Fields

• u_node_id :: Id
• u_node_p_id :: Id
• u_node_p_index :: Port_Index
• u_node_p_rate :: Rate

Instances

Show U_Node

Defined in Sound.Sc3.Ugen.Graph

Methods

showsPrec :: Int -> U_Node -> ShowS

show :: U_Node -> String

showList :: [U_Node] -> ShowS

Eq U_Node

Defined in Sound.Sc3.Ugen.Graph

Methods

(==) :: U_Node -> U_Node -> Bool

(/=) :: U_Node -> U_Node -> Bool

u_node_is_c :: U_Node -> Bool

u_node_is_k :: U_Node -> Bool

u_node_is_u :: U_Node -> Bool

u_node_k_to_control :: U_Node -> Control

Convert from U_Node_K to Control (ie. discard index).

u_node_user_name :: U_Node -> String

Derive "user" name for U_Node

data U_Graph

Type to represent a unit generator graph.

Constructors

U_Graph

Fields

• ug_next_id :: Id
• ug_constants :: [U_Node]
• ug_controls :: [U_Node]
• ug_ugens :: [U_Node]

Instances

Show U_Graph

Defined in Sound.Sc3.Ugen.Graph

Methods

showsPrec :: Int -> U_Graph -> ShowS

show :: U_Graph -> String

showList :: [U_Graph] -> ShowS

Ports

port_idx_or_zero :: From_Port -> Port_Index

Get port_idx for From_Port_U, else 0.

is_from_port_u :: From_Port -> Bool

Is From_Port From_Port_U.

Nodes

is_u_node_c :: U_Node -> Bool

Is U_Node a constant.

is_u_node_c_of :: Sample -> U_Node -> Bool

Predicate to determine if U_Node is a constant with indicated value.

is_u_node_k :: U_Node -> Bool

Is U_Node a control.

is_u_node_k_of :: String -> U_Node -> Bool

Predicate to determine if U_Node is a control with indicated name. Names must be unique.

is_u_node_u :: U_Node -> Bool

Is U_Node a Ugen.

u_node_k_cmp :: U_Node -> U_Node -> Ordering

Compare U_Node_K values on u_node_k_type.

u_node_sort :: [U_Node] -> [U_Node]

Sort by u_node_id.

u_node_k_eq :: U_Node -> U_Node -> Bool

Equality test, error if not U_Node_K.

u_node_rate :: U_Node -> Rate

Rate of U_Node, ie. InitialisationRate for constants. See through U_Node_P. Not used at hsc3 but used by hsc3-dot &etc.

u_node_label :: U_Node -> String

Generate a label for U_Node using the type and the u_node_id.

u_node_in_edges :: U_Node -> [U_Edge]

Calculate all in edges for a U_Node_U.

u_node_from_port :: U_Node -> From_Port

Transform U_Node to From_Port.

u_node_sort_controls :: [U_Node] -> [U_Node]

If controls have been given indices they must be coherent.

u_node_ktype :: U_Node -> Maybe K_Type

Determine K_Type of a control Ugen at U_Node_U, or not.

u_node_is_control :: U_Node -> Bool

Is U_Node a control Ugen?

u_node_is_implicit_control :: U_Node -> Bool

Is U_Node an implicit control Ugen?

u_node_is_implicit :: U_Node -> Bool

Is U_Node implicit?

u_node_localbuf_count :: [U_Node] -> Int

Zero if no local buffers, or if maxLocalBufs is given.

u_node_fetch_k :: Id -> K_Type -> [U_Node] -> Int

Controls are a special case. We need to know not the overall index but the index in relation to controls of the same type.

type U_Node_NoId = (Rate, String, [From_Port], [Output], Special, UgenId)

All the elements of a U_Node_U, except the u_node_id.

u_node_eq_noid :: U_Node_NoId -> U_Node -> Bool

Predicate to locate primitive, names must be unique.

u_node_mk_ktype_map :: [U_Node] -> [(K_Type, Int)]

Make map associating K_Type with Ugen index.

Nodes (Implicit)

type U_NODE_KS_COUNT = (Int, Int, Int, Int)

4-tuple to count K_Types, ie. (InitialisationRate,ControlRate,TriggerRate,AudioRate).

u_node_ks_count :: [U_Node] -> U_NODE_KS_COUNT

Count the number of controls of each K_Type.

u_node_mk_implicit_ctl :: [U_Node] -> [U_Node]

Construct implicit control unit generator U_Nodes. Unit generators are only constructed for instances of control types that are present. The special-index holds the accumulated offset where multiple Control Ugens (at different rates) are present.

Edges

u_edge_multiple_out_edges :: [U_Edge] -> [From_Port]

List of From_Port_U at e with multiple out edges.

Graph

ug_edges :: U_Graph -> [U_Edge]

Calculate all edges of a U_Graph.

ug_empty_graph :: U_Graph

The empty U_Graph.

ug_maximum_id :: U_Graph -> Id

Find the maximum Id used at U_Graph. It is an error if this is not ug_next_id.

ug_find_node :: U_Graph -> Id -> Maybe U_Node

Find U_Node with indicated Id.

ug_from_port_node :: U_Graph -> From_Port -> Maybe U_Node

Locate U_Node of From_Port in U_Graph.

ug_from_port_node_err :: U_Graph -> From_Port -> U_Node

Erroring variant.

Graph (Construct from Ugen)

ug_push_c :: Sample -> U_Graph -> (U_Node, U_Graph)

Insert a constant U_Node into the U_Graph.

ug_mk_node_c :: Constant -> U_Graph -> (U_Node, U_Graph)

Either find existing Constant U_Node, or insert a new U_Node. Brackets are discarded.

ug_push_k :: Control -> U_Graph -> (U_Node, U_Graph)

Insert a control node into the U_Graph.

ug_mk_node_k :: Control -> U_Graph -> (U_Node, U_Graph)

Either find existing Control U_Node, or insert a new U_Node.

ug_push_u :: U_Node_NoId -> U_Graph -> (U_Node, U_Graph)

Insert a primitive U_Node_U into the U_Graph.

ug_mk_node_rec :: [Ugen] -> [U_Node] -> U_Graph -> ([U_Node], U_Graph)

Recursively traverse set of Ugen calling ug_mk_node.

ug_mk_node_u :: Primitive Ugen -> U_Graph -> (U_Node, U_Graph)

Run ug_mk_node_rec at inputs and either find existing primitive node or insert a new one. Brackets are discarded.

ug_mk_node_p :: U_Node -> Port_Index -> U_Graph -> (U_Node, U_Graph)

Proxies do not get stored in the graph. Proxies are always of U nodes.

ug_mk_node :: Ugen -> U_Graph -> (U_Node, U_Graph)

Transform Ugen into U_Graph, appending to existing U_Graph. Allow rhs of Mrg node to be Mce (splice all nodes into graph).

Implicit

ug_add_implicit_ctl :: U_Graph -> U_Graph

Add implicit control Ugens to U_Graph.

ug_add_implicit_buf :: U_Graph -> U_Graph

Add implicit maxLocalBufs if not present.

ug_add_implicit :: U_Graph -> U_Graph

ug_add_implicit_buf and ug_add_implicit_ctl.

ug_remove_implicit :: U_Graph -> U_Graph

Remove implicit Ugens from U_Graph

Graph (Queries)

u_node_descendents :: U_Graph -> U_Node -> [U_Node]

Descendents at U_Graph of U_Node.

PV edge accounting

ug_pv_multiple_out_edges :: U_Graph -> [U_Node]

List PV U_Nodes at U_Graph with multiple out edges.

ug_pv_check :: U_Graph -> Maybe String

Error string if graph has an invalid PV subgraph, ie. multiple out edges at PV node not connecting to Unpack1FFT & PackFFT, else Nothing.

ug_pv_validate :: U_Graph -> U_Graph

Variant that runs error as required.

Ugen to U_Graph

ugen_to_graph_direct :: Ugen -> U_Graph

Transform a unit generator into a graph. ug_mk_node begins with an empty graph, then reverses the resulting Ugen list and sorts the Control list, and finally adds implicit nodes and validates PV sub-graphs.

import Sound.Sc3 {\- hsc3 -\}
ugen_to_graph (out 0 (pan2 (sinOsc ar 440 0) 0.5 0.1))

ugen_to_graph :: Ugen -> U_Graph

Stat

ug_stat_ln :: U_Graph -> [String]

Simple statistical analysis of a unit generator graph.

ug_stat :: U_Graph -> String

unlines of ug_stat_ln.

Indices

ug_ugen_indices :: (Num n, Enum n) => String -> U_Graph -> [n]

Find indices of all instances of the named Ugen at Graph. The index is required when using u_cmd.