hgl 0.5.42~jessie
A compiler/interpreter suite for developing images (plugin development)
The Concept of Control Sources in HGL

Table of Contents

HGL compiles its sources statically and needs an interpreter to execute them. In some cases you want to dynamically interfere in the execution flow of the interpreter, i.e. if you use HGL as a web service to provide customized pictures.

Here the control sources join the game.

Control sources are plugins which gather their input from arbitary sources like from a web form or a database or a simple properties file. This input then is passed to the interpreter while executing the HGL binary. This way it is possible to dynamically control the output of the interpreter.

How it works

In your HGL source you can refer to input from the plugins with '$n' where 'n' is a number specifying the parameter to retrieve.
The interpreter queries the control sources for parameters for the current procedure it executes and returns the n-th parameter if found.
Since there can be several plugins serving the same parameter they add them to the list.

An example

You have to plugins serving two parameters for the procedure 'foo' it will return the parameters '$1', '$2', '$3' and '$4'. To distinguish which parameter came from which plugin, every plugin has a priority. The plugin with the highest priority serves the first values and the next higher priorized serves the next values, and so on.

To see which plugins are installed and their respective priorities you can call hgl with '–list-controlsource-plugins'. It will output something like:

0; Dummy Control Source; Heiko Schäfer; (c) 2013 by Heiko Schäfer heiko.nosp@m.@hgl.nosp@m..rang.nosp@m.un.d.nosp@m.e; [...]
200; CGI Control Source; Heiko Schäfer; (c) 2013 by Heiko Schäfer heiko.nosp@m.@hgl.nosp@m..rang.nosp@m.un.d.nosp@m.e; [...]

The number in front is the priority. Therefore the parameters '$1' and '$2' would be served by "CGI Control Source" and the parameters '$3' and '$4' would be served by "Dummy Control Source".

But you can fine tune the choice of the plugins even more by defining a range from within which priorities the parameters should be served. This can be achieved with '–controlsource-priority-threshold=RANGE' or short '-T'. '-T' takes a parameter in the form "n:m". 'n' specifies the minimum priority, 'm' the maximum (255) priority. All other plugins outside of that range will get ignored.

'-T' allows you define the range in several ways:

"n:m" = from 'n' to 'm'
"n" = exactly 'n'
"n:" = fom 'n' to maximum (255)
":m" = from minimum (0) to 'm'

The default is to include plugins in range "10:245".

In the example '-T 1' would exclude the "Dummy Control Source" plugin and only "CGI Control Source" would serve the parameters '$1' and '$2'. '$3' and '$4' would have no values.

Which kind of values can control sources return?

Control sources return types which can be used as parameters to functions too. These are strings, numeric values, 2D vectors and references to other objects.

How does the plugins serve the parameters?

To find out how the plugins serve the parameters, please consult their respective documentation.