Anchor
1.0 Overview
2.0 Transport DLL Exports
2.1 DLL Export SetHelpersDLL()
2.1.1 Helper Function getSensor()
2.1.2 Helper Function updateFrameSize()
2.1.3 Helper Function updateImageType()
2.1.4 Helper Function errorLog()
2.1.5 Helper Function log()
2.1.6 Helper Function setMode()
2.1.7 Helper Function getMode()
2.1.8 Helper Function setContext()
2.1.9 Helper Function getContext()
2.1.10 Helper Function unswizzleBuffer()
2.1.11 Helper Function readReg()
2.1.12 Helper Function getBoardConfig()
2.2 DLL Export OpenCameraDLL()
2.3 DLL Export CloseCameraDLL()
2.4 DLL Export StartTransportDLL()
2.5 DLL Export StopTransportDLL()
2.6 DLL Export ReadSystemRegistersDLL()
2.7 DLL Export WriteSystemRegistersDLL()
2.8 DLL Export ReadSensorRegistersDLL()
2.9 DLL Export WriteSensorRegistersDLL()
2.10 DLL Export ReadRegisterDLL()
2.11 DLL Export WriteRegisterDLL()
2.12 DLL Export ReadRegistersDLL()
2.13 DLL Export WriteRegistersDLL()
2.14 DLL Export SendCommandDLL()
2.15 DLL Export ReadFarRegistersDLL()
2.16 DLL Export WriteFarRegistersDLL()
2.17 DLL Export GrabFrameDLL()
2.18 DLL Export UpdateFrameSizeDLL()
2.19 DLL Export UpdateBufferSizeDLL()
2.20 DLL Export GetFrameDataDLL()
2.21 DLL Export SetModeDLL()
2.22 DLL Export GetModeDLL()
2.23 DLL Export GetDeviceNameDLL()
2.24 DLL Export EnableDeviceNotificationDLL()
2.25 DLL Export MatchDevChangeMsgDLL()
2.26 DLL Export DisableDeviceNotificationDLL()
2.27 DLL Export RegControlDLL()
2.28 DLL Export PlayCapableDLL()
2.29 DLL Export IsViewfinderDLL()
2.30 DLL Export SetNotifyCallbackDLL()
2.31 Application Callback AppNotifyCallback()
2.31.1 MI_NOTIFY_PAUSE
2.31.2 MI_NOTIFY_RESUME
2.31.3 MI_NOTIFY_UPDATEFRAMESIZE
2.31.4 MI_NOTIFY_REFRESH
3.0 Employing the DLL
4.0 Example Code
| Table of Contents | ||
|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
...
Introduction
A transport is the link between a camera device and the Aptina onsemi software libraries. The purpose of a transport is to implement the camera control (read and write registers, set modes) and image acquisition functions needed by the higher level software. With a Transport DLL you can:
- Support an Aptina onsemi sensor on a device other than the Demo System camera so DevWare or any other ApBase-based application will work with the device.
- Create a software simulated camera and sensor, simulating either an existing sensor or new sensor, and be able to use DevWare as the user interface for the simulation.
...
The functions you need to implement and export from your Transport DLL are described below.
The exported functions should use the C calling convention. If you are using C or C++ this would normally be the default, so no special syntax is needed. If it is not, the keyword to force a function to the C calling convention is normally __cdecl in most C/C++ compilers. The function prototypes in this document assume C calling convention is the default.
To make your functions export from the DLL in C or C++ you would normally precede the function declaration with __declspec(dllexport).
The symbols and data structures used by the Transport DLL interface are defined in the midlib2.h and midlib2_trans.h header files.
Several of these functions are required to be implemented and exported from your DLL. If they are not exported then the Aptina onsemi libraries will not load the DLL. The remaining functions are optional. If an optional function is not present then either a default handler will be provided to the application, of the feature will not be available. Whether a function is required or optional will be noted for each one below.
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
This function is not necessary if you don't need the helper functions.
The following sections describe the helper functions in the pHelpers structure.
| Anchor | ||||
|---|---|---|---|---|
|
...
Definition:
void updateFrameSize(mi_camera_t* pCamera , mi_u32 nWidth, mi_u32 nHeight, mi_s32 nBitsPerClock, mi_s32 nClocksPerPixel);
Summary:
Boilerplate code for UpdateFrameSizeDLL(). Sets pCamera->sensor->width, >height, ->pixelBits, and ->pixelBytes according to the parameters. Also sets BITS_PER_CLOCK and CLOCKS_PER_PIXEL in the camera context structure (see setContext() below). Sets pCamera>sensor->bufferSize to width * height * pixelBytes; you may need to fix up the bufferSize after calling this function. Call from UpdateFrameSizeDLL(). See sample code.
Parameters (same as UpdateFrameSizeDLL()):
pCamera | Pointer to a camera structure. |
nWidth | New image width, or 0 to keep the current width. |
nHeight | New image height, or 0 to keep the current height. |
nBitsPerClock | New bits/pixel clock, or 0 to keep the current value. |
nClocksPerPixel | New clocks/pixel, or 0 to keep the same value. |
Returns:
void |
|
| Anchor | ||||
|---|---|---|---|---|
|
...
pCamera | Pointer to a camera structure. |
Returns:
void |
| Anchor | ||||
|---|---|---|---|---|
|
...
logType | A log message type defined in midlib2.h. The different log types can be turned on/off by the user on the DevWare Options dialog. |
logMsg | The text of the message. |
szSource | Source code file name where this log() call is located. Normally _FILE_. |
szFunc | Name of function where this log() call is located. Normally _FUNCTION_. |
nLine | Source code line number of this log() call. Normally _LINE_. |
Returns:
void |
| Anchor | ||||
|---|---|---|---|---|
|
...
Summary:
MI_CONTEXT_PRIVATE_DATA gives you a convenient way to associate your own per-camera device data with the pCamera pointer. The val parameter can be an integer or a pointer to a data structure.
Field MI_CONTEXT_DRIVER_INFO
Summary:
In this case the val parameter is interpreted as a const char *. The DRIVER_INFO is a string up to 255 characters long that will be included in bug reports, and can be viewed by the user in DevWare with the menu Help System Dump. You can put any information you want that you think would be useful.
Field MI_CONTEXT_BITS_PER_CLOCK
Summary:
Initialize the bits per clock value. Combined with the clocks per pixel, this defines the format of pixels.
Field MI_CONTEXT_CLOCKS_PER_PIXEL
Summary:
Initialize the clocks per pixel value. Combined with the bits per clock, this defines the format of pixels.
Field MI_CONTEXT_PIXCLK_POLARITY
Summary:
Initialize the pixel clock polarity for parallel data.
| Anchor | ||||
|---|---|---|---|---|
|
...
pCamera | Pointer to the camera structure. |
pInBuffer | Pointer to the raw data |
Returns:
void |
|
| Anchor | ||||
|---|---|---|---|---|
|
...
Register or bitfield value |
| Anchor | ||||
|---|---|---|---|---|
|
Definition:
mi_s32 getBoardConfig(mi_camera_t *pCamera, const char *dir_or_file);
Summary:
If the camera is an Aptina onsemi Demo camera such as Demo2X or Demo3, this function fills in the chip[] array of the pCamera structure by loading .cdat files that correspond to FPGAs or peripherals on the camera system I2C bus.
Parameters:
...
MI_CAMERA_SUCCESS | Initialization successful (even if no matching cdat files were found). |
MI_PARSE_FILE_ERROR | Error opening the config file. |
| Anchor | ||||
|---|---|---|---|---|
|
Definition:
mi_s32 getBoardConfig(mi_camera_t *pCamera);
Summary:
Clean up after getBoardConfig(); removes all items in chip[] array of the pCamera structure.
Parameters:
void |
Returns:
MI_CAMERA_SUCCESS | Initialization successful (even if no matching cdat files were found). |
| Anchor | ||||
|---|---|---|---|---|
|
Definition:
__declspec(dllexport) mi_s32 OpenCameraDLL(mi_camera_t *pCamera, const char *sensor_dir_file, int deviceIndex);
Summary:
This function is called when the DLL is loaded, repeatedly, once for each camera. The deviceIndex parameter will = 0 on the first call, 1 on the second call, and so on. For each camera, do any internal initialization you may need. Fill in pCamera fields including pCamera->sensor, but do not touch pCamera->context, which is already initialized and is used internally by the Aptina onsemi libraries. You can use the setContext() helper function to associate the deviceIndex and/or any other private per-camera data to the pCamera object. The sensor_dir_file parameter is the name of the sensor data file or directory passed by the application to ap_DeviceProbe(). You can quickly initialize your pCamera->sensor with the helper function getSensor().
If all cameras have already been initialized, return MI_CAMERA_ERROR to end the init process. For example, if there are two cameras, return MI_CAMERA_SUCCESS on deviceIndex = 0 and deviceIndex = 1, and return MI_CAMERA_ERROR on deviceIndex = 2.
Parameters:
...
Required:
If this function is not exported, the Transport DLL will be ignored.
| Anchor | ||||
|---|---|---|---|---|
|
...
Returns:
The return value is ignored.
Required:
If this function is not exported, it could cause memory leaks.
| Anchor | ||||
|---|---|---|---|---|
|
...
Required:
If this function is not exported, the DLL will be ignored.
| Anchor | ||||
|---|---|---|---|---|
|
...
Required:
If this function is not exported, the DLL will be ignored.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
If this function is not exported, lower-level register accesses will be used instead if possible.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
If this function is not exported, lower-level register accesses will be used instead if possible.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
If this function is not exported, lower-level register access functions will be used instead.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
If this function is not exported, lower-level register access functions will be used instead.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
If this function is not exported, ReadRegistersDLL will be used. Either this function or ReadRegistersDLL must be implemented to support register read capability.
| Anchor | ||||
|---|---|---|---|---|
|
...
Required:
If this function is not exported, WriteRegistersDLL will be used. Either this function or WriteRegistersDLL must be implemented to support register write capability.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
If this function is not exported, ReadRegisterDLL will be used. Either this function or ReadRegisterDLL must be implemented to support register read capability.
| Anchor | ||||
|---|---|---|---|---|
|
...
Required:
If this function is not exported, WriteRegisterDLL will be used. Either this function or WriteRegisterDLL must be implemented to support register write capability.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
This function is not needed if the underlying transport mechanism doesn't support host commands.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
This function is not needed if there is no bus master on the main device, or if the main device is an Aptina onsemi product.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
This function is not needed if there is no bus master on the main device, or if the main device is an Aptina onsemi product.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
If this function is not exported, MI_GRAB_FRAME_ERROR will be returned to the application for any grab frame request.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
If this function is not exported, the default handler will perform the calculation based on image dimensions and bits per pixel.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
If this function is not exported, it may not be possible to capture JPEG format images.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
If this function is not exported it will not be possible to capture compressed image formats.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
If this function is not exported from the DLL, a standard setMode function will be used.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
If this function is not exported from the DLL, a standard getMode function will be used.
| Anchor | ||||
|---|---|---|---|---|
|
...
Returns:
device name string |
Optional:
This function is optional. However, if it's not implemented and the user opens two applications at the same time, the processes won't be synchronized, possibly causing unexpected results.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
This function is optional. If not implemented, the application will not recieve device removal messages from this device.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
This function is optional. If not implemented, the application will not recieve device removal messages from this device.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
This function is optional, but should be implemented if EnableDeviceNotificationDLL() was implemented.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
The application will first call its built-in function, then the DLL function if it's exported.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
If this function is not exported from the DLL, the application will use its built-in function.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
If this function is not exported from the DLL, the application will use its built-in function.
| Anchor | ||||
|---|---|---|---|---|
|
...
Optional:
If this function is not exported from the DLL, there is no consequence.
| Anchor | ||||
|---|---|---|---|---|
|
...
lParam: 0 (ignored)
Action:
Refresh dialogs. Use this message to resync the user interface to the register values if you change a lot of register values unbeknownst to the application. Function may return before the action is completed.
Calling Thread: Call from any thread.
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
To use your transport DLL, just copy it to the Plugins folder in the Demo Software installation location, typically C:\Aptina Imaging\Plugins.
Alternatively, the application can pass the filename of the DLL to ApBase using the ap_DeviceProbeDll() function. If the application passes in a DLL filename then the Plugins folder is not searched.
DevWare-specific: You can use a command line parameter to specify the DLL. DevWare will pass the given DLL path to the Aptina onsemi libraries.
DevWare.exe /DLL="C:\path\to\your\transport\yourdev.dll"
...