Image Capture

• Download demo project - 317 Kb
• Download source - 336 Kb

Introduction

The following subjects are discussed in this article:

1. Capturing an image of the desktop or its work area.
2. Capturing an image of a control or its client area.
3. Capturing an image of what's underneath a control or its client area.
4. Converting images from one format to another.
5. Converting an image to usable icon.

Background

Several C# and C++ articles are available discussing desktop capture. This article generalizes from there and presents a testbed for loading, capturing, and saving images in various graphical formats including conversion of an image to a usable icon.

Captured images are specified areas of GDI windows such as the desktop or a GDI+ control. A GDI (Graphical Device Interface) window is specified by a window handle. To operate on a GDI+ object (basically a .NET control) using a GDI method, we need to use its GDI window handle. Fortunately, it is available.

//  get a control's window handle for GDI manipulation
    ...
System.Windows.Forms.Control ctl = new System.Windows.Forms.Control();
System.IntPtr wndHandle = ctl.Handle;
    ...

Code Organization

The solution consists of two projects;

1. A C# library containing the capture methods (Capture.cs), \ the interop methods (Dll.cs), as well as some debug and sound methods, and
2. A testing form (TestCapture.cs) to exercise the capture methods.

Module Dll.cs

This module defines entry points to methods contained in various DLLs. To simplify access, a namespace called Dll is defined whose class names are the same as the DLLs to be accessed. Each class then defines the desired interop DLL entry points and equivalent C# methods.

Example class defining C# accessible entry points for a DLL

    ...
/// <summary>
/// GDI32 dll access
/// </summary>
public class GDI32
{
  public const int SRCCOPY = 13369376;

  [DllImport("gdi32.dll", EntryPoint="DeleteDC")]
  public static extern IntPtr DeleteDC(IntPtr hDc);

  [DllImport("gdi32.dll", EntryPoint="DeleteObject")]
  public static extern IntPtr DeleteObject(IntPtr hDc);

  [DllImport("gdi32.dll", EntryPoint="BitBlt")]
  public static extern bool BitBlt(IntPtr hdcDest,int xDest,
             int yDest,int wDest,int hDest,IntPtr hdcSource,
             int xSrc,int ySrc,int RasterOp);

  [DllImport("gdi32.dll", EntryPoint="CreateCompatibleBitmap")]
  public static extern IntPtr CreateCompatibleBitmap(IntPtr hdc,
             int nWidth, int nHeight);

  [DllImport("gdi32.dll", EntryPoint="CreateCompatibleDC")]
  public static extern IntPtr CreateCompatibleDC(IntPtr hdc);

  [DllImport("gdi32.dll", EntryPoint="SelectObject")]
  public static extern IntPtr SelectObject(IntPtr hdc,IntPtr bmp);
}                                           // end class GDI32
    ...

Rather than directly accessing the interop methods from other projects, access in this solution is isolated to the classes in the C# library such as the Capture class.

/// <SUMMARY>
/// Example of fully qualified Dll interop method access
/// </SUMMARY>
    ...
//    release window and capture resources
  Dll.USER32.ReleaseDC(wndHWND,wndHDC);  // release window context
  Dll.GDI32.DeleteDC(capHDC);            // delete capture context
  Dll.GDI32.DeleteObject(capBMP);        // delete capture bitmap
    ...

Module Capture.cs

GDI Window Capture

The underlying method used by other capture methods is shown below. This method captures an image within a specified rectangle within a specified window. The window is specified by a GDI window handle. The image is returned as a .NET bitmap.

The method operates as follows. First, a window device context is procured. Second, using the window device context, a compatible capture device context is created, and a GDI bitmap is created and associated with this capture device context. Third, the specified rectangle in the window device context is copied to the capture device context thus populating the GDI bitmap. Finally, the GDI bitmap is converted to a GDI+ bitmap and returned to the caller.

