Image Attributes and the ImageAttributes Class

Images represented by the Image class and its inherited classes can also store attributes. The ImageAttributes class represents the attributes of an image. DrawImage can take a parameter of type ImageAttributes, which represents how the colors are applied to an image when it is rendered. The ImageAttributes class has no properties, but it provides many useful methods. Let's take a look at the methods provided by the ImageAttributes class.

8.4.1 The SetWrapMode Method

Sometimes we need to fill a graphics shape with a texture that's smaller or larger than the graphics shape. The wrap moderepresented by the WrapMode enumerationspecifies how a texture is tiled when it is larger or smaller than the area being filled. The members of the WrapMode enumeration are described in Table 8.7.

SetWrapMode is used to set the wrap mode of a texture or gradient. This method takes three parameters: a wrap mode (WrapMode), a color (Color), and a clamp (Boolean). The last two parameters are optional. If the clamp value is true, the texture will be clamped to the image boundary; otherwise there is no clamping.

Listing 8.9 uses this method. First we create an ImageAttributes object and set the wrap mode using SetWrapMode. Then we create an Image object using FromFile, followed by a call to DrawImage with an argument of the ImageAttributes object. DrawImage draws an image on the form, rendered using the colors defined by ImageAttributes.

Table 8.7. WrapMode members

Member	Description
Clamp	Clamps the texture or gradient to the object boundary.
Tile	Tiles the gradient or texture.
TileFlipX	Reverses the texture or gradient horizontally and then tiles it.
TileFlipXY	Reverses the texture or gradient horizontally and vertically and then tiles it.
TileFlipY	Reverses the texture or gradient vertically and then tiles it.

Listing 8.9 Using the SetWrapMode method of ImageAttributes

private void SetWrapMode_Click(object sender,
 System.EventArgs e)
{
 Graphics g = this.CreateGraphics();
 g.Clear(this.BackColor);
 // Create ImageAttributes object
 ImageAttributes ImgAttr = new ImageAttributes();
 // Set wrap mode to tile
 ImgAttr.SetWrapMode(WrapMode.Tile);
 // Create an image
 Image curImage = Image.FromFile("dnWatcher.gif");
 // Draw image
 Rectangle rect = new Rectangle(0, 0, 400, 400);
 g.DrawImage(curImage, rect, 0, 0, 400, 400,
 GraphicsUnit.Pixel, ImgAttr);
 // Dispose of object
 g.Dispose();
}

Figure 8.8 shows the output from Listing 8.9. If the image is smaller than the surface, images are wrapped.

Figure 8.8. Wrapping images

Note

The WrapMode enumeration is defined in the System.Drawing.Drawing2D namespace. Don't forget to add the namespace reference to the project.

 

8.4.2 The SetGamma Method

The SetGamma method sets the gamma value, which represents the brightness of a graphics shape, for all graphics objects, including images, brushes, and pens. Gamma values range from 0.1 to 5.0 (normally 0.1 to 2.2), with 0.1 being the brightest and 5.0 the darkest.

This method takes a floating type parameter as gamma value and a second optional parameter of the ColorAdjustType enumeration type. Using the ColorAdjustType enumeration from the Imaging namespace, you can even specify which GDI+ objects use this color adjustment. For example, if you want to apply gamma values on text only, you can do so using ColorAdjustType.Text, which is described in Table 8.8. The following code snippet sets the gamma value of ImageAttributes.

ImageAttributes ImgAttr = new ImageAttributes();
imageAttr.SetGamma(2.0f, ColorAdjustType.Default);

Now you can use this ImageAttributes object as a parameter of the DrawImage method.

8.4.3 The SetColorMatrix Method

A color matrix represents how colors are represented in an Image object. As we saw in Section 8.3.2, the ColorMatrix object represents a color matrix. SetColorMatrix applies a color matrix to an image. This method takes a parameter of the ColorMatrix class, with two optional parameters of ColorMatrixFlag and ColorAdjustType enumerations.

Table 8.8. ColorAdjustType members

Member	Description
Any	Reserved
Bitmap	For Bitmap objects only
Brush	For Brush objects only
Count	The number of types specified (used internally by GDI+)
Default	For all objects that do no have their own color adjustment information
Pen	For Pen objects only
Text	For text only

