/ HALion Developer Resource / HALion Script / Class Reference / Element /

Bus

The Bus class inherits all properties and methods of the Element class.

On this page:

Bus Class, Bus Constructor, findEffects, getEffect, insertEffect, appendEffect, removeEffect, getOutputBus, setOutpuBus

List of inherited members:

Element

Element Class, findChildren, getChild, getParameter, getParameterDefinition, getParameterNormalized, hasParameter, removeFromParent, setName, setParameter, setParameterNormalized

Classes

Bus Class

Description

The Element object of a bus can be obtained with findBusses or getBus. It has the following fields.

Available in: Controller, Processor.

Fields

Example

-- Print the names of the active output busses of the plug-in.

busses = this.program.instance:findBusses()
 
for i, bus in ipairs(busses) do
    if bus.active then
        print(bus.name)
    end
end

Jump to Top

Constructors

Bus Constructor

Bus()

(Since HALion 6.4.0)

Description

Constructor to create a new Bus object.

Available in: Controller.

Return Values

Returns a new Bus object.

Example

-- The following function creates different types of objects in the Program Tree.
-- The objects in the Program Tree do not have a name. You will see only their icons.

function createProgram()
  local inst = this.program.instance
  local prg = Program()
  local bus = Bus()
  prg:appendBus(bus)
  inst:setProgram(prg, 1)
  local layer = Layer()
  prg:appendLayer(layer)
  layer:appendZone(Zone())
  local mm = MidiModule('MIDI Player')
  layer:appendMidiModule(mm)
  local fx = Effect('Distortion')
  bus:appendEffect(fx)
end
 
createProgram()

Jump to Top

Methods

findEffects

findEffects(recursive, nameOrFilterFunction)

Description

Function to find effects in the specified Element object. For example, this.parent specifies the parent of the script module as the Element object to be searched in. To specifiy a bus to be searched in, use getBus or findBusses. If recursive is set to true, subelements will also be searched. The function returns an array with the Effect objects of the found effects. Particular effects can be searched by name or via a filter function. If searching by name, findEffects accepts only the Effect objects that match the specified name. The filter function uses the Effect object of each effect as argument. Only those Effect objects that return true for the search criteria defined in the filter function will be accepted by findEffects. Without a name or filter function, the Effect objects of all effects in the searched Element objects will be returned.

Available in: Controller, Processor.

Arguments

Return Values

Returns an array with the Effect objects of the found effects. Returns an empty table if no effects are found.

Example

-- Find all effects and print their names.
effects = this.program:findEffects(true)
 
if effects[1] then
    for i, effect in ipairs(effects) do
        print(effect.name)
    end
else
    print("Could not find any effects!")
end

Jump to Top

getEffect

getEffect(nameOrPosition)

Description

Function to retrieve the Effect object of an effect from the specified bus. You can use getBus or findBusses to specify the bus. A particular effect can be searched by name or position. The position is the number indexing the effects in the specified bus. If several effects share the same name, only the first match will be returned. If no argument is set, the function returns the first effect that it finds.

Available in: Controller, Processor.

Arguments

Return Values

Returns the Effect object of the found effect. Returns nil if no bus is found.

Example

-- Locate the first bus in the program.

bus = this.program:getBus()

if bus then
    -- Locate the first effect of the bus and print its name.
    effect = bus:getEffect()
    if effect then
        print(effect.name)
    else
        print("Could not find an effect!")
    end
else
    print("Could not find a bus!")
end

Jump to Top

insertEffect

insertEffect(effect, position)

Description

Function to insert an effect at a specific position in a destination bus. The effect to be inserted is determined by its Effect object. You can use getEffect or findEffects to determine the effect. The destination bus is determined by its Bus object. You can use getBus or findBusses to determine the destination bus. The position is the number indexing the effects in the destination bus. The new effect will be inserted before the specified position. To add the effect at the end, use appendEffect instead.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, an Element object that you retrieved from the running plug-in instance must be removed before it can be inserted again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be inserted freely, because these functions create a copy of the Element objects when reading them.

