Lingo Dictionary > A-C > copyPixels() |  |

copyPixels()

Syntax

    imageObject.copyPixels(sourceImageObject, destinationRect, sourceRect {, parameterList})
    imageObject.copyPixels(sourceImageObject, destinationQuad, sourceRect {, parameterList })

Description

This function copies the contents of the `sourceRect` from the `sourceImageObject` into the given `imageObject`. The pixels are copied from the `sourceRect` in the `sourceImageObject` and placed into the `destinationRect` or `destinationQuad` in the given `imageObject`. See `quad` for information on using quads.

You can include an optional property list of parameters in order to manipulate the pixels being copied before they are placed into the `destinationRect`. The property list may contain any or all of the following parameters:

Property | Use and Effect
--- | ---
#color | The foreground color to apply for colorization effects. The default color is black.
#bgColor | The background color to apply for colorization effects or background transparency. The default background color is white.
#ink | The type of ink to apply to the copied pixels. This can be an ink symbol or the corresponding numeric ink value. The default ink is #copy. See ink for the list of possible values.
#blendLevel | The degree of blend (transparency) to apply to the copied pixels. The range of values is from 0 to 255. The devault value is 255 (opaque). Using a value less than 255 forces the #ink setting to be #blend, or #blendTransparent if it was originally #backgroundTransparent. You may also substitute #blend as the property name and use a value range of 0 to 100. See blend for more information.
#dither | A TRUE or FALSE value that determines whether the copied pixels will be dithered when placed into the `destinationRect` in 8- and 16-bit images. The default value is FALSE, which maps the copied pixels directly into the `imageObject`'s color palette.
#useFastQuads | A TRUE or FALSE value that determines whether quad calculations are made using Director's faster but less precise method when copying pixels into a `destinationQuad`. Set this to TRUE if you are using quads for simple rotation and skew operations. Leave it FALSE (the default value) for arbitrary quads, such as those used for perspective transformations. See useFastQuads.
#maskImage | Used to specified a mask or matte object created with the `createMask()` or `createMatte()` functions to be used as a mask for the pixels being copied. This allows you to duplicate the effects of mask and matte sprite inks. Note that if the source image has an alpha channel and its `useAlpha` property is TRUE, the alpha channel is used and the specified mask or matte is ignored. The default is no mask.
#maskOffset | A point indicating the amount of x and y offset to apply to the mask specified by #maskImage. The offset is relative to the upper left corner of the `sourceImage`. The default offset is (0, 0).

When copying pixels from one area of a cast member to another area of the same member, it is best to copy the pixels first into a duplicate image object before copying them back into the original member. Copying directly from one area to another in the same image is not recommended. See `duplicate()`.

To simulate matte ink with `copyPixels()`, create a matte object with `createMatte()` and then pass that object as the `#maskImage` parameter with `copyPixels()`.

Copying pixels from an image object into itself is not recommended. Use separate image objects instead.

To see an example of `quad` used in a completed movie, see the Quad movie in the Learning\Lingo Examples folder inside the Director application folder.

Example

This statement copies the entire image of member Happy into the rectangle of member flower. If the members are different sizes, the image of member Happy will be resized to fit the rectangle of member flower.

    member("flower").image.copyPixels(member("Happy").image,  \
    member("flower").rect, member("Happy").rect)

Example

This statement copies part of the image of member Happy into part of member flower. The part of the image copied from Happy is within rectangle(0, 0, 200, 90). It is pasted into rectangle(20, 20, 100, 40) within the image of member flower. The copied portion of Happy is resized to fit the rectangle into which it is pasted.

    member("flower").image.copyPixels(member("Happy").image,\
    rect(20, 20, 100, 40), rect(0, 0, 200, 90))

Example

This statement copies the entire image of member Happy into a rectangle within the image of member flower. The rectangle into which the copied image of member Happy is pasted is the same size as the rectangle of member Happy, so the copied image is not resized. The blend level of the copied image is 50, so it is semi-transparent, revealing the part of member flower it is pasted over.

    member("flower").image.copyPixels(member("Happy").image,\
    member("Happy").rect, member("Happy").rect, [#blendLevel: 50])

See also

`ink`, `color()`