NewPicture Function

Returns a picture object of the size and depth specified. Used for off-screen drawing and direct pixel manipulation using the RGBSurface property of the Picture class.

Syntax
result = NewPicture( width, height, depth )

Parameters
width | Integer | The width (in pixels) of the new picture.
height | Integer | The height (in pixels) of the new picture.
depth | Integer | The color depth of the new picture. Acceptable values are 0, 1, 2, 4, 8, 16, and 32. A depth of zero indicates that the picture will be created with no pixel map at all; this option is for creating vector graphics, for example with the subclasses of the Object2D class.

Return Value
Result | Picture | A new picture based on the width, height, and depth specified.

# Notes

Use the NewPicture function to create an empty picture object that can be used to create graphics that you don't want drawn to screen immediately. This is commonly referred to as "drawing to an off-screen area."

Pictures that are created with NewPicture with a color depth of 16 or 32 can be manipulated at the pixel level using the RGBSurface property of the Picture class. This is faster than equivalent operations using the Graphics class's methods.

If the application doesn't have enough memory to create the new picture, it will be Nil. The way to detect this is to immediately test for a Nil Picture object immediately after calling NewPicture. This is done in the example in the following section.

Alternatively, you can create a new picture using the New operator instead of using NewPicture. The parameters are the same in either case (width, height, depth), but when you use New, an OutOfMemoryException will be raised if there is insufficient memory to create the requested pixel map.

# Example

The following example creates an animation in an off-screen area and then displays it in a Canvas control once the animation is complete. This approach produces a flicker-free animation.

Dim x,y as Integer
Dim buffer as Picture
'Build a buffer to hold the graphics while they
'are being assembled. Use the canvas Width and
'Height and the color depth on the main screen
Buffer=NewPicture(cvsImage. Graphics.Width,cvsImage. Graphics.Height, Screen(0).Depth)
If Buffer <> Nil then
'Set the starting x and a random y
'position for the spaceship
x=0
y= Rnd*(cvsImage. Graphics.width-50)
'Loop until the x position of the ship is greater
'than the width of the canvas.
Do
'Draw the background into the buffer
buffer. Graphics.DrawPicture Space,0,0
'Draw the spaceship into the buffer
buffer. Graphics.DrawPicture Ship,x,y
'Increment the ship's position
'Note: I increased the increment because this method takes a little longer.
x=x+2
'Update the canvas with the buffer image
cvsImage. Graphics.DrawPicture buffer,0,0
loop until x>cvsImage. Graphics.Width
else 'buffer is Nil
MsgBox "Insufficient memory to continue"
end if

The following code creates the animation directly in the Canvas control, resulting in flicker as the object is moved:

Dim x,y as Integer
'Set the starting x and a random y
'position for the spaceship
x=0
y= Rnd*(cvsImage. Graphics.width-50)
'Loop until the x position of the ship is greater
'than the width of the canvas.
Do
'Draw the background
cvsImage. Graphics.DrawPicture Space,0,0
'Draw the spaceship
cvsImage. Graphics.DrawPicture Ship,x,y
'Increment the ship's position
x=x+1
loop until x>cvsImage. Graphics.Width

Whenever possible, use NewPicture to create smoother animations.

# See Also

Graphics, Picture classes; Canvas control; Nil keyword.