ImageWrite

Description

Writes a ColdFusion image to the specified on-disk or in-memory destination.

Returns

Nothing.

Category

Image functions

Function syntax

ImageWrite(name [, destination, quality, optional])

See also

cfimage, GetWriteableImageFormats, ImageNew, ImageRead, IsImageFile

History

ColdFusion 8: Added this function.

Parameters

Parameter

Description

name

Required. The ColdFusion image on which this operation is performed.

destination

Optional. The absolute or relative on-disk or in-memory pathname where you write the file.

If you create the image with the ImageNew function or another operation where you do not specify the filename, specify the destination parameter.

The file format is derived from the extension of the filename. The default value for this parameter is the filename of the original image source.

overwrite

Optional. If set to true, overwrites the destination file.

quality

Optional. Defines the JPEG quality used to encode the image. This parameter applies only to destination files with an extension of JPG or JPEG. Valid values are fractions that range from 0 through 1 (the lower the number, the lower the quality). The default value is 0.75.

Usage

Use the following syntax to specify an in-memory file, which is not written to disk. In-memory files speed processing of transient data.

ram:///filepath

The filepath can include directories, for example ram:///petStore/images/poodle.jpg. Create the directories in the path before you specify the file. For more information on using in-memory files, see Working with in-memory files in the Developing ColdFusion Applications.

The file format is derived from the file extension, therefore, use this function to convert images.

For a list of valid formats to write, see the supported image file formats listed in cfimage. To retrieve a list of writable formats on the server where the ColdFusion application is deployed, use the GetWriteableImageFormats function.

Note: Converting images between one file format to another is time-consuming. Also, image quality can degrade; for example, PNG images support 24-bit color, but GIF images support only 256 colors. Converting transparent images (images with alpha) can degrade image quality.

Example

<!--- This example shows how to convert a GIF image to a PNG image. ---> 
<!--- Use the ImageNew function to create a ColdFusion image. ---> 
<cfset myImage = ImageNew("http://www.google.com/images/logo_sm.gif")> 
<!--- Convert the image to a PNG format. ---> 
<cfset ImageWrite(myImage,"google.png")> 
<!--- Display the PNG image. ---> 
<img src="google.png">