ImageGear for C and C++ on Windows v19.1 - Updated
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:
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:
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:
The values representing the vertical alignment are:
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:
Flags representing the vertical zoom values are:
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:
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.
}
|
|