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". For example, a width of -10 crops 10 pixels from the right of the image.

; 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

Only useful if calling ImagePutBitmap. Defaults to false.

  • 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, as calling GdipValidateImage at any other time other than after immediate creation of the bitmap will cause GdipValidateImage to secretly fail.

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

    ; Set global flag. ImagePut.validate := false ; Default is false.

Clone this wiki locally