User Guide

Chapter 3156
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:
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.
Examples
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)
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 default 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 the
faster but less precise method available in Director 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).