So far, this documentation has described how a single config can specify specific parameters for a scene and how this technique can be applied to create simple configs. Not all of the configs included with SoftSkies, however, behave this way. Instead, the included configs are typically separated into three groups: "component configs" (like those described in the previous section), which specify a subset of parameters for a scene; "super-configs", which choose and combine component configs; and "interface configs" which setup interface elements but which do not change any scene settings. Though component configs can specify any set of scene parameters, the standard set of component configs are further divided into the groups "Colors" and "Backgrounds". This approach allows for far more diversity of cloud scenes. It lets the visualizer dynamically choose from a library of components and combine them into unique scenes based on a user's wishes.

     Component picking is accomplished using a scheme based on "meta-tags", which specify general information about the appearence or "feeling" of a component. The super-configs use these meta-tags to assemble diverse components into coherent scenes. A super-config, might, for example, specify that a user is interested only in bright, fast moving scenes with abstract backgrounds. Instead of keeping a list of specific configs which provide this specific combonation of features, the meta-tags system allows the super-config to find all matching components dynamically.

The Configs Directory Structure

     Before going into detail on each config type is written, the structure of the "Configs" directory is discussed. If you wish to work with a config which interacts with other configs, you'll need to familiarize with how the different categories of configs are organized. Though the structure defined here is not strictly enforced, the convention should be followed so that user-authored configs can be found and executed by the SoftSkies visualizer.

Directory: Configs
Any configs held in the top-level directory are considered super-configs. They are called directly from the visualizer in order to handle configuration. Typically, however, they do not perform configuration by themselves–they choose from component config files stored in subdirectories (described below).

Directory: Configs/Library
A directory containing utility Python files which perform frequently used tasks. These files should not be modified.

Directory: Configs/Backgrounds
A directory of component configs that specify background styles and imagery. If you design custom component configs which specify backgrounds, they should be placed in this directory.

Directory: Configs/Colors
A directory of component configs that specify color schemes. If you design custom component configs which specify color schemes, they should be placed in this directory.

Directory: Other subdirectories
A number of other subdirectories are used to stored resources used by specific configs. These folders should not typically be modified.

Slightly More Advanced Python

     The concepts discussed below will require some additional Python knowledge. Again, this documentation is not intended as a general introduction to the Python language. Only the concepts required to implement SoftSkies configs are covered here. For a more general introduction to Python, see https://www.python.org.

Setting Python Variables

     As configs become more complex, they may need to preform more advanced computations and store the result of such computation in Python variables. In Python, values are assigned to variables using the following syntaxt:

myVariable = 10

     This example shows a variable set to a simple integer, but variables can be set to a wide variety of types including strings, numbers and dictionaries, as described below. More information on setting variables in Python can be found here.

Python Dictionaries

     A "dictionary" in Python is a way to associate one piece of information (a "key") with another (a "value"), much in the way a real dictionary associates a word with its meaning. Dictionaries are used in SoftSkies to associate keywords with numerical values in order to specify meta-tags and meta-tag queries. In a meta-tag information dictionary or a meta-tag request dictionary, each meta-tag keyword is associated with a value indicating the keyword's importance. The specfics of meta-tag dictionaries are explained in more detail below. For the moment, however, we examine the syntax of a dictionary in Python.  The first example below creates a dictionary with values for 3 different keys. Dictionaries can hold any number of elements, including 0. The second example shows an empty dictionary.

myQuery = { 'myKey1' : 1, 'myKey2' : 2, 'myKey3' : 3 }
    
myQuery = {}

     More information on dictionaries in Python can be found here.

Defining Functions and "Callbacks"

                    def functionName():
                        line-of-code-1
                        line-of-code-2
                        ...
                        line-of-code-n
                    
                    

                    def myCallback():
                        SoundSpectrum.SetRGBColor( "cloud_color", 0, 0, 1 )
                        SoundSpectrum.SetParameter( "cloud_camera_angle", 0.0 )
                    
                    

