Crop, Scale, & Other Flags

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.

Upscale / Downscale

Use the upscale and downscale flags to force a single direction. This can be useful to enforce upscaling or downscaling only.

; Resize to 640 x 480 if and only if the input is smaller.
ImagePutWindow({image: "cats.jpg", upscale: [640, 480]})

; Resize to 640 x 480 if and only if the input is bigger.
ImagePutWindow({image: "cats.jpg", downscale: [640, 480]})

Decode

Disables the use of fast stream conversions when set to true. Affects: pdf, url, file, stream, randomaccessstream, base64, and hex. Defaults to false.

Enabling this flag will remove the original file encoding, including any compression gains from the original file format. May be useful to verify the contents of the pixel data which would otherwise remain unchecked. Decreases conversion speed.

; Image will be decoded into pixel data and reencoded to PNG.
str := ImagePutBase64({image: "cats.jpg", decode: True})

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

Validate

Checks the pixel data immediately by loading the bitmap into memory. In the future, this may check the headers of stream data.

If calling ImagePutBitmap:

• Calls GdipValidateImage on the bitmap if enabled.
• Forces the image to be loaded into memory. (Bad: Increases peak memory usage.)
• Avoids returning a reference to image data. (Good: Prevents multiple references which can cause data races.)
• Prevents delayed rendering via copy-on-read or copy-on-write. (Good: Loading image data immediately prevents unintentional modifications from being copied.)
• 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. Setting this flag to true is not needed unless you meet the criteria above.

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

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