Skip to content

Crop, Scale, & Other Flags

Jump to bottom
Edison Hua edited this page Jun 21, 2022 · 43 revisions

Usage

Specify image as the object key to cover all possible inputs.

ImagePutWindow({image: "cats.jpg", scale: 2})

Or use a specific data type, such as file:

ImagePutWindow({file: "cats.jpg", scale: 2})

Crop

Pass an [x, y, w, h] array. All four members are required.

; Crop to image to 250 x 250 pixels starting at (100, 100).
ImagePutWindow({image: "cats.jpg", crop: [100, 100, 250, 250]})

Any negative values are interpreted as an absolute value "from the edge". Width and Height correspond to right and bottom respectively.

; Crop 10 pixels from each edge.
ImagePutWindow({image: "cats.jpg", crop: [-10, -10, -10, -10]})

If any of these values are percentages, they should be entered as strings.

; Crop 10% from each edge.
ImagePutWindow({image: "cats.jpg", crop: ["-10%", "-10%", "-10%", "-10%"]})

Any out of bounds values are ignored. Cropping a 200 x 300 image to 500 x 500 pixels will perform no actions, and the original file is unmodified.

Scale

Pass a positive real number. The scaling algorithm uses GDI+ HighQualityBicubic.

; Scale by a factor of 2.5x.
ImagePutWindow({image: "cats.jpg", scale: 2.5})

To scale to a specific width and height, use a 2-member array. Width and height must be integer values.

; Resize to 640 x 480.
ImagePutWindow({image: "cats.jpg", scale: [640, 480]})

To calculate a missing edge, use a size array and replace one of the parameters with any string. This keeps the original aspect ratio.

; Scale height to be 480 pixels.
ImagePutWindow({image: "cats.jpg", scale: ["", 480]})
ImagePutWindow({image: "cats.jpg", scale: ["auto", 480]}) ; Easier to understand.

Decode

If this flag is enabled, the image will be decoded into pixels, losing its original file encoding. Generally, this increases the file size and outputs a PNG. Can be enabled to ensure that valid pixel data is being passed. This flag only affects streams: pdf, url, file, stream, randomaccessstream, base64, and hex. Will increase file size and decrease conversion speed. Defaults to false.

; Creates a PNG file.
ImagePutFile({image: "cats.jpg", decode: true})

; Set global flag.
ImagePut.decode := True ; Default is false.

Validate

If calling ImagePutBitmap:

  • Calls GdipValidateImage on the bitmap if enabled.
  • Forces the image to be loaded into memory.
  • Avoids returning a reference to image data.
  • Prevents delayed rendering via copy-on-read or copy-on-write.
  • Enabling this flag may increase peak memory usage.
  • As a side effect, the image is loaded into memory immediately, meaning any modifications to the original image data will not be copied over.
  • Fixes a rare bug where a bitmap clone of a bitmap clone (2 layers of references) can cause a data race when decoding the image from a stream.
  • Setting the validate flag to true is recommended when returning a GDI+ Bitmap, as calling GdipValidateImage at any time other following immediate creation of the bitmap will cause GdipValidateImage to secretly fail.

Defaults to false.

; Load cats.jpg immediately into memory.
pBitmap := ImagePutBitmap({image: "cats.jpg", validate: true})

; Set global flag.
ImagePut.validate := True ; Default is false.
Clone this wiki locally