Creates a new McImage instance and optionally adds it to the McImages collection.

A McImage object.  

The new McImage instance.

object.Add ([Name], [Width], [Height], [FrameCount], [Type], [ImageCreationFlags])

The Add Method syntax has these parts:

The settings for ImageCreationFlags are:

Constant		Value	Description
	mcicfDefault	0
	mcicfContiguous	1	If set, frames are allocated contiguously, and you cannot add to the FrameCount at a later time.
	mcicfNoInit	2	Default is to initialize to 0 (black), this flag suppresses initialization.
	mcicfNoAddToCollection	4	If set, the image is created, but not added to the collection (see Notes).
	mcicfNotVisible	8	If set, the image is created, possibly added to collection (see above), but not made visible.
	mcipfNoImportProperties	8388608	Suppress ImportProperties for functions creating an image from another.

An McImage instance is created with a specified name, size, pixel type, and number of frames. By default the new image is also added to the Engine.Images collection. A SNC_NOTIFY_IMS_IMAGE_WAS_ADDED SpecialNotify is sent to standard notify clients of the Engine.Images collection after an image is added to the collection; the SpecialNotify VARIANT* pvarNotifyData argument will point to a VT_DISPATCH Variant holding an instance pointer to the newly created McImage.

By default the new image is also added to the Engine.Images collection, however if the mcicfNoAddToCollection Flag bit is set, then the image is not made part of the collection, and it will exist only as long as an AddRef is held on the returned McImage instance pointer.

All images are backed by an McObject instance which bears the McImage.Name property with Engine.McObject(Engine.Images) as its ParentMcObject. All McObject instances connected to McImage instances have the McObject.Category property “McImage”.

“For each” enumerations will only find McImage instances which are part of the collection, and there is no need to keep an AddRef on the interface instance. McImages.Item will return only collection members for numeric (index value) arguments, but it will find any image with a matching Name for string arguments, whether the image is part of the images collection or not.

No SNC_NOTIFY_IMS_IMAGE_WAS_ADDED SpecialNotify is fired if the new image is not to be part of the collection (mcicfNoAddToCollection Flag bit set). However, notify clients can call the McObjects.AttachNotifySinkToCategory to get notifies whenever an object is added to the “McImage” category. Note that at the time this notification is sent, the new image will not yet be part of the images collection.

Resource limits may be reached. The total pixel memory required for a frame of the given Width and Height, with pixels sized and laid out as specified by the Type must be less than 256 MB. If the mcicfContiguous mcImageCreateFlags bit is set in the Flags argument, then the total memory required for all of the FrameCount of these frames must be less than 256 MB.