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.



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.