...
The ApBase COM object makes key functions of the ApBase API available via the COM (Component Object Model) mechanism.
Quick Start
To use ApBase COM, create an object of type apbaseCom.ApBase. The details will depend on the tool or language you are using. The following example is in Matlab.
Here is a minimal procedure to open a demo kit camera, initialize the Aptina device, grab an image and convert it to RGB.
...
apbaseCom.ApBase Methods and Properties
First create an object of type abpaseCOM.ApBase. Then use this object to enumerate devices and create a camera object.
The ApBase object is free-threaded.
LONG DeviceProbe(BSTR sSensorDataDirOrFile)
Parameters
A file name or directory name, or an empty string.
...
Error code.
...
Search the system for Aptina demo kit devices or other ApBase compatible camera devices, identify the type of sensor or ISP, and build a set of internal data structures for each device. Use Create() to create a camera object.
...
void CancelProbe()
Cancel a device probe in progress in another thread.
LONG NumCameras
Property Value
Number of cameras.
...
Return the number of cameras discovered by the device probe function.
void Finalize()
Close all drivers and free all memory associated with the devices. Any existing camera objects become invalid. Called automatically when the object is released.
LONG LastError
Property Value
Error code.
...
The error code from the last function call made in the current thread.
LONG LastSideEffects
Property Value
Side effects flags.
Remarks
The side effects flags from the last register write made in the current thread.
IApCamera Create(LONG nDeviceIndex)
Parameters
A device index, 0…NumCameras – 1.
Return Value
An apbaseCOM.ApCamera object.
Remarks
Create a camera object for one of the devices discovered by the device probe. If the device probe has not been done yet, this function will call DeviceProbe() with the default parameters.
Creating and destroying these objects does not affect the device or the device state information kept within ApBase.
After creating a camera device, call LoadIniPreset() or CheckSensorState() to make sure the state of the object is synchronized with the state of the device.
IApCamera CreateFromImageFile(BSTR sFilename)
Parameters
An image file name. Cannot be NULL.
Return Value
ApCamera object.
Remarks
Create a camera object from an image file. This is a way to make use of the image file reading feature of ApBase. Calling GrabFrame() on this object will retrieve the image. The ColorPipe() call can convert it to RGB if it is not RGB already, for example a Bayer image or YCbCr image.
Note:Although it's possible to pass an image file name to DeviceProbe() and call Create(0) to get a camera device object, that method then precludes the possibility of probing for physical camera devices. This function is the preferred way to make a camera object from an image file.
IApCamera CreateVirtual(BSTR sFilename)
Parameters
A sensor data file name. Cannot be NULL.
Return Value
ApCamera object.
Remarks
Create an in-memory camera object from a sensor data file. This is a way to make use of the sensor data file parsing feature of ApBase. No I/O can be done on the resulting object, but it is possible to numerate the registers and get other property values defined in the sensor data file.
BSTR Home
Property Value
Path to the Aptina Imaging installation folder.
BSTR SensorData
Property Value
Path to the sensor_data installation folder where sensor data files are stored.
void OpenIoLog(ULONG nLogFlags, BSTR sFilename)
Parameters
nLogFlags – A combination of AP_LOG_x flags.
sFilename – Name of a file for the log data. A new file is created each time this function is called. Digits 0, 1, etc. will be appended to the file name.
Remarks
Starts a new log file. The file extension is usually .txt. Digits are appended to the filename so the previous log is not overwritten when the program is run again. Use ap_GetIoLogFilename() to get the actual log filename if needed.
void CloseIoLog()
Remarks
Close the current I/O log file.
BSTR IoLogFilename()
Property Value
The current I/O log file name.
Remarks
This function can be called after CloseIoLog(), and will return the most recent log filename.
void IoLogMsg(BSTR sText)
Parameters
sText – A text string to add to the log.
Remarks
The text will be added to the log if there is a log file currently open and AP_LOG was one of the flags passed to OpenIoLog(). A newline at the end of the string is not needed. The text will be preceded by a timestamp in the log file.
void IoLogDebugMsg(BSTR sText, BSTR sSource, BSTR sFunc, ULONG nLine)
Parameters
sText – The message for the log.
sSource – Name of the current source file. Can be empty.
sFunc – Name of the calling function.
nLine – Line number of the source file.
Remarks
The text will be added to the log if there is a log file currently open and AP_LOG_DEBUG was one of the flags passed to OpenIoLog(). A newline at the end of the string is not needed. The text will be preceded by a timestamp in the log file.
The sSource, sFunc, and nLine parameters are optional; if included they will be appended to the message. They are included to make it easy to find the location in your source code where a debug message originated from. Many compilers have macros like _FILE, __FUNCTION, __LINE_ that can be used here.
apbaseCom.ApCamera Properties
Properties of the apbaseCOM.ApCamera interface.
BSTR Name
Property Value
Name of device or sensor.
Remarks
Can be different from the part number. Read only.
BSTR PartNumber
Property Value
Part number.
LONG Version
Property Value
Revision number. Read only.
BSTR VersionName
Property Value
Version string.
Remarks
Usually like REV1, REV2, etc., but can be more descriptive in some cases. Read only.
BSTR FileName
Property Value
The name of the file the device parameters are based on.
Remarks
A .xsdat file for a physical camera, or an image or video file name. Read only.
LONG Width
Property Value
Image width in pixels.
Remarks
This property can be set, but setting it does not affect the state of a physical camera. The width, height, and image type can be set together in one call with SetImageFormat().
LONG Height
Property Value
Image height in pixels.
Remarks
This property can be set, but setting it does not affect the state of a physical camera. The width, height, and image type can be set together in one call with SetImageFormat().
BSTR ImageType
Property Value
The image type as a string.
Remarks
This property can be set, but setting it does not affect the state of a physical camera. The width, height, and image type can be set together in one call with SetImageFormat().
The possible image types are "BAYER-6", "BAYER-8", "BAYER-10", "BAYER-8+2", "BAYER-10IHDR", "BAYER-12", "BAYER-12HDR", "BAYER-8+4", "BAYER-14", "BAYER-14HDR", "BAYER-16", "BAYER-20", "BAYER-16+4", "BAYER-STEREO", "YCBCR", "YCBCR-16", "YCBCR-10", "YCBCR-20", "YUV-420", "M420", "RGB-565", "RGB-555", "RGB-444X", "RGB-X444", "RGB-332", "RGB-24", "RGB-32", "RGB-48", "BGRG", "JPEG", "JPEG-SPEEDTAGS", and "JPEG-ROT".
Functions for Executing Scripts
Functions of the apbaseCOM.ApCamera interface for initializing the camera.
LONG LoadIniPreset(BSTR sIniFile, BSTR sPreset)
Parameters
sIniFile – An ini file name. Can be NULL or empty.
sPreset – Name of the preset to run. Can be NULL or empty.
Return Value
Error code. 256 for success.
Remarks
Execute the ini file preset specified. If the sIniFile parameter is NULL or empty, the default ini file is used. If the sPreset parameter is NULL or empty, the default initialization procedure is executed, usually "Python:", if it exists, followed by "Demo Initialization".
After creating a camera device, call this function or CheckSensorState() to make sure the state of the object is synchronized with the state of the device.
LONG CheckSensorState(LONG nCheckFlags)
Parameters
Flags. Not used. Pass 0.
Return Value
Side effects flags.
Remarks
Re-read all registers on the device to determine the current modes, and update the internal data structures and the demo kit hardware.
Although ApBase examines all register writes as they happen to track the current modes of the camera, there are cases where the internal state of ApBase can get out of sync with the device. For example, downloading a firmware patch to an SOC or ISP can have results that can't be predicted by the software. This function can be used to re-sync ApBase to the device state.
Functions for Reading Sensor or ISP Registers
Functions of the apbaseCOM.ApCamera interface for accessing device registers.
ULONG GetSensorRegister(BSTR sRegisterName, BSTR sBitfieldName, LONG bCached)
Parameters
sRegisterName – Register name, from xsdat file.
sBitfieldName – Bitfield name, from xsdat file. Can be NULL or empty to read the whole register.
bCached – If non-zero, use a cached register value if available.
Return Value
Register value.
Remarks
Read the contents of a sensor or ISP register or bitfield, referenced by symbolic name.
ULONG GetSensorRegisterAddr(LONG nAddrType, ULONG nAddrSpace, ULONG nAddr, ULONG nDataBits, LONG bCached)
Parameters
nAddrType – Midlib address type symbol (MI_REG_ADDR, etc.)
nAddrSpace – Register page or addressable region.
nAddr – Register address.
nDataBits – Width of the register read operation.
bCached – If non-zero, use a cached value if available.
Return Value
Register value.
Remarks
Read the contents of a sensor or ISP register, referenced by register type and address.
Functions for Writing Sensor or ISP Registers
Functions of the apbaseCOM.ApCamera interface for accessing device registers.
Register write flags
Some register write functions can return status flags. The LastSideEffect property of the ApBase object can retrieve the flags from the most recent register write.
AP_FLAG_OK – No side-effect.
AP_FLAG_REALLOC – Image format (width, height) or buffer size may change.
AP_FLAG_PAUSE – Sensor may stop streaming.
AP_FLAG_RESUME – Sensor may resume streaming.
AP_FLAG_NOT_SUPPORTED – Selecting a mode that is not supported by the demo system.
AP_FLAG_ILLEGAL_REG_COMBO – The new value creates an invalid combination with some other register(s).
AP_FLAG_ILLEGAL_REG_VALUE – The new value is not supported by the device.
AP_FLAG_REGISTER_RESET – Many other register values will change (reset or state change).
AP_FLAG_CLOCK_FREQUENCY – The clock frequency will change (this is a PLL register or clock divider).
AP_FLAG_REG_LIST_CHANGED – The set of camera registers will change.
AP_FLAG_NOT_ACCESSIBLE – Register is not accessible (standby).
AP_FLAG_READONLY – Writing a read-only register.
AP_FLAG_WRITEONLY – Reading a write-only register.
LONG SetSensorRegister(BSTR sRegisterName, BSTR sBitfieldName, ULONG nValue)
Parameters
szRegisterName – Register name, from xsdat file.
szBitfieldName – Bitfield name, from xsdat file. Can be NULL or empty to write the whole register.
nValue – New register value.
Return Value
Side effects flags.
Remarks
Write the contents of a sensor or ISP register or bitfield, referenced by symbolic name.
LONG SetSensorRegisterAddr(LONG nAddrType, ULONG nAddrSpace, ULONG nAddr, ULONG nDataBits, ULONG nValue)
Parameters
nAddrType – Midlib address type symbol (MI_REG_ADDR, etc.)
nAddrSpace – Register page or addressable region.
nAddr – Register address.
nDataBits – Width of the register read operation.
nValue – New value for the register.
Return Value
Side effects flags.
Remarks
Same as SetSensorRegister(), but the register is referenced by register type and address, and always writes the whole register.
Functions for Accessing Any Device Register
These functions can access any device on the I2C bus with burst read or burst write transactions.
VARIANT GetRegisters(ULONG nBus, ULONG nDevice, ULONG nAddr, ULONG nAddrBits, ULONG nDataBits, ULONG nValues)
Parameters
nBus – 0 for local bus, 1 for secondary (Far) bus.
nDevice – Device address, usu. 8-bit I2C address.
nAddr – Register address..
nAddrBits – Size of register address in bits.
nDataBits – Size of one register in bits.
nValues – Number of consecutive registers to read.
Return Value
Array of register values.
Remarks
Read the contents of a series of consecutive device registers.
void SetRegisters(ULONG nBus, ULONG nDevice, ULONG nAddr, ULONG nAddrBits, ULONG nDataBits, ULONG nValues, VARIANT pnValues)
Parameters
nBus – 0 for local bus, 1 for secondary (Far) bus.
nDevice – Device address, usu. 8-bit I2C address.
nAddr – Register address..
nAddrBits – Size of register address in bits.
nDataBits – Size of one register in bits.
pnValues – Array of register values.
Return Value
None. Use LastError for status.
Remarks
Write a series of consecutive device registers.
Functions for Getting and Processing Images
Functions of the apbaseCOM.ApCamera interface for getting images.
LONG SetImageFormat(ULONG nWidth, ULONG nHeight, BSTR sImageType)
Parameters
nWidth – New image width, or 0 to keep the current width.
nHeight – New image height, or 0 to keep the current height.
szImageType – Name of new image type, or NULL to keep the current image type.
Return Value
Error code.
Remarks
ApBase normally calculates the image format from the device register settings automatically. This function can be used as an override if necessary.
VARIANT GrabFrame()
Return Value
A 1-dimensional array of pixel values or byte values.
Remarks
Get the next image from the camera.
Use LastError for the error code.
VARIANT ColorPipe(VARIANT inImage, ULONG *outWidth, ULONG *outHeight, ULONG *outBitDepth)
Parameters
inImage – An image received from the device, or a similarly formatted image.
outWidth – Pointer to a memory location to receive the width of the output image. May be NULL.
outHeight – Pointer to a memory location to receive the height of the output image. May be NULL.
outBitDepth – Pointer to a memory location to receive the pixel size of the output image. May be NULL.
Return Value
The processed image, normally an array of RGB pixel values.
Remarks
Convert image data returned from GrabFrame(), or similarly formatted image, to RGB. The output is normally 32 bits per pixel with B – G – R – X byte order.
The converted image could conceivably have different dimensions than the input image. The rgbWidth, rgbHeight and rgbBitDepth parameters will be filled in with the converted image size. These parameters may be NULL.
...
Note: ApBaseCOM does not use Matlab itself, but if you are using DevWare plug-ins that use Matlab, you must install the MatLab Runtime library via this link.
http://www.onsemi.com/pub/Collateral/MCRINSTALLER.ZIP
ApBaseCom.DLL Registration
Although the software installer registersapbaseCom.dll, it is possible that the registration process fails without warning.
If you experience errors regarding server creation, please perform the following;
- Search for “Command Prompt” from Start menu, right click on it and select “Run as administrator”.
- Navigate to the installation folder, usually “C:\Aptina Imaging\bin”.
- Enter; %SystemRoot%\system32\regsvr32 apbasecom.dll
- A “RegSvr32” dialog will appear with “DllRegisterServer in apbasecom.dll succeeded”.
Quick Start
To use ApBase COM, create an object of type apbaseCom.ApBase. The details will depend on the tool or language you are using. The following example is in Matlab.
Here is a minimal procedure to open a demo kit camera, initialize the ON Semiconductor device, grab an image and convert it to RGB.
% open ApBase and Camera, and initialize via "Demo Initialization" preset
apbase = actxserver('apbaseCom.ApBase');
camera = apbase.Create(0);
camera.LoadIniPreset('', '');
% Throw-away the first frame after initialization
raw = camera.GrabFrame;
% grab a frame, convert to RGB
raw = camera.GrabFrame;
rgb = camera.ColorPipe(raw);
Note: The call to LoadIniPreset() with blank parameters is only applicable in situations where the default initialization is sufficient. For demo kits with multiple possible configurations, such as ISP + sensor combinations or different connection options, you will need to specify the particular initialization preset for the configuration.
Note: The rgb image is one long line; this is for performance reasons.
In Matlab you will need to reshape it for display
apbaseCom.ApBase Methods and Properties
First create an object of type abpaseCOM.ApBase. Then use this object to enumerate devices and create a camera object.
The ApBase object is free-threaded.
LONG DeviceProbe(BSTR sSensorDataDirOrFile)
Parameters
A file name or directory name, or an empty string.
Return Value
Error code.
Remarks
Search the system for ON Semiconductor demo kit devices or other ApBase compatible camera devices, identify the type of sensor or ISP, and build a set of internal data structures for each device. Use Create() to create a camera object.
If the parameter is an empty string, the default installation directory is searched for a sensor data file matching each device. Otherwise the parameter can be a specific sensor data file (.xsdat file) to be used with the device, or a directory to be searched for compatible sensor data files.
void CancelProbe()
Cancel a device probe in progress in another thread.
LONG NumCameras
Property Value
Number of cameras.
Remarks
Return the number of cameras discovered by the device probe function.
void Finalize()
Close all drivers and free all memory associated with the devices. Any existing camera objects become invalid. Called automatically when the object is released.
LONG LastError
Property Value
Error code.
Remarks
The error code from the last function call made in the current thread.
LONG LastSideEffects
Property Value
Side effects flags.
Remarks
The side effects flags from the last register write made in the current thread.
IApCamera Create(LONG nDeviceIndex)
Parameters
A device index, 0…NumCameras – 1.
Return Value
An apbaseCOM.ApCamera object.
Remarks
Create a camera object for one of the devices discovered by the device probe. If the device probe has not been done yet, this function will call DeviceProbe() with the default parameters.
Creating and destroying these objects does not affect the device or the device state information kept within ApBase.
After creating a camera device, call LoadIniPreset() or CheckSensorState() to make sure the state of the object is synchronized with the state of the device.
IApCamera CreateFromImageFile(BSTR sFilename)
Parameters
An image file name. Cannot be NULL.
Return Value
ApCamera object.
Remarks
Create a camera object from an image file. This is a way to make use of the image file reading feature of ApBase. Calling GrabFrame() on this object will retrieve the image. The ColorPipe() call can convert it to RGB if it is not RGB already, for example a Bayer image or YCbCr image.
Note:Although it's possible to pass an image file name to DeviceProbe() and call Create(0) to get a camera device object, that method then precludes the possibility of probing for physical camera devices. This function is the preferred way to make a camera object from an image file.
IApCamera CreateVirtual(BSTR sFilename)
Parameters
A sensor data file name. Cannot be NULL.
Return Value
ApCamera object.
Remarks
Create an in-memory camera object from a sensor data file. This is a way to make use of the sensor data file parsing feature of ApBase. No I/O can be done on the resulting object, but it is possible to numerate the registers and get other property values defined in the sensor data file.
BSTR Home
Property Value
Path to the ON Semiconductor Imaging installation folder.
BSTR SensorData
Property Value
Path to the sensor_data installation folder where sensor data files are stored.
BSTR Version
Property Value
The software version number as a string. Example '5.0.24.46000'.
BSTR BuildName
Property Value
Software build name string. Example '5.0.24_Release'.
void OpenIoLog(ULONG nLogFlags, BSTR sFilename)
Parameters
nLogFlags – A combination of AP_LOG_x flags.
sFilename – Name of a file for the log data. A new file is created each time this function is called. Digits 0, 1, etc. will be appended to the file name.
Remarks
Starts a new log file. The file extension is usually .txt. Digits are appended to the filename so the previous log is not overwritten when the program is run again. Use ap_GetIoLogFilename() to get the actual log filename if needed.
ULONG IoLogFlags
Property Value
Flags controlling which logging output is enabled.
1: Errors
2: Minor errors
4: Messages from IoLogMsg() calls
8: Register read/write traffic
16: I/O transport (USB) traffic
32: Messages from IoLogDebugMsg() calls and internal debug messages
void CloseIoLog()
Remarks
Close the current I/O log file.
BSTR IoLogFilename()
Property Value
The current I/O log file name.
Remarks
This function can be called after CloseIoLog(), and will return the most recent log filename.
void IoLogMsg(BSTR sText)
Parameters
sText – A text string to add to the log.
Remarks
The text will be added to the log if there is a log file currently open and AP_LOG was one of the flags passed to OpenIoLog(). A newline at the end of the string is not needed. The text will be preceded by a timestamp in the log file.
void IoLogDebugMsg(BSTR sText, BSTR sSource, BSTR sFunc, ULONG nLine)
Parameters
sText – The message for the log.
sSource – Name of the current source file. Can be empty.
sFunc – Name of the calling function.
nLine – Line number of the source file.
Remarks
The text will be added to the log if there is a log file currently open and AP_LOG_DEBUG was one of the flags passed to OpenIoLog(). A newline at the end of the string is not needed. The text will be preceded by a timestamp in the log file.
The sSource, sFunc, and nLine parameters are optional; if included they will be appended to the message. They are included to make it easy to find the location in your source code where a debug message originated from. Many compilers have macros like _FILE, __FUNCTION, __LINE_ that can be used here.
apbaseCom.ApCamera Properties
Properties of the apbaseCOM.ApCamera interface.
BSTR Name
Property Value
Name of device or sensor.
Remarks
Can be different from the part number. Read only.
BSTR PartNumber
Property Value
Part number.
LONG Version
Property Value
Revision number. Read only.
BSTR VersionName
Property Value
Version string.
Remarks
Usually like REV1, REV2, etc., but can be more descriptive in some cases. Read only.
BSTR FileName
Property Value
The name of the file the device parameters are based on.
Remarks
A .xsdat file for a physical camera, or an image or video file name. Read only.
LONG Width
Property Value
Image width in pixels.
Remarks
This property can be set, but setting it does not affect the state of a physical camera. The width, height, and image type can be set together in one call with SetImageFormat().
LONG Height
Property Value
Image height in pixels.
Remarks
This property can be set, but setting it does not affect the state of a physical camera. The width, height, and image type can be set together in one call with SetImageFormat().
BSTR ImageType
Property Value
The image type as a string.
Remarks
This property can be set, but setting it does not affect the state of a physical camera. The width, height, and image type can be set together in one call with SetImageFormat().
The possible image types are "BAYER-6", "BAYER-8", "BAYER-10", "BAYER-8+2", "BAYER-10IHDR", "BAYER-12", "BAYER-12HDR", "BAYER-8+4", "BAYER-14", "BAYER-14HDR", "BAYER-16", "BAYER-20", "BAYER-16+4", "BAYER-STEREO", "YCBCR", "YCBCR-16", "YCBCR-10", "YCBCR-20", "YUV-420", "M420", "RGB-565", "RGB-555", "RGB-444X", "RGB-X444", "RGB-332", "RGB-24", "RGB-32", "RGB-48", "BGRG", "JPEG", "JPEG-SPEEDTAGS", and "JPEG-ROT".
BSTR GetFuseID(LONG nIndex)
Parameters
nIndex – Index of the device if there are more than one.
Remarks
Gets the FuseID of the device as ASCII hex digits. The nIndex parameter can be used if there are more than one device with a FuseID; for example in the case of an AP0200 with an AR0140 attached, nIndex = 0 will get the AP0200 FuseID, and nIndex = 1 will get the AR0140 FuseID. Use 0 in most cases.
Functions for Executing Scripts
Functions of the apbaseCOM.ApCamera interface for initializing the camera.
LONG LoadIniPreset(BSTR sIniFile, BSTR sPreset)
Parameters
sIniFile – An ini file name. Can be NULL or empty.
sPreset – Name of the preset to run. Can be NULL or empty.
Return Value
Error code. 256 for success.
Remarks
Execute the ini file preset specified. If the sIniFile parameter is NULL or empty, the default ini file is used. If the sPreset parameter is NULL or empty, the default initialization procedure is executed, usually "Python:", if it exists, followed by "Demo Initialization".
After creating a camera device, call this function or CheckSensorState() to make sure the state of the object is synchronized with the state of the device.
LONG RunPython(BSTR sStatements)
Parameters
szStatements – Pointer to a text string consisting of executable Python statements.
Return Value
Error code.
Remarks
Invoke the Python interpreter to execute the given statements.
Note: If your Python statements expect the preset named "Python:" in the default ini file to be executed prior, you may need to do that explicitly in your application using LoadIniPreset().
LONG CheckSensorState(LONG nCheckFlags)
Parameters
Flags. Not used. Pass 0.
Return Value
Side effects flags.
Remarks
Re-read all registers on the device to determine the current modes, and update the internal data structures and the demo kit hardware.
Although ApBase examines all register writes as they happen to track the current modes of the camera, there are cases where the internal state of ApBase can get out of sync with the device. For example, downloading a firmware patch to an SOC or ISP can have results that can't be predicted by the software. This function can be used to re-sync ApBase to the device state.
Functions for Reading Sensor or ISP Registers
Functions of the apbaseCOM.ApCamera interface for accessing device registers.
ULONG GetSensorRegister(BSTR sRegisterName, BSTR sBitfieldName, LONG bCached)
Parameters
sRegisterName – Register name, from xsdat file.
sBitfieldName – Bitfield name, from xsdat file. Can be NULL or empty to read the whole register.
bCached – If non-zero, use a cached register value if available.
Return Value
Register value.
Remarks
Read the contents of a sensor or ISP register or bitfield, referenced by symbolic name.
ULONG GetSensorRegisterAddr(LONG nAddrType, ULONG nAddrSpace, ULONG nAddr, ULONG nDataBits, LONG bCached)
Parameters
nAddrType – Midlib address type symbol (MI_REG_ADDR, etc.)
nAddrSpace – Register page or addressable region.
nAddr – Register address.
nDataBits – Width of the register read operation.
bCached – If non-zero, use a cached value if available.
Return Value
Register value.
Remarks
Read the contents of a sensor or ISP register, referenced by register type and address.
Functions for Writing Sensor or ISP Registers
Functions of the apbaseCOM.ApCamera interface for accessing device registers.
Register write flags
Some register write functions can return status flags. The LastSideEffect property of the ApBase object can retrieve the flags from the most recent register write.
AP_FLAG_OK – No side-effect.
AP_FLAG_REALLOC – Image format (width, height) or buffer size may change.
AP_FLAG_PAUSE – Sensor may stop streaming.
AP_FLAG_RESUME – Sensor may resume streaming.
AP_FLAG_NOT_SUPPORTED – Selecting a mode that is not supported by the demo system.
AP_FLAG_ILLEGAL_REG_COMBO – The new value creates an invalid combination with some other register(s).
AP_FLAG_ILLEGAL_REG_VALUE – The new value is not supported by the device.
AP_FLAG_REGISTER_RESET – Many other register values will change (reset or state change).
AP_FLAG_CLOCK_FREQUENCY – The clock frequency will change (this is a PLL register or clock divider).
AP_FLAG_REG_LIST_CHANGED – The set of camera registers will change.
AP_FLAG_NOT_ACCESSIBLE – Register is not accessible (standby).
AP_FLAG_READONLY – Writing a read-only register.
AP_FLAG_WRITEONLY – Reading a write-only register.
LONG SetSensorRegister(BSTR sRegisterName, BSTR sBitfieldName, ULONG nValue)
Parameters
szRegisterName – Register name, from xsdat file.
szBitfieldName – Bitfield name, from xsdat file. Can be NULL or empty to write the whole register.
nValue – New register value.
Return Value
Side effects flags.
Remarks
Write the contents of a sensor or ISP register or bitfield, referenced by symbolic name.
LONG SetSensorRegisterAddr(LONG nAddrType, ULONG nAddrSpace, ULONG nAddr, ULONG nDataBits, ULONG nValue)
Parameters
nAddrType – Midlib address type symbol (MI_REG_ADDR, etc.)
nAddrSpace – Register page or addressable region.
nAddr – Register address.
nDataBits – Width of the register read operation.
nValue – New value for the register.
Return Value
Side effects flags.
Remarks
Same as SetSensorRegister(), but the register is referenced by register type and address, and always writes the whole register.
Functions for Accessing Any Device Register
These functions can access any device on the I2C bus with burst read or burst write transactions.
VARIANT GetRegisters(ULONG nBus, ULONG nDevice, ULONG nAddr, ULONG nAddrBits, ULONG nDataBits, ULONG nValues)
Parameters
nBus – 0 for local bus, 1 for secondary (Far) bus.
nDevice – Device address, usu. 8-bit I2C address.
nAddr – Register address..
nAddrBits – Size of register address in bits.
nDataBits – Size of one register in bits.
nValues – Number of consecutive registers to read.
Return Value
Array of register values.
Remarks
Read the contents of a series of consecutive device registers.
void SetRegisters(ULONG nBus, ULONG nDevice, ULONG nAddr, ULONG nAddrBits, ULONG nDataBits, ULONG nValues, VARIANT pnValues)
Parameters
nBus – 0 for local bus, 1 for secondary (Far) bus.
nDevice – Device address, usu. 8-bit I2C address.
nAddr – Register address..
nAddrBits – Size of register address in bits.
nDataBits – Size of one register in bits.
pnValues – Array of register values.
Return Value
None. Use LastError for status.
Remarks
Write a series of consecutive device registers.
Functions for Getting and Processing Images
Functions of the apbaseCOM.ApCamera interface for getting images.
LONG SetImageFormat(ULONG nWidth, ULONG nHeight, BSTR sImageType)
Parameters
nWidth – New image width, or 0 to keep the current width.
nHeight – New image height, or 0 to keep the current height.
szImageType – Name of new image type, or NULL to keep the current image type.
Return Value
Error code.
Remarks
ApBase normally calculates the image format from the device register settings automatically. This function can be used as an override if necessary.
VARIANT GrabFrame()
Return Value
A 1-dimensional array of pixel values or byte values.
Remarks
Get the next image from the camera.
Use LastError for the error code.
Note: after initialization via "LoadIniPreset('', '')", do a call to GrabFrame() to throw-away the first frame due to possibility it will be a partial frame - first-waffle kind of thing.
Frames after that will be full frames.
VARIANT ColorPipe(VARIANT inImage, ULONG *outWidth, ULONG *outHeight, ULONG *outBitDepth)
Parameters
inImage – An image received from the device, or a similarly formatted image.
outWidth – Pointer to a memory location to receive the width of the output image. May be NULL.
outHeight – Pointer to a memory location to receive the height of the output image. May be NULL.
outBitDepth – Pointer to a memory location to receive the pixel size of the output image. May be NULL.
Return Value
The processed image, normally an array of RGB pixel values.
Remarks
Convert image data returned from GrabFrame(), or similarly formatted image, to RGB. The output is normally 32 bits per pixel with B – G – R – X byte order.
The converted image could conceivably have different dimensions than the input image. The rgbWidth, rgbHeight and rgbBitDepth parameters will be filled in with the converted image size. These parameters may be NULL.
Calling ColorPipe() before setting Begin Noise Measurement is required.
void SaveFrame(VARIANT Image)
Parameters
Image – An image received from the device, or a similarly formatted image.
Remarks
Save an image from GrabFrame() in any of several file formats, similar to the capability of the Image Save Options dialog in DevWareX. This function will use the ColorPipe() function to create RGB images for file formats requiring RGB. Set the file saving options and path with SetState() and SetStateStr() before calling this function. The following state settings will affect the files created. Adjust the values as desired:
SetState("Save RAW", 1)
SetState("Save HEX", 0)
SetState("Save ITX", 0)
SetState("Save CCR", 0)
SetState("Save DXR", 0)
SetState("Save RAW PNG", 0)
SetState("Save RAW JPEG", 0)
SetState("Save DNG", 0)
SetState("Save 24bpp BMP", 1)
SetState("Save PNG", 0)
SetState("Save 48bpp COLOR TIFF", 0)
SetState("Save JPEG", 0)
SetState("Save TXT", 1)
SetState("Save SS", 1)
SetState("Save Selection Rectangle", 0)
SetState("JPEG Quality (1-100)" 90)
SetState("Still Filename Increment", 0)
SetStateStr("Still File", path...)
Use LastError for the error code.
void GrabFrameAndSave(void)
Remarks
A convenience function equivalent to calling SaveFrame(GrabFrame()). This function is therefore similar to the Grab button on DevWareX.
Use LastError for the error code.
LONG GetState(BSTR sState)
Parameters
sState – Name of an integer-valued color pipe state variable.
Return Value
Value of the variable.
Remarks
Get the value of an integer-valued color pipe state variable. See the STATE Variables for a list of color pipe variables.
void SetState(BSTR sState, LONG nValue)
Parameters
sState – Name of an integer-valued color pipe state variable.
nValue – New value for the variable.
Remarks
Set the value of an integer-valued color pipe state variable. See the STATE Variables for a list of color pipe variables.
BSTR GetStateStr(BSTR sState)
Parameters
sState – Name of an integera string-valued color pipe state variable.
...
Value of the variable.
Remarks
Get the value of an integera string-valued color pipe state variable. See the State See the STATE Variables for a list of color pipe variables.
void
...
SetStateStr(BSTR sState,
...
BSTR sValue)
Parameters
sState – Name of an integerstring-valued color pipe state variable.
nValue sValue – New value for the variable.
Remarks
Set the value of an integera string-valued color pipe state variable. See the State STATE Variables for a list of color pipe variables.
BSTR
...
SystemDump(BSTR
...
sAppFileName)
Parameters
sState sAppFileName – Name of a string-valued color pipe state variableA a string containing the application name, which will be included in the output text.
Return Value
Value of the variableThe System Dump text.
Remarks
Get the value of a string-valued color pipe state variable. See the State Variables for a list of color pipe variables.
void SetStateStr(BSTR sState, BSTR sValue)
Parameters
sState – Name of an string-valued color pipe state variable.
sValue – New value for the variable.
Remarks
Set the value of a string-valued color pipe state variable. See the State Variables for a list of color pipe variablesThis function creates the System Dump text, as on the DevWareX System Dump menu, or the xx_info.txt files saved by DevWareX. This function will read all device registers, and so can take several seconds.
The text from the szAppFileName parameter will appear in the output text as 'Application Name = ...'.
Functions for Enumerating Sensor or ISP Registers
...