Newton Developer Technical Information: Newton Programmer's Guide: 2.1 OS Addendum /

Chapter 6 - Drawing and Graphics 2.1 / Drawing and Graphics Reference

Functions and Methods /

MakeBitmap

MakeBitmap(widthInPixels, heightInPixels, optionsFrame)

Returns a blank (white) bitmap shape of the specified size.

widthInPixels

Width of the bitmap shape.

heightInPixels

Height of the bitmap shape.

optionsFrame

An optional frame specifying additional characteristics of the bitmap shape created by this method. It can contain any of the slots specified here. If this frame is not used, the value of the optionsFrame parameter must be nil.

rowBytes Specifies the number of bytes per row of the bitmap; use only for a data source that creates scan lines longer than the default value. An exMakeBitmapBadArgs exception is thrown if the value of rowBytes is not a multiple of 32 bits or is too narrow for the bitmap's width as specified by the widthInPixels parameter. When no other value is specified, this slot has the default value BAND(widthInPixels + 31, -32) / 8.

depth Specifies a bit depth for the creation of grayscale or color images. The value of depth must be an integer describing the number of bits per pixel, and it must be one of the values 1, 2, or 4. This slot's default value is 1 when no other value is specified.

resolution Specifies high- or low-resolution images. Like a pen size, the value of the resolution slot may be an array or a single value. If this value is an array, the elements of the array specify the x and y dimensions of the pixels comprising the bitmap. If this slot stores a single value, it specifies that the pixels are square, having equal values for their x and y dimensions. Applications that display or otherwise manipulate bitmap documents (for example, fax pages) need to use this slot to control scaling functionality. This slot's default value is [72,72] when no other value is specified.

store By specifying a store, the bitmap is created as a VBO (virtual binary object). To applications, VBOs appear to be NewtonScript binaries, but they are actually handled directly by the system, using automatic compression and decompression to allow these objects to be much larger than the available heap space. If you are going to create a bitmap, and you know that it will ultimately wind up in a soup on a particular store, you can increase the system efficiency by using this slot to specify the store on which to create the object.

If this slot is nil, the NewtonScript heap is used, and the bitmap will not be a VBO. You must limit the use of the NewtonScript heap to small bitmaps only.

A n exception occurs in the event the NewtonScript heap or store does not have enough space for the bitmap.

companderName When a VBO is written to the store, the system uses a compander, or compression- decompression utility. This slot is a string that represents the name of the compander to use when writing or reading this bitmap from the store.

The default compander is TPixelMapCompander, which is efficient for monochrome images.

You can supply your own compander as a protocol. If you don't want to compress the data when written out to the store you would need to supply an appropriate protocol. If you are not writing to the store (default), then there is no compression, no VBO, and the data is written out to the frames heap.

companderData This slot is intended for optional arguments that would be passed to the compander. The default is nil.

return value

A bitmap shape.

DISCUSSION

The origin of the bitmap returned is at (0,0); however, you can subsequently use the OffsetShape function to modify the returned bitmap's origin.

COMPATIBILTITY

Versions of this function prior to Newton 2.1 OS ignore a the depth slot in optionsFrame.