/// <summary>
/// Captures the window or part thereof to a bitmap image.
/// </summary>
public static Bitmap Window(IntPtr wndHWND, 
             int x, int y, int width, int height)
{
  IntPtr  wndHDC = USER32.GetDC(wndHWND);
  // get context for window 

  //  create compatibile capture context and bitmap
  IntPtr  capHDC = GDI32.CreateCompatibleDC(wndHDC);
  IntPtr  capBMP = GDI32.CreateCompatibleBitmap(wndHDC, width, height);

  //  make sure bitmap non-zero
  if (capBMP == IntPtr.Zero)// if no compatible bitmap
  {
    USER32.ReleaseDC(wndHWND,wndHDC); //   release window context
    GDI32.DeleteDC(capHDC); //   delete capture context
    return null; //   return null bitmap
  }

  //  select compatible bitmap in compatible context
  //  copy window context to compatible context
  //  select previous bitmap back into compatible context
  IntPtr  prvHDC = (IntPtr)GDI32.SelectObject(capHDC,capBMP); 
  GDI32.BitBlt(capHDC,0,0,width,height,wndHDC,x,y,GDI32.SRCCOPY); 
  GDI32.SelectObject(capHDC,prvHDC);

  //  create GDI+ bitmap for window
  Bitmap  bmp = System.Drawing.Image.FromHbitmap(capBMP); 

  //  release window and capture resources
  USER32.ReleaseDC(wndHWND,wndHDC); // release window context
  GDI32.DeleteDC(capHDC); // delete capture context
  GDI32.DeleteObject(capBMP); // delete capture bitmap

  //  return bitmap image to user
  return bmp;  // return bitmap
}              // end method Window

Desktop Capture

The desktop capture methods (Desktop and DesktopWA) are shown below.

Method Desktop captures the entire desktop. It picks up the width and height of the desktop, a window handle for the desktop and then uses capture method Window to return a bitmap of the desktop. The width and height are procured using interop routines. This information can also be attained using the method System.Windows.Forms.Screen.PrimaryScreen.Bounds.

Method DesktopWA captures the working area of the desktop. It picks up the bounds of the desktop working area based on a specified control in that working area and then uses capture method Window to return a bitmap of the desktop.

/// <summary>
/// Captures the desktop to a bitmap image
/// </summary>
public static Bitmap Desktop()
{
  // desktop width
  int    width = USER32.GetSystemMetrics(USER32.SM_CXSCREEN);
  // desktop height
  int    height = USER32.GetSystemMetrics(USER32.SM_CYSCREEN);
  // desktop window handle
  IntPtr desktopHWND = USER32.GetDesktopWindow();
  // return desktop bitmap
  return Window(desktopHWND,0,0,width,height);
} // end method Desktop

/// <summary>
/// Captures the desktop work area to a bitmap image
/// </summary>
public static Bitmap DesktopWA(Control ctl)
{
  // desktop work area
  Rectangle wa = Screen.GetWorkingArea(ctl);
  // desktop window handle          
  IntPtr    desktopHWND = USER32.GetDesktopWindow();
  // return work area bitmap
  return    Window(desktopHWND,wa.X,wa.Y,wa.Width,wa.Height);
} // end method DesktopWA

Control Capture

The control capture method is Control. The first method Control captures the entire control. The second method Control captures a specified portion of the control or what's underneath the control.

When capturing what's beneath a control, the desired area is converted to screen coordinates and a window handle to the screen (desktop) is utilized for the capture. The window handle for the control cannot be used since the desired area is on the screen under the control. To perform this capture and procure the desired bitmap, the control must be hidden prior to capture.

When capturing an area on the control, the desired area is converted to control coordinates and a window handle for the control is utilized for the capture.

/// <summary>
/// Captures the control to a bitmap image. The entire control is
/// captured including both the client and non-client areas.
/// </summary>
public static Bitmap  Control(System.Windows.Forms.Control ctl)
{
  return Control(ctl,false,false); // capture entire control
} // end method Control

/// <summary>
/// Captures the specified area of the control or whats underneath
/// the control. If the argument flag client is true, only the client
/// area of the control is captured, otherwise the entire control is 
/// captured. If the argument flag under is true, the capture area under
/// the control is captured, otherwise the specified area on the control
/// is captured.
/// </summary>
public static Bitmap  Control(System.Windows.Forms.Control ctl
                             ,bool client,bool under)
{
  Bitmap    bmp;      // capture bitmap
  Rectangle ctlR;     // capture area in control coordinates
  Rectangle scrR;     // capture area in screen coordinates
  
  // get capture rectangle in control
  // coordinates and in screen coordinates
  if (client)        // if capturing client area
  {
     //   get rectangle in control coordinates
     ctlR = ctl.ClientRectangle;
     //   get rectangle in screen coordinates
     scrR = ctl.RectangleToScreen(ctlR);
  }
  else   // if capturing entire control
  {
    //   get rectangle in parent coordinates
    scrR = ctl.Bounds;
    if (ctl.Parent != null)  //   if parent exists
      //     map to screen coordinates
      scrR = ctl.Parent.RectangleToScreen(scrR);
    // get rectangle in control coordinates
    ctlR = ctl.RectangleToClient(scrR);
  }
  
  // capture an area under the control
  if (under)  // if capture area is under control
  {
    //   save control visibility
    bool prvV = ctl.Visible;
    if (prvV)   //   if control visible
    {
      //     make control invisible
      ctl.Visible = false;
      //     allow time for control to vanish
      Thread.Sleep(m_HDelay);
    ) //     prior to image capture

    //  Capture bitmap using desktop window handle and screen coordinates
    //  for the capture area. Note, the control window handle can NOT be used
    //  for capturing an area under the control.
    //   get window handle for desktop
    IntPtr  desktopHWND = USER32.GetDesktopWindow();
    //   get bitmap for capture area under control
    bmp = Window(desktopHWND,scrR);
    if (ctl.Visible != prvV) //   if control visibility was changed
      ctl.Visible = prvV;    //     restore previous visibility
  }

  //  capture an area on the control
  else  // if capture area not under control
  {
    //  Capture bitmap using control window handle and control coordinates
    //  for capture area.
    bmp = Window(ctl.Handle,ctlR);
    //   get bitmap using control window handle
  }
  return bmp;  // return requested bitmap
}              // end method Control

