ImageGear for C and C++ on Windows v19.1 - Updated
Geometric Layout
User Guide > How to Work with... > Common Operations > Viewing > Display Options > Geometric Layout

In ImageGear, an "image rectangle" defines the coordinates for the area of the bitmap that will be saved or displayed. The image rectangle represents a rectangular array of pixels from the bitmap that can include the whole image or any rectangular portion of the image.

You can leave the image rectangle set to its default, which includes the whole image, or you can specify a portion of the image by setting the image rectangle with IG_dspl_layout_set(). 

For a more detailed description of the Image Rectangle and other ImageGear display rectangles, see Geometric Transformations.

The Geometric Layout category includes options that determine the image layout on the destination device:

ImageRect (AT_RECTANGLE) A rectangle that defines the part of the image that is output to the device. It is expressed in image coordinates. By default, this option is set to the entire image.
ClipRect (AT_RECTANGLE) A rectangle that identifies the destination device area that is affected by display operations. Display operations never affect parts of the destination device outside of the ClipRect. It is expressed by device coordinates and is initially assigned the entire client area of the destination device.
DeviceRect (AT_RECTANGLE) A rectangle that identifies the area on the destination device upon which the image is projected. Only the portion of the projection falling within the clip rectangle will be seen. The rest of the clip rectangle may be painted with the background color depending on BkMode. The image does not necessarily fit exactly into the device rectangle. The position of the image inside the device rectangle is determined by other options such as AspectMode, FitMode, and AlignMode (see their descriptions below).
DisplayedImageRect (AT_RECTANGLE) This is not a display option that you can set, however this is a very important concept discussed below. This is the rectangular area that represents the image's size and location on the device (and therefore, it is expressed in device coordinates). It is important to understand that it is not related to ClipRect, which represents the visible part of the image. The DisplayedImageRect's value can be calculated and used but cannot be directly set.
AspectMode (AT_MODE) and AspectValue (DOUBLE)

These options determine an image's aspect ratio (its width-to-height ratio). AspectMode can be assigned one of two possible values:

  • IG_DSPL_ASPECT_FIXED - this aspect ratio is the one contained in AspectValue.
  • IG_DSPL_ASPECT_NOT_FIXED - this aspect ratio is that of the device rectangle.

AspectValue may be any positive number with the following meaning: AspectValue = (DisplayedImageRect.Width / DisplayedImageRect.Height) / (ImageRect.Width / ImageRect.Height). The default values for these options are IG_DISPL_ASPECT_FIXED and 1.0, respectively.

PPMCorrect (BOOL) This option allows you to take into account the image's resolution when calculating the aspect ratio, such that physical width and height are actually used for calculation. If this value is TRUE then ImageRect.Width and ImageRect.Height will be altered based on the horizontal and vertical resolution, respectively. The default value is FALSE.
FitMode (AT_MODE)

This value defines how an image fits to the device rectangle while preserving its aspect ratio according to the AspectMode and AspectValue options. The possible values are:

  • IG_DSPL_FIT_TO_DEVICE - in this mode, the image is scaled to fit both the width and height of the device rectangle.
  • IG_DSPL_FIT_TO_WIDTH - in this mode, the image is scaled to fit the width of the device rectangle.
  • IG_DSPL_FIT_TO_HEIGHT - in this mode, the image is scaled to fit the height of the device rectangle.
  • IG_DSPL_ACTUAL_SIZE - in this mode, the device rectangle is ignored, and the image is scaled 1:1.

The default value is IG_DSPL_FIT_TO_DEVICE.

AlignMode (AT_MODE)

This value defines how the displayed image is aligned relative to the device rectangle. Possible values are bitwise ORs of any two values, such that one of them represents the horizontal alignment and the other represents the vertical alignment.

The values representing the horizontal alignment are:

  • IG_DSPL_ALIGN_X_LEFT - the image is aligned to the left border of the device rectangle.
  • IG_DSPL_ALIGN_X_CENTER - the image is centered horizontally.
  • IG_DSPL_ALIGN_X_RIGHT - the image is aligned to the right border of the device rectangle.

The values representing the vertical alignment are:

  • IG_DSPL_ALIGN_Y_TOP - the image is aligned to the top border of the device rectangle.
  • IG_DSPL_ALIGN_Y_CENTER - the image is centered vertically.
  • IG_DSPL_ALIGN_Y_BOTTOM - the image is aligned to the bottom border of the device rectangle.

The default value is IG_DSPL_ALIGN_X_CENTER | IG_DSPL_ALIGN_Y_CENTER.

ZoomMode (AT_MODE)

The value that specifies how the image is zoomed in the horizontal and vertical directions. Possible values for this option are bitwise ORs of any two flags such that one of them represents a horizontal zoom value and the other represents a vertical zoom value.

Flags representing the horizontal zoom values are:

  • IG_DSPL_ZOOM_H_NOT_FIXED - this mode allows any horizontal zoom value.
  • IG_DSPL_ZOOM_H_FIXED - in this mode, the horizontal zoom factor is taken from ZoomValueH (see below for details).

Flags representing the vertical zoom values are:

  • IG_DSPL_ZOOM_V_NOT_FIXED - this mode allows any vertical zoom value.
  • IG_DSPL_ZOOM_V_FIXED - in this mode the vertical zoom factor is taken from ZoomValueV (see below for details).

