Image Attributes and the ImageAttributes Class in GDI+


This article has been excerpted from book "Graphics Programming with GDI+".

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 shown it is rendered. The ImageAttributes class has no properties, but it provides many useful methods. Let's take a look at the method provided by the ImageAttributes class.

The SetWrapMode Method

Sometimes we need to fill a graphics shape with a texture that's smaller or large than the graphics shape. The wrap mode-represented by the WrapMode enumeration-specifies 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

Clams the texture or gradient to the object boundary.

Title

Tiles the gradient or texture.

TileFlipX

Reverse the texture or gradient horizontally and then tiles it.

TileFlipXY

Reverse the texture or gradient horizontally and vertically then tiles it.

TileFlipY

Reverse 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

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

Figure 8.8.jpg

FIGURE 8.8: Wrapping images

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.

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. 

TABLE 8.8: ColorAdjustType members

Member

Description

Any

Reserved

Bitmap

For Bitmap Object only

Brush

For Brush object 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

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 enumeration.

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 uses 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.jpg

FIGURE 8.9: Drawing semitransparent images

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.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.

Now if we uncomment the following line in Listing 8.11:

            //ImgAttr.SetNoOp (ColorAdjustType.Defualt);

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

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);

Figure 8.10.jpg

FIGURE 8.10: Applying SetGamma and SetColorKey

Figure-8.11.jpg

FIGURE 8.11: Using the SetNoOp method

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 represents old and new colors, respectively. SetBrushRemapTable converts only the colors of brushes. The ColorMap class also provides both ColorMap 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("Simple.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();
}

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 section 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 values 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);

Conclusion

Hope the article would have helped you in understanding Image Attributes and the ImageAttributes Class in GDI+. Read other articles on GDI+ on the website.

bookGDI.jpg
This book teaches .NET developers how to work with GDI+ as they develop applications that include graphics, or that interact with monitors or printers. It begins by explaining the difference between GDI and GDI+, and covering the basic concepts of graphics programming in Windows.


Similar Articles
Mindcracker
Founded in 2003, Mindcracker is the authority in custom software development and innovation. We put best practices into action. We deliver solutions based on consumer and industry analysis.