Overview

The DevWare application provides a dialog plug-in API which allows developers to integrate their own DLLs in DevWare. The Auto Focus Mechanics (AFM) plug-in API described in this document is an extended version of the original plug-in API. Developers can modify the C++ source code to meet their specific AF Mechanics requirements. Please read the Plugin Dialog Development Guide before reading this document.

AFM Plug-in Dialog

Besides the standard Dialog Plug-in functions that must exported to DevWare, the AFM Plug-in adds two functions which the Developer needs to export to DevWare.

Include Files

#include "apbase.h"
#include "DlgImport.h"
#include "miafmlib.h"// in the samples folder, or any other name the developer prefer
These files are in the include directory where the Aptina Imaging software is installed, typically C:\Aptina Imaging\include.

DLL exported Functions

The plug-in dialog must be compiled into a DLL. The DLL file must have the extension ".dll" and should export the functions described below. The exported functions must use the standard WIN32 calling convention, normally indicated with the __stdcall keyword. (Parameters passed right to left, called function restores the stack.) The addition two functions user must export are as follows:

GetAFMParams()

Definition:

__declspec(dllexport)
mi_AFMParams* GetAFMParams(void);

Summary:

This function is called when the DevWare auto focus algorithm started.

Parameters:

None.

Return value:

The structure mi_AFMParams is defined as:

typedef struct AFMParams_S {
int m_nMinPosition;
int m_nMaxPosition;
int m_afBigStep;
int m_afSmallStep;
int m_afGap;
} mi_AFMParams;

Where:

m_nMinPosition - is the minimum position the mechanics module can reach.
m_nMaxPosition - is the maximum position the module can reach.
m_afBigStep – the step coarse step size.
m_afSmallStep – the fine step size.
m_afGap – the gap between the specified movement and the actual physical movement of the mechanics (Hysteresis).

SetAFMPosition()

Definition:

__declspec(dllexport)
int SetAFMPosition(int nNewPosition);

Summary:

This function called when the internal Devware AF algorithm finished calculate the new actuator position.

Parameters:

nNewPosition - DevWare pass this value to the AFM Plug-ins. The developer can use this number to move the mechanics modules to the new positions. This number should be between m_nMinPosition and m_nMaxPosition.

Return value:

Non zero value for success. Zero for failure.

Initializing and Closing the Mechanism

In addition to the two exported functions, the developer may want to add special handling code to open and close the mechanics. Corresponding calls are made in the provided example inside the functions OpenDialog() and CloseDialog().
Refer to miAFM_Open() and miAFM_Close() in the section SAMPLE CODE for additional details.

Sample code

There is a sample AFM plug-in dialog called "AFMTest", located in the samples directory. The sample code is in C++ and includes VS .NET 2003 project files. Please refer the "DialogDll" sample code for the original (non-AFM specific) Dialog Plug-in DLLs. In this sample the "miAFMLib.cpp" and "miAFMLib.h" files are AFM specific and the User/Developer needs to modify to fit their requirements. Here is some suggested functionality for AFM specific code.
/////////////////////////////////////////////////////////////////////////////
// miafmlib.cpp : Defines the entry point for the DLL application :
//
// Abstract:
// ---------
// Control the autofocus mechanism (AFM), if present.
// It is anticipated that this class will control any type of AFM,
// automatically detecting which is present.
//
// Classes:
// --------
// CAFMechanics
//
// Methods:
// -----------------------
// miAFM_Open()
// miAFM_Cloase()
// miAFM_GetParameters()
// miAFM_SetPosition()
//
//
/****************************************************************************

Function: miAFM_Open
Summary:
This exported routine initialize the AFM specific paramaters
User must define the global structure "mi_AFMParams" first.
This is the first routine the application must call.
Parameters:
None
Returns:
TRUE if function success
*****************************************************************************/
/****************************************************************************

Function: miAFM_Close
Summary:
This exported routine reset the AFM specific paramaters
Parameters:
None
Returns:
TRUE if function success
*****************************************************************************/
/****************************************************************************
Function: miAFM_GetParameters
Summary:
This exported routine return the mi_AFMParams structure pointer.
Parameters:
None
Returns:
mi_AFMParams structure pointer
*****************************************************************************/
/****************************************************************************
Function: miAFM_SetPosition
Summary:
This exported routine set the new AFM position (after AF algorithm)
User must define the "m_Camera.pCamera" from the application.
Parameters:
None
Returns:
TRUE if function success
*****************************************************************************/
Here is the screen-shot of the AFM plug-in dialog and the Software Auto Focus page (different from SOC Firmware Auto Focus) in the DevWare "Sensor Control". When the user click "Enable Auto Focus" box, the AF algorithm will kick-in.

DevWare Sensor Control page

Figure 1. Auto Focus Page in the DevWare Sensor Control Dialog.

The above control page become active in DevWare once the AFMTest.dll plug-in is added to the plugins directory of DevWare. Refer to the document The Dialog Plug-in API for DevWare for more information.
It allows the user to manually adjust the actuator position of the mechanical device, or to enable auto focus, which uses DevWare's built-in AF algorithm.

DevWare AFM Dialog Plug-in User Interface

Figure 2. The Sample AFM Plug-in Dialog GUI.
The following dialog window becomes available once the AFMTest.dll plug-in is added to the Plugins directory in DevWare. Refer to the document Plugin Dialog Development Guide for more information.
It allows the user to specify the default values for the AFM plug-in. The user can modify the user interface in order to include controls and UI elements that are specific to their needs.

auto focus algorithm

The AF algorithm in DevWare needs these parameters:
Maximum Position: The maximum position the actuator can move.
Minimum Position: The minimum position the actuator can move.
Big Step: The Coarse actuator movement to get the focused position.
Small Step: The fine actuator movement to get the focused position.
Gap Step: The reverse movement after the best coarse focused position is reached.