Available in: Controller.

Arguments

Example

To explore the following script:

1. Download Program.vstpreset.
2. Drag the preset on the MediaBay to import it to the user folder for VST presets.
3. Create an empty program and add a script module.
4. Paste the script into the text editor of the script module and execute the script.

-- Insert an effect from Program.vstpreset into the current program.
  
-- Get the file path for user VST presets.
path = getUserPresetPath()
  
-- Load the VST preset.
loadedProgram = loadPreset(path.."/Program/Program.vstpreset")
  
-- Get the first effect from the loaded program.
effect = loadedProgram:getBus():getEffect()
 
-- Get the first bus of this program.
bus = this.program:getBus()
 
-- Insert the effect.
if (effect and bus) then
   bus:insertEffect(effect, 1)
end

Jump to Top

appendEffect

appendEffect(effect)

Description

Function to add an effect to the specified destination bus. The destination bus is determined by its Bus object. You can use getBus or findBusses to determine the destination bus. The effect to be added is determined by its Effect object. You can use getEffect or findEffects to determine the effect. The new effect will be added behind the existing effects. To insert an effect at a specific position in the bus, use insertEffect instead.

❕ An Element object can only have one parent. It cannot be child of multiple parents. Therefore, an Element object that you retrieved from the running plug-in instance must be removed before it can be inserted again. The Element objects that you retrieve through loadPreset or loadPresetAsync can be inserted freely, because these functions create a copy of the Element objects when reading them.

Available in: Controller.

Arguments

Example

To explore the following script:

1. Download Program.vstpreset.
2. Drag the preset on the MediaBay to import it to the user folder for VST presets.
3. Create an empty program and add a script module.
4. Paste the script into the text editor of the script module and execute the script.

-- Insert an effect from Program.vstpreset into the current program.
  
-- Get the file path for user VST presets.
path = getUserPresetPath()
  
-- Load the VST preset.
loadedProgram = loadPreset(path.."/Program/Program.vstpreset")
  
-- Get the first effect from the loaded program.
effect = loadedProgram:getBus():getEffect()
  
-- Get the first bus of this program.
bus = this.program:getBus()
  
-- Append the effect.
if (insert and bus) then
    bus:appendEffect(effect)
end

Jump to Top

removeEffect

removeEffect(effectOrPosition)

Description

Function to remove an effect from a bus. You can use getBus or findBusses to define the bus that contains the effect. The effect to be removed is determined by its Effect object or its position. You can use getEffect or findEffects to determine the Effect object. The position is the number indexing the effects in the bus.

Available in: Controller.

Arguments

Example

-- Remove all effects from the program.
 
busses = this.program:findBusses(true)
 
for i, bus in ipairs(busses) do
    effects = bus:findEffects(true)
    for j, effect in ipairs(effects) do
        bus:removeEffect(effect)
    end
end

Jump to Top

getOutputBus

getOutputBus()

Description

Function to retrieve the currently assigned output bus of a zone or bus.

Available in: Controller, Processor.

Return Values

Returns the Bus object of the currently assigned output bus or nil if the default routing is used.

Example

-- Raise an error if no output bus is assigned.

zone = this.parent:getZone()

assert(zone:getOutputBus(), "No output bus assigned. The default routing is used!")

Jump to Top

setOutputBus

setOutputBus(bus)

Description

Function to assign the output of a zone or bus to the specified output bus. The sending zone or bus is determined by its Element object. The receiving output bus is specified by its Bus object. Setting the output bus to nil enables the default signal routing for the zone or bus.

❕ Output busses that are higher up in the hierarchy of the Program Tree can be assigned freely. If the sending bus and the receiving output bus have the same parent layer, the output bus must come later in the signal flow.

Available in: Controller.

Arguments

Example

-- Assign the output of the zone to the Master output bus of the plug-in.

zone = this.parent:getZone()
masterbus = this.program.instance:getBus(1)
 
zone:setOutputBus(masterbus)
 
print("Output of "..zone.name.." is assigned to "..masterbus.name..".")

Jump to Top