ImageCapture.cs

The image capture form allows images to be loaded, saved, captured, and converted. It handles one image at a time and does not as yet include image editing functions. It will, optionally, retain the aspect ratio of an image. Load and save support a number of image formats allowing image format conversion. And, images can be converted and saved as usable icons. The form was used for testing, and has very elemental error checking and recovery capabilities.

Image Capture

Action menu items control image capture. Desktop or desktop area image capture is accomplished by clicking the appropriate action menu item, "Capture Desktop" or "Capture Desktop Work Area" respectively.

Partial desktop image captures are done using the viewport. The viewport is the client area of the form. To use the viewport, it must first be opened. This is done by clicking action menu item "Open Viewport". Opening the viewport causes the form's transparency key to be set to the background color of the form. This makes the area underneath the client area of the form visible to the user. The user moves the form over and sizes the form to encompass the desired selection. Capture of the image is accomplished by clicking action menu item "Capture View". This causes the view to be captured and the viewport to be closed.

Prior to loading or capturing another image, the current image must be saved or released. The action menu item "Release View" will dispose off the current image.

Image Load

An image may be loaded from a file. For images other than icons, the method Image.FromFile is utilized to input the image. This method automatically detects the format of the image upon input, without requiring the user to specify that format. The image is then converted to a bitmap.

Icons are special cased. Icons are input using the Icon constructor, and then converted to a bitmap.

/// <summary>
/// Menu selection to load an image from a file.
/// </summary>
private void miLoad_Click(object sender, System.EventArgs e)
{
  if (UnsavedBM())                         // if unsaved image exists
    return;                                //   return
  CloseViewport();                         // close viewport

  DialogResult dr = ofd.ShowDialog(this);  // show the dialog
  if (dr != DialogResult.OK)               // if not ok
    return;                                //   forget it

  string fn = ofd.FileName;                // pick up file path
  int    idx = fn.LastIndexOf("\\");       // get last backslash
  sfd.InitialDirectory = (idx <= 0)? "" : fn.Substring(0,idx);
  sfd.FileName = fn;                       // make default for save
  Dispose(capBM);              // dispose of previous bitmap (if any)
    
  idx = fn.LastIndexOf(".") + 1;           // find start of extension
  string ext = (idx > 0) && (idx < fn.Length)? fn.Substring(idx) : "";
  if (ext.ToLower().Equals("ico"))         // if file is an icon
  {
    this.Icon = new Icon(fn);              //   read new form icon from file
    capBM = this.Icon.ToBitmap();          //   convert to bitmap
  }
  else                                     // if file not an icon
    capBM = new Bitmap(Image.FromFile(fn));//   read bitmap from file

  PicInCtl(curCtl,false);   // place new image in current control
  capBMSaved = true;        // image has been saved, it came from a file
  Play("LoadView.wav");     // play load view sound
}                           // end action miLoad_Click

Image Display

A loaded or captured image is manipulated internally as a Bitmap. It should be noted that a Bitmap is based on an Image and can thus be thought of as an image when necessary. Essentially, the current image is displayed as the background of the client area of the form. When the form is resized, the image is resized to fit within its client area. If the image aspect ratio is being preserved, the normal case, then an aspect sized version of the image will be fit within the client area of the form. No image significance is lost since the original bitmap is preserved.

Image Save

An image may be saved to a file. For images other than icons, the Bitmap instance method Save is utilized to output the image. This method supports a large number of image formats. However, the image format must be explicitly specified when invoking Bitmap instance method Save. A filter is used in the save file dialog to allow the user to select the image format.