Writing Component Configs

     As discussed previously, a component config simply sets a number of scene parameters in a certain way. In order for the component config to be picked by super-configs, however, some additional code is required. Component configs are picked based on the meta-tag qualities they exhibit. The Natural config, for example, does not keep a list of natural-looking components by name. Instead, it uses the "Natural" meta-tag to locate all of the components which fit the description. In this way, new component configs can be introduced at any time and the Natural config will find them. Additionally, super-configs can request multiple meta-tags in order to pick more specific components. A list of standard meta-tags used with SoftSkies is shown in the next section.

     To make a component config work with meta-tag requests (and thus allow it to be picked, when appropriate, by existing super-configs), a config must define a method called getMetaTags(). getMetaTags() should return a dictionary defining the meta-information about the component config. The dictionary should contain a list of meta-tag keys and a values, on a scale from -5 to 5, representing how strongly they fit the tag. Meta-tags which do not have values in the dictionary are implicitly interpreted as 0–a meta-tag value of 0 indicates that the config is neutral with respect to a certain quality.

     An example getMetaTags() function is shown below. These meta-tags indicate that the config is very bright, somewhat natural, but not very colorful.

                    def getMetaTags():
                        return { 'Bright' : 4, 'Natural' : 2, 'Colorful' : -3 }

     For a given meta-tag describing a quality of the component config, the following table indicates how the tag value should be assigned.

     The classification of meta-tags in configs is not an exact science, but it's usually possible to give a good indication of whether a certain quality is fulfilled by a config. The goal is to simply give the super-configs some an indication of what a config is like without knowing exactly what it does.

Standard Meta-Tags for Included SoftSkies Configs

The following meta-tags are used for the config files distributed with SoftSkies. When creating your own configs, you can create and use any meta-tags you desire. Arbitrary meta-tags can be specified, though they are only effective if they are used by both component configs and super-configs. If a meta-tag appears in a component config, but is never requested by a super-config, the meta information for that tag will not be used.

• Bright: specifies whether a config produces light or dark imagery
• Natural: specifies whether a config produces natural or unnatural imagery
• Colorful: specifies whether a config produces colorful or non-colorful imagery
• SunSets: specifies whether a config can be classified as a sunset
• Storms: specifies whether a config can be classified as a storm

Writing Super-Configs

     Super-Configs work by choosing and running component configs based on meta-queries. To choose component configs, a super-config will typically use the function SoundSpectrum.PickConfig(), and to execute the component, the super-config will typically call SoundSpectrum.RunFile().

     The function SoundSpectrum.PickConfig() expects two parameters: a string specifying the directory to search (relative to the Configs directory) and a dictionary describing the meta-query. The meta-query dictionary takes the same form as the dictionary returned by the getMetaTags() function described in the previous section: each dictionary key specifies a value indicating to importance of each meta-quality on a scale from -5 to 5. Positive values indicate that a quality is desirable while negative values indicate that the quality is undesirable. If a quality is not specified or its value is 0, the quality is not used in the search. SoundSpectrum.PickConfig() returns another dinctionary, which includes the name of the component config it picked with the key "Filename". The following example picks a color scheme from the "Colors" directory which is "Natural" but not too "Bright". The relative weights of the two tags specifies that the desire for a "Natural" config is more important than the desire for one that is not bright:

color = SoundSpectrum.PickConfig( 'Colors', { 'Natural' : 5, 'Bright' : -2 } )

     Once a config has been chosen, it is executed using the function SoundSpectrum.RunFile(). To use SoundSpectrum.RunFile(), simply pass it the name of the file selected with SoundSpectrum.PickConfig():

SoundSpectrum.RunFile( color[ 'Filename' ] )

Using these two functions, you can assemble a simple super config which picks and then executes component configs.

Super-Config Callback Functions

     Code in the main body of a super-config file gets executed as soon as the config is loaded. So while we can now construct a config which generates a scene as soon as it is run, we cannot yet construct a config which creates new scene settings continuously. In order to generate custom new scene parameters each time a scene transition occurs, the super-config must provide callback methods. A callback method is a special Python method which is called internally from the SoftSkies engine in response to certain events. Callback methods have special names that the SoftSkies engine will look for, and if your config implements these methods, they will be called automatically when appropriate. By convention, all of the callback function names used by SoftSkies begin with "Handle". The standard SoftSkies callback function are described below.

