(Engine-Level Function)
| Description: | Modifies an existing image, producing a new one that displays a sub-section of the original. |
| Returns: | Image handle |
Usage:  |
Script or steady state. |
| Function Groups: | Graphics, Window |
| Related to: | BitmapInfo | GUIBitmap | GUIButton | ImageArray | ImageSweep | MakeBitmap | ModifyBitmap |
| Format: |
Crop(OrigBMP, Left, Top, Width, Height) |
| Parameters: |
| OrigBMP |
| Required. The original image to be cropped. This must be a valid image object, created with the MakeBitmap statement. |
| Left |
| Required. Any expression for the number of pixels from the left side of the original image to set to be the left side of the new image. "0" will start at the same place as the original image. |
| Top |
| Required. Any expression for the number of pixels from the top of the original image to set to be the top of the new image. "0" will start at the top of the original image. |
| Width |
| Required. Any expression for the number of pixels wide the new image will be. The new image will be enforced to be at least 1 pixel wide, even if Width is set to less than 1 pixel. |
| Height |
| Required. Any expression for the number of pixels high the new image will be. The new image will always be at least 1 pixel height, even if Height is set to less than 1 pixel. |
| Comments: | This function allows for the enlargement of parts of an original image, without requiring that the entire image be drawn. It also uses very little memory, and is very fast, as compared to calls to creating a file from a disk file each time. There are no restrictions on how large the new image may be, so it can be larger (in any dimension) than the original. If this is the case, the extra space will be filled with black pixels. Values for Left and Top that are less than zero (0) are therefore permitted. Width and Height should be given a value of at least one "1", but may be as large as desired. Any transparency in the original image is preserved in the cropped image. Cropping can be cumulative, so that you can take the output of one crop function and use that as input to another. The result is that the left and top of the new transform are equivalent to the sum of the values in each of the original transforms. However, since width and height are in pixels, the number of pixels specified each time is exactly how large the resulting image will be. The image resulting from a call to Crop() can be used any place that an image may be used, such as in a call to GUIBitmap or GUIButton. |
Example:
Img = Crop(MakeBitmap("TANKS.BMP", 0), 10, 10, 50, 50);
GUIBitmap(250, 150, 350, 50 { position },
1, 1, 1, 1, 1 { scaling },
0, 0 { trajectory, rotation },
1, 0 { visibility },
0, 1, 1 { selectability },
Img { image });
This example displays a 50x50 pixel subsection beginning 10 pixels from the left and 10 pixels from the top of the original image, "TANKS.BMP". It is then displayed in a 100x100 pixel square on the screen. Any place the color was black (index 0) in the image will be shown as transparent.
If Watch(1, BitmapFile);
[
Img = MakeBitmap(BitmapFile);
ImgWidth = BitmapInfo(Img, 0);
ImgHeight = BitmapInfo(Img, 1);
]
Img2 = Crop(Img, ImgWidth*0.25, ImgHeight*0.25,
ImgWidth*0.5, ImgHeight*0.5);
This example creates and stores an image in Img2 which is the middle section of the original image.
