Defining your own decors for the Analog VU meter plugin

You can define your own decors for the Analog VU meter visualization plugin, and make it look almost any way you like.

The look of the Analog VU plugin is defined by textfiles in the (AnalogVU) folder that is inside the plugins-folder, with each textfile containing the definition of one decor. Here is an example of such a definition:

    # Pretty name for this decoder
    name Moldava's VU meter

    # Define a bitmap that we can refer to by name
    # bitmap bitmapalias path-to-bitmapfile [transparentcolor RGBhex]
    bitmap back moldava/moldavaVU_back.jpg
    bitmap front moldava/moldavaVU_front.tga transparentcolor ffffff

    # This bitmap is used for left and right background
    region leftbackground	back 0 0 149 99
    region rightbackground	back 150 0 299 99
    region leftoverlay		front 0 0 149 99
    region rightoverlay	front 150 0 299 99

    # Define the position and movement of the needle
    # needle axisX axisY length zerodegree stroke RGBhex
    leftneedle 75 130 110 122 65 000000
    rightneedle 75 130 110 122 65 000000

The above definition can be used with the background and foreground pictures of the "Moldava" decor (courtesy of Mario Buchichio).
Let's look at this decor-definition in detail:
Comments
Lines that start with # are comments, and are ignored, as are empty lines.

Definitions
Each non-comment line consists of a keyword followed by one or more arguments (which themselves could be keywords). Currently defined keywords are name, bitmap, region, leftbackground, leftoverlay, rightbackground, rightoverlay, leftneedle and rightneedle.

name
The name keyword is followed by the "pretty name" of the decor. This name will be displayed in the decor selection popup. Everything after the name keyword is taken literally, including spaces.

bitmap
The bitmap keywords binds a name to a bitmapfile.
The first argument is the name that will be used to refer to the bitmap in the rest of the decor-definition.
The second argument is the location of the bitmapfile. The bitmapfile may be in any format for which you have a translator installed.
The third and fourth argument are optional. When present, the third argument must be "transparentcolor", and the fourth argument must be the hexadecimal RGB code of the color that is used as the transparent color in this bitmap. Note that if the image contains an alpha channel, this alpha channel will be used to determine transparency, in addition to the specified transparent color.
Also note that it only makes sense to define transparency for the overlay images (see below).

region
The region keyword defines regions within the already defined bitmaps. From this it follows that you must always define bitmaps before you define regions that use them.
The first argument is the name of the region
The second argument is the name of the bitmap that contains the region.
The third and fourth argument specify the top-left coordinate of the region within the bitmap.
The fifth and sixth argument specify the bottom-right coordinate of the region within the bitmap.
Note that multiple regions may refer to the same bitmap, even to the same space within that bitmap.
The following region-names are defined:

- leftbackground - the background image that will be used for the left channel VU meter.
- righttbackground - the background image that will be used for the right channel VU meter.
- leftoverlay - the overlay image that will be used for the left channel VU meter.
- rightoverlay - the overlay image that will be used for the right channel VU meter.

The way drawing of the VU meter works is that first the background image is drawn, the needle is drawn on top of that, and then the overlay image is drawn on top of the resulting image ( using full alpha blending), yielding the final image. Note that the overlay image is optional.

leftneedle/rightneedle
leftneedle and rightneedle define the position and color of the VU meter's needles.
The first two arguments are x and y coordinate of the point around which the needle rotates. It is allowed for this point to be outside of the bitmap. The top-left corner has coordinates (0,0).
The third argument is the length of the needle, in pixels.
The fourth argument is the angle (in degrees) of the zero-position of the needle (using the standard convention that 0 degrees means pointing right, 90 degrees is up, 180 is left).
The fifth argument is the "stroke" of the needle, in degrees. Note that this value can be both positive and negative; a positive value causes a counterclockwise rotation, a negative value causes a clockwise rotation.
The sixth argument is the hexadecimal RGB code of the needle's color.

Size of the VU meter

The total size of the VU meter is derived from the "leftbackground" region. The VU meter will be as high as this region, and twice as wide. The left and right channel meters are always displayed horizontally next to each other. From this it follows that the left and right regions should always be the same size.