HandleNewScene()

     This function is called when a new scene is created. This function changes scene colors, backgrounds or any other parameter that the config controls. You should typically use a >HandleNewScene() to pick new semi-random scene parameters. That means that the function will change backgrounds or colors somewhat, while still maintaining the overall look and feel of your config.

     Most of the standard configs implement this function to pick new component configs when the scene is changed. For certain configs, however, namely those that wish the allow a style to persist until it is explicitly changed (such as the SceneBuilder), this function may not make any changes to the scene.

 

HasCustomMenu()

     This function must return 1 if a config has a custom menu associated with it. If this function is defined and returns 1, a config may add entries to the SoftSkies menu (and is expected to do so!). More detail on using custom menus is given in below in the section "Custom Interfaces".

An Example SuperConfig:

     Combining the topics covered in the previous two sections, it is now possible to create a super-config which dynamically generates new scene parameters at every scene transition. To do so, a super-config will implement a HandleNewScene() callback function which picks and executes component configs based on some meta-tag query. A sample super-config, Natural.config, is shown below:

                    def HandleNewScene():
                        color = SoundSpectrum.PickConfig( 'Colors', { 'Natural' : 5 } )
                        background = SoundSpectrum.PickConfig( 'Backgrounds', { 'Natural' : 5 } )
                    
                        SoundSpectrum.RunFile( color[ 'Filename' ] )
                        SoundSpectrum.RunFile( background[ 'Filename' ] )
                    
                        print "Created new scene!"
                    
                    HandleNewScene()

     Code outside of function definitions is executed immediately and is considered to be initialization code for the config. In this case, the config the HandleNewScene() function immediately so that the config picks a new color and background as soon as it is executed. In addition, the HandleNewScene() function will be executed again each time the scene changes and new component configs will be picked. The HandleNewScene() function shown here uses the SoundSpectrum.PickConfig() method to choose component configs based on meta-queries and then executes them. As a final touch, this function will print out the message "Created new scene!" to the SoftSkies text console each time the scene is changed

     Note that for some configs, it is undesirable to pick new colors and backgrounds at each new scene. In these cases, the config author may choose not to implement a HandleNewScene() function at all, and instead implement all config execution directly from the initialization code. Additionally, a config author may opt not to use SoundSpectrum.PickConfig() at all, and instead select predetermined component configs by name.

Custom Interfaces

     A final feature of configs is the ability to modify the SoftSkies menu to allow users to interact with a config. The menu may be configured to allow users to navigate through available settings (as with the main "Skies Library", which is itself generate by a config file), or it may allow users to interact with a running config (as with the "Skies Builder", also a config!). In order to setup a custom interface with a config, your config must implement the callback function HasCustomMenu(), and the function must return 1. The functions used for creating custom interfaces are listed below and discussed in more detail in the section "The SoundSpectrum Config API"

• SoundSpectrum.SetHelpImage( imagepath ): sets the help image in the center of the screen
• SoundSpectrum.AddButton( title, action [, iconpath ] ): adds a button to the interface menu
• SoundSpectrum.AddSlider( title, action, minvalue, maxvalue ): adds a slider to the interface menu
• SoundSpectrum.GetControlValue( object ): returns the value of an interface object (created using SoundSpectrum.AddButton or SoundSpectrum.AddButton)

The Power of Python

     So far this document has described the features that SoftSkies provides to allow interaction with the engine. What this documentation does not cover is the unlimited potential of the Python scripting language and how all of the features of Python can be used to further customize the SoftSkies experience. Python includes advanced support for text processing, file handling, networking and much more–all of these features can be used to create SoftSkies configs with unique behaviors.

• Download customized cloud settings from a webserver
• Upload information about a selected configs to a webserver
• Create a SoftSkies based RSS Reader
• Dynamically generate custom config files
• Interface with any other program or code you have!

The SoundSpectrum Config API

     A number of utility functions are available for constructing customized SoftSkies configs. Collectively, these functions are part of the "Sound Spectrum Config API". The API functions are described below:

     For detailed examples of how these API calls are used, see the "Skies Designer" config located in "Configs/Library/Menus/Skies Designer.config".