Copying/converting the whole or part of an image

      #include <gandalf/image/image_defs.h>

To copy a whole image of any format or type, use one of the following routines:

      Gan_Image *pImage1, *pImage2, *pImage3; /* declare images 1, 2 & 3 */

      /* ... create images 1 & 2, fill image 1 ... */
      gan_image_copy_q ( pImage1, pImage2 ); /* copy image 1 to image 2, OR */
      pImage3 = gan_image_copy_s ( pImage1 ); /* copy image 1 as new image */

Image 2 here may have been created with any format, type or dimensions. Gandalf will reset the attributes of image 2 to those of image 1 before copying the image data. These routines make copies of the image data, so image 1 may be destroyed after it is copied.

To copy parts of an image, you will need to include the header file

      #include <gandalf/image/image_extract.h>

The routines to extract sub-parts of an image are gan_image_extract_q() and gan_image_extract_s(). They have the following extra features over a simple routine to copy image sub-regions:

1. You can convert the image sub-region to any desired format and type, avoiding the need to perform the two steps of extracting and converting sequentially, and thus saving computation and memory.
2. There is an option to make the resulting sub-image point into the source image, rather than copy the pixel data from it. This saves computation time, and the sub-image produced can be manipulated in the same way as other Gandalf images. Obviously use of this feature precludes use of feature 1.

Here are a couple of examples using the sub-region extraction routines. Firstly a code fragment showing showing the simplest form, where the region is copied from the source image and the format/type remain the same.

      Gan_Image *pImage1, *pImage2; /* declare images 1 & 2 */
      Gan_RGBPixel_uc rgbucPixel;

      /* create RGB unsigned character image 1 and fill with constant */
      pImage1 = gan_image_alloc_rgb_uc ( 200, 100 );
      rgbucPixel.R = 128; rgbucPixel.R = 80; rgbucPixel.R = 200;
      gan_image_fill_const_rgb_uc ( pImage1, &rgbucPixel );

      /* create image 2 in an arbitrary way */
      pImage2 = gan_image_alloc_gl_uc(0,0);

      /* extract sub-region in image 1 into image 2, with height 60, width 50,
         starting as position 30,40 (y,x), leaving the format/type the same.
         The pixel data is copied */
      gan_image_extract_q ( pImage1, 30, 40, 60, 50,
                            pImage1->format, pImage1->type, GAN_TRUE,
                            pImage2 );

Now an example continuing from the above, and showing how to make the result image point into the source image.

      /* extract sub-region in image 1 into image 2, with height 60, width 50,
         starting as position 30,40 (y,x), leaving the format/type the same.
         Here the pixel data is not copied; instead the result image points
         into the source image */
      gan_image_extract_q ( pImage1, 30, 40, 60, 50,
                            pImage1->format, pImage1->type, GAN_FALSE,
                            pImage2 );

Finally an example showing how to convert the sub-region to a different format and type.

      {
         Gan_Image *pImage3; /* declare image 3 */

         /* extract sub-region in image 1 into image 2, with height 60, width 50,
            starting as position 30,40 (y,x), converting the format to grey-level
            and the type to unsigned short. Here the format and type are modified
*           as the pixels are extracted from the source image */
         pImage3 = gan_image_extract_s ( pImage1, 30, 40, 60, 50,
                                         GAN_GREY_LEVEL_IMAGE, GAN_USHORT,
                                         GAN_TRUE );
      }

There are also routines to convert the whole of an image to a different format or type (or both). These are simpler macro versions of gan_image_extract_[qs](), and can be illustrated as follows:

      Gan_Image *pImage1, *pImage2, *pImage3; /* declare images 1, 2 & 3 */

      /* ... create RGB unsigned character image 1 and fill with constant,
             and create image 2 in an arbitrary way ... */

      /* convert image 1 to grey-level format and unsigned short type */
      gan_image_convert_q ( pImage1, GAN_GREY_LEVEL_IMAGE, GAN_USHORT,
                            pImage2 ); /* convert image 1 to image 2, OR */
      pImage3 = gan_image_convert_s ( pImage1, GAN_GREY_LEVEL_IMAGE, GAN_USHORT );

Error detection: These routines return the result image pointer, and return NULL on error.