/// <summary>
/// Menu selection to save the image to a file.
/// </summary>
private void miSave_Click(object sender, System.EventArgs e)
{
  if (capBM == null)                       // if no bitmap
    return;                                //   return
  DialogResult dr = sfd.ShowDialog(this);  // show the dialog
  if (dr != DialogResult.OK)               // if not ok
    return;                                //   forget it

  string fn = sfd.FileName;                // pick up file path
  if (fn.Equals(""))                       // if no filename
  {
    Play("Error.wav");                     //   play nothing saved sound
    MessageBox.Show("No filename specified, nothing saved");
    return;
  }

  // set default image type to selected filter format
  ImageType it = ImageType.SetImageType(sfd.FilterIndex-1);  
  // filter index is one based
  
  if (it.format == ImageFormat.Icon)     // if saving an icon
  {
    Icon = BitmapToIcon(capBM,aspect);   //   convert bitmap to icon
    Stream s = sfd.OpenFile();           //   open file
    Icon.Save(s);                        //   save the icon
    s.Close();                           //   close file
  }
  else                                   // if saving other format
    capBM.Save(fn,it.format);            //   use generic image save
  capBMSaved = true;                     // image has been saved
  Play("SaveView.wav");                  // play image saved sound
}                                        // end action miSave_Click

Image to Icon

An image may be saved as an icon. A usable icon is based on a small bitmap. The maximum size of this bitmap is determined by display resolution and color support. For the purposes of this demo, a display supporting at least 256 colors or more was assumed. For this display assumption, the maximum bitmap size is 96 by 96. Converting the image bitmap to a bitmap for the icon is not a problem. However, preserving the image aspect ratio is a problem.

The choice made in this demo for icon aspect preservation was to drop significance in the longest direction. In other words, a bitmap was formed that was 96 pixels in the shortest direction and more than this in the longest direction. The icon bitmap was then extracted from this bitmap using a centering rectangle thus dropping some significance along both outer edges for the longest direction. To preserve aspect without losing significance, the image should be edited and/or cropped into a square. This can be done in an external image editor since these features don't currently exist in ImageCapture.

/// <summary>
/// Convert bitmap to icon preserving aspect if requested
/// </summary>
private Icon BitmapToIcon(Bitmap obm,bool preserve)
{
  Bitmap bm;
  //  if not preserving aspect
  if (!preserve)                         // if not preserving aspect
    bm = new Bitmap(obm,ICON_W,ICON_H);  //   rescale from original bitmap

  //  if preserving aspect drop excess
  //  significance in least significant direction
  else                           // if preserving aspect
  {
    Rectangle rc = new Rectangle(0,0,ICON_W,ICON_H);
    if (obm.Width >= obm.Height)  //   if width least significant
    {                            //  rescale width based on max icon height
      bm = new Bitmap(obm,(ICON_H*obm.Width)/obm.Height,ICON_H);
      rc.X = (bm.Width - ICON_W) / 2; // chop off excess width significance
      if (rc.X < 0) rc.X = 0;
    }
    else                   //   if height least significant
    {                      //   rescale height based on max icon width
      bm = new Bitmap(obm,ICON_W,(ICON_W*obm.Height)/obm.Width);
      rc.Y = (bm.Height - ICON_H) / 2; // chop off excess height significance
      if (rc.Y < 0) rc.Y = 0;
    }
    bm = bm.Clone(rc,bm.PixelFormat); //   bitmap for icon rectangle
  }

  //  create icon from bitmap
  Icon icon = Icon.FromHandle(bm.GetHicon()); // create icon from bitmap
  bm.Dispose();                               // dispose of bitmap
  return icon;                                // return icon
}                                             // end method BitmapToIcon

Points of Interest

1. Aspect Preservation - Abandoned Approach. Keying off form size changes to then modify the client area of the form for aspect preservation created an out of order resonating series of form size changes that led to unfortunate behavior. Even though these issues were eventually overcome, the approach was abandoned as too cumbersome.
2. GDI Window Handles - Since a GDI window handle can be used to conger up the associated GDI+ control, using the Control.FromHandle method, it seemed possible there might be a GDI+ control available for the desktop that could be accessed using this method. Of course, the results after testing this hypothesis were disappointing. Although the test crashes were variously reported by the debugger, no GDI+ control for the desktop was ever forthcoming using this technique.
3. Image Beneath Control - Various methods were tested to gather the image beneath a control. Timing issues arose during some of the early tests. A variable delay was introduced to overcome this problem. The code still has a 5ms delay to allow the control being hidden to drop out of the desktop bitmap. This delay may no longer be required. More testing needs to be done in this regard.

History

01/31/2004 - Initial release.