Power PlugIn SDK v1.02 to make own Skins
========================================
This file ("pwrp-sdk.txt") will describe how to make your own
skins for Power PlugIn.
You are not allowed to change this file nor any of the files
delivered with the Power PlugIn package.
Please notice, that the version number of this SDK is not
identical to the version number of Power PlugIn itself.
SDK v1.02 was introduced with Power PlugIn v1.03.
Please read this file with a font with fixed width.
For a description of Power PlugIn and how to install, configure
and use it, as well as copyright and license information,
read the file "readme_powerp.txt".
For a description, what files you should deliver with your own skin and
which one must be included, read section "HOW TO DELIVER YOUR SKIN(S)"
in the file "readme_powerp.txt" which should have been delivered with
the Power PlugIn package.
HOW DOES POWER PLUGIN LOAD THE A SKIN FOR SPEED:
------------------------------------------------
When started, Power PlugIn will load the selected Design.
It will load *all* images of the selected Design. This means
that the images for all sizes of the music-player window
will be loaded at startup.
This can result in long loading times (some seconds)
(including the analysation and optimization process).
For a description about the analysation and optimization
process, see section "HOW DOES POWER PLUGIN ANALYSE AND
OPTIMIZE A SKIN:" below.
DIRECTORY STRUCTORE OF SKIN FILES:
----------------------------------
Let me start with a description, how the files for Power PlugIn Skins
should be stored.
Power PlugIn has a specific location where its skins are stored.
The user can select a path for all skins of its desire, but by default, the
Skin path is set to "powerp\Skins" (which is relative to the path where
Power PlugIn is installed to).
Example: Imagine Power PlugIn is installed in "C:\Program Files\WinAmp\PlugIns"
then the Skins will be reside by default in
"C:\Program Files\WinAmp\PlugIns\powerp\Skins".
Now each subdirectory in the skin-path contains a skin and the name of each
subdirectory is the name of the skin itself.
Example: With the Power PlugIn archive you should have received a skin
named "HiFi-X".
Such a subdirectory should contain a file "skin.txt" which contains
the definition of the skin. The syntax and required contents of the file
"skin.txt" will be described later.
Furthermore the subdirectory should contain a "readme.txt". What the
readme should contain will be explained in the section "HOW TO DELIVER
YOUR SKIN(S)" below.
Then the subdirectory should also contain all the images the skin
will use. These images can be placed in the subdirectory itself or
in deeper subdirectories with names of your desire.
The locations of the images will then be referenced in the "skin.txt" file.
Example: My "HiFi-X" skin directory structure (nearly) looks like this:
HiFi-X\skin.txt the skin definition file
HiFi-X\116\ contains the images for WinAmp's normal size
HiFi-X\126\ contains the images for ModPlug
HiFi-X\232\ contains the images for WinAmp's double size
SYNTAX AND CONTENTS OF FILE SKIN.TXT:
-------------------------------------
Note: If you want to know how to design a skin so that Power PlugIn can
execute it as fast as possible, see the section "HOW TO DESIGN
A PLUGIN FOR SPEED" below.
1/ Syntax of the file "skin.txt":
------------------------------
The syntax of the file "skin.txt" is arranged like the registry
but in textual format. It is similar to normal "*.ini"-files,
but with the difference that it can support keys and subkeys.
First of all, that "skin.txt" can be interpreted as valid configuration
file, one text line should contain only the following text:
PRIVATECONFIG1
This text should not have any preceeding and trailing spaces nor
it should contain other characters.
All text lines before the line containing "PRIVATECONFIG1" will be
ignored. All following lines will be interpreted as part of
the configuration information.
The configuration can contain keys and values. Each name (of key
or value) must be encapsulated in " quotation marks (to be able
to include spaces in the names).
Each key-name brackets will follow enclosing subkeys or values.
Example key:
"Some Key"
{
}
Values can be strings, double-words or binary-fields.
After each value defintion, a ; character must follow
( like in C/C++-language ).
Double-word values normally are in hexadecimal mode. But when you
preceed the value with a # character, it will be in decimal mode.
Example values:
"Some String" = "This is a string.";
"The same string" = "This is "
"a string";
"A Hex Double Word" = dword: F0;
"A Decimal Double Word" = dword: #250;
"A negative Double Word" = dword: #-20;
"A Binary Field" = hex:00,01,02,03,fc,fd,fe,ff;
"The same Binary Field" = hex:00,01,
02,03,
fc,fd,
fe,ff;
Some words about strings:
A string has a special syntax format. It is similar to the format of
C/C++-strings. If a "\" character is found in the string, the following
character(s) indicate a special escape-sequence. The sequences are (mostly)
the same as for C/C++-strings.
The following escape-sequences are supported:
simple-escape-sequence:
\a \b \f \n \r \t \v \' \" \\ \?
octal-escape-sequence:
\ octal-digit
\ octal-digit octal-digit
\ octal-digit octal-digit octal-digit
In here, a maximum of 3 oct-digits are supported.
hexadecimal-escape-sequence:
\x hexadecimal-digit
hexadecimal-escape-sequence hexadecimal-digit
In here, a maximum of 3 hex-digits are supported.
Example: If you define a string like
"a String\nwith \"escape-sequences\"\nsamples: \\ \x41 \102"
this will represent the following text sequence:
a String
with "escape-sequences"
samples: \ A B
You can include remarks in the configuration information:
Like in C++-language, there are 2 remark methods:
- If a line contains a "!" character, all following characters only
in that line will be ignored ( similar to the C++ "//" remark ).
- All text within a "[<" and ">]" section will be ignored ( similar
to the C/C++ "/*" and "*/" remark ).
There is some small bug:
Imagine following remark constellation:
[< start of remark
remark continues here. ! and now the end of remark should follow >]
"a string"="this should be a valid string value";
In this example, the remark will start with "[<". And it should end
with the ">]". But the ">]" will not be interpreted as end
of remark, because a "!" character is preceeding in that text line.
The result will be that the value "a string" still is interpreted to
be inside a remark section and therefore will be ignored.
Sorry about this.
Be sure to prevent this case.
The example above would be valid if you write it like this:
[< start of remark
remark continues here. ! and now the end of remark should follow
>]
"a string"="this should be a valid string value";
Some more notes about "skin.txt":
---------------------------------
Power PlugIn will only read the file "skin.txt". It will never write
to it or change it in any way.
2/ Contents of the file "skin.txt" for defining a skin:
----------------------------------------------------
First Note: The best example how to make a "skin.txt" file you can
find in the "HiFi-X" skin delivered with the Power PlugIn package.
A Skin is designed in an hierarchical order.
It consists of one or more Designs.
Each Design is intended for one Music-Player. But it is also
possible to make more Designs for one Music-Player and let the
user select the Design he wants.
Each Design contains a Scheme for one size of the Music-Player
window (escpecially its height).
Supprted are: normal size, double size, windowshade size, windowshade
double size.
Finally a Scheme contains
- a height value for Power PlugIn to know for which height
the Scheme is intended.
- the plugin-window definitions with their animations.
On root of the "skin.txt" file there must be two keys:
> The "Design" key contains subkeys where each subkey represents
a design and the subkey's name is the name of the design.
One of these designs the user will be able to select
in the configuration of Power PlugIn.
> A key named "Schemes" which contains subkeys. Each subkey
contains the definitions of a scheme. A subkey's name is
the name of the Scheme.
The names of the schemes will be referenced by the Design
definitions.
> In addition, there can (but need not) be values for global
settings.
Supported values are:
- "Start Message" for displaying a startup message.
This is a string value.
If it is defined, the string will be displayed in a
startup dialog when the Power PlugIn is started.
Note: In the settings of Power PlugIn you can select
if the start message dialog shall be dismissed
automatically.
Each Design definition must contain a value "Normal Size".
It contains the name of the scheme to use for normal size of
the player window.
Example:
"Designs"
{
"First Design"
{
"Normal Size" = "First Scheme";
}
}
"Schemes"
{
"First Scheme"
{
! ... in here, the scheme will be defined
}
}
Besides the "Normal Size", there can be defined:
"Double Size" for double size of the player-window
"WindowShade Size" for windowshade size (like for WinAmp)
WindowShade means, that the player is
just a titlebar.
"WindowShade Double Size" for windowshade but also double size
If more than only normal-size is defined, then Power PlugIn will select
that scheme to be visible which height-value "Height" is closest to the
current player-window's height.
Example:
"Designs"
{
"First Design"
{
"Normal Size" = "Normal Scheme";
"Double Size" = "Double Scheme";
}
}
"Schemes"
{
"Normal Scheme"
{
"Height" = dword: #116;
! ... and some other scheme definitions
}
"Double Scheme"
{
"Height" = dword: #232;
! ... and some other scheme definitions
}
}
In this example, the "Normal Scheme" will be displayed when the
player-window's height is 116 or greater. But if the height
is 232 or greater, "Double Scheme" will be displayed instead.
Of course, if the window height is less than 116, Power PlugIn will
use the closest scheme, which is "Normal Size".
Some other options for Designs:
-------------------------------
- Which design should be used as default (before the user explicitely
selects one in the Power PlugIn configuration) ?
Normally, the first defined Design will be used.
Example:
"Designs"
{
"Design for WinAmp"
{
! ... some design definitions
}
"Design for ModPlug"
{
! ... some design definitions
}
}
In this example, the default design is "Design for WinAmp", no
matter which music-player you are using.
But if you would want ModPlug to use "Design for ModPlug" as
default Design, you can define a mask string for the
"Default if Player class name matches" value or the
"Default if Player window title matches" value.
Example:
"Designs"
{
"Design for WinAmp"
{
! ... some design definitions
}
"Design for ModPlug"
{
"Default if Player class name matches" = "*modplug*";
! ... some design definitions
}
}
or:
"Designs"
{
"Design for WinAmp"
{
! ... some design definitions
}
"Design for ModPlug"
{
"Default if Player window title matches" = "*modplug*";
! ... some design definitions
}
}
For definition of "Default if Player class name matches" value:
The design "Design for ModPlug" will be used as default design if
the player-window's class name matches one of the masks in the
mask string.
For definition of "Default if Player window title matches" value:
The design "Design for ModPlug" will be used as default design if
the player-window's title matches one of the masks in the
mask string.
The mask string can contain one or more masks seperated by ";"
characters.
Each mask is a case-INsensitive string supporting wildcards
Supported wildcards:
* specifies and string of any length
(even length zero).
? specifies any character
[afex-z] specifies a list of characters which must match
the current character ( in this example the
current character must be 'a', 'f', 'e', 'x', 'y' or 'z',
no matter which letter case ).
[?] the current character must be a '?' char.
[;] the current character must be a ';' char (and the ';'
char is not interpreted as the end of a mask which will
be followed by another mask. see description below).
Example:
"*mp*3*pl*" will match with class names like
"MPEG3 Player" or "The super mp3player v1.0".
You can also define more than one mask, if you seperate them
by ";" characters.
Example:
"music*pl*;song*pl*" will match with class names like
"MusicPlayer" or "Music Player v1.0" but also "Song-Player"
or "Songs Player v2.0" etc.
How a Scheme is designed:
-------------------------
A Scheme contains one or more plugin-windows for each of the 4 sides
of the music-player window.
Each window contains a background image (maybe with mask to support
non-rectangular windows) and zero, one or more animation definitions.
An animation can be made of a list of images or by a drawing.
Different types of animations are supported.
In the "skin.txt" a Scheme can contain up to 4 keys each representing
a side of the music-player-window: "Left", "Right", "Top" and "Bottom".
Example:
"Schemes"
{
"A Scheme"
{
"Height" = dword: #116;
"Left"
{
! ... definitions for plugin-windows on the left side
! of the player-window.
}
"Right"
{
! ... definitions for plugin-windows on the right side
! of the player-window.
}
"Top"
{
! ... definitions for plugin-windows on the top side
! of the player-window.
}
"Bottom"
{
! ... definitions for plugin-windows on the bottom side
! of the player-window.
}
}
}
The order of the 4 keys is not important.
The plugin-windows created on the left side of the player window will
be positioned like that: The first plugin-window will be positioned on
left side of the player window without space in between.
The next plugin-window will be created on the left side of the previous
plugin-window, and so on...
So the plugin-windows will be created on a chain on the left side of
the player window.
With an option "Image ? Window Offset", described later, you will be able
to move a plugin-window away from its default position.
If a left plugin-window is aligned on the top, center or bottom, can be
defined using the "Image ? Align" option which will be described later.
In similar ways, this also belongs to the right, top and bottom sides.
How to create plugin-windows at one side of the player window:
For this, you will have to define a number of images where each image
will represent the background image for one plugin-window. The width
and height of the plugin-window will be as large as the smallest
bounding rectangle around the visible parts of the image (with or
without mask).
Example for the left side of the player window:
"Schemes"
{
"A Scheme"
{
"Left"
{
"Number of Images" = dword: #2;
"Image 1" = "img1.bmp";
"Image 2" = "img2.bmp";
"Image 2 Mask" = "mask2.bmp";
! ... some other definitions
}
}
}
First of all, the number of plugin-windows to be created on that side
of the player window must be defined using the "Number of Images" option.
Note: The order of the value-definitions in "skin.txt" is not important
within one key. Also the order of subkeys within one key is not important
except in cases where it is explicitely described (ie. the order of animations
for each plugin-window, but this will be described later).
In the example above, 2 plugin-windows will be created on the left side of
the player window.
The first will use "img1.bmp" as background image,
the second will use "img2.bmp" as background image with a mask image "mask2.bmp".
I will speak about the masks a bit later.
First lets talk about image definitions in common in the file "skin.txt".
Please remember that image defintions not only belongs to defining plugin-windows
but also to define animations with images (I will explain animations later).
So as shown above, "Number of Images" tells the number of images which will
be loaded within that key.
The images themselves will be defined by "Image ?" definitions where the "?"
character here means only a number starting from 1 till the number of images.
This number *must not* have preceeding zeros. So a value like "Image 01"
will not be interpreted as image definition and will be ignored. As well the
spaces in between should be always only one space character. Definitions like
"Image 1" also will be wrong and therefore ignored.
Correct will be something like that: "Image 9", "Image 10", "Image 315" etc.
For one image, there will be several options which can be defined. I will list
them later. But you should remember, that the prefix always should be "Image ?".
So ie. a mask will be defined with the option "Image ? Mask" as shown in the
example above.
It can be that you want to define a large number of images.
In that case you will not have to write the options for each image separately.
A prefix of "Image n" instead of "Image ?" (where "?" means a number) is supported.
Example: The example from above can look like this as well:
"Number of Images" = dword: #2;
"Image n" = "img?.bmp";
"Image 2 Mask" = "mask2.bmp";
For an "Image n" or "Image n Mask" option (masks will be described later),
the file name specified may contain one or more "?" characters. These characters
will be replaced by the number of an image starting with 1 till the number of
images specified.
You should include as many "?" chars in the filename as there can be chars for
the largest number.
Example:
"Number of Images" = dword: #315;
"Image n" = "img???.bmp";
In this example, images with numbers from 1 to 315 will be loaded. So there
should be 3 "?" chars since the largest number (315) contains 3 chars.
If a number has less chars as the number of "?" chars provided, the number
will be preceeded by zeros.
Example from above will try to load the following images:
img001.bmp
img002.bmp
img003.bmp
....
img314.bmp
img315.bmp
If for one image option, there is present an option with a "Image ?" prefix
as well as a "Image n" prefix, then the option with the "Image ?" prefix
will be used and the option with the "Image n" prefix will ignored for that
special index.
Example:
"Number of Images" = dword: #20;
"Image n" = "img??.bmp";
"Image 18" = "other.bmp";
This example will load the following images:
img01.bmp
img02.bmp
....
img16.bmp
img17.bmp
other.bmp
img19.bmp
img20.bmp
You see instead for image 18, option "Image n" will be ignored because
the option "Image 18" has been defined.
This belongs not only to the images themselves but also for all other options
using "Image ?" or "Image n" as prefix.
You can define images using "Image n" but specifying *no* "?" character in
the filename. This will cause the same image file to be loaded for
all images.
Example:
"Image n" = "image.bmp";
"Image n Mask" = "mask.bmp";
This can make sense ie. for animations of type thermometer (described later)
which can use just the same image but on different locations (which
can be manipulted using "Image n Move Origin" option described below) or
in different colors (which can be changed using "Image ? Colorize" or
"Image n Color Fade" option described below).
Now a list of all common options possible for Image definitions using
"Image ?" or "Image n" as prefix.
Please notice, that in the list, I use prefix "Image ?", but you can
use prefix "Image n" instead as well.
If only one of these 2 prefixes are supported for an option, it will be
explained explicitely at the option description.
The list contains image options which always can be used for image definitions,
no matter if the image definition is used to define a plugin-window or to
define an animtion with images (animations are described later).
- "Image ?"
This option will load an image. For prefix "Image n", the filename can contain
"?" chars as described above.
You can also define paths followed by the filename.
Please remember, how in "skin.txt" a string should be specified: It has
predefined special chars which are intruded by a "\" char (similar to
the C/C++-string-syntax as described above in section
"Syntax of the file "skin.txt"").
So if you specify a path, it could look like this:
"images\\img1.bmp"
You see, 2 "\" chars must be specified.
Please notice, you should *not* specify absolute paths (with drive letters)
since you cannot know the directory structure of other computers than yours.
I strongly recommend to use *only* relative paths.
The paths will be relative to the location where the "skin.txt" file is
located.
Example:
Imagine the "skin.txt" file is located in
"C:\Program Files\WinAmp\PlugIns\powerp\Skins\My_Skin".
Following is a list of example definitions with relative paths
on the left and the corresponding absolute paths with filename
on the right side:
"img1.bmp" C:\Program Files\WinAmp\PlugIns\powerp\Skins\My_Skin\img1.bmp
"images\\img1.bmp" C:\Program Files\WinAmp\PlugIns\powerp\Skins\My_Skin\images\img1.bmp
"..\\Other_Skin\\img1.bmp" C:\Program Files\WinAmp\PlugIns\powerp\Skins\Other_Skin\img1.bmp
"..\\Other_Skin\\pictures\\img1.bmp" C:\Program Files\WinAmp\PlugIns\powerp\Skins\Other_Skin\pictures\img1.bmp
You see, you can also specify ".." for parent path. You can specify
it also multiple times (if you could use it), e.g.:
"..\\..\\..\\pics\\an_image.bmp".
Following is a list of image file types which can be loaded:
*.bmp
*.dib
*.pbm
*.pcx
*.pgm
*.ppm
*.rle
*.tga
Sorry, but JPG, GIF and PNG are not supported.
Maybe JPG and PNG will be supported in future.
- "Image ? Mask"
With this option, you can define to use a mask which specifies which
parts (or even pixels) of the image are opaque and which ones are
transparent.
A filename can be specified using the "Image ? Mask" or "Image n Mask"
option. The syntax of the filename is the same as for the "Image ?"
and "Image n" options described above.
There are 3 options which influence mask handling:
"Image ? Mask"
"Image ? Glass Color"
"Image ? Use Glass"
If neighter of the 3 options is specified, no mask is used for the
current image and the whole image will be opaque.
If eighter "Image ? Mask" is specified, or only "Image ? Glass Color",
or both are specified, then the usage of a mask will be enabled and
the image can contain transparent parts.
If you explicitely set "Image ? Use Glass", then this option will
enable or disable the usage of a mask no matter if the other 2 options
are specified or not.
If you only specify the "Image ? Mask" option, then the mask image
should contain white pixels for pixels which should be transparent.
All other colors in the mask image will be interpreted as opaque.
If you only specify the "Image ? Glass Color" option, then Power PlugIn
will generate a mask internally using the image of "Image ?" option.
The "Image ? Glass Color" will specifiy an RGB (red-green-blue) color
which indicates the transparent color. All pixels in the image of
"Image ?" option with that color will be transparent.
The "Image ? Glass Color" option is a dword of format RRGGBB (hexadecimal).
Example:
"Image 1 Glass Color" = dword: A024FF
In this example the color is specified as red=160, green=36, blue=255.
If you specify both, the "Image ? Mask" option as well as the
"Image ? Glass Color" option, the "Image ? Mask" option specifies
the mask image, but the transparent color is not white any more.
The transparent color is specified by the "Image ? Glass Color"
option.
With the "Image ? Use Glass" option, you can explicitely enable or disable
the usage of a mask.
This option is a boolean. A value of 0 means it is set to false, each other
value means it is set to true.
Example:
"Image 1 Use Glass" = dword: 0;
will disable the usage of a mask, no matter if the "Image ? Mask" and/or
"Image ? Glass Color" options are specified.
"Image 1 Use Glass" = dword: 1;
will enable the usage of a mask, even if none of the "Image ? Mask" and
"Image ? Glass Color" options is specified.
So if the usage of a mask is enabled, but none of the "Image ? Mask" and
"Image ? Glass Color" options is specified, the mask will be generated
from the image specified by the "Image ?" or "Image n" option. It pixels
with total white color will be interpreted as transparent.
You see, with masks, you can set pixels to be completely opaque or
completely transparent.
Sorry, but the degree of transparency (which is called alpha-blending)
is not supported (yet) for images.
Some notes to plugin-windows:
If you specify a mask for a plugin-window's background image, then the
plugin-window can be non-rectangular according to the transparent parts
of the mask.
- "Image ? Glass Color"
See description to "Image ? Mask"
- "Image ? Use Glass"
See description to "Image ? Mask"
- "Image ? Origin"
This option (a string) will position the image (including a mask if present)
relative to an imaginary coordinate-space-origin.
If this option is not specified, the origin will be set to "0,0" which
means it is on the top left corner of the image.
The specified coordinates have the format "x,y" where x is a coordinate
in x-direction (horizontal, where positive values reach from left to right)
and y is a coordinate in y-direction (vertical, where positive values
reach from top to bottom).
The specified coordinates indicate the offset of the top left corner
of the image relative to the imaginary origin.
Example:
"Image 1 Origin" = "-1,12";
means that the top left corner of the image is at position x=-1, y=12.
Note: The string should not contain any spaces.
To origin is fixed to the position defined by the background image's
origin definition (of a plugin-window).
All other images, which may be defined in animations of that
plugin-window, will be relative to the same imaginary origin.
Example (how to specify animations is described later):
"Left"
{
"Number of Images" = dword: 1;
"Image 1" = "img1.bmp";
"Image 1 Origin" = "-1,12";
"Image 1 Anims"
{
"An Animation"
{
"Number of Images" = dword: 4;
"Image n" = "anim?.bmp";
"Image 1 Origin" = "-2,9";
"Image 2 Origin" = "-1,12";
"Image 3 Origin" = "0,15";
"Image 4 Origin" = "1,18";
}
}
}
In this example the background image is at position -1,12 relative
to the imaginary origin while the first anim image is at position -2,9.
This means that the first anim image is at position -1,-3 relative
to the background image. ( -1,-3 is calculated from (-2)-(-1),(9)-(12) ).
In the example above you see 4 origin definitions which all have the
offset 1,3 relative to the previous origin definition.
Such a case can be realized by an easier definition:
"Image n Origin" = "-2,9";
"Image n Move Origin" = "1,3";
With the "Image n Move Origin" option (a "Image ? Move Origin" is
not supported since it makes no sense) you can define a dynamic
offset of the origin for n images while you only need to write
2 lines of text.
The calculation of the origin for image X from the example above
will be: -2+(X-1)*1,9+(X-1)*3
which will result in the 4 origins from the example above.
The "Image n Move Origin" can be very helpful for animations of type
thermometer (described later).
See "HiFi-X" skin delivered with the Power PlugIn package for
a nice example.
Some notes to masks:
When a mask is specified and mask is looking like an image having
somewhere in the middle the opaque parts where at the borders it is
transparent, then Power PlugIn will load only that rectangular part
of the image which matches the smallest bounding rectangle of the
opaque area. This means that the loaded rectangular area is smaller
than the real image.
In such a case, do *not* forget, that the origin definition is
relative to the top left corner of the image and not of the smaller
image which has been cropped internally by Power PlugIn.
For you, the designer of the skin, it is not important to know how
Power PlugIn stores its images internally. For you, it is only
interresting, that the *top left corner* of the image has an offset
from the imaginary origin.
- "Image n Move Origin" (a "Image ? Move Origin" option does not exist)
See description to "Image ? Origin" above.
- "Image ? Rect" and
"Image ? Mask Rect"
You can define a rectangle which will be cut out when the image (or
mask image) is loaded. Only the rect-area will be used as (mask) image.
This is helpful if in one image file there are stored several images.
"Image ? Rect" makes sense only if a "Image ?" is defined.
"Image ? Mask Rect" makes sense only if a "Image ? Mask" is defined.
Please notice, that cutting out a rectangle does *not* affect the
image's origin. If the origin definition was ie. "0,0" then cutting
out a rectangle will cause the new image's top left corner (which
is the top left corner of the rectangle) to be relative to the
imaginary origin with offset "0,0".
Format: "x,y,cx,cy" where x is the x-coordinate (horizontal direction
with positive values on the right) and y is the y-coordinate
(vertical direction with positive values from top to bottom direction).
x and y define the top left point of the rectangle. The coordinates are
relative to the top left corner of the source image.
cx is the width and cy is the height of the rectangle.
Be sure to define a rectangle which compeletely lies inside the
source image's rect are. So if an image has a width 320 and height
240, the largest rectangle you may define is "0,0,320,240".
It is *not* guaranteed what will happen if only one side of the
rectangle exceeds the image's dimensions.
Example:
"Image 1 Rect" = "100,0,50,50";
"Image 1 Mask Rect" = "0,200,50,50";
- "Image ? Index" and
"Image ? Mask Index"
Now this is a little bit complicated. I hope I can explain it to you
so that it is clear to you.
Power PlugIn will store as many images as necessary but as few
images as possible.
(When I am speaking of images, then I mean an image defined by "Image ?"
but I also mean an image defined by "Image ? Mask". So this means, that
the images from "Image ?" themselves are stored separately and images
from "Image ? Mask" are also stored separately).
Now if you are using the same images multiple times, Power PlugIn will
load only one instance into memory.
But Power PlugIn has a complicated mechanism to determine, if an image
references in the skin definition are the same.
For Power PlugIn, an image definition is identical to anotherone if
1/ the filenames in "Image ?" are the same, and
2/ if the glass color and glass color usage are the same, and
3/ if the "Image ? Rect" or "Image ? Mask Rect" are the same, and
4/ has the same index (defined by "Image ? Index" or "Image ? Mask Index").
By default (if no index is specified), each image will be loaded as having
the index 1.
Now if you specify an image definition ie. twice, you could specify an index
of 2 for the second image definition which will cause Power PlugIn to
store 2 seperate copies of the same image in memory.
This can make sense (although it will not be necessary in normal life,
but for exotic designers I did want to allow most flexibility)
ie. for the background images of the plugin-windows:
Example:
Imagine you are designing a plugin-window on the left and one on the
right side of the player window. For both you want to use the same
background window.
"Left"
{
"Number of Images" = dword: #1;
"Image 1" = "bkgnd.bmp";
"Image 1 Glass Color" = dword: 000000; ! use black as transparent color
! ... some other definitions
}
"Right"
{
"Number of Images" = dword: #1;
"Image 1" = "bkgnd.bmp";
"Image 1 Glass Color" = dword: 000000;
! ... some other definitions
}
You see, both images are the same and Power PlugIn will store only one
copy of the image to be used for both windows at the same time.
But now imagine, you want to draw something into the background image
using option "Image ? Mix Bkgnd" (described later). This option gives
the possibility to draw (colorized) images of an animation into the
background image. The drawing will be done once after loading the images
and will not be changed.
Now imagine, you have an animation somewhere in the left window which
uses "Image ? Mix Bkgnd" to draw itself into the background image.
If now, the right window would also use a animation with option
"Image ? Mix Bkgnd" to draw into the background, but that animation
looks differently than the anim in the left window, then this will
result in a conflict.
The left anim will draw itself into the background image. But the window
on the right side will display also that background image. And so also
in the right window, the drawing of the left anim will be visible.
Of course, this case should be prevented.
By specifying another index for the background image on the right
window, Power PlugIn will store 2 different copies of the same
background image and each of the anims can draw its images in
an own copy of the background image. The left and right windows will
display different background images then.
"Right"
{
"Number of Images" = dword: #1;
"Image 1" = "bkgnd.bmp";
"Image 1 Glass Color" = dword: 000000;
"Image 1 Index" = dword: #2;
! ... some other definitions
}
BUT IMPORTANT: There may be also another (not unimportant) case where
you would want to cause Power PlugIn to store seperate copies of the same
image:
As described below in section "HOW DOES POWER PLUGIN ANALYSE AND
OPTIMIZE A SKIN", Power PlugIn will try to optimize images of some
animations for faster drawing operations.
Power PlugIn will not be able to optimize an animation, if the images of
that animation are used in another animation (no matter if they are
used in the same or in another plugin-window) as well, but the background
is not exactly the same as in the first animation. Even if an
image which is used multiple times (no matter if it is used multiple
times in the same animation or in different animations) and the
background images are exactly the same (for this the background images
even must have the same index from "Image ? Index") but the image
which is used multiple times only differ by the origin definition
(so that it is on the same background image but on different locations),
Power PlugIn will not be able to optimize animations using that image.
If you want to check, which animations Power PlugIn did optimize
successfully, enable the test-optimization-option in the Power PlugIn
configuration.
Images with only red borders mean that they have been optimized
according during pass 1. You will see the borders *only* if the images
have been designed with a non-rectangular mask. It the image already
was a rectangle, you will not see red borders since the optimization
pass 1 will make non-rectangular images to rectangles again.
Optimization pass 2 will try to make all images as large as the largest
one of that animation. You will see this when (for some of the anim's
images) there have been added green borders.
For more info on the optimization process, see section
"HOW DOES POWER PLUGIN ANALYSE AND OPTIMIZE A SKIN" below.
- "Image ? Colorize"
It is possible to colorize an image. This is helpful for ie. animations
of type thermometer where only one little image file is used for all images
of that animation. Colorizing gives the possiblity of making a colorful
set of images for the animation while only one image file has to be defined.
Example:
"Number of Images" = dword: #3;
"Image n" = "image.bmp";
"Image 1 Colorize" = dword: ff0000;
"Image 2 Colorize" = dword: ffff00;
"Image 3 Colorize" = dword: 00ff00;
Imagine "image.bmp" is a non-colored image (ie. it is white with possibly
some gray pixels). The colorizing will cause image 1 to be red, image 2
to be yellow and image 3 to be green.
The format of the RGB color is the same as for "Image ? Glass Color"
(see above).
The colorizing will be done by a multiplication of the red, green and
blue components of the color with the pixel's colors.
So a colorization with color white will not change the image while a
colorization with color black will make the whole image also black.
Gray values in between make the image darker. If you use a color instead
of only a gray color, the image will be colorized using that color.
Of course "Image n Colorize" also is supported to colorize all images
with the same color.
If "Image n Colorize" is specified, but also a "Image ? Colorize" is
specified, then the "Image ? Colorize" will have priority for that
image number.
Example:
"Image n Colorize" = dword: ff0000;
"Image 4 Colorize" = dword: ff00ff;
will colorize all images with color red except image 4 will be
colorized with color violet.
(Please see also "Image n Color Fade" option below).
- "Image n Color Fade" (a "Image ? Color Fade" option does not exist)
Like "Image ? Colorize", the "Image n Color Fade" option also can
colorize images but it does not colorize all images with the
same color. It colorizes them according to a list of colors and
it will automatically fade between these colors.
Example:
"Number of Images" = dword: #34;
"Image n" = "image.bmp";
"Image n Fade Color" = "2,ff0000;16,ffff00;32,00ff00";
Format:
The format is a string with several color definitions separated
by ";" characters.
Each color definition consists of an image number (decimal value
only), then a "," char followed by an RGB color value (hexadecimal
value only) similar to the RGB color format described in
"Image ? Glass Color" option.
The list should be order by increasing image numbers. So the first
color definition in the string should have the lowest image
number while the last one should have the greatest image number.
The images with the specified numbers will be colorized using the
specified color. Images with numbers in between will be colorized
by a color faded between the closest color definitions.
In the example above this means image 2 is colorized red, image 16
is colorized yellow and the images in between are colorized with
colors faded between red and yellow. In similar ways, this also
belongs to images between number 16 and 32.
In that example, image 1, 33 and 34 are not colorized.
A "Image ? Colorize" option has a priority before "Image n Color Fade"
for the specific image number.
Example:
"Image n Color Fade" = "1,ff0000;32,0000ff";
"Image 8 Colorize" = dword: 00ff00;
In this example, the images 1 to 32 are colorized with a color fade
from red to blue, except image 8 is colorized with color green instead.
- "Image ? Mix Bkgnd"
With this option, an animation may cause its images (after they have been
colorized with option "Image ? Colorize" or "Image n Color Fade")
to be colorized again with the color specified (but the result will not
be stored in the images).
The result will be draw directly into the background image and the new
image will be stored as new background image.
(See how I did make this in "HiFi-X" skin delivered with the
Power PlugIn package).
Both option possiblities "Image ? Mix Bkgnd" and "Image n Mix Bkgnd"
are supported where, like in normal case, the "Image ? Mix Bkgnd"
has a higher priority. That means in a case like
"Image n Mix Bkgnd" = dword: 808080;
"Image 3 Mix Bkgnd" = dword: a0a0a0;
all images of the animation will be colorized with RGB color 808080
before they are drawn into the background image, except image 3
which will be colorized with RGB color a0a0a0 instead.
The RGB color format is the same as for the "Image ? Glass Color"
option.
Now following is a list of image definition options, which will
work *only* for defining the background image of a plugin-window:
Please notice, that in the list, I use prefix "Image ?", but you can
use prefix "Image n" instead as well.
If only one of these 2 prefixes are supported for an option, it will be
explained explicitely at the option description.
- "Image ? Align"
With this option, you can influence the default position where the
plugin-window is to be created.
For plugin-windows on the left or right side of the player-window:
You can specifiy, if the plugin-window shall be created aligned
to the top, center, or bottom of the player-window height.
In that case, the option can take one of the following string values:
"top"
"center"
"bottom"
For plugin-windows on the top or bottom side of the player-window:
You can specifiy, if the plugin-window shall be created aligned
to the left, center, or right of the player-window width.
In that case, the option can take one of the following string values:
"left"
"center"
"right"
- "Image ? Window Offset"
With this option, you can cause a plugin-window to be moved away
from its default creation position.
The format is similar to that of the "Image ? Origin" option
explained above.
Example:
"Image 1 Window Offset" = "-10,20";
In this example, the window will be moved 10 pixels to the left
and 20 pixels downwards away from its default position.
- "Image ? Copy of"
With this string option you can define a copy of another plugin-window
defintion of the same or another scheme and player-side.
This option will *not* work with the "Image n" prefix.
Format:
"
\\\\Image "
is the configuration-key-name of the scheme from
where to make a copy of a plugin-window.
defines the side of the music-player from where to
copy the plugin-window definition. Possible sides: "Left", "Right",
"Top", "Bottom".
specifies the number of the plugin-window definition which shall
be copied.
Example:
"Schemes"
{
"First Scheme"
{
"Bottom"
{
"Number of Images" = dword: #2;
"Image 1" = "img1.bmp";
! ... some other options for plugin-window with background image 1
"Image 1 Anims"
{
! ... some animations for plugin-window with background image 1
}
"Image 2" = "img2.bmp";
"Image 2 Window Offset" = "10,10";
! ... some other options for plugin-window with background image 2
"Image 2 Anims"
{
! ... some animations for plugin-window with background image 2
}
}
}
"Second Scheme"
{
"Top"
{
"Number of Images" = dword: #1;
"Image 1 Copy of" = "First Scheme\\Bottom\\Image 2";
"Image 1 Window Offset" = "-2,-1";
}
}
}
In this example, the scheme "Second Scheme" has a plugin-window on top
which is a copy of the 2nd plugin-window used in scheme "First Scheme"
at its bottom. Also its animations will be copied.
Please notice, that also the specified option "Image 2 Window Offset"
will be used for the copy in "Second Scheme", but in addition,
the window will be moved again according to the other window offset
"-2,-1". So the copied plugin-window will be moved by "8,9".
Please notice, that it is not possible to make a copy of a copy.
So something like the following "Scheme 3" is not possible:
"Schemes"
{
"A Scheme"
{
"Left"
{
"Number of Images" = dword: #1;
"Image 1" = "img1.bmp";
}
}
"Scheme 2"
{
"Left"
{
"Number of Images" = dword: #1;
"Image 1 Copy of" = "A Scheme\\Left\\Image 1";
}
}
"Scheme 3"
{
"Left"
{
"Number of Images" = dword: #1;
"Image 1 Copy of" = "Scheme 2\\Left\\Image 1";
}
}
}
But
"Scheme 3"
{
"Left"
{
"Number of Images" = dword: #1;
"Image 1 Copy of" = "A Scheme\\Left\\Image 1";
}
}
is legal again.
How to create animations for a plugin-window definition:
--------------------------------------------------------
In a plugin-window definition key, you must specifiy a key named
"Image ? Anims" where "?" stands for the number of the plugin-window
(or its background image).
Within this key, you can specify several subkeys each one containing
definitions for one animation. The name of such a subkey will be
the name of the animation. (Currently the name of an animation is
ignored, but it may be used in future versions of Power PlugIn).
Against the normal handling of "skin.txt", the order of animations
*can be important*. It can be important for you when Power PlugIn tries
to optimize an animation. Normally Power PlugIn will not be able to
optimize an animation if it is overlapping with other animations,
EXCEPT IF the animation is the *first* one in the list of animations.
(Of course, the animation must met all other necessary requirements
so that Power PlugIn can optimize it. Read more about this in section
"HOW DOES POWER PLUGIN ANALYSE AND OPTIMIZE A SKIN" below).
On the other hand the order of Anim definitions *is* important because
this will be the order they are drawn (which is important
if parts of the animation images overlap with images of
other animations). The first one will be drawn at bottom,
the last one will be drawn on top.
Example:
"Schemes"
{
"A Scheme"
{
"Left"
{
"Number of Images" = dword: #1;
"Image 1" = "bkgnd.bmp";
"Image 1 Anims"
{
"First Anim"
{
! ... some animation definitions
}
"Second Anim"
{
! ... some animation definitions
}
! ... other animations may follow
}
}
}
}
Of course, it is possible for a plugin-window not to have any animations.
For this, simply do not sepcify a "Image ? Anims" key.
How an animation is defined:
----------------------------
An animation consists of these main parts: A timer, the data source,
the animation type, a sequence and a sound-channel.
In certain cases, there also can be transformation functions.
Example:
"First Anim"
{
"Timer Delay" = dword: #50;
"Anim Type" = "single";
"Anim Sequences" = "1:1";
"Anim Data Source" = "Spectrum";
"Channel" = "left";
}
Data flow:
The data will be taken from the specified data source (which can contain
some internal filter functions) taken from the selected channel.
It then will be passed to the animation-sequence transformer which
will transform it and pass it to the drawing engine of Power PlugIn.
The drawing engine then will draw the animation according to the
specified animation type.
The definition options:
- "Timer Delay"
This defines a timer in milliseconds for the animation.
It defines the minimum delay between two frames of an animation.
If not timer is defined for an animation, the default timer of 25 ms
(milliseconds) will be used.
If you specify a timer, you should set it to multiples of 25 ms for
best results.
Note: To ModPlug: It seems, that Modplug ignores the internal timer
setting of 25 ms. It uses its own timer (which seems to be nearly
25 ms). But this has no real influence on a "Timer Delay" definition.
- "Anim Type"
This defines how the animation will be drawn.
Currently possible types:
"single"
The animation contains images.
Only one of the images will be drawn at any time.
This is the type to be used for ie. jumping speakers.
"thermometer"
The animation contains images.
This is the type used for displaying scales. It is called
thermometer because it looks like a thermometer scale.
It will draw the images starting from number 1 to a
number calculated from the current data source value.
"drawing"
The animation does not contain images.
It will be generated just by drawing something into the
plugin-window.
Currently only for drawings, blur and alpha-blending
operations are supported.
Be sure to make drawing animations not too large and not
too intensive because it can increase CPU-usage dramatically
under certain circumstances.
Options for the anim types will be explained later.
For types singe and thermometer, I recommend not to use
"Spectrum Peaks" as "Anim Data Source" (which will be described
later) since it makes no sense for these animations.
Use "Spectrum" instead.
- "Anim Sequences"
You can specify one or more sequences (seperated by ";" characters).
But currently only the first sequence will be used, all other
sequences, if specified, will be ignored. This may change in
future versions of Power PlugIn.
Currently supported Sequences:
"1:1"
This will simply take the source data and forward it to the
drawing engine.
This means, it will do nothing.
If the source data is negative (which can be done using
"Spectrum Scale" option (described later) if using spectrum
or spectrum peaks as source data), must animation types will
not do anything then. Try it out.
"Rotate"
This will cause the animation to loop its images. The higher
the source data values the faster the rotation will be and
vice versa.
If source data is negative, the rotation will loop in
the other direction.
- "Anim Data Source"
Describes where the data to influence the animation will be
taken from.
Currently supported Data Sources:
"Spectrum"
With this data source, you can specify a range to be
taken from the spectrum data the music-player sends
to Power PlugIn.
From that data-range a mean value will be calculated
(with some addition functionality which will be described
later) and passed to the animation-sequence transformer.
As you see, this data source will generate one single
data value which will be used for the animation.
This data source can be used for animations using images
(this with anim types single and thermometer).
But it also may be used by drawings if you want only
one data value to be used for the drawing.
"Spectrum Peaks"
This allows the same functionality (and more) like
the "Spectrum" data source, but with the main difference
that it will generate more than only one data value.
How to define options for the selected data source, will
be described later.
- "Channel"
Describes the channel from which to take the source data.
The source data then will be prepared defined by the
"Anim Data Source" option.
Supported Channels:
"left"
"right"
"mono" will be a mean of the left and right channel.
"maximum" similar like mono, but it will take the maximum
of the left or right channel.
This option is good ie. for a single SubWoofer speaker
acting like a mono speaker. If you would take "mono",
it speaker will not react very much if a sound is
played only on the left *or* right channel while
the other one is quiet, because "mono" will calculate
a mean value. Taking the maximum instead will make
react the speaker equally no matter if a sound
is played only on one or on both channels.
If the "Channel" option is not specified, Power PlugIn will use
a default channel according to the player-window side the plugin-window,
which uses this animaion, is created on.
For plugin-windows on the left side, Power PlugIn will use the "left"
channel by default. For plugin-windows on the right side, the "right"
channel will be used by default. For plugin-windows on the top or
bottom side of the player-window, Power PlugIn will use the "mono"
channel by default.
Options for the anim-data-source "Spectrum" and "Spectrum Peaks":
-----------------------------------------------------------------
Main option for data-source "Spectrum":
- "Spectrum Start" and
"Spectrum End"
With these values (they are dword values), you can select the
range of data from the spectrum that the music-player sends
to Power PlugIn.
From this range Power PlugIn will calculate a mean value and
pass this one to the animation transformation function.
In the range, the start and end indices themselves will also
be included.
The range of possible data indices into the spectrum that
the music-player sends to Power PlugIn goes from 0 to 575.
So there are 576 data values of the spectrum.
Low indices indicate bass frequencies.
High indices indicate treble frequencies.
Example:
"Spectrum Start" = dword: #0;
"Spectrum End" = dword: #575;
This example will generate a mean value over the whole
input spectrum.
If you want only one value to be taken from the input
spectrum, specify something like this:
"Spectrum Start" = dword: #34;
"Spectrum End" = dword: #34;
The index 34 will be taken as data value from the
input spectrum.
Note: The ending index must be equal or greater than
the starting index.
Main option for data-source "Spectrum Peaks":
The "Spectrum Peaks" data-source is similar to the "Spectrum" data-source
but with the difference that more than only one data value will be
calculated.
There are two possibilities to define a list of spectrum peaks:
- "Spectrum Peaks"
With this option, you can define a list where you specify
each peak seperately.
A peak value can be defined by eigher one value which must be
in the range of 0 to 575.
Or you can define it with a starting and ending index like
described in the "Spectrum" data-source.
Format:
A string where the peaks are seperated by "," characters
and a input range for a peak is specified using the "-"
character.
Example:
"Spectrum Peaks" = "0,10,20,100-199,200-299,300-399";
In this example, 6 peak values will be generated.
The first will be the peak at index 0 of the input spectrum (which
the music-player sends to Power PlugIn).
Peak number 2 and 3 are taken from index 10 and 20.
The 4th peak will be generated similar to start and end values
of the "Spectrum" data-source described above.
The 5th and 6th peak will be generated as mean values from
the 200 to 299 and 300 to 399 (each including the start end
end indices).
Note: You can use spectrum peaks for animations which use images
(anim types single or thermometer) but this makes no sense since
these animations (at the moment) support only one data value.
If you use spectrum-peaks for these animation types, the last
value will be used and all other ones will be ignored.
I recommend to use "Spectrum" data-source instead for these anim
types since with spectrum-peaks Power PlugIn will have to calculate
values which then will not be used.
Note: You can specify any order of peaks you want (but be
sure that for each peak, the starting index is less or equal
to its ending index).
Example:
"Spectrum Peaks" = "100,190,10-20,400,0-10,575,150,75";
This example will look a bit confusing since the peaks are not
ordered in any way :-)
- "Spectrum Peaks List"
This option is a replacement for the "Spectrum Peaks" option.
It has the same purpose and will produce the same results, but
for a large number of peaks, with this option it is more easily
to define them all.
Format: Is a string value of syntax:
"-: W"
Example:
"Spectrum Peaks List" = "0-575:100 W50";
It will produce a list of peaks which each will be calculated
from a mean value out of a range from the input spectrum's data.
The range will be defined by a start and end index as described
above in "Spectrum Peaks".
The start-index for a peak will be calculated like this:
1/ If is less or equal than :
start-index = + (k-1)*
2/ If is greater than :
start-index = - (k-1)*
where 'k' means the number of the peak (1 for the first peak,
2 for the second peak,...).
There will be created so many peaks as long as:
for case 1/
the start-index is *less* or *equal* to
for case 2/
the start-index is *greater* or *equal* to .
The end-index for each peak will be calculated in both
cases like this:
end-index = start-index + - 1
If the width is 1, the end- and start-indices will be equal for
each peak, which means that only one data value will be taken
from the input spectrum to calculate a peak value.
The example above will be the same as if you would define:
"Spectrum Peaks" = "0-49,100-149,200-249,300-349,400-449,500-549";
must be in the range from 0 to 575.
must be in the range from 0 to 575.
must be >= 1, even if is greater than
must be >= 1
Note: If a range of one peak exceeds the limits of 0 and 575,
Power PlugIn will automatically truncate the values to
the possible range.
Note: It is not recommended to produce a very large number of
peaks since an animation of type "drawing" will have to
draw each peak seperately which can increase CPU usage.
I recommend to make not much more than 50 or 100 peaks
for an animation.
I hope the following examples do show all special cases which
can happen.
Example:
"Spectrum Peaks List" = "0-40:10 W1";
is the same as
"Spectrum Peaks" = "0,10,20,30,40";
In here you see, that the value is included, because
the start-index of the 5th peak is equal to (which is
40).
Example:
"Spectrum Peaks List" = "0-40:10 W5";
is the same as
"Spectrum Peaks" = "0-4,10-14,20-24,30-34,40-44";
Example:
"Spectrum Peaks List" = "0-575:200 W200";
is the same as
"Spectrum Peaks" = "0-199,200-399,400-575";
In here, you see and are defined in its valid
range, but start- and end-indices for the last peak would
be calculated to "400-599" which is not possible because
this exceeds the possible input spectrum's range.
Power PlugIn will automatically use just the range "400-575".
Example:
"Spectrum Peaks List" = "574-0:200 W10";
is the same as
"Spectrum Peaks" = "574-575,374-383,174-183";
In this example, you see that the first peak would exceed the
possible range (it would be "574-583") which Power PlugIn
automatically truncates to "574-575".
Example:
"Spectrum Peaks List" = "0-575:1 W1";
will return a peak for each frequency index of the input spectrum
sent by the music-player.
It is not recommended to use so much peaks since this will rapidely
increase CPU usage.
Most of the other options can be used for both data-sources. But there
are some which only can be used by one of them. See the following lists.
Following is a list of options which can be used by both
data-sources ("Spectrum" as well as "Spectrum Peaks"):
- "Spectrum Sensitivity"
This is a dword in the range from 0 to 1000.
If not defined, a default value of 0 will be used.
It defines, how easily the spectrum data (or peaks) will push
to the maximum. The higher the value, the easier the animation
will react on quiet sounds.
0 is the normal value (normal sensitivity).
At the moment, negative values are not supported. This may change
in a future version of Power PlugIn.
Sorry, but the sensitivity value is not linear. This means that
a sensitivity of 100 or 200 makes nearly no difference while
the difference between 990 and 991 is extremely large.
Sorry about this.
To find the best sensitivity value for an animation
you will have to try it out.
Especially for animations which use spectrum data from the
treble frequencies (the higher index values somewhere between
index 200 and 575 or something), you would want to set a higher
sensitivity since in nature, bass frequencies are much louder
than treble frequencies.
HINT: When you try to find a good sensitivity value, please do
this by resetting the user-sensitivity (which the user can
select in the configuration of Power PlugIn). Both, the
bass- and treble-user-sensitivity should be set to 0 when
you try to find good "Spectrum Sensitivity" values for
your animations.
- "Spectrum Function"
This also will influence how easily the spectrum data (or peaks)
will push to the maximum.
This also is a dword in the range from 0 to 1000.
If not defined, a default value of 0 will be used.
0 will make a 100% linear spectrum-transformation function.
1000 will make a 100% logarithmic transformation function.
Values in between will make the transformation function a
interpolation between the linear transformaion and the
logarithmic transformation.
So a value of 500 will make it half linear and half
logarithmic. A value of 250 will make 75% linear and
25% logarithmic.
If the transformation is logarithmic, the input spectrum
data will managed like this. For low frequency volumes,
the transformed data will be increased very fast. But
the higher the input frequency volume goes, the slower
the transformed data will be increased.
This means for logarithmic transformation, the animation
will react more sensitive for low volumes, but for
loud volumes the animation will hardly react.
This option is good ie. for jumping speakers because with
logarithmic transformation, the jumping of the speakers
look for realistic.
It is also good for ie. displaying a spectrum in animation
of type "drawing" (using spectrum-peaks), because the treble
frequencies can be hardly seen with linear transformation.
Making it a bit more logarithmic will cause the treble
frequencies to be seen better while the bass frequencies
still will be seen (nearly) as good as before.
PLEASE NOTICE THE DIFFERENCE BETWEEN THE "Spectrum Function"
AND "Spectrum Sensitivity":
By increasing the sensitivity, you will simply scale the
the input spectrum data.
This means, that for ie. a very high sensitivity, the animation
will react like this: For input data volumes in the range
from very quiet to nearly quiet, the animation will react
extremely strong which will of course look good.
But if the volumes are in the range of loud till maximum
loudness, the animation will stay continuously at the maximum
value. You will not see any reaction as long as the input data's
volume is loud.
With a logarithmic function, you can prevent this case.
Imagine you are using a very logarthmic function.
For input data between quiet and nearly quiet, the animation
will react very strong. But in the case of volumes in the
range from loud to very loud, the animation still will react
a bit.
With completely linear transformation, the animation would
react equally scaled for quiet and loud volumes.
It is on you now to find a good combination of both options
for your animations.
- "Spectrum Scale"
This options has (nearly) the same influence on the animation as
the "Spectrum Sensitivity" value, but with the difference
that "Spectrum Scale" will be a linear value while the
"Spectrum Sensitivity" is not.
As explained above, the difference between low
"Spectrum Sensitivity" values is not so large as for high
values.
With "Spectrum Scale", this effect does not exist. The
data will simply be multiplied with the "Spectrum Scale" value.
In addition, "Spectrum Scale" also supports negative values
which can be used ie. for animation sequences "Rotate" to
rotate in the other direction.
This value must be provided as floating point value in a string.
Example:
"Spectrum Scale" = "1.0";
will not cause any scaling.
Example:
"Spectrum Scale" = "2.0";
will not double the calculated data.
Example:
"Spectrum Scale" = "0.5";
will half the calculated data.
Example:
"Spectrum Scale" = "-1.0";
will not cause the data-source to be negative.
PLEASE NOTICE THE ORDER POWER PLUGIN WILL USE THESE THREE DEFINITIONS:
From each data of the input-spectrum (which is sent from the music-player
to Power PlugIn), Power PlugIn will first manipulate them using the
"Spectrum Sensitivity", then it will use the "Spectrum Function" on
the data.
At last Power PlugIn will take the result and multiply it with
the value of "Spectrum Scale".
The final result will be the final value(s) of the source-data which
then will be passed to the other animation steps (like anim-sequence
calculation and painting of the animation).
Note: The "Spectrum Scale" can be used (besides the
"Spectrum Sensitivity") to make the animation react more hardly
or stronger.
But on the other hand, the "Spectrum Scale" can be used to adjust
the average speed for "Rotate" animation sequences. (Of course
this will also work with "Spectrum Sensitivity", but since the
"Spectrum Scale" works linear, it is more easily to handle).
Note: The "Spectrum Scale" is *not* a replacement for the
"Spectrum Sensitivity". If both values are defined, Power PlugIn
will then use both values in the calculation process.
To see the difference: the "Spectrum Sensitivity" will be used
on the data, *before* "Spectrum Function" is used.
But "Spectrum Scale" is used *after* the "Spectrum Function"
has been used.
For all 3 options try out the values which match best your
wishes for an animation.
- "Spectrum Falloff"
This option will give the possibility to adjust the speed for the
falloff of a spectrum value.
The higher this value, the slower the calculated spectrum source-data
will fall off.
The value is a dword in the range from 0 to 1000.
If the option is not specified, a default of 0 will be used.
0 = immediately fall off (as fast as possible).
1000 = the value will never fall off. It will stay at this value
as long as the data does not get greater. It the value
becomes greater, the it will stay on the new value.
With this option, you can simulate a spectrum-display like for
normal hifi-systems (best simulated using an animation of type
"thermometer" or "drawing").
- "Ignore User Sensitivity"
This option is a dword acting as boolean value.
If you set it to 0, this means false.
Any other value means true.
If this value is not specified, false will be suggested.
If set to true, the user-sensitivity (which the user can
adjust in the configuration of Power PlugIn) will be ignored.
This is helpful if ie. an animation of type "drawing" is used
where many spectrum peaks are displayed.
If you want them to be displayed independent of the user
settings, then you can set this option to true.
But for ie. an animation with jumping speakers you will
want to user to influence the animation by the user-
sensitivity so that the user can adjust how strong the
jumping speakers will react on bass or treble frequencies.
The following options still can be used by both data-sources
("Spectrum" and "Spectrum Peaks"), but they can be used for
animations on type "drawing" only.
For animations of type "thermometer" or "single" they will be
ignored.
Maybe in a future version of Power PlugIn, this will also work
for animations of type "thermometer" (for "single" the top
value makes no sense).
In addition it may be that in a future version of Power PlugIn,
there will be added some new animations of type "drawing"
(which can be selected using option "Drawing Object" described
later). It may be that not all of these drawing objects will
support the spectrum-top-values.
In each case where an animation does not use spectrum-top-values,
it is not harmful to define the spectrum-top-value options but
Power PlugIn simply will ignore them for these animations.
Note: If an animation can use spectrum-top-values, but you are
using animation-sequence "Rotate", the top-values will be drawn,
but they will be calculated based upon sequence "1:1" while
the data values of the spectrum themselves will be calculated
based upon "Rotate".
So for sequence "Rotate", usage of spectrum-top-values make
no sense. But if you want to use them, do so (if you can
find any sense in it).
The following 2 options define a top-value for each peak of
the spectrum (works for data-source "Spectrum Peaks" as well
as for "Spectrum").
The top value will be hold on its position for a specific time
and then will fall off with a specific speed.
- "Spectrum Top Falloff"
This option is used to define the falloff speed of the
spectrum-top-values.
It is a dword in the range of 0 to 1000.
It is similar to the "Spectrum Falloff" option above.
- "Spectrum Top Wait Delay"
This option defines the time delay in milliseconds
which a spectrum-top-value will wait till it will
fall off.
It is a dword value.
additional Options for anim-type ("Anim Type") "single":
--------------------------------------------------------
- "Empty Image"
This option is a dword value operating as boolean.
If set to 0, false is meant. All other values mean true.
If not defined, false will be suggested.
Noramlly (if set to false), Power PlugIn will draw only one
of the images of animation at any time.
When settings this option to true, the animation
will be handled as having one more image. (But you
should not change the "Number of Images" value).
The new image will be the first one and it will
be completely empty which means, only the background
will be visible.
I did implement this option because for a situation like that:
Imagine you have an animation of type "single" and
sequence "1:1" displaying several lamps where only one
lamp at a time is visible. It then may be your wish
that if no sound is played, none of the lamps is displayed.
This will be possible when using the "Empty Image" option.
additional Options for anim-type ("Anim Type") "thermometer":
-------------------------------------------------------------
Currently there are no special options for this
animation type.
additional Options for anim-type ("Anim Type") "drawing":
---------------------------------------------------------
For this anim type, you will have to define, which drawing
should be used.
- "Drawing Object"
With this (string) option you can define, which drawing to use.
Supported objects:
- "Top Spectrum" : will generate a spectrum from left to right
placed at the top of the effective drawing rect.
- "VCenter Spectrum" : will generate a spectrum from left
to right where the top half is mirrored
to the bottom half.
- "Bottom Spectrum" : will generate a spectrum from left to right
placed at the bottom of the effective drawing rect.
- "Left Spectrum" : will generate a spectrum from top to bottom
placed at the left side of the effective drawing rect.
- "HCenter Spectrum" : will generate a spectrum from top
to bottom where the left half is mirrored
to the right half.
- "Right Spectrum" : will generate a spectrum from top to bottom
placed at the right side of the effective drawing rect.
- "Fire" : A fire will be generated like this: In the effective drawing rect,
there will be drawn some colors (axplained later).
For a horizontal fire source (I am speaking of a fire whose flames
move upwards like normal fire, or downwards) the height of the
effective drawing rect (defined by option "Effective Drawing Rect")
should be only some pixels large. When adding a blur (which moves
upwards or downwards) the flames will be visible.
For a vertical fire source (when the flames shall move left or
right), the width of the effective drawing rect should be only
some pixels large. For this, a blur should be added which
moves left or right.
This object does not work with a data-source "Spectrum Peaks".
It needs only the data-source "Spectrum".
More options for a fire will be described below.
- "Flare" : This one works with "Spectrum Peaks" as data-source rather
than "Spectrum".
It draws the spectrum peaks ordered in an ellipse using
lines. By defining the "Drawing Style" of "outlined" or "filled"
you can select if only the lines should be drawn or
if the area should be filled.
More options for a flare will be described below.
Note:
As described at the data-source "Spectrum Peaks", each peak is
calculated from the average value of a range of input spectrum
data values. The larger you set this range (ie. in the
"Spectrum Peaks List" option, this range is set by the
"W" parameter in the string) the more the flare will look
like an ellipse and react smoother. If you set the range
very small (ie. 2 or 3), the spectrum peaks will react very
heavy and the flare will flicker very much.
In addition you can specify the "Spectrum Falloff" option which
will cause the flare to become more slowly smaller.
Try out some different settings. Of course you can also use all
other options which manipulte the data-source (like
"Spectrum Sensitivity", "Spectrum Function" etc.) since the
manipulation of the data-source is independent from the
other animation settings (like animation type, sequence etc).
Note to all possible spectrum-objects:
If you do not want the visible spectrum to be generated from left to
right or from top to bottom, you can reverse the order of the
"Spectrum Peaks" or "Spectrum Peaks List". This will cause the visible
spectrum to be generated from right to left or from bottom to top.
Please tell me if you want me to implement your ideas of drawing-
objects for future versions of Power PlugIn and I will try to do so.
Note: You *must* specify this option ("Drawing Object") or Power PlugIn will
not draw anything in the animation.
- "Drawing Rect"
Defines the rectangle wherein the drawing will be placed in over
the background image.
This is a string value.
Format:
"x,y,cx,cy"
x is the x-coordinate and y the y-coordinate of the top left corner
of the rectangle. It is relative to the imaginary origin of
the plugin-window. (The imaginary origin has been explained above
at the descriptions of the image options, especially the
"Image ? Origin" option).
cx and cy define the width and height of the rectangle.
In addition this is the size of the image where the drawing will
be placed into. Power PlugIn will then plot the image into the
the plugin-window.
Note: You *must* specify this option or Power PlugIn will not draw
anything in the animation.
- "Effective Drawing Rect"
This is the effective drawing rectangle where Power PlugIn will draw
points, rectangles, lines, circles etc. into. The drawing
will not exceed this rectangle (the drawing will be clipped to
this rectangle).
The format is the same as for "Drawing Rect". In addition, this
rectangle also is relative to the imaginary origin.
Normally you will set this rectangle to the same as the
"Drawing Rect".
But if you are using blur (described a bit later), you would want
to make this rect a bit smaller (about 2 to 8 pixels border width
on each side of the rectangle) because the drawings will be
made smoother and thicker the more blurry they become.
Note: You *must* specify this option or Power PlugIn will not draw
anything in the animation.
- "Drawing Color Table"
This defines a palette for the drawing image to use.
The drawing image will be created as image using 256 colors.
So the palette should contain 256 colors.
The syntax is similar to the one of the "Image n Color Fade"
option described above. Look there for a exact description
of the syntax.
BUT with the "Drawing Color Table" you also can specifiy
a palette using a slightely different syntax:
You can define an alpha-channel value for each color.
The alpha-channel will be necessary only if you will
enable alpha-blending (using the "Alpha Blending" option
described a bit later).
Alpha blending will offer the possiblity of transpareny while
you can tell for each color entry in the palette, *how much*
transparent the color will be.
The format for colors with alpha-blending is:
The format is a string with several color definitions separated
by ";" characters.
Each color definition consists of a color index (decimal value
only) in the range 0 to 255, then a "," char followed by an ARGB
color value (hexadecimal value only) (the A in ARGB means the
alpha channel).
An ARGB color will be a hexadecimal value of format AARRGGBB where
A is the alpha channel, R the red channel, G the green channel
and B the blue channel.
For the alpha channel, a color is completely opaque if its alpha
value is set to 0, and completely transparent for 255.
Example:
"Drawing Color Table" = "0,ff000000;255,00ffffff";
In this example, the color at index 255 is completely white and
totally opaque, while color at index 0 is completely black and
totally transparent.
The colors in between are a fading between these colors, but
also the alpha channel will be faded in between so that a
color with lower index will be more transparent (for that
example above).
IMPORTANT NOTE:
If you are using blur, I recommend that you should set
the "Drawing Color" (described a bit later) to the color at
index 255, because the blur will function that way that it
will decrease the color index for each pixel in the image.
So the drawing should be made with the color at index 255
to get the best blur effect.
BUT FOR THIS, you should ensure that in the color table
only *ONE INDEX* has the RRGGBB color value to be used for
drawing the rectangles, lines, points, circles etc.
(In addition for a blur that index should be index 255).
Even if there are 2 colors with the same RRGGBB values but
differ only by their AA values, the colors will be interpreted
as equal.
You should prevent such a case, because Power PlugIn will take the
first color index which matches the RGB color defined
in "Drawing Color" for drawing the rects, lines etc.
If you want that the drawing engine will use index 255
as drawing color, you will have to ensure that *only*
the color at index 255 has the RRGGBB color value defined
by "Drawing Color".
Note: You *must* specify this option or Power PlugIn will not draw
anything in the animation.
- "Drawing Color"
This is a dword defining the RGB color to use for drawing
rectangles, lines, circles, points etc. into the
drawing image.
Format is the same as of the "Image ? Glass Color" option
described somewhere above.
Example:
"Drawing Color" = dword: A0FF00;
This example uses a color of red=160, green=255, blue=0 as
drawing color.
This color should be present in the "Drawing Color Table".
Please read the IMPORTANT NOTE in the "Drawing Color Table"
option to know, how to define a color for drawing.
If you define a "Drawing Color" which is not present in
the "Drawing Color Table", then Power PlugIn will use that
color of the color table which matches closest to the
specified drawing color.
In such a case, it is not exactly clear, which index of
the color table Power PlugIn will choose.
Note: You *must* specify this option or Power PlugIn will not draw
anything in the animation.
- "Drawing Style"
Defines the style, how Power PlugIn will draw the drawing
object.
This option is a string value.
I will list here all supported values you can specify.
But it can be for different drawing objects (defined by
the "Drawing Object" option), that not all of the specified
styles are possible.
Try it out.
Supported values:
- "filled" : (this is the default if "Drawing Style"
is not specified)
This will cause the drawing (ie. a spectrum)
to be drawn filled (ie. with filled boxes).
Note: For a spectrum, the top-values (if enabled)
will be drawn non-filled nevertheless.
- "outlined" : This will cause the drawing (ie. a spectrum)
to be drawn only using thin lines.
additional Options for animation-types:
---------------------------------------
The following options are currently supported only for
an animation type "drawing" (defined by "Anim Type" option).
If they are defined for other anim types, they will be ignored.
This may change in a future version of Power PlugIn.
- "Blur"
This is a dword value working as boolean. If set to 0, this
means false, all other values mean true.
It set to true, the blur operation is enabled.
IMPORTANT NOTE:
The blur operation can be very time-expensive if the
"Drawing Rect" option is set to a large size.
Please notice, that the blur-operation will performed
on the whole rect defined by "Drawing Rect" and not just
on the (possibly smaller) rect defined by
"Effective Drawing Rect".
- "Blur Speed"
This option will be ignored if the "Blur" option not true.
With this option (a dword value) you can define the speed for
the blur operation.
The higher the value, the faster the blurring will be, (this means
the faster the blur will clear the image).
Slowest = 0.
Note: Although negative values are possible,
they make no sense.
IMPORTANT NOTE:
The make a good blur, you should define a "Drawing Color Table"
where the "Drawing Color" should be the color on index 255, because
the blur operation will work that way, that it decreases the
index values of the pixels in the image.
For more about it, read the IMPORTANT NOTE at the description of the
"Drawing Color Table" option above.
Note: If you want the blur to be slower than 0, you can define a
"Timer Delay". But do not forget that this also will slow down
the interval of retrieving source data.
- "Blur Movement"
This string option will enable the blur to move in one direction.
Format: ","
defines the movement in horizontal direction.
0 will not move in that direction.
1 will move right.
2 will move right in double speed.
etc.
Negative values will move in left direction.
defines the movement in vertical direction.
0 will not move in that direction.
1 will move down.
2 will move down in double speed.
etc.
Negative values will move upwards.
Example:
"Blur Movement" = "3,-1";
will move in triple speed to the right and upwards as well.
Note for fire (I mean when option "Drawing Object" is set to "Fire"):
For a fire you will want to add a moving blur to see the flames.
Imagine a fire whose flames shall move upwards.
For this, a horizontal fire source shall be created (see explanations
of fire options below). In that case, the effective drawing rect
(defined by option "Effective Drawing Rect") should be only some
pixels high. But the height should not be smaller than the moving
speed or else the flames will look to pixelized.
Example:
"Blur Movement" = "0,-4";
For this the effective drawing rect should have a height of 4 at minimum,
better will be 5 or 6.
For a fire whose flames shall move left or right, the fire source shall
be a vertical one (specified by option "Vertical Fire Source") and
the *width* of the effective drawing rect shall be set that way as
explained above for the height of a horizontal fire source.
If this option is not provided, no movement will be allpied on the blur.
- "Blur Scale"
With this option, you can stretch the blur effect in x- and/or y-direction.
The more a blur is stretched, it will look more pixelized.
Format: ","
shall be set to a value greater or equal to 1.
shall be set to a value greater or equal to 1.
The default will be 1 for both directions. (No stretching if this
option is not provided).
- "Alpha Blending"
This option is a dword value working as boolean. If set to
0, this means false, all other values mean true.
If set to true, alpha blending will enabled.
For this, the "Drawing Color Table" should be defined with
colors in for AARRGGBB (where A means the alpha channel).
See the description *and* IMPORTANT NOTE to "Drawing Color Table".
With alpha blending enabled, the background will shine through.
I recommend to use alpha blending for an animation *only* if
it does not overlap with other animations (which is the case
when even only the bounding rectangles of each of an anims
images overlap with the bouding rects of the images of another
anim; do not forget that for an anim of type "drawing" also uses
an image defined by "Drawing Rect" option).
If it would overlap nevertheless, this would result in a wrong
displaying, because the alpha-blending for an anim will work
only with the background image. All other anims below the
"drawing"-anim will not be visible (in the area where the anims
do overlap).
IMPORTANT NOTE:
The alpha blending is a very time-expensive operation (it is
even slower than the blur operation), because for each pixel,
the CPU will have to do 6 multiplications, 3 additions and
3 shift operations.
Please, when using alpha blending, hold the image size defined
by "Drawing Rect" as small as possible.
- "Mask Image"
With this option you can specify a mask image to be used for
animations of type "drawing" so that the visible part is not
just a simple rectangle.
The format is the same as for the "Image ?" option.
Note: It is *not* necessary that the image is at the same position
and the same size as the drawing rect defined by the "Drawing Rect"
option. Power PlugIn will automatically handle this correctly and
will use the intersection of the non-rectangular area defined by
the mask image and the drawing rect.
- "Mask Image Rect"
Has the same meaning as "Image ? Rect" option but is intended
for image defined by the "Mask Image" option.
- "Mask Image Origin"
Has the same meaning as "Image ? Origin" option but is intended
for image defined by the "Mask Image" option.
- "Mask Image Glass Color"
Has the same meaning as "Image ? Glass Color" option but is intended
for image defined by the "Mask Image" option.
additional Options for drawing-object "Fire":
---------------------------------------------
- "Fire Color Index Range"
With this option you can specify a basic, permanent fire to use
for the animation. This permanent fire will be visible even if
no sound can be heard from the music-player (as long as you do
not specify the "Min Number of Hotspots for Permanent Fire" option).
Format: "-"
is the minimum index (it must be equal or smaller to )
is the maximum index to use
Each index value is an index into the color table (defined by
"Drawing Color Table" option). So it can be only a value in
the range of 0 to 255.
Power PlugIn will generate the permanent fire by taking
color values randomly out of the specified range and put
it on random positions in the effective drawing rect (defined
by "Effective Drawing Rect" option).
Examples:
"Fire Color Index Range" = "20-100";
"Fire Color Index Range" = "0-0";
The second example will completely switch off usage of a permanent
fire.
The permanent fire will make look the fire more smooth and more
realistic when there are some/many hotspots drawn as well.
(See explanation of hotspots below).
You may want this to happen, but in addition you may want no
fire visible if no sound is being heard from the music-player.
This you may handle with the "Min Number of Hotspots for
Permanent Fire" option explained below.
- "Number of Fire Hotspots"
In addition to a permanent fire, there are hotspots which will
be drawn into the effective drawing rect (defined by the
"Effective Drawing Rect" option) as well.
The hotspots are drawn with a special color (defined by the
"Fire Hotspot Color Index" option), which mostly will be set
to 255 which mostly will represent a light color so that
the hotspots really look 'hot'.
The "Number of Fire Hotspots" option specifies the minimum and
maximum number of hotspots to draw. Power PlugIn will select
a number in that range according to the data-source.
(For a fire, you cannot use "Spectrum Peaks" as data-source defined
by the "Anim Data Source" option. But you can use a data-source
which generates only one single data value like the "Spectrum"
data-source).
Format: "-"
where is the minimum number of hotspots and is the
maximum number.
must be equal or greater than .
Each of the 2 values must be greater or equal to zero.
Mostly you will want to be zero so that no hotspots are
drawn if no sound is heard from the music-player.
The value mostly you will set according to the size
of the effective drawing rect.
Example:
"Number of Fire Hotspots" = "0-50";
- "Fire Hotspot Color Index"
specifies the color to use for drawing hotspots.
This is an index value which points into the color table defined
by the "Drawing Color Table" option.
So it can be taken out of the range 0 to 255.
Mostly the color table you will create that way that at index 0
you have the drakest (and possible most transparent) color whereas
at index 255 you will select the lightest (and possibly most opaque)
color. (This order you will want because of the blur operation if
enabled).
In that case you will mostly use 255 as color index for hotspots
because it represents the lightest color.
- "Min Number of Hotspots for Permanent Fire"
As explained in option "Fire Color Index Range" above, a permanent
fire mostly makes sense to make the fire look more realistic.
Sometimes you want the permanent fire to visible even if no sound
can be heard from the music-player.
But on the other hand you may want to use a permanent fire to make
a realistic fire, but when no sound is heard, no fire should be
visible.
To make this, you can specifiy the option
"Min Number of Hotspots for Permanent Fire".
It specifies the minimum number of hotspots which must be drawn so
that also the permanent fire is drawn.
If the number of hotspots is less than the specified number, than
no permanent fire will be drawn.
Example:
"Min Number of Hotspots for Permanent Fire" = dword: #1;
will cause the permanent fire to be drawn only if one or more
hotspots are drawn. If no hotspots are drawn, also no permanent
fire will be visible.
If this option is not speicified, it will be imagined as if it has
been set to 0 (which means that the permanent fire will always
be drawn).
- "Vertical Fire Source"
This is a dword value interpreted as boolean.
If set to 0 it means false, all other values mean true.
By default (if this option is not specified), the fire source
will be drawn horizontally. This will be used for fires which
shall move upwards or downwards. In that case the height
of the effective drawing rect shall be only some pixels large
(depending on the "Blur Movement" option).
If you set this to true, the fire souce will be vertically to
be used for a fire which moves to the left or to the right.
In that case, the *width* of the effective drawing rect shall
be only some pixels large.
Example:
"Vertical Fire Source" = dword: 0;
- "Clear Fire Source"
A dword value which acts as a boolean.
If set to 0 it means false, all other values mean true.
If this option is not specified, true will be imagined.
If set to true, Power PlugIn will generate the fire as
following:
- It will draw the permanent fire and the hotspots into
the effective drawing rect.
- Then it will do the blur on the image.
- Then it will clear the fire source again. For this it
will clear the effective drawing rect (and a somewhere
outside where the blur did draw something which does
not look like a fire).
If set to false, the last step will not be done.
This option has been implemented, because if the fire source
would stay visible, it will not look realistic, because the
blur will (hardly) done no smoothing on it.
- "Fire Wobble Size"
By default, Power PlugIn will always fill the whole effective
drawing rect with the fire source. This means that the
width of a horizontal fire source and the height of a vertical
fire source always are the same.
By setting this dword value greater than 0, you can specifify
an offset value which Power PlugIn will use randomly to decrease
the width of a horizontal fire source or the height of a
vertical fire source.
The value specified will be the maximum value which Power PlugIn
will subtract from the left and right border of the horizontal
fire source or from the top and bottom border of the vertical
fire source.
This will make the fire look more realistic.
The value cannot be greater than the width (for horizontal fire
source) or height (for vertical fire source) of the effective
drawing rect (defined by "Effective Drawing Rect" option).
If you nevertheless set it to a greater value, Power PlugIn
will automatically truncate it to the maximum value possible.
If this option is not specified, it is the same as if it has
been set to 0 (which means no wobbling).
Example:
"Fire Wobble Size" = dword: #10;
Normally you would want to set the wobble size to a value of
10% or 20% of the full width (for horz fire source) or height
(for vert fire source) of the effective drawing rect to
get good results.
Try out some values.
- "Fire Hotspot Size"
Normally a hotspot has a size of 3.
You may want to change this by setting this dword value.
This value will affect the width of the hotspot (for horizontal
fire source) or the height of the hotspot (for vertical
fire source).
Example:
"Fire Hotspot Size" = dword: #3;
Note: To test how only the fire source looks like, make the
effective drawing rect ("Effective Drawing Rect" option) as
large as the drawing rect ("Drawing Rect" option) and switch
off the blur. Also set "Clear Fire Source" option to false.
HOW DOES POWER PLUGIN ANALYSE AND OPTIMIZE A SKIN:
--------------------------------------------------
After a Skin has been loaded, Power PlugIn will analyse it
and try to optimize it for faster drawing operations. Normally,
animations with images will be drawn internally like that: For
images with a mask, the background image will be drawn into a
temporary image, then the non-transparent parts of the animation-
image will be drawn into the temprary image. Finally the temporary
image will be drawn into the plugin-window. The usage of a temporary
image is necessary to prevent flickering.
The disadvantage is that for drawing one image, 3 drawing operations
have to be done.
But in certain cases, Power PlugIn will be able to optimize the
skin's images for speed. Currently this is possible only for
animations of type "single" (for a description of animation
types, see the option "Anim Type" in section
"SYNTAX AND CONTENTS OF FILE SKIN.TXT" above).
An animation of type single means that only one of the images will
be visible at any time (this is used for ie. jumping speakers).
Power PlugIn will try to optimize in two passes:
( Please do not forget, that this works only with animations
of type "single" ).
1/ First it will analyse all loaded animtions of type "single".
The optimization for an animation will not be possible, if:
- one or more of its images overlap with images of other animations, or
- if one image of the animation is used multiple times (no matter
if it used multiple times in the same anim or in different anims)
and that image is not always over the same background image (if the
same image is in different plugin-windows) and at the same offset
position.
The background images will be different, if even only their
index defined by "Image ? Index" is different.
If you have background images which only differ by the
"Image ? Index" and you have animation images which are the same
each one over one of the backgrounds, you should also define
different "Image ? Index" indices for these animation images.
Then again, Power PlugIn will be able to optimize the images.
After images have been optimized with pass 1, they internally are
stored only as rectangular images. The advantage is, that
Power PlugIn will not need to handle non-rectangular areas when
drawing these images.
But nevertheless, it will have to use a temporary image (as
described above) to clear the old image and draw the new
one. Still, it will have to do 3 drawing operations to do
one animation frame.
With pass 2, it will try to reduce this to only one drawing
operation for each anim frame.
2/ If all requirements of pass 1 are met, then Power PlugIn will try
to do pass 2. In this pass, it will check (only for anims
of type "single"), if all its images bounding rects completely
lies inside of the bouding rect of its largest image.
If only one pixel of only one of the rects lies outside of
the largest rect, Power PlugIn will not be able to do pass 2.
If it is able to do pass 2, it will enlarge all images to the
largest rect, filling the new borders with the background image.
The result will be that Power PlugIn only needs to draw one of
the images into the plugin-window to clear the old one and
draw the new one. (When doing so, Power PlugIn will nevertheless
calculate the smallest necessary rect for that draw opertion to
hold the execution as low as possible).
In that case, Power PlugIn will not need a temporary image for
the drawing operation.
If you, the skin designer, want to see, which images Power PlugIn
can optimize, open the Power PlugIn configuration and enable
the test-optimization option.
The images will then be drawn with red borders (which will be visible
only if the images have been non-rectangular, else for rectangular
images, the red borders will not be visible, but these images
are optimized with pass 1 automatically since pass 1 does nothing
else as making non-rectangular images rectangular).
If an image has been optimized with pass 2, there will also be visible
a green border (but the red one can be visible nevertheless).
A Hint:
-------
If you see that images for an animation of type "single"
have not been optimized, but you believe Power PlugIn should have
optimized them, try to define a differen index for the animation
images using "Image n Index". Also if the background image is used
in another plugin-window as well, try to set the index of the
background image (I mean that one below the anim you want to
be optimized) to a different value using "Image ? Index".
Be sure that you really define index values, which are not used
elsewhere.
Power PlugIn should now optimize the images using pass 1.
If pass 2 still does not work, then the reason can be that one
of the anim's images lies (partially) outside of the bounding
rect of the largest image. Sorry, but for this, the only solutions
will be that you have to move that image or use a different one
so that it lies inside the largest rect.
Now there are still some other optimizations
which will be done for *all* types of animations where possible:
- If an image has a mask (regardless if the mask is defined by a
seperate mask image, or by setting the glass-color), and if
the mask has some transparent borders, then Power PlugIn will
automatically load only that part of the image which is obscured
by the smallest possible bounding rectangle.
- If an image has a mask, and Power PlugIn finds that the mask is
only one rectangle, it will automatically loads only that
rectangle of the image. The image then will be handled internally
as having no mask (because it is just one rect) since this will
decrease CPU-usage.
- For animations of type "thermometer": Power PlugIn will not always draw
all visible images of the animation. It will only draw the images
which have been added since the last animation frame, or it will
clear the images which have been removed since the last animation
frame.
HOW TO DESIGN A PLUGIN FOR SPEED:
---------------------------------
- First of all you should prevent animations in the same plugin-window
from overlapping each other (redardless of the "Anim Type" of the
animations, even if an animation is of type "Drawing").
If an animation overlaps with other(s), then, when one frame of the
animation is drawn, the overlapping parts of the other animation(s)
will have to be drawn as well. This concerns to all overlapping
animations (in the same plugin-window of course).
In addition, Power PlugIn will not be able to optimize animations
which do overlap.
You see, overlapping animations can increase CPU usage dramatically.
So if you really need overlapping animations, be sure to make
their images or drawings as small as possible, and set a timer
for these animations to make them to be drawn not so often.
The higher the timer the better it is for CPU-usage (but of
course the animation will run more jerky).
Note: An animation is interpreted as overlapping with another if
the bounding rectangle of one or more of its images overlap
with the bounding rectangle of images of another animation.
(For animations with drawings, the rectangle defined by
"Drawing Rect" will be used to check for overlapping with other
animations).
So DO NOT FORGET: It can be that 2 circular images (I mean images
with mask images containing a circle) do not overlap but their
bounding rectangles *do* overlap. In that case, the 2 animations
*will* be interpreted as overlapping animations.
Note: Animations in different plugin-windows are independent and
therefore can never be interpreted as overlapping animations, even
if the plugin-windows do overlap.
- For animations of type "thermometer", you should ensure that none
of its images (or only as few as possible) do overlap with each other.
I am speaking only of the images of the *same* animation.
Similar to the overlapping animations explained above, a thermometer-
animation will have to draw overlapping parts of its own images
multiple times.
THE WORST CASE would be if there are animations of type "thermometer"
having overlapping images as well as being overlapped with other
animations (maybe also of type "thermometer"). As you can imagine
this can increase CPU-usage dramatically.
- For animations of type "thermometer", you should try to use images
*without* any mask (or with a mask with just one single rectangle).
Images with non-rectangular masks or with masks with more than one
rectangle will cause Power PlugIn to use a temporary image for
drawing which can increase CPU-usage (especially if the thermometer-
animations contains many images).
- For animations using blur or alpha-blending you should try to
make their rectangles (defined by "Drawing Rect") as small
as possible since these operations (especiall alpha-blending)
can increase CPU-usage dramatically.
Wyszukiwarka
Podobne podstrony:
SDK EULA
sdk
28 Interfejsy API i SDK
SSO SDK README
WMobile6 5 SDK konfiguracja v1
SDK README
sdk esej mk
SMS SDK README
więcej podobnych podstron