The default value for this option is IG_DSPL_ZOOM_H_NOT_FIXED | IG_DSPL_ZOOM_V_NOT_FIXED. Please note that AspectMode takes precedence over ZoomMode. In other words, the vertical zoom values are ignored if AspectMode is set to IG_DSPL_ASPECT_FIXED.

ZoomValueH, ZoomValueV (DOUBLE) These options specify actual horizontal and vertical zoom values according to ZoomMode. Their meaning may be expressed as follows: ZoomValueH = DisplayedImageRect.width / ImageRect.width, ZoomValueV = DisplayedImageRect.height / ImageRect.height. Please note that ZoomValueV is not used if AspectMode is set to IG_DSPL_ASPECT_FIXED.
OrientMode (AT_MODE)

This parameter identifies how the image is oriented before it is drawn on the output device. Possible values are determined by the constants that have the form of IG_DSPL_ORIENT_X_Y, where each of X and Y can be LEFT, TOP, RIGHT, or BOTTOM. X stands for the position where the top-most row of the bitmap will be located after applying the transformation, and Y stands for the position where the left-most column of the bitmap will be located after applying the transformation. For example, IG_DSPL_ORIENT_RIGHT_TOP means that the left-most column will become the image's new top-most row, and the top-most row will become the image's new right-most column. The image will be rotated 90 degrees.

The following constants are defined:

  • IG_DSPL_ORIENT_TOP_LEFT - the image is displayed unchanged.
  • IG_DSPL_ORIENT_LEFT_TOP - the image is rotated 270 degrees and then flipped vertically.
  • IG_DSPL_ORIENT_RIGHT_TOP - the image is rotated 90 degrees.
  • IG_DSPL_ORIENT_TOP_RIGHT - the image is flipped horizontally.
  • IG_DSPL_ORIENT_BOTTOM_RIGHT - the image is rotated 180 degrees.
  • IG_DSPL_ORIENT_RIGHT_BOTTOM - the image is rotated 90 degrees and then flipped vertically.
  • IG_DSPL_ORIENT_LEFT_BOTTOM - the image is rotated 270 degrees.
  • IG_DSPL_ORIENT_BOTTOM_LEFT - the image is flipped vertically.

The default value is IG_DSPL_ORIENT_TOP_LEFT. Note that when changing an image's orientation, the image rectangle's orientation is also changed. The other rectangles and options remain unchanged.

ScrollbarMode (AT_MODE) Scrolling is automatically supported in both horizontal and vertical directions. Scroll parameters are automatically calculated by ImageGear. All scroll parameters are stored apart from scrollbars, and therefore, the image can be scrolled in any possible way. If you want to manage the scrollbars yourself, you may do so by using this option. Possible values for this option include any combination of two flags, such that one of them is a "horizontal" flag and the other is a "vertical" flag. Horizontal flags are: IG_DSPL_HSCROLLBAR_AUTO - allows ImageGear to show and hide the horizontal scrollbar depending on the scroll range. IG_DSPL_HSCROLLBAR_ENABLE - in this mode, ImageGear always shows the horizontal scrollbar even if the scroll range is 0. IG_DSPL_HSCROLLBAR_DISABLE - in this mode, ImageGear ignores the horizontal scrollbar and does not set any of its properties. IG_DSPL_VSCROLLBAR_AUTO - allows ImageGear to show and hide the vertical scrollbar depending on the scroll range. IG_DSPL_VSCROLLBAR_ENABLE - in this mode, ImageGear always shows the vertical scrollbar even if the scroll range is 0. IG_DSPL_VSCROLLBAR_DISABLE - in this mode, ImageGear ignores the vertical scrollbar and does not set any of its properties.
ScrollPosH, ScrollPosV(LONG) These options determine how DisplayedImageRect is moved in the horizontal and vertical directions. These values should fall within the corresponding scroll range. Both are set to 0 by default.
MapMode (DWORD), Viewport (AT_RECTANGLE),Window (AT_RECTANGLE) These options are device dependent and allow you to set logical coordinates. It is assumed by ImageGear that all coordinates except ImageRect are logical. These options are necessary to properly convert logical to device coordinates. For the Windows platform the value of MapMode can be any value accepted by the GDI's functions GetMapMode/SetMapMode. The Viewport and Window contain values that are the same as GDI's SetViewportOrgEx/SetViewportExtEx and SetWindowOrgEx/SetWindowExtEx. The default value is the same as current desktop map mode.

This figure demonstrates the meaning of the rectangles listed above:

Some of the options listed above conflict unless priorities are defined. Consider the general algorithm of display rendering. It consists of several steps, and on each step ImageGear processes some options to introduce modifications to the resulting image.

 
Copy Code
if( (ZoomMode&IG_DSPL_ZOOM_H_FIXED) != 0 )
        DisplayedImageRect.width = DisplayedImageRect.width*ZoomValueH,

and

 
Copy Code
if( (ZoomMode&IG_DSPL_ZOOM_V_FIXED) != 0 )
        DisplayedImageRect.height = DisplayedImageRect.height*ZoomValueV.

If AspectMode is set to IG_DSPL_ASPECT_FIXED, then ZoomValueV is not used and the above procedure is changed in the following way:

 
Copy Code
If( (ZoomMode&IG_DSPL_ZOOM_H_FIXED) != 0 )
{
DisplayedImageRect.width = DisplayedImageRect.width*ZoomValueH,
DisplayedImageRect.height = DisplayedImageRect.height*ZoomValueH.
}