Often we don't want all graphics objects to be affected by a color adjustment. Suppose we have some graphics shapes, an image, and some text, and we want only the image to be affected by the color adjustment specified by the SetColorMatrix method. The ColorAdjustType enumeration allows us to specify which graphics objects use the color adjustment information. Table 8.8 describes the members of the ColorAdjustType enumeration.

ColorMatrixFlag specifies the types of images and colors that will be affected by the color adjustment settings. The ColorMatrixFlag enumeration has three members: AltGrays, Default, and SkipGrays. AltGrays is not available for use except by the .NET Framework internally, so basically ColorMatrixFlag provides the option of affecting gray colors or not. The Default value means that all colors will be affected; SkipGrays means that gray shades will not be affected. (You may want to skip some of the gray shades that are used when you're smoothing images.)

In Listing 8.10 we create ColorMatrix and ImageAttributes objects. Then we call SetColorMatrix to add a color matrix to ImageAttributes.ImageAttributes.SetColorMatrix takes ColorMatrix as its first argument.

Listing 8.10 Drawing semitransparent images

private void SetColorMatrix_Click(object sender,
 System.EventArgs e)
{
 Graphics g = this.CreateGraphics();
 g.Clear(this.BackColor);
 Rectangle rect = new Rectangle(20, 20, 200, 100);
 Bitmap bitmap = new Bitmap("MyPhoto.jpg");
 // Create an array of matrix points
 float[][] ptsArray =
 {
 new float[] {1, 0, 0, 0, 0},
 new float[] {0, 1, 0, 0, 0},
 new float[] {0, 0, 1, 0, 0},
 new float[] {0, 0, 0, 0.5f, 0},
 new float[] {0, 0, 0, 0, 1}
 };
 // Create a color matrix
 ColorMatrix clrMatrix = new ColorMatrix(ptsArray);
 // Set ColorMatrix properties
 if( clrMatrix.Matrix34 <= 0.5)
 {
 clrMatrix.Matrix34 = 0.8f;
 clrMatrix.Matrix11 = 0.3f;
 }
 // Create image attributes
 ImageAttributes imgAttributes = new ImageAttributes();
 // Set color matrix
 imgAttributes.SetColorMatrix(clrMatrix,
 ColorMatrixFlag.Default,
 ColorAdjustType.Bitmap);
 g.FillRectangle(Brushes.Red, rect);
 rect.Y += 120;
 g.FillEllipse(Brushes.Black, rect);
 // Draw image
 g.DrawImage(bitmap,
 new Rectangle(0, 0, bitmap.Width, bitmap.Height),
 0, 0, bitmap.Width, bitmap.Height,
 GraphicsUnit.Pixel, imgAttributes);
 // Dispose of object
 g.Dispose();
}

Figure 8.9 shows the output from Listing 8.10. A rectangle and a circle are drawn, and then an image with lower color resolution, as specified by ImageAttributes.

Figure 8.9. Drawing semitransparent images

8.4.4 The SetNoOp and SetColorKey Methods

The SetNoOp method sets the NoOp correction value for Graphics objects. When NoOp is set, no adjustments to the color will be made during the rendering process.

SetColorKey sets the low and high color values for graphics objects and shapes. The SetColorKey method takes a parameter of type ColorAdjustType enumeration (see Table 8.8) that specifies the type of the graphics objects and shapes to be affected by SetColorKey.

Listing 8.11 applies gamma effect and sets color key values using the SetColorKey method.

Listing 8.11 Applying SetGamma and SetColorKey

private void SetNoOp_Click(object sender,
 System.EventArgs e)
{
 // Create a Graphics object
 Graphics g = this.CreateGraphics();
 g.Clear(this.BackColor);
 // Create two colors
 Color lClr = Color.FromArgb(245,0,0);
 Color uClr = Color.FromArgb(255,0,0);
 // Create ImageAttributes object
 ImageAttributes ImgAttr = new ImageAttributes();
 // Set color key
 ImgAttr.SetColorKey(lClr, uClr,
 ColorAdjustType.Default);
 // Set gamma
 ImgAttr.SetGamma(2.0f, ColorAdjustType.Default);
 // Set NoOp
 // ImgAttr.SetNoOp(ColorAdjustType.Default);
 // Create an Image object
 Image curImage = Image.FromFile("dnWatcher.gif");
 // Draw image
 Rectangle rect = new Rectangle(0, 0, 400, 400);
 g.DrawImage(curImage, rect, 0, 0, 400, 400,
 GraphicsUnit.Pixel, ImgAttr);
 // Dispose of object
 g.Dispose();
}

Figure 8.10 shows the output from Listing 8.11.

Figure 8.10. Applying SetGamma and SetColorKey

Now if we uncomment the following line in Listing 8.11:

//ImgAttr.SetNoOp(ColorAdjustType.Default);

the output will look like Figure 8.11. Using SetNoOp cancels all image attribute effects.

Figure 8.11. Using the SetNoOp method

8.4.5 The SetThreshold Method

The SetThreshold method sets the transparency range (threshold) for a specified category. This method takes one parameter representing a threshold value ranging between 0.0 and 1.0, and an optional second parameter of type ColorAdjustType. The value of the threshold specifies a cutoff point for each component of color. For example, suppose that the threshold is set to 0.8 and the value of the red component is 240. Because the value of the red component (240) is greater than 0.8, the red component will be changed to 255 (full intensity).

imageAttr.SetThreshold(0.8f, ColorAdjustType.Default);

8.4.6 The SetBrushRemapTable Method

We have already discussed how the SetRemapTable method sets a remap table to the specified ColorMap object. The OldColor and NewColor properties of ColorMap represent old and new colors, respectively. SetBrushRemapTable converts only the colors of brushes. The ColorMap class also provides both OldColor and NewColor properties.

Listing 8.12 creates a ColorMap object, sets its OldColor and NewColor properties, and then calls SetBrushRemapTable with the ColorMap object.

Listing 8.12 Using SetBrushRemapTable

private void SetBrushRemapTable_Click(object sender,
 System.EventArgs e)
{
 Graphics g = this.CreateGraphics();
 g.Clear(this.BackColor);
 ColorMap[] clrMapTable = new ColorMap[1];
 clrMapTable[0] = new ColorMap();
 clrMapTable[0].OldColor = Color.Red;;
 clrMapTable[0].NewColor = Color.Green;
 ImageAttributes ImgAttr = new ImageAttributes();
 ImgAttr.SetBrushRemapTable(clrMapTable);
 Image curImage = Image.FromFile("Sample.bmp");
 g.DrawImage(curImage, 0, 0);
 Rectangle rect = new Rectangle(0, 0, 400, 400);
 g.DrawImage(curImage, rect, 0, 0, 400, 400,
 GraphicsUnit.Pixel, ImgAttr);
 // Dispose of object
 g.Dispose();
}

8.4.7 The Clear Methods

The ImageAttributes class provides a "clear" method for almost every set method we have discussed in this section. The clear methods take either no parameter or an optional parameter of ColorAdjustType enumeration. These clear methods are listed in Table 8.9.

Table 8.9. The clear methods of ImageAttributes

Method	Description
ClearBrushRemapTable	Clears color remap table for brush.
ClearColorKey	Clears color key values for the graphics objects specified by the ColorAdjustType enumeration.
ClearColorMatrix	Clears color adjust matrix to all zeros.
ClearGamma	Clears gamma effect for the graphics objects specified by the ColorAdjustType enumeration.
ClearNoOp	Clears NoOp setting for all graphics objects.
ClearOutputChannel	Clears output channel selection for graphics objects specified by the ColorAdjustType enumeration.
ClearOutputChannelColorProfile	Clears output channel selection and color profile file for graphics objects specified by the ColorAdjustType enumeration.
ClearRemapTable	Clears color remap table for graphics objects specified by the ColorAdjustType enumeration.
ClearThreshold	Clears threshold value for graphics objects specified by the ColorAdjustType enumeration.

Suppose that we wanted to clear the color key values for all graphics objects. We would use the ClearColorKey method as follows:

imageAttr.ClearColorKey(ColorAdjustType.Default);