Description
Create an McRegionAccess interface for pixel access, where access may be read-only, write-only or read-write.
-
Return Type
-
A McRegionAccess object.
A new McRegionAccess instance allowing AccessMode pixel access to pixels of the given Type in the given Frame for the given Channel within the given limits.
-
Syntax
-
object.CreateRegionAccessEx ([Type], [Channel], [Frame], [RegionRect], [AccessMode])
The CreateRegionAccessEx Method syntax has these parts: |
| object | An expression evaluating to an object of type McImage. | | Type | Optional. A Variant value. If given, Type of pixel values different from the image Type. For instance, to set/get 16 bit pixel values to/from an 8 bit image, pass the constant mciqtGray16 or an equivalent McImageType interface. By default if Type is missing or Empty, the pixel values will be exposed in the native format of the image.
| | Channel | Optional. A Long value. If given, for multi-channel images, where each pixel has one value per channel, specifies which channel value (starting with channel 0, e.g. Red for mciqtRGB) is to be set/read. By default, if channel = -1, all channel values are considered. When given as a non-negative channel index, the McRegionAccess Get* and Put* methods effectively access the given Channel as a monochrome array of pixels.
| | Frame | Optional. A Long value. If given, the 0-based frame index of the frame to be accessed. Other allowed values are McActiveFrame and McLastFrame. McActiveFrame is the default.
| | RegionRect | Optional. A Variant value. If given, a LONGRECT or an array of four values in the order left, top, right, bottom giving the rectangle to be accessed. If not given, then the whole image is accessed (i.e., left and top are zero while right is Width-1 and bottom is Height-1).
| | AccessMode | Optional. A mcRegionAccessMode enumeration, as described in settings. If given, specifies whether pixel access will be read-only, write-only or read-write (mcramReadWrite is the default). For mcramReadOnly AccessMode, any attempt to write to pixels will result in an error. Similarly, for mcramWriteOnly AccessMode, any attempt to read pixels is an error. The main advantage of specifying the AccessMode is for mcramWriteOnly access to a non-native (i.e., cast) Type. In this case, the initial forward cast of pixels from the native image Type to the requested McRegionAccess.Type can be skipped, thereby potentially saving substantial time.
|
Settings The settings for AccessMode are:
|
 | mcramReadWrite | 0 |
Access may be both read and write
|
| mcramReadOnly | 1 |
Access will be read only. An attempt to write to such an McRegionAccess instance will result in an error.
|
| mcramWriteOnly | 2 |
Access will be write only. For a cast Type this avoids an unnecessary cast when the McRegionAccess is created.
|
Remarks
This method creates an McRegionAccess instance with specified access to pixels. The older CreateRegionAccess method only supports read-write access, CreateRegionAccessEx also allows specification of the region-of-interest as an array or LONGRECT rather than as four separate values as does the older CreateRegionAccess method.
A McRegionAccess instance gives full control over access to pixel values. For simple pixel access, use GetPixel / PutPixel, GetLine / PutLine, GetArea / PutArea.
The source Type.MinCastingLuminance and Type.MaxCastingLuminance can be set by assigning to the CastingSourceRange property. CastingSourceRange is always reset to its default value (RangeMin to RangeMax) after any call to CreateRegionAccessEx.
|
CreateRegionAccessEx Method
