The advantage of using an image file is that the code (and the work involved) is slightly simpler. The disadvantage is that distributing your plugin to users involves also distributing the image file. Also, those image files have to be installed in a specific place, which increases the chances that your user will never see the icon you so lovingly crafted. We do not recommend that you implement icons with this method. However, this section is necessary because there is overlap with the second, recommended, method.
To use an icon in this way, you use the setup call
void cpiDefineIcon( const char *baseName, const char *normalFile, const char *locatedFile, const char *disabledFile, const char *selectedFile, const char *selectedLocatedFile, const char *selectedDisabledFile, CPI_Uint8 transColorRed, CPI_Uint8 transColorGreen, CPI_Uint8 transColorBlue );This allows a file to be defined for each of the icon's possible states, namely
You must supply an entry for the "Normal" state, but NULL may be given for any other icon states for which there is no image. In those cases, the "Normal" state icon will be used.
The baseName is path which is appended to the current Theme path, to create a path name to the icons. The current Theme path can be seen (and changed) in the File Paths section of the Preferences dialog - the default Theme path is $HOME/.rayz/2.2/Themes.
For example, given the following call:
cpiDefineIcon( "Nodes/Pizza/", "Pizza.tiff", NULL, NULL, NULL, NULL, NULL, 255, 0, 255 );RAYZ would look for the file called Pizza.tiff in the directory
The three entries for transColorRed, Green and Blue define the color which is used as a transparency value for the icon. RAYZ icons are not alpha-blended with the background, they are simply painted onto the interface. So the color given here is the color which will be transparent. There is no semi-transparency. This means that anti-aliased icons are more difficult to do in RAYZ, unless the entire icon is color-matched to the interface. You can do that, but since the user can change all the interface colors, that might not be a good idea.
The default transparency color in RAYZ is magenta, which is (255, 0, 255)
To compile in the icon image, you still need to define the icon as given in Method One, and then there is the added step of registering the icon data. This looks like this:
cpiRegisterIconData( "Pizza.tiff", Pizza_SIZEX, Pizza_SIZEY, Pizza_data, 255, 0, 255 );This must be done for each icon that was defined in the preceding cpiDefineIcon() call. The definition of cpiRegisterIconData is:
void cpiRegisterIconData( const char *name, CPI_Int32 sizeX, CPI_Int32 sizeY, const CPI_Uint8 *iconData, CPI_Uint8 transColorRed, CPI_Uint8 transColorGreen, CPI_Uint8 transColorBlue );where "name" must match the name of the filename given in cpiDefineIcon(). The size is the size of the image in pixels, and the iconData array is an array of pixel data of the appropriate size. The RAYZ developer's kit comes with a utility program, rayz_iconreader, which can read in an icon image file and write out a header file for inclusion in the plugin. This is explained fully in the next section.
The transColorRed, Green and Blue values are the same as for Method One, and in RAYZ the default transparency color is magenta, or (255, 0, 255).
rayz_iconreader <inputfile> <iconfile> <outputfile> where: <inputfile> is the full path to the icon file to read <iconfile> is a base name for use in constructing #defines, etc <outputfile> is the full path to the resulting header fileFor example, to create the file Pizza.h, which is supplied with the examples, the command line use was:
% rayz_iconreader Pizza.tiff Pizza Pizza.hImportant Note: The resulting array declaration is appended to the contents of the output file, if any. This allows a use such as:
% rayz_iconreader icon1.tiff Icon1 icons.h % rayz_iconreader icon2.tiff Icon2 icons.h % rayz_iconreader icon3.tiff Icon3 icons.hIn which all the icons are defined in a single header file.
Part of the output is a set of #define statements listing the size of the icon, which may be used in the Register() calls. For example, the file Pizza.h (supplied as an example), lists
#define Pizza_SIZEX 60 #define Pizza_SIZEY 45These constants are then used in the call to cpiRegisterIconData().
Important note: Icons must be 3 channel, tiff format files. Alpha is not currently used in RAYZ icon images. To create an icon image with transparent areas, use the transparency color (magenta, by default) instead of alpha.