Name

image_raw_embed -- embed an image into the PDF

Synopsis

int image_raw_embed ( string data, string colorspace, int bitspercolor, int height, int widht[, string filter[, array additional]] )

Description

This function is used to insert an image into the PDF file.

data should contain the raw, binary imagedata.

colorspace is a string value used to tell the PDF viewer how to decode the binary data. Possible values are '/DeviceGray', '/DeviceRGB', '/DeviceCYMK', '/CalGray', '/CalRGB', '/Lab', '/ICCBased', '/DeviceN', '/Seperation', and '/Indexed'. See the PDF specification for details.

bitspercolor tells the PDF viewer how many bits each color component uses. The most common value is 8, although all integers are legal. The PDF viewer application will use this value and the colorspace value to calculate how many bits are used to define each pixel. For example, if the colorspace is /DeviceCYMK and the bitspercolor is 4, then 16 bits define each pixel (4 colors * 4 bits per color).

height and width must describe the height and width of the image in pixels.

The optional parameter filter is a string used to determine what filter to use to decode the binary data. If omitted, no filter is used. Note that if compression is enabled, then the '/FlateDecode' filter is applied during the ->generate() process; thus it is not recommended to use /FlateDecode during this part of the process. Common values (for images) are '/LZWDecode', '/RunLenghtDecode', '/DCTDecode', and '/CCITTFaxDecode'. See the PDF spec for all possible values.

additional is an array of additional entries for the image dictionary. Common use of this could be to set the /DecodeParms value.

The function returns a library ID that must be used to paint the embedded image, or false on error.

Examples

The following creates a single-pixel image and embeds it

$data = "\xff\x00\x00";
$image = $pdf->image_raw_embed($data, '/DeviceRGB', 8, 1, 1);
$placement = $pdf->image_place($image, 10, 10, $page);

See Also

History

This function has been in the library longer than jfif_embed() but was missing documentation until version 2.5.

The additional parameter was added in 2.5

Bugs

This method doesn't have near the sanity checking it could/should have. It's perfectly possible to specify a number of bogus values and this method would return successfully while creating a totally invalid embedded image.

Some PDF viewers have problems displaying images in certain formats. Before reporting bugs concerning images, ensure that you are using the latest version of your PDF viewer program. Also be sure that the image is valid in the format that you are using.