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 "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%"]})

Specifying a crop array larger than the original file does nothing. Individual out of bounds values are ignored.

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 decode flag.
ImagePut.decode := True ; Default is false.

Validate

If calling ImagePutBitmap:

  • Ensure pixel data is valid by passing validate and decode.
  • 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, meaning that pixel data is pulled when needed, conserving memory and increasing speed. If true, pixels are always pushed to memory immediately.

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

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