IDEA SDK

SOFTWARE DEVELOPER’S
KIT
USER’S GUIDE

052585-31
 Foresight Imaging Software License Agreement

Foresight Imaging Installation and User’s Guide

Version 3.1 February 2009
Foresight Imaging is a registered trademark of Foresight Imaging, LLC. I-75, I-60, I-
50, I-25, I-50 HSN, I-Series, I-Mono, I-Color, I-RGB, AccuStream 50, AccuStream 75,
AccuStream 170, AccuStream 50a, AccuStream 75a, AccuStream 205a, AccuStream
50+, AccuStream 75+, AccuStream 170+, IDEA, HI*DEF Accura, HI*DEF Plus, and
Auto-SYNC are trademarks of Foresight Imaging, LLC.
This manual may contain product names and references that are used for
identification purposes only. These product names may be trademarks or
registered trademarks and are the sole property of their respective owners.

Copyright © 2009 by Foresight Imaging, LLC.

All rights reserved.
This document is to be used in conjunction with the AccuStream 50, AccuStream
75, AccuStream 170, AccuStream 50a, AccuStream 75a, AccuStream 205a,
AccuStream 50+, AccuStream 75+, and AccuStream 170+ video capture boards.
The information in this document has been carefully checked and is believed to
be accurate. However, Foresight Imaging assumes no responsibility for
inaccuracies. All specifications are subject to change without notice.

Version 3.1 supports the AccuStream 50, AccuStream 75, AccuStream 170,
AccuStream 50a, AccuStream 75a, AccuStream 205a, AccuStream 50+,
AccuStream 75+, and AccuStream 170+ video capture boards. Version 3.1
supports the Windows XP, Windows XP64, Windows Vista Business and Windows
Vista Business with 64-bit operating systems. For all I-Series boards (I-Color, I-
RGB, I-50, I-60, I-75) support, you must download Version 2.4 from the Foresight
Imaging website: www.fi-llc.com. Version 2.4 supports the Windows XP and
Windows 2000 operating systems.

Previous Editions
First printing: January 1999
Second Edition: August 2000
Third Edition: September 2001
Fourth Edition: November 2001
Fifth Edition: May 2002
Sixth Edition: April 2003
Seventh Edition: February 2008
Eighth Edition: February 2009

IDEA SDK User’s Guide

i
ii
Foresight Imaging Software License Agreement

iv IDEA SDK User’s Guide

 Foresight Imaging Software License Agreement

Preface
This manual is a complete user’s guide and reference for IDEA: Foresight
Imaging’s Imaging Development Environment for Applications. It consists of a C
software developer’s kit (SDK), ActiveX control, Tools Library, Video for Windows
driver, example programs with source code, and device drivers for the
appropriate operating system.

Intended Audience
This documentation has been designed for a software engineer with prior C
programming experience.

Technical Support
The goal of this manual is to provide you with documentation on the IDEA and
Tools Library functions required for producing your own programs. If you need
assistance after reading this manual, visit our web site at www.fi-llc.com. Here,
you can access FAQs, driver downloads, and an online support form.

IDEA SDK User’s Guide

v
Foresight Imaging Software License Agreement

Foresight Imaging Software License

Agreement
Single User Products
This Foresight Imaging software (the “Software”) is copyrighted by Foresight
Imaging, LLC. All rights are reserved. The purchaser is granted a license to use
the software only, subject to the following restrictions and limitations.
1. The license is to the original purchaser only, and is not transferable without
written permission of Foresight Imaging.
2. The original purchaser may use the Software on a single computer owned or
leased by the original purchaser. You may not use the Software on more than
a single machine, even if you own or lease more than one machine, without
written consent of Foresight Imaging.
3. The original purchaser may make back-up copies of the Software for his or
her own use only, subject to the use limitations of this license.
4. Holders of a single computer Foresight Imaging development library or SDK
software license, may freely distribute without royalty payments or prior
consent by Foresight Imaging, only the resultant object and/or executable
code created from the use of this development SOFTWARE.
5. The original purchaser may not engage in, nor permit third parties to engage
in, any of the following:
A. Providing or disclosing the Software to third parties.
B. Providing use of the Software in a computer service business, network,
time-sharing, multiple CPU or multi-user arrangement to users who are
not individually licensed by Foresight Imaging.
C. Making alterations or copies of any kind in the Software (except as
specifically permitted above).
D. Attempting to un-assemble, de-compile or reverse engineer the Software
in any way.
E. Granting sublicenses, leases, or any other rights in the Software to
others.
F. Making copies, or verbal or media translations, of the Users Guide.
G. Making telecommunication data transmissions of the Software.

vi IDEA SDK User’s Guide

 Foresight Imaging Software License Agreement

Foresight Imaging reserves the right to terminate this license if there is a

violation of its term or default by the Original Purchaser. Upon termination, for
any reason, all copies of the Software must be immediately returned to Foresight
Imaging, and the Original Purchaser shall be liable to Foresight Imaging for any
and all damages suffered as a result of the violation or default.

IDEA SDK User’s Guide

vii
Software Limited Warranty

Software Limited Warranty

Foresight Imaging warrants to you that, for a period of ninety (90) days normal
use from your date of purchase, that:
1. The media on which the software is furnished and the electronic
documentation is not defective.
2. The software is properly recorded upon the software media enclosed.
3. The electronic documentation is substantially complete and contains all the
information Foresight Imaging deems necessary to use the Software.
4. The Software functions substantially as described in the documentation.
Foresight Imaging’s entire liability and your exclusive remedy shall be the
replacement of any software media or electronic documentation not meeting
these warranties, which is returned to Foresight Imaging or an authorized dealer,
together with a copy of your paid receipt. The above is the only warranty of any
kind, either express or implied, including, but not limited to the implied
warranties of merchantability and fitness for a particular use that is made by
Foresight Imaging on this Licensed Software. In no event shall Foresight Imaging
be liable to you or to any third party for consequential, special, indirect or
incidental damages which you may incur as a result of using the license software,
including, but not limited to, loss of data, or information of any kind which you
may experience.

viii IDEA SDK User’s Guide

 Hardware Limited Warranty

Hardware Limited Warranty

a. Seller warrants that the goods sold will be free from defects in material and
workmanship and perform to Seller’s applicable published specifications for a
period of two (2) years from date of delivery to Buyer. The liability of Seller
hereunder shall be limited to replacing or repairing, at its option any defective
units which are returned to Seller. The cost of freight and insurance to and from
the point of repair will be borne solely by Buyer. In no case are goods to be
returned without first obtaining permission and a customer R.M.A. number from
Seller. b. The standard warranties are contingent upon the proper use of the
product and will not apply to product on which the original identification marks
have been removed or altered. The standard warranties shall not apply to
defects or failures due to accident, neglect or misuse; any party other than
FORESIGHT IMAGING modifying, adjusting, repairing or servicing the product and
failure to provide a suitable installation environment.
c. If Seller determines that products returned are not covered by this warranty,
Buyer shall pay Seller standard charges for handling and repair.
EXCEPT AS PROVIDED ABOVE, SELLER MAKES NO WARRANTIES, EXPRESS OR
IMPLIED, INCLUDING ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR
PARTICULAR PURPOSE.

IDEA SDK User’s Guide

i
x
Compliance Information

Compliance Information
FCC Compliance Information

FCC NOTICE
WARNING
Changes or modifications to this unit not expressly approved by the party
responsible for compliance could void the user’s authority to operate this
equipment.
NOTE: This equipment has been tested and found to comply with the limits for a
Class A digital device, pursuant to Part 15 of the FCC rules. The limits are
designed to provide reasonable protection against harmful interference when the
equipment is operated in a commercial environment. This equipment generates,
uses, and can radiate radio frequency energy and, if not installed and used in
accordance with the instruction manual, may cause harmful interference to radio
communications. Operation of this equipment in a residential area is likely to
cause harmful interference in which case the user will be required to correct the
interference at his/her own expense.
Shielded cables must be used with this unit to ensure compliance with the Class
A FCC limits.

Canadian Emissions Requirements

This Class A digital apparatus complies with Canadian ICES-003.

CE Compliance Information
EN 55022:1998 Class B ITE emissions requirements (EU)
EN 55024:1998 Information technology equipment – immunity characteristics

x IDEA SDK User’s Guide

 Compliance Information

WARNING: Each board has been shipped in its own "plastic" bag. This bag has
properties that prevent the board from being damaged from Electrostatic
Discharge (ESD). After you remove the board from this bag, the board becomes
very susceptible to damage from ESD. We strongly recommend that you use a
grounding strap while handling these boards. Try not to place your fingers on the
components on the boards. In other words, handle the boards by grabbing the
edges of the boards between your fingers. Also remember not to place your
fingers on the gold plated edge connectors.

IDEA SDK User’s Guide

xi
Compliance Information

xii IDEA SDK User’s Guide

 Table of Contents

Table of Contents
Preface ............................................................... v
Foresight Imaging Software License Agreement ............... vi
Single User Products................................................vi
Software Limited Warranty ....................................... viii
Hardware Limited Warranty ....................................... ix
Compliance Information ............................................. x
FCC Compliance Information...................................... x
Canadian Emissions Requirements ............................... x
CE Compliance Information ....................................... x
Structure of this Document ......................................... 1
IDEA Library.......................................................... 1
IDEA Tools Library .................................................. 1
CHAPTER 1: Introduction .............................................. 3
Requirements ........................................................ 3
Compiling Samples.................................................. 4
Information Update................................................. 4
Installing the IDEA SDK and Tools Libraries ..................... 4
IDEA Files............................................................. 5
CHAPTER 2: Theory of Operation .................................... 9
Using Preprocessor Statements ................................... 9
Using the Register Functions ...................................... 9
Using the Millisecond Timer Functions ......................... 10
Error Handling ...................................................... 10
Image Handles vs. Board Handles ............................... 12
Comparing the Two Types of Handles .......................... 12
Asynchronous Board Access ...................................... 13
Using an External Trigger ......................................... 14
Using “Live Video”................................................. 14
Live Display Operations ........................................... 15
Live Streaming of Data to Buffers ............................... 16
CHAPTER 3: Understanding the CHP File ......................... 20
Using the IDEA CHP File ........................................... 20
The RSET Structure and Associated Values and Macros...... 23

IDEA SDK User’s Guide

xiii
Table of Contents

CHP Setting Table ..................................................25

Detailed [HIDEFPLUS] Video Setting Descriptions.............27
Detailed [I-RGB] Video Setting Descriptions ...................42
Detailed [I-RGB Calibration] Video Setting Descriptions .....44
CHAPTER 4: C Function Listings .................................... 45
Function Table......................................................45
Function Descriptions..............................................48
CHAPTER 5: ActiveX Function Listings ...........................105
Using the Controls in an Application .......................... 105
Definitions......................................................... 106
Include Files ...................................................... 107
Programmer’s Guide............................................. 107
IdeaFG Control Reference ...................................... 137
IdeaBoardInfo Control Reference.............................. 212
IdeaDisplay Control Reference ................................. 213
CHAPTER 6: IDEA Tools API Introduction.........................222
Components of the Tools API................................... 222
Sample Application Code ....................................... 223
Putting Auto-SYNC into Context – Six Guidelines ........... 224
Guideline 1 ........................................................ 224
Guideline 2 ........................................................ 224
Guideline 3 ........................................................ 225
Guideline 4 ........................................................ 225
Guideline 5 ........................................................ 226
Guideline 6 ........................................................ 227
CHAPTER 7: Structures in IDEATOOLS.H .........................228
AS_RUNSTATE Structure......................................... 228
Structure Elements .............................................. 229
CHAPTER 8: Tools API Functions and Operating Sequence ..256
Function Descriptions............................................ 256
HD_VideoMeasure ................................................ 258
HD_VideoAlign .................................................... 260
eHD_ASTerminate ................................................ 260
VESA Mode Scanning ............................................. 260
Automatic Phase Recalculation ................................ 264

xiv IDEA SDK User’s Guide

 Table of Contents

APPENDIX A: IDEA SDK and Tools Library Functional Summary268

Board Information ............................................... 268
Image Data Access ............................................... 268
Image Handle ..................................................... 269
Millisecond Timer ................................................ 269
Preparing Board Access ......................................... 270
Register Functions ............................................... 270
Tools ............................................................... 271
Video Control ..................................................... 272
Live Video Display and Streaming ............................. 272
Function Return Values ......................................... 273
Error Codes for the IDEA Tools Library ....................... 277
IDEA Auto-SYNC Channel Elimination Codes ................. 278
IDEA Auto-SYNC Channel/Mode Elimination Codes ......... 279
IDEA Auto-SYNC Pixel Detection Error Codes ................ 279

IDEA SDK User’s Guide

xv
xvi IDEA SDK User’s Guide
 Structure of this Document

Structure of this Document

Chapter 1: Introduction contains information about installation and hardware
and software requirements.

IDEA Library
Chapter 2: Theory of Operation contains information about some of the
function types and error handling.
Chapter 3: Understanding the CHP File provides background on the Common
Hardware Profile (CHP), default settings, sample CHP, as well as descriptions
for each setting.
Chapter 4: C Function Listings contains information about the functions
available for the Foresight Imaging frame grabbers & video streamers.
Chapter 5: ActiveX Function Listings contains information concerning the
ActiveX controls available in IDEA.

IDEA Tools Library

Chapter 6: IDEA Tools API Introduction contains information concerning the
components of the Tools Library, sample application code and rules for using
the IDEA Auto-SYNC functionality.
Chapter 7: Structures in IDEATOOLS.H discusses the structures found in the
Tools Library’s IDEATOOLS.H include file.
Chapter 8: Tools API Functions and Operating Sequence contains information
about the Tools Library functions and the order they are used.
Appendix: IDEA SDK and Tools Library Functional Summary lists functions by
functional categories.

IDEA SDK User’s Guide 1

2 IDEA SDK User’s Guide
 Chapter 1:
Introduction

CHAPTER 1:
Introduction
This manual is for users of the Foresight Imaging® IDEA™ SDK (Software
Developer's Kit). IDEA is Foresight Imaging’s Imaging Development Environment
for Applications.
It consists of a C SDK, and ActiveX control, a Tools Library, a Video for Windows
driver, example programs with source code, and device drivers for the
appropriate operating system.
The C SDK consists of a set of C/C++ callable functions that provide the
application developer with hardware-independent tools for board
configuration, video control, image capture, video streaming, memory
management, and more. The ActiveX control provides methods and properties
that abstract the functionality of the C SDK to ease application development in
such environments as Visual Basic and Delphi.
The hardware independence of IDEA allows developers to create a single
application that will support all AccuStream frame grabbers and video
streamers from Foresight Imaging. Applications written with IDEA will function
across all of the supported operating system platforms.
Several demonstration programs are included with these libraries. These
programs contain source code that utilizes common IDEA Library functions to
initialize hardware, capture, and store images. Thus, these demonstration
programs may provide a template for your application.

Requirements
The following are the compilers and/or operating systems that are supported
by the IDEA library, as well as the Tools library:
ƒ Microsoft Visual Studio 2005.
ƒ Windows XP, Windows XP64, Windows Vista Business and Windows Vista
Business with 64-bit.
ƒ Version 3.1 supports the AccuStream 50, AccuStream 75, and AccuStream
170, AccuStream 50a, AccuStream 75a, AccuStream 205a, AccuStream 50+,
AccuStream 75+, and AccuStream 170+ boards. Version 2.5 supports the
Windows XP, Windows XP64, Windows Vista Business and Windows Vista
Business with 64-bit operating systems. For all I-Series boards (I-Color, I-
RGB, I-50, I-60, I-75) support, you must download Version 2.4 from the
Foresight Imaging website: www.fi-llc.com. Version 2.4 supports the
Windows XP and Windows 2000 operating systems.

IDEA SDK User’s Guide 3

Chapter 1:
Introduction

Compiling Samples
The IDEA executables for sample applications can be complied using Microsoft
Visual Studio 2005. Each demonstration application gets installed into its own
directory complete with source code, make files and Microsoft Visual Studio
compatible project files.
The make files can be linked to produce a “DEBUG” or “RELEASE” version:
ƒ RELEASE: This is the default (no symbol table included).
ƒ DEBUG: If a debug version is wanted, “DEBUG” must be chosen using the
Active Configuration pulldown list in the Developer’s Studio.
Each demonstration application supports Win32 or X64 platforms. If you are
developing a 32-bit application, whether on 32- or 64-bit Windows XP, you
should select the Win32 platform. If you are developing a 64-bit application on
Windows XP64, select the X64 platform. Note that you must have installed 64-
bit support with the Visual Studio 2005 before you attempt to compile for the
X64 platform.
Copies of the resulting *.EXE files are left in the appropriate release or debug
directories.

Information Update
There may be additional release-specific information available on the software
media. This information may be in two different locations:
ƒ README.TXT in the root directory of the software media or IDEA SDK on
your hard drive (after you have installed the software).
ƒ ASCII files (*.TXT) or Adobe Acrobat (*.PDF) in the \Foresight\Idea\Doc
directory.

Installing the IDEA SDK and Tools Libraries

Please read this section in its entirety before beginning the installation of your
software and hardware. It is recommended that you install the software before
inserting the board into your computer. This will make it easier for plug-and-
play-enabled operating systems to correctly identify and install the drivers for
your hardware. If you are installing this release over an existing release, it is
recommended that you uninstall the previous version.
The following are the instructions for installing this software:
1. Insert the Foresight Imaging Software CD into the CD-ROM drive.

4 IDEA SDK User’s Guide

 Chapter 1:
Introduction

2. If you have AutoRun enabled, the AutoRun.INF will invoke the installation
procedure. If you do not have AutoRun enabled, you must change to the
Setup directory on the CD and run the Setup.exe application. Follow the
directions regarding the destination and program folders.
NOTE: For 32-bit installations, the default installation directory is:
\Program Files\Foresight\IDEA
For 64-bit installations, the default installation directory is:
\Program Files (x86)\Foresight\IDEA
(The 32- and 64-bit installations are provided on separate disks. You should
only install one or the other.)
It is recommended that you select automatic restart when the installation
has finished.
3. Alternatively, you can install the software from the Control Panel by
selecting Add/Remove Programs.
4. Check the CD for version-specific release notes. These are in README.TXT
in the Setup directory. This file contains important information that
augments this documentation. This file is also installed in the destination
folder, with a shortcut to it in the IDEA application folder.
5. If this is a new hardware installation, you should now power down the
computer and install the frame grabber in an appropriate slot. If plug-and-
play is enabled on your operating system, it will tell you that you have a
new device. Follow the installation directions until you are prompted for an
installation disk. The CD contains a Drivers directory that has a
subdirectory for 32-bit Windows and a subdirectory for 64-bit Windows. The
software installation will also create a Drivers directory under your
installation directory. Select the directory that matches your operating
system. The installation procedure reads the appropriate INF file and
installs the correct device driver for your system.

IDEA Files
Directory Structure
The following table shows the \Foresight\IDEA directory structure for the IDEA
Library and Tools Library.
1
Folder Explanation
AutoSync Auto-SYNC application and associated files.
Chp Sample Common Hardware Profile (CHP) files.

1
Directory and Folder are used interchangeably throughout this guide.

IDEA SDK User’s Guide 5

Chapter 1:
Introduction

Demo Sample source code, including make files, to build a sample

application.
DirectX Include, Library files for DirectX applications.
Doc Additional information not found in this document.
Drivers Windows 32-bit and Windows 64-bit device drivers.
IDEAVA Generic video adjustments DLL for use by several applications.
Imafile DLL for saving images to various file formats.
Include Contains C-language include files for interfacing with the library.
ISeries Contains loadable Altera files for the I-Series and I-Color frame
grabbers.
Legacy Old non-supported sample applications.
Lib Library files needed by the demo program.
Samples Older demonstration applications.
System DLLs, ActiveX control.
TWAIN Contains a TWAIN data source driver file.
Utilities External utility applications like VideoTest.

Demonstration Code
There are several directories of demonstration code under the Demo directory.
Most of these applications are meant to demonstrate a particular aspect of the
IDEA software or of Foresight frame grabbers.

One of the demos is simply called IDEA. It is an all encompassing application

that demonstrates how to initialize a board, snap and image, save an image,
display live video, stream video to an AVI file, stream video to a DICOM file and
how to use triggers to initiate an operation.

The other applications show a subset of this functionality for one or more board
types as summarized in the following table.

Directory Explanation
IDEA All-encompassing demonstration application.
FI_DICOM Contains sources for a DLL that allows the IDEA demo to
transfer images using the DICOM protocol. Building and using
this DLL requires that the LeadTools evaluation kit be installed

6 IDEA SDK User’s Guide

 Chapter 1:
Introduction

from the installation CD.

Idea_avcolor ActiveX sample code that includes streaming video and audio to
an AVI file.
Idea_capi Snapping, saving and live video for monochrome grabbers.
Idea_icolor Snapping, saving and live video for I-Color, I-RGB and
AccuStream grabbers.
LiveIColor Live Video and Streaming to AVI for I-Color, I-RGB and
AccuStream grabbers.
Idea_VideoTest Source for video test application. This application will scan the
video capabilities of your system to determine if it is capable
of using DirectDraw for displaying live video in a window.
LiveVideo Live Video and Streaming to AVI for monochrome I-Series
grabbers.
VB.Net Multifunction demonstration of ActiveX control using Visual
Basic.
VBLive.Net Visual Basic application using the ActiveX control to
demonstrate live video.
VBSnap.Net Visual Basic application using the ActiveX control to
demonstrate snapping operations.
VBStream.Net Visual Basic application using the ActiveX control to
demonstrate streaming to AVI functionality.
VBStreamEvents.N Visual Basic application using the ActiveX control to
et demonstrate streaming functionality with event notifications.
CppLive C++ version of the VBLive.Net application
CppSnap C++ version of the VBSnap.Net application
CppStream C++ version of the VBStram.Net application

IDEA SDK User’s Guide 7

Chapter 1:
Introduction

8 IDEA SDK User’s Guide

 Chapter 2:
Theory of Operation

CHAPTER 2:
Theory of Operation
This chapter describes the principles of using the Preprocessor Statements,
Register Functions, Millisecond Timer Functions, IDEA CHP files, Trigger Inputs
and Live Video Display and Streaming. Error Handling is also discussed.

Using Preprocessor Statements

When creating applications with the IDEA Library, there are two preprocessor
statements that must be included:
#include “HDP_LIB.H”
#include “HDP_ERR.H”

HDP_LIB contains direct and indirect register specifiers, function prototypes,

and other code. HDP_ERR.H defines the error return codes.

Using the Register Functions

In the simplest cases, the board registers are set with predetermined values
kept in an IDEA Common Hardware Profile (CHP) file. This file format is
described later in this chapter. A sample file called RS170.CHP can be used as a
template for the manual generation of these files. It is recommended that you
make a copy of this CHP file before making changes to it. Also, the IDEA Auto-
SYNC utility is available to produce these files automatically.
The function eHP_RSET_FRead( ) is used to read the data from the
configuration file into a structure of type RSET (defined in HDP_LIB.H). This
data is then used to set the registers on a specific board with a call to
eHD_RSET_Set( ).
The size and contents of structure RSET changes from version to version of the
library. Therefore, do not write code that depends on this structure being of a
specific size. If you allocate memory for this structure, use the sizeof operator.
Although some clues are given about the contents of this structure in
HDP_LIB.H, in most cases it should be considered a black box. Exceptions are
listed below. If application code references are made to the elements in this
structure, the enumeration symbols (HPR_VATTR, HPR_HFREQ, etc.) should be
used so that changes made in later IDEA Library revisions are handled as
smoothly as possible.
Certain RSET elements will be retained in future versions of the library. These
elements can be safely read or changed by application programs. Values in the

IDEA SDK User’s Guide 9

Chapter 2:
Theory of Operation

RSET structure are checked for validity in both of the eHD_RSET_...( ) routines.
Therefore, it is possible that erroneous changes made by the application
program to the RSET structure can be caught (and reported) by eHD_RSET_Set(
) when an attempt is made to use the data. Given a structure declared by
"RSET rset;", the version-stable elements of RSET can be represented as
follows:
(rset.dwRegSpecd &(1<<HPR_x))!=0 /* TRUE if element HPR_x is specified*/
rset.lRegs[HPR_HFREQ] /* The horizontal frequency (in hertz)*/
rset.lRegs[HPR_HTOTAL] /* The horizontal total (pixel freq/horz.freq) */
rset.lRegs[HPR_WIDTH] /* Width of image (pixels)*/
rset.lRegs[HPR_HEIGHT] /* Height of image (lines)*/

Using the Millisecond Timer Functions

The millisecond timer functions are used by the library routines to check for
time-out conditions and are available to the applications code as general
utilities. They are referred to as the "FINE_TIME" routines and all but one
(fine_wait) uses a data structure called FINE_TIME or the pointer to that
structure, pFINE_TIME. These routines are declared in HP_FTIME.H.

Error Handling
All library routines that take a BoardHandle as a parameter use a common error
reporting system. These routines report an error as one of the error codes
listed in HDP_ERR.H. These codes (for example, HPERR_PARAM or
HPERR_CHP_SYNTAX) are always of type ERRTYPE. When one of these errors is
reported, several items are checked:

10 IDEA SDK User’s Guide

 Chapter 2:
Theory of Operation

1. If the BoardHandle has been opened, the OpenData structure (see

eHP_Open( ) below) is updated so that a running list of the last four errors
associated with this board is maintained. OpenData structure eError is set
equal to the most recent error.
NOTE: Resetting eError to zero immediately after errors are processed
provides an easy way of identifying "new" (unprocessed) errors.
2. The OpenData structure is also checked to see if an error callback routine
has been specified. If the callback is non-NULL, the error message file is
opened (unless it has already been opened) and the error message
corresponding to the error code is retrieved. A pointer to this error
message along with the board handle and the error code are then passed to
the error handler (callback routine).
3. The Registry key
HKEY_LOCAL_MACHINE\Software\Foresight\IDEA\Common\HDP_ERR_REPORT is checked.
If such a variable exists, it specifies an error-logging file and the error
message for the new error code is appended to the end of this file.
4. Library routines that start with the letters “eHP_” return the error code if
an error is detected. If no error code is generated, the routines return 0.
When it is necessary to open the error message file, the Registry Key
HKEY_LOCAL_MACHINE\Software\Foresight\IDEA\Common\HDP_ERR_SOURCE is checked.
If it exists, it specifies the name (and path) of the error message file. If it
does not exist, file HDPERROR.DAT is opened. The user can modify the
error message file as long as the error messages are kept to 249 characters
or less and the existing indentations are preserved.
There is also a provision for changing error message files on an application-
specific or board-specific basis. To do this, open the error message file for
reading (fopen(...,"r")) and set the field “fpErrSrc” in the OpenData
structure to the file handle. Then set the OpenData field “eLibMax” to the
largest error code value that will still be using the default error message
list (set to 0 to change all messages). When the replacement error message
file is no longer needed, set “eLibMax” to 0xFFFF and “fpErrSrc” to FNULL
before (or immediately after) closing the replacement error message file.
Use
_HP_Error( ) to declare new errors discovered in your code and pszExePath(
) to find your new error message file.

NOTE: See the Appendix for more information on the function return values.

IDEA SDK User’s Guide 11

Chapter 2:
Theory of Operation

Image Handles vs. Board Handles

When using the Foresight boards, image data is first "grabbed" into frame grabber
memory and then transferred to host memory. The IDEA API provides separate
calls for each of these two steps. For the first step, the eHP_Command( ) or
eHD_Command( ) function calls can be used to direct the board to acquire a
frame of the image. For the second step, several subroutine calls are provided to
transfer the frame or a rectangular portion of the frame into host memory, or to
transfer only a histogram of that data.
The AccuStream boards have four million pixels of memory, but the addressing
is linear - not rectangular. There are also several considerations in allocating
memory for an image that you should not have to deal with. The solution is
image handles. Image handles are used as follows:
1. First a Foresight board is claimed and a Board Handle is returned.
2. Next an RSET structure, which describes a video signal format, and the
board handle are used to allocate frame grabber memory and return an
image handle. The image handle is a handle to A) The Foresight board; B)
an RSET video description maintained by the IDEA library; and C) a section
of frame grabber memory reserved for capturing a frame of imagery from
that particular video format.
3. eHD_Command( ) is used with the image handle to cause a frame of
imagery to be acquired by the Foresight board.
4. A "Xfer" or "Histo" routine is called to move the image data into an array
(host memory) where the application can use it.
Multiple image handles can be opened on a single Foresight board. The only
limitation is that eventually there is not enough of the four million pixels
remaining for the next image handle.
If your application never holds more than one frame in frame grabber memory
at a time, then you might find board handle access simpler. You could always
grab into frame grabber memory location (0,0) so that frame grabber memory
coordinates would always be the same as image coordinates.
Image handles completely hide the detailed structure of the frame grabber
memory from the application.

Comparing the Two Types of Handles

Board handle access and frame grabber access differ as follows:
1. With board handles, you must decide whether frame grabber memory is to
be laid out wide (2048x1024) or tall (1024x2048). With image handles, this
is handled for you.

12 IDEA SDK User’s Guide

 Chapter 2:
Theory of Operation

2. With board handles, you must specify the top left coordinate in frame
grabber memory where the acquisition starts (CHP values “XStart” and
“YStart”). These coordinates must then be retained so your application can
find the image later. With image handles, your application must keep track
of the image handle but the library generates the handle and access to the
image data is by image coordinates.
3. With board handles, the RSET is loaded directly onto the board. With image
handles, the RSET is kept with the image handle and is loaded onto the
board just before an image is grabbed. This makes it easier to work with
two different video formats connected to that same board.

Asynchronous Board Access

The AccuStream boards can be accessed synchronously or asynchronously. This
section describes how to use the library functions asynchronously.
Many of the API functions take a parameter called HDOP_HDL *pHDOP.
Normally, this parameter is set to NULL, indicating a synchronous operation i.e.
it will not return to the application until it has completed. If this parameter is
not NULL, then the function will return to the application after performing its
error checking. The application can then use this mechanism to be notified
when the function has completed. This notification can come in the form of a
callback function, or the setting of a Win32 event.
The HDOP_HDL structure is defined in hdp_lib.h as:
typedef struct {
HD_ABOS *pABOS; /* NULL if operation is synchronous. */
HD_ABOCB *pABOCB; /* NULL for no callback. */
FINE_TIME ftVEnd; /* 0 if not specifying field by time. */
unsigned long dwFieldN; /* 0 if not specifying field by number. */
} HDOP_HDL;

The following auxiliary structures are also defined in hdp_lib.h.

ypedef unsigned long HD_ABOSERIAL;
typedef struct {
BoardHandle bh;
short nResv; /* for DWORD alignment */
HD_ABOSERIAL nABO;
HANDLE hAppEvent;
} HD_ABOHandle;

typedef struct {
ImageHandle ih;
ERRTYPE e;
short nResv; /* for DWORD alignment */
FINE_TIME ftVEnd;
unsigned long dwFieldN;
} HD_ABOSTAT;

typedef struct {

IDEA SDK User’s Guide 13

Chapter 2:
Theory of Operation
HD_ABOHandle hABO;
HD_ABOSTAT ABOStat;
} HD_ABOS;

typedef void (*HCB_ABO)(void *,long,long,HD_ABOS *);

typedef struct {
HCB_ABO cbABO;
void *pThis;
long lUser;
} HD_ABOCB;

To be notified by an event, zero out all members or these structures except

the board handle and image handle members. Then set the hAppEvent member
of HD_ABOHandle to an event handle as created by the Win32 call CreateEvent.
When the command has completed, the library will signal this event.
To be notified by a callback function, zero out all members of this structure
except the board handle and image handle members. Set the cbABO member of
HD_ABOCB to be a pointer to a function that will be called by the library on the
completion of the command. If the callback function is a member of a C++
class, that function must be defined as static. To access members of the class
from this static function set the pThis member of HD_ABOCB to the this class
member. The lUser member of HD_ABOCB is a user-defined parameter that will
also be passed into the callback function.

Using an External Trigger

Foresight Imaging frame grabbers can accept an external trigger to initiate a
board operation. The actual trigger line varies from cable to cable but is
always labeled.
The frame grabbers only accept edge triggers – that is, a transition from high to
low or from low to high. The polarity of the trigger is configurable by setting
the “TriggerPolarity” control value as described in Chapter 5. Additionally,
there are control values to desensitize the hardware to bouncy mechanical
switches or to delay the time in which the board will accept another trigger
signal. These also are described in Chapter 4.

Using “Live Video”

As of the 2.5 Release, you can no longer call the eHD_LiveVideo() functions.
You must call either eHD_LiveStreamInit(), eHD_LiveStreamMode() or
eHD_LiveDisplayInit(), eHD_LiveDisplayMode().
This section describes how to use this functionality from the C and C++ based
library. Similar functionality is available in the ActiveX control and is described
in Chapter 5.

14 IDEA SDK User’s Guide

 Chapter 2:
Theory of Operation

Examples of these functions can be found in the IDEA demo.

Live Display Operations

Live display is accomplished by putting the grabber in a mode in which it is
constantly grabbing images and transferring them to a destination on the
display card. The Foresight demonstration application uses DirectDraw to
accomplish this. The application makes DirectDraw calls to acquire a pointer to
an overlay surface on the display card. The frame grabber transfers the video
data to this surface via DMA, which is displayed on the primary surface on the
display card using a color key.
There are two function calls that are necessary for displaying live video. The
first call is eHD_LiveDisplayInit which will prepare the library to do continuous
capture and transfer of images. The second call is eHD_LiveDisplayMode which
begins or ends the display.
The call to eHD_LiveDisplayInit takes a structure that describes the format and
destination of the video. This structure is called LIVEDISPLAY_INFO and is
defined in hdp_lib.h as:
typedef struct {
DWORD dwSize; // size of the structure
void *pDestination; // Destination address
DWORD dwPitch; // width of destination rectangle
BOOL bFieldUpdate; // True if doing field updates
int nDecimateX; // X Decimation factor
int nDecimateY; // Y Decimation factor
int nDecimateFrames; // Number of frames to skip
long hLUT; // handle to a look up table
int nTop; // video input top
int nBottom; // video input bottom
int nLeft; // video input left
int nRight; // video input right
int nMode; // Unused...
} LIVEDISPLAY_INFO;

Prior to calling eHD_LiveDisplayInit, the application fills in this structure with

the appropriate values to describe the video source and destination. It is
imperative that the dwSize member be set to sizeof( LIVEDISPLAY_INFO );
When the application is ready to display video in a window, it calls
eHD_LiveDisplayMode( …, LVM_RUN ). This will cause the grabber to
continuously grab images and transfer the data to the off screen overlay
surface. In the IDEA demo, the position of the video window is tracked, and the
destination of the overlay rectangle is moved to correspond to the position of
the video window.
When the application wants to terminate live video display, it calls
eHD_LiveDisplayMode( …, LVM_STOP );

IDEA SDK User’s Guide 15

Chapter 2:
Theory of Operation

Live Streaming of Data to Buffers

Live streaming-to-buffers in accomplished in the SDK by making calls to
eHD_LiveStreamInit, eHD_LiveStreamMode and eHD_LiveStreamClose.
eHD_LiveStreamInit takes a structure that describes the format of the input
video and the output buffers. The structure is called LIVESTREAM_INFO and is
described in hdp_lib.h as:
typedef struct {
DWORD dwSize; // size of this structure
void **pBufferList; // pointer to buffer list
DWORD dwNumberOfBuffers; // number of buffers in list
int nDataType; // pixel type
BOOL bDIBTarget; // True if destination is a bottom-up DIB
int nDecimateX; // X Decimation factor
int nDecimateY; // Y Decimation factor
int nDecimateFrames; // Number of frames to skip
BOOL bFieldUpdate; // True if doing field updates
long hLUT; // handle to look-up table
int nTop; // video source top
int nBottom; // video source bottom
int nLeft; // video source left
int nRight; // video source right
int nMode; // unused by application
HD_LIVEVIDEO *pLiveVideoDescriptors; // video header descriptors
HDVID_HEADER *pVidHeaders; // video headers
HANDLE hBufferEvent; // event fired on each frame
HANDLE hStartEvent; // event fired when streaming starts
HANDLE hStopEvent; // event fired when streaming stops
HANDLE hErrorEvent; // event fired on error
} LIVESTREAM_INFO;

The dwSize member must be set to sizeof( LIVESTREAM_INFO ). The pBufferList

is a list of application-allocated buffers to receive the captured images. The
dwNumberOfBuffers is the number of allocated buffers in the list. The
nDatatype is the format of the pixel data. It can be one of:
IDEA_TYPE_MONO_8 8 bit monochrome data
IDEA_TYPE_MONO_10 10 bits of monochrome data in 16 bits
IDEA_TYPE_MONO_16 Full 16 bit monochrome data
IDEA_TYPE_YONLY_8 Y component of YCbCr data in 8 bits
IDEA_TYPE_YONLY_16 Y component of YCbCr data in 16 bits
IDEA_TYPE_YCBCR_16 Full YCbCr data in 16 bits
IDEA_TYPE_RGB_32 RGB data in 32 bits

16 IDEA SDK User’s Guide

 Chapter 2:
Theory of Operation

IDEA_TYPE_RGB_555 RGB data in 16 bit 555 format

IDEA_TYPE_RGB_565 RGB data in 16 bit 565 format. NOTE: This
is not currently supported. Using this tag
will result in RGB555 data.
IDEA_TYPE_RGB24 RGB data in 24 bit format.

If you want the data to arrive in bottom-up format that is native to Window’s
DIBs, then set the bDIBTarget to TRUE. The nDecimateX and nDecimateY
parameters are used to scale the video down. Note that the entire image is still
captured, but the smaller image is transferred to the buffer. The
nDecimateFrames can be used to reduce the frame rate by skipping frames if
the system is not capable of processing the data at full speed.
Set bFieldUpdate to TRUE if you want each buffer to receive a field of data
instead of the full, interlaced, frame.
The hLut parameter allows for a look-up-table to be applied to the data.
The top, bottom, right and left parameters affect the size of the captured
image.
pLiveVideoDescriptors is not used and should be set to zero.
The pVidHeaders is set by the library to contain one HDVID_HEADER structure
for each buffer in the buffer list. The application can interrogate this structure
to determine the currently active buffer and frame counter as a means of
determining if the library has had to drop a buffer due to system speed
constraints.
The event parameters are a way for the library to notify the application that a
streaming event has occurred. The application creates the events using the
Win32 CreateEvent call. It then uses one of the Win32 methods of waiting on
events to see if the library has encountered the condition.
When the application is ready to begin streaming data, it makes a call to
eHD_LiveStreamMode( ). The mode parameter can be one of the following as
defined in hdp_lib.h:
LVM_PAUSE Pause a currently streaming operation
LVM_RUN Begin streaming
LVM_SNAP Snap an image into the next buffer, not yet
implemented
LVM_STOP Stop the current streaming operation

IDEA SDK User’s Guide 17

Chapter 2:
Theory of Operation

LVM_TRIGGER_RUN Begin streaming on an external trigger

LVM_TRIGGER_STOP Stop streaming on an external trigger
LVM_TRIGGER_RUN_STOP Start streaming on first trigger and stop on
the next.

The application can then use the event mechanism to count and process the
incoming video buffers.
When the application has finished streaming, it calls eHD_LiveStreamClose(). It
is imperative that an application call this function before terminating because
eHD_LiveStreamInit will cause the application buffers to be locked in memory.
Failing to call eHD_LiveStreamClose will leave these buffers locked, severely
affecting system performance and likely leading to a crash.

Level Trigger Streaming

Foresight Imaging’s frame grabbers only implement edge-sensitive triggers. It is
possible to simulate streaming on a trigger level by using the events and the
programmable polarity of the trigger. The algorithm is as follows:
1. Initialize the stream information, making sure to create a start event,
and a stop event and call eHD_LiveStreamInit.
2. Call eHD_LiveStreamMode with LVM_TRIGGER_RUN_STOP.
3. Wait on the start event, which will arrive when the trigger transitions
into the desired level state. When the start event arrives, change the
polarity of the trigger with a call to:
eHP_SetControlValue(…, "TriggerPolarity",…)
to toggle the polarity of the trigger.
4. On the next trigger edge you will receive a stop event at which time
you should reset the trigger polarity to prepare for the next streaming
run.

In this way, you can stream data while holding a trigger in a particular state.
There are a couple of caveats to using this method. The first is that it will not
begin streaming if the trigger is in the desired state when eHD_LiveStreamMode
is called. The streaming will not begin until there is a transition into the
desired state.
The second caveat is that this method is susceptible to trigger bounces, as
happens frequently with mechanical switches. If this is the case, then the
application should experiment with

18 IDEA SDK User’s Guide

 Chapter 2:
Theory of Operation

eHP_SetControlValue(…, “TriggerFilterTime”,… )
to find a value that will reliably ignore such trigger bounces.

IDEA SDK User’s Guide 19

Chapter 3:
Understanding the CHP File

CHAPTER 3:
Understanding the CHP File
This chapter describes the CHP file and provides its settings, with information
concerning each setting

Using the IDEA CHP File

The IDEA library uses Common Hardware Profile (CHP) files as a way to
describe video sources. CHP files contain video settings that are used to set up
your Foresight Imaging board for image capture and other operations.
The IDEA CHP file is intended to be compatible with Windows *.INI files to the
extent that the CHP sections could be included in an *.INI file without
interfering with other sections. When eHP_RSET_FRead( ) reads this file, it
reads one line at a time; converts all letters to upper case; and eliminates all
white-space characters (blanks, tabs etc.), semicolons, and anything to the
right of a semicolon.

NOTE: The AccuStream boards can used predefined CHP files (especially if you are
using standard VESA inputs) or you may use Auto-SYNC to created CHP files
for your specific video input

The following are sample settings in a CHP file. The default values for each
parameter is displayed on the right side of this list:
Settings in CHP File Default Value

[HIDEFPLUS]
Video Channel = CA1 CA1
Composite Sync Source = CA1 CA1
Video Attributes = 0x49 0x0000
Signal Control = 0x00 0x0000
TTL Pixel Clock = NONE NONE
Vertical Total = 525 [Future use]
Frame Period = 34 [Not specified]
Interlace = ON OFF
Vertical Sync Type = NORMAL NORMAL
Vertical Back Porch = 17.0 0.0
Image Height = 480 0
Horizontal Frequency = 15750 15725
Horizontal Total = 800 26
Horizontal Back Porch = 122 4

20 IDEA SDK User’s Guide

 Chapter 3:
Understanding the CHP File

Settings in CHP File Default Value

Horizontal Back Sync = 128 4

Image Width = 640 1
Horizontal Sync Width = 5235 [Not specified]
Gain = 0.8549 0.6000
Black Level = 0.0416 0.0000
Black Reference = 0.0080 0.0000
White Reference = 0.9920 1.0000
Zoom Down = 0x00 0x00
Pitch = 2048 [Not specified]
Pass Mode = SINGLE [Not specified]
Phase Delay = 10.0 0.0
Imaport = OFF [Obsolete-do not use]]
Horizontal Start =0 0
Vertical Start =0 [Not appropriate]
Reference Program = AS_DEMO [Not appropriate]
Reference Board Type = ACCURA [Not appropriate]
Reference Serial No = 043707 0
Pixel Frequency = 12600 [Not appropriate]
Vertical Frequency = 5998 [Not appropriate]
Additional default values not shown in the above [HIDEFPLUS] section:
Dual Pass Delay [Not specified]
Phase Delay 2 [Not specified]
Pixel Set Value 0x00

[I-COLOR]
VideoFormat = NTSC NTSC
InputChannel = Composite1 Composite1
Hue =0 0
Saturation =0 0
Brightness =0 0
Contrast =0 0
HorizontalPosition =0 0
OutputFormat = YCbCr422 YCbCr422
LowPassFilter = Enable Disable
YCodeRange = Full Full
Luma_Pedestal = OFF OFF
NotchFilter = Disable Disable
YCOutRange = Full Full
Luma_Decimation =On On
Luma_Peaking =Minimal Minimal

IDEA SDK User’s Guide 21

Chapter 3:
Understanding the CHP File

Settings in CHP File Default Value

Luma_Comb =Auto Auto

Chroma_Comb =Auto Auto

[I-RGB]
Cable = DVI-to-VGA DVI-to-BNC
FinePhaseAdjust =0 2
ActiveInterface = Analog Analog
PixelMode = RGB RGB
ClampMode = RGB RGB

[I-RGB Calibration xxxxx] xxxxx is the Board Serial

Number
RED_GAIN_CALIB =0 0
GREEN_GAIN_CALIB =0 0
BLUE_GAIN_CALIB =0 0
RED_OFFSET_CALIB =0 0
GREEN_OFFSET_CALIB =0 0
BLUE_OFFSET_CALIB =0 0

This file can automatically be created with the IDEA Auto-SYNC Utility.
Initially, all lines that are read before “[HIDEFPLUS]” is found are treated as
strictly text.

NOTE: The CHP file always has a [HIDEFPLUS], when you are using an an
AccuStream board. This was kept to maintain compatibility with older CHP
files written for the HI*DEF Plus. The CHP also refers to [I-RGB]. This also
applies to AccuStream to maintain compatibility.

Subsequent lines are data lines. The data lines are read until the end-of-file is
reached or a line that begins with "[" is encountered. Keep the following in
mind when setting up this file:
• Each data line specifies a field and is expected to include an equal sign
that separates the tag from the data.
• Fields that take integer values can accept either hexadecimal or
decimal numbers. Hexadecimal numbers must begin with "0x".
• Certain numeric fields accept values other than integers. Non-integer
values must be specified in decimal and must include a decimal point.

22 IDEA SDK User’s Guide

 Chapter 3:
Understanding the CHP File

The RSET Structure and Associated Values and

Macros
CHP file data is represented internally in the IDEA library in a register set
(RSET) structure. This structure is an array of long integers containing the
setting values and a bit mask indicating whether or not the corresponding
setting is valid for the particular RSET. The internal contents of the RSET’s are
subject to change in the future. However, direct use of RSET is a practical
requirement for application code intended for tuning the setup for a particular
installation.
Foresight Imaging has provided a set of macros in the header file HDP_LIB.H for
accessing the individual elements of RSET’s, using names, in a manner that is
independent of the element’s particular location in the structure. New RSET
elements can be added and the storage order of the RSET elements can be
changed without breaking code that uses the macros. This is important for
maintaining compatibility with future versions of the IDEA library.
The RSET structure contains the bit mask byaRegSpecd, which can be accessed
with the following macros. The parameter ‘p’ is a pointer to the RSET, and the
parameter ‘i’ is one of the enumerations specified below. The
HD_RSETINDEX_RPT macro returns true or false depending upon whether the
specified bit is set. The HD_RSETINDEX_CLR macro clears the specified bit. The
HD_RSETINDEX_SET macro sets the specified bit.
#define HD_RSETINDEX_RPT(p,i) ((((BYTE *)p)[i/8] & (1<<(i&7))) != 0)
#define HD_RSETINDEX_CLR(p,i) ( ((BYTE *)p)[i/8] &= ~(1<<(i&7)) )
#define HD_RSETINDEX_SET(p,i) ( ((BYTE *)p)[i/8] |= (1<<(i&7)) )
typedef enum {
HPR_VCHAN=0, HPR_CSYNC, HPR_PCLOCK HPR_RESV0,
HPR_RESV1, HPR_VTOTAL, HPR_FR_MSEC, HPR_INTERL,
HPR_VSTYPE, HPR_VBP, HPR_HEIGHT, HPR_RESV2,
HPR_RESV3, HPR_HFREQ, HPR_HTOTAL, HPR_HBS,
HPR_WIDTH, HPR_HS_NSEC, HPR_HBP, HPR_RESV4,
HPR_GAIN, HPR_BLEVEL, HPR_BLACKREF, HPR_WHITEREF,
HPR_PIXSET10, HPR_PIXELSET, HPR_ZOOMDOWN, HPR_RESV5,
HPR_RESV6, HPR_PITCH, HPR_PASSMODE, HPR_DPDELAY,
HPR_PHASE2, HPR_PHASE, HPR_VATTR, HPR_CONTROL,
HPR_IMAPORT, HPR_HSTART, HPR_VSTART, HPR_RESV7,
HPR_REFPROG, HPR_REFBTYPE, HPR_REFBOARD,
HPR_REF_MPAL,
HPR_REF_PLL, HPR_RESV8, HPR_PIXFREQ, HPR_VERTFREQ,
HPR_N
} REGINDEX;

IDEA SDK User’s Guide 23

Chapter 3:
Understanding the CHP File

typedef struct {
unsigned char byaRegSpecd[8]; /* Bit=1 for each lRegs[] specified. */
long lRegs[HPR_N];
} RSET;
//
// Defines for rset element [HPR_VCHAN] and [HPR_CSYNC].
//
#define HDCHAN_CA1 0
#define HDCHAN_CA2 1
#define HDCHAN_CA3 2
#define HDCHAN_CA4 3
#define HDCHAN_SS12 4
#define HDCHAN_SS12H 5
#define HDCHAN_SS12V 6
#define HDCHAN_SS12I 7
#define HDCHAN_CT1 8
#define HDCHAN_CT2 9
#define HDCHAN_CT3 10
#define HDCHAN_CT4 11
#define HDCHAN_CT1I 12
#define HDCHAN_CT2I 13
#define HDCHAN_CT3I 14
#define HDCHAN_CT4I 15
/*
// Defines for rset element [HPR_REFPROG].
*/
#define HCHPREFP_APP_0 0
#define HCHPREFP_APP_1 1
#define HCHPREFP_APP_2 2
#define HCHPREFP_AS_TOOL 3
#define HCHPREFP_AS_DEMO 4
#define HCHPREFP_AUTOSYNC 5
#define HCHPREFP_SETUP 6
/*
// Defines for rset element [HPR_PASSMODE].
*/
#define HD_PMODE_SINGLE 0
#define HD_PMODE_DUAL 1
#define HD_PMODE_DUALODD 2

24 IDEA SDK User’s Guide

 Chapter 3:
Understanding the CHP File

CHP Setting Table

The full set of CHP file settings for Foresight Imaging boards is listed in the
following table. This table lists the setting name and whether it is a required
setting or not.
Not all settings must be explicitly specified for video board setup. They can be
broken up into four major groups: Required, Major set, Automatic, and Ignored.
• Major set: A subset of the settings, called the major set, is always
required. Major set settings are identified by an ‘M’ in the Required
column of the table and should always be changed as a set, not
individually.
• Required: Some settings should be considered required for practical
setup and use of the board. These settings are identified with an ‘R’ in
the Required column. Because the I-Color supports additional CHP file
settings (and ignores some standard settings used by the other boards),
a separate “required” column is provided.
• Automatic: Some settings are not required and these have no
designation in the Required column in the table.
Ignored: Some settings are not used by some board types and are identified
with an ‘I’ in the Required column.
If a required video setting is not specified, the video board setup and image
grab fails. If a setting that is not required is not specified, your IDEA
application automatically selects a value.

IDEA SDK User’s Guide 25

Chapter 3:
Understanding the CHP File

CHP Setting Name Required Page

[HIDEFPLUS]
Black Level R 27
Black Reference R 28
Composite Sync Source R 29
Frame Period 30
Gain R 30
Horizontal Back Porch M (a) 31
Horizontal Back Sync M (a) 32
Horizontal Frequency M 32
Horizontal Start M (b) 33
Horizontal Sync Width 33
Horizontal Total M 33
Image Height M 34
Image Width M 34
Interlace R 34
Pass Mode 35
Phase Delay R 35
Phase Delay 2 36
Pitch 36
Pixel Frequency 37
Pixel Set Value 37
Pixel Set10 Value 37
Reference Board Type 38
Reference Program 38
Reference Serial No 38
TTL Pixel Clock 39
Vertical Back Porch M 39
Vertical Frequency 40
Vertical Start 40
Vertical Sync Type R 40
Video Channel R 41
White Reference R 41
[I-RGB]
Cable I 42
FinePhaseAdjust I 43
ActiveInterface I 42
PixelMode I 43

26 IDEA SDK User’s Guide

 Chapter 3:
Understanding the CHP File

CHP Setting Name Required Page

ClampMode I 43
[I-RGB Calibration xxxxx]
RED_GAIN_CALIB I 44
GREEN_GAIN_CALIB I 44
BLUE_GAIN_CALIB I 44
RED_OFFSET_CALIB I 44
GREEN_OFFSET_CALIB I 44
BLUE_OFFSET_CALIB I 44

(a) = Only one of these is required, but both may be present.

(b) = Not required if Video Channel, Composite Sync Source and Interlace are specified (all
three).
(c) = The Video Channel and Composite Sync Source must be consistent with the InputChannel
setting on I-Color boards.

(d) = IDEA requires this value to be set, but the I-Color board does not use the setting.

Detailed [HIDEFPLUS] Video Setting

Descriptions
The following are detailed descriptions of all CHP settings in the [HIDEFPLUS]
section, ordered alphabetically, by setting name. This applies to all boards.

Black Level

Description This is part of Stage One of video amplitude and level control.
This compensates for any difference between the video blanking
level and the voltage level corresponding to black in the picture.
The units are in terms of the specified Gain range (qv). Further
adjustments can be made to the black voltage specification using
Black Reference (qv).
As Black Level is increased, the image becomes lighter but mid-
range contrast is not affected.
Example: Assume that a video signal has a blanking level of 12
mV, a black level of 17 mV and a white level of 720 mV. Eliminate
the affects of the Black and White Reference specifications by
setting them to 0.0 and 1.0, respectively. In this case, the Gain
range is 0.703 (720-17 mV).

IDEA SDK User’s Guide 27

Chapter 3:
Understanding the CHP File

The black level voltage relative to the blanking level is +5 mV (17-

12 mV). The BLevel specification can now be computed by
dividing the relative black level (+5 mV) by the Gain range (703
mV) and multiplying by minus one yielding –0.0071. Once BLevel
has been specified, the relative black level voltage can be
computed by multiplying BLevel by minus one and the Gain range
value. In this case, that would be –0.0071 times 0.703 volts
yielding 0.0050 volts.
Note See the description of Gain for additional information concerning
the two stages of video amplitude and level control.
Required Setting Yes
Units Gain Value Ratio
Default Value 0.000
Value Options Range [-0.5000 – 0.5000]
Can be specified with up to four decimal places.

Black Reference

Description This specification is part of the Stage Two of video amplitude

and level control. Black Reference (BRef) permits fine
adjustment of the black voltage level specification with little
effect on the white voltage level. On the HI*DEF Plus where both
control stages are implemented in the hardware, BRef and White
Reference (WRef) can also be used to capture weak video signals.
BRef represents the first stage signal level that is coded 0 (a black
pixel).
The neutral value for BRef is 0.0000.
For example, you have acquisition set up with BLevel and Gain
set, BRef=0.0000 and WRef=l.0000. But based on histogram data
from actual 10-bit captures, black is yielding pixel codes of 8 and
white is yielding 1023. If the intended pixel code range is 0 to
1023, then the correction can be made through adjustments to
either the first stage (BLevel and Gain) or the second stage (BRef
and WRef). For this case, use of the second stage is simpler.
Increasing the BRef to 0.0078, the current black code value (8)
divided by the pixel value range (1023-0) makes the captures
correct.
Note See the description of Gain for additional information concerning
the two stages of video amplitude and level control.
Required Setting Yes
Units Gain Value Ratio (qv)

28 IDEA SDK User’s Guide

 Chapter 3:
Understanding the CHP File

Default Value 0.0000 (As BRef is increased, the image becomes darker and has
more contrast)
Value Options Range [-0.0200 – 0.9500]
Can be specified with up to four decimal places.

Composite Sync Source

Description Specifies the video signal sync source. This setting overrides
selected bits in the Video Attributes (bits 1, 2, 11, 12, and 13) and
Signal Control (bits 8, 9, and 11) values. This setting is the
preferred way to specify sync source and it is recommended that
this value be set explicitly. If not specified, Video Attributes and
Signal Control are used to select the sync source. Note that for an
I-Color board, the Composite Sync Source and Video Channel
entries are overridden by the InputChannel entry in the I-Color
section.
Required Setting Yes
Default Value CA1
Value Options Video Signal Source CHP Programming
Value Value
Composite video, channel 1 CA1 HDCHAN_CA1
Composite video, channel 2 CA2 HDCHAN_CA2
Composite video, channel 3 CA3 HDCHAN_CA3
Composite video, channel 4 CA4 HDCHAN_CA4
Separate Horizontal and Vertical sync, SS HDCHAN_SS12
neither inverted. Horizontal on CT1,
Vertical on CT2
Separate sync on CT1 and CT2, SS(-H) HDCHAN_SS12H
Horizontal inverted
Separate sync, Vertical inverted SS(-V) HDCHAN_SS12V
Separate sync, both Horizontal and -SS HDCHAN_SS12I
Vertical inverted
Composite sync, channel 1 CT1 HDCHAN_CT1
Composite sync, channel 2 CT2 HDCHAN_CT2
Composite sync, channel 3 CT3 HDCHAN_CT3
Composite sync, channel 4 CT4 HDCHAN_CT4
Inverted composite sync, channel 1 -CT1 HDCHAN_CT1I
Inverted composite sync, channel 2 -CT2 HDCHAN_CT2I

IDEA SDK User’s Guide 29

Chapter 3:
Understanding the CHP File

Inverted composite sync, channel 3 -CT3 HDCHAN_CT3I

Inverted composite sync, channel 4 -CT4 HDCHAN_CT4I

NOTE: CT3 may be used either as the external TTL clock or

as a sync input, but not both in the same installation.

Frame Period

Description The time it takes to transmit a single frame (all scan lines) of
video signal, rounded up to the next whole number. Interlaced
format has two fields per frame. Frame Period includes both
fields.
This value is used to calculate some time-out values for video
operations. It is not recommended to specify Frame Period in a
CHP file. The only situation where you may want to specify a
value is if you are grabbing only part of the scan lines in an
image. In this case, the time-out values may be computed to be
too small, possibly resulting in a premature time-out.
Units msec
Default Value Not Specified
Value Options Range [0 – 999999]
This should always be entered as a whole number. Decimal digits
are truncated.

Gain

Description The Gain specification is part of the first stage of video amplitude
and level control. When the second video control stage is
bypassed (BRef=0.0000 and WRef=1.0000), it specifies the video
signal voltage difference between black and white.
As the Gain specification is increased, the picture becomes darker
and has less contrast.
Note The Gain value forms the units for all three of the other video
amplitude and control specifications (BLevel, BRef and WRef). For
example, if the following settings are made:
BLevel =-0.0071
BRef = 0.0078
WRef = 0.9950
Gain = 0.7030

30 IDEA SDK User’s Guide

 Chapter 3:
Understanding the CHP File

then the corresponding voltages would be:

Gain*BLevel = 0.7030 * -0.0071 V = -0.0050 V
Gain*BRef = 0.7030 * 0.0078 V = 0.0055 V
Gain*WRef = 0.7030 * 0.9950 V = 0.6995 V
Gain*l = 0.7030 V
Required Setting Yes
Units Volts
Default Value 0.6000
Value Options Range [0.5 – 1.0]
Can be specified with up to four decimal places.

Horizontal Back Porch

Description Horizontal Back Porch and Horizontal Back Sync define the time
period from the beginning of the horizontal sync pulse to the
beginning of active video. This is potentially confusing, because
back porch usually refers to the time starting at the end of the
horizontal sync pulse, not the beginning.
Board electronics will alter this time period; therefore the value
sent to the board must compensate for those timings.
Compensation is different for the HI*DEF Plus and the I-Series/
HI*DEF Accura. Horizontal Back Sync is the best value to use
because it does not include this compensation:
When Horizontal Back Sync is used, the library computes
the compensation based on which board is being used.
Horizontal Back Porch includes compensation appropriate
to the HI*DEF Plus only.
When Horizontal Back Sync is not available, the library uses
Horizontal Back Porch but does not compute
compensation.
Note This setting is available for backward compatibility. Horizontal
Back Sync is the preferred setting. This value is overridden by
Horizontal Back Sync.
Required Setting Required within a major set. Must specify either this setting or
the Horizontal Back Sync.
Units Pixels
Default Value 4
Value Options Range [4 – 8191]

IDEA SDK User’s Guide 31

Chapter 3:
Understanding the CHP File

Horizontal Back Sync

Description Defines the time period from the beginning of the horizontal sync
pulse to the beginning of active video. Board electronics will alter
this time period; therefore the value sent to the board must
compensate for those timings. Compensation is different for the
HI*DEF Plus and the I-Series/HI*DEF Accura boards:
When Horizontal Back Sync is used, the library computes
the compensation based on which board is being used.
Horizontal Back Porch includes compensation appropriate
to the HI*DEF Plus only.
When Horizontal Back Sync is not available, the library uses
Horizontal Back Porch but does not compute
compensation.
This value overrides the Horizontal Back Porch. More precise
adjustments can be made to this value using the Phase Delay
parameters.
Required Setting Required within a major set. Must specify either this setting or
the Horizontal Back Sync.
Units Pixels
Default Value 4
Value Options Range [4 – 8191]

Horizontal Frequency

Description The number of scan lines transmitted per second in the video
signal.
Required Setting Required within a major set.
Units Hz
Default Value 15725

32 IDEA SDK User’s Guide

 Chapter 3:
Understanding the CHP File

Value Options Range AccuStream 170/170+ [10600 – 105100]

AccuStream 75/75+ [10600 – 62000]
AccuStream 50/50+ [10600 – 62000]
AccuStream 205a [10600 – 105100]
AccuStream 75a [10600 – 62000]
AccuStream 50a [10600 – 62000]

Horizontal Start

Description The horizontal start address of the image data storage in frame
grabber (video board) memory. This is used for frame grabber
memory management in board handle mode only. This setting is
not used in image handle mode and is ignored if specified.
Note Specifying this setting is not recommended. If specified, it should
be set to 0.
Required Setting Required within a major set. Not required if Video Channel,
Composite Sync Source and Interlace are specified (all three).
Units Pixels (frame grabber coordinates)
Default Value 0
Value Options Defined at time of CHP creation.

Horizontal Sync Width

Description Width of the horizontal sync portion of the video signal. This is
critical only when there are very small horizontal back porches.
Note Setting this value does not change the definition of Horizontal
Back Porch or Horizontal Back Sync.
Foresight Imaging does not recommend specifying this setting.
Required Setting No
Units Nanoseconds
Default Value Not Specified
Value Options Range [0 – 999999]

Horizontal Total

Description The total number of pixels in one video scan line (i.e. per
horizontal period). This includes active video, horizontal front
porch, horizontal back porch, and horizontal sync.

IDEA SDK User’s Guide 33

Chapter 3:
Understanding the CHP File

Required Setting Required within a major set.

Units Pixels
Default Value 26
Value Options Range [26 - 8192]

Image Height

Description Number of active vertical scan lines in the image.

Required Setting Required within a major set.
Units Scan lines
Default Value 0
Value Options Range [0 – 2048]

Image Width

Description Number of active horizontal video pixels in one scan line.

Required Setting Required within a major set.
Units Pixels
Default Value 1
Value Options Range [1 – 2048]

Interlace

Description Specifies whether or not the video signal is interlaced and, if so,
the polarity (order of the odd and even fields) of the signal.
This setting overrides bits 0 and 14 of the Video Attributes
setting. This is the preferred way to specify interlace attributes.
Required Setting Yes
Default Value OFF
Value Options Video Signal CHP Value Programming
Value
Non-interlaced OFF 0
Interlaced; Even scan line first; ON 1
odd-even field pairing
Interlaced; Odd scan line first; ODD_UP 2
odd-even field pairing

34 IDEA SDK User’s Guide

 Chapter 3:
Understanding the CHP File

Interlaced; Even scan line first; ON_EVENODD 3

even-odd field pairing
Interlaced; Odd scan line first; ODD_UP_EVENOD 4
even-odd field pairing D

Pass Mode

Description Specifies the order in which the video pixel data will be captured.
This differs from interlacing, which specifies scan line order, not
pixel order.
Note Foresight Imaging does not recommend specifying this setting.
The IDEA application chooses the appropriate option, based on
other settings.
Required Setting No
Default Value Not Specified

Value Options Video Signal CHP Value Programming Value

Even and odd pixels are SINGLE HD_PMODE_SINGLE
captured on the same pass.
Used for all pixel frequencies
below 70 MHz.
Even pixels are captured on DUAL HD_PMODE_DUAL
the first pass and odd pixels
are captured on the second
pass.
Dual Pass Extended in IDEA DUALODD HD_PMODE_DUALODD
Auto-SYNC.
Not currently supported.

Phase Delay

Description Specifies the phase of the sampling clock, which is a delay

relative to horizontal sync. This allows the sampling operation to
be optimally placed relative to the pixel wave form.
Accuracy is 0.5 nanoseconds.
Required Setting Yes
Units Nanoseconds
Default Value 0.0
Value Options Range [0.0 – 127.5]

IDEA SDK User’s Guide 35

Chapter 3:
Understanding the CHP File

Must have 1 decimal place.

Phase Delay 2

Description Phase delay for the second pass of dual pass grab. This is typically
not used in practice.
Typically, this is calculated as phase delay plus one pixel period.
Specifying this value is not recommended unless absolutely
necessary. The reason it would be necessary is when lowered
accuracy due to rounding or step values during calculation causes
the second phase delay to be slightly inaccurate.
Accuracy is 0.5 nanoseconds.
Required Setting No
Units Nanoseconds
Default Value Not Specified
Value Options Range [0.0 – 127.5]
Must have 1 decimal place.

Pitch

Description A pitch is an absolute width reserved for one line of video in

frame grabber (i.e. video board) memory. Pitch is used to manage
frame grabber memory.
Note
Specifying this setting is not recommended. The appropriate pitch
will be selected automatically by the IDEA library if operating in
board handle mode.
Required Setting No
Units Pixels
Default Value Not Specified
Value Options 1024 Can use if the grabbed image size is less than or equal
to 1024 pixels.
2048 Must use if the grabbed image size is greater than 1024
pixels.

36 IDEA SDK User’s Guide

 Chapter 3:
Understanding the CHP File

Pixel Frequency

Description The number of pixels transmitted per second in the video signal,
typically measured in megahertz.
The pixel frequency can be calculated as the product of the
Horizontal Frequency and the Horizontal Total.
Note This setting is provided for informational purposes only. Changing
the value does not affect the frame grabber board.
Required Setting No
Units kHz
Default Value Not Specified
Value Options Range [0 – 300000]

Pixel Set Value

Description Pixel value used to fill a region of frame grabber (video board)
memory during a SET command for 8-bit operations. This
operation does exactly what a grab does except the pixel set
value is used as the data source instead of the AD converter.
Note This setting is overridden by Pixel Set 10 Value.
This setting is used primarily for diagnostic purposes and other
special operations. It is not used for normal video grabs.
Required Setting No
Default Value 0x00
Value Options Range [0x00 – 0xFF]

Pixel Set10 Value

Description Pixel value used to fill a region of frame grabber (video board)
memory during a SET command for 10 bit operations. This
operation does exactly what a grab does except the pixel set
value is used as the data source instead of the AD converter.
Note This setting overrides Pixel Set Value.
This setting is used primarily for diagnostic purposes and other
special operations. It is not used for normal video grabs.
Default Value 0x000
Value Options Range [0x000 – 0x3FF]

IDEA SDK User’s Guide 37

Chapter 3:
Understanding the CHP File

Reference Board Type

Description Type of video board used to create the CHP file. This setting is for
documentation purposes.
Required Setting No
Default Value Board dependent. Defined at time of CHP creation.
Value Options ACCUSTREAM 170
ACCUSTREAM 70
ACCUSTREAM 50
ACCUSTREAM 170+
ACCUSTREAM 70+
ACCUSTREAM 50+
ACCUSTREAM 205a
ACCUSTREAM 75a
ACCUSTREAM 50a

Reference Program

Description Identification of the program used to create the CHP file. This
setting is for documentation purposes.
Required Setting No
Default Value Application dependent. Defined at time of CHP creation.
Value Options APP_0
APP_1
APP_2
AS_TOOL
AS_DEMO
AUTOSYNC
SETUP

Reference Serial No

Description Serial number of the video board used to create the CHP file. This
setting is for documentation purposes.
Note The serial number is stored in coded form in the RSET structure.
IDEA library routines are supplied for encoding and decoding.

38 IDEA SDK User’s Guide

 Chapter 3:
Understanding the CHP File

Required Setting No
Default Value 0
Value Options Serial numbers are up to 6 digits in length.

TTL Pixel Clock

Description Specifies whether an external TTL Pixel Clock is being supplied

and whether or not it is inverted.
Note This setting overrides bit 6 of the Signal Control setting. This is
the preferred method to specify external clock.
Default Value NONE
Value Options NONE No External Clock.
CT3 On CT3, not inverted.
-CT3 On CT3, inverted.

Vertical Back Porch

Description The number of vertical blanking lines in the video signal that does
not include any vertical sync information. This is the portion of
the video signal from the trailing edge of the vertical sync to the
beginning of active video. (Note that this differs from the
definition of the Horizontal Back Porch and Horizontal Back Sync
settings, which do include sync.)
If the video signal is interlaced, the Vertical Back Porch is on a
per field basis.
For interlaced images, it is possible for the even and odd fields to
have blanking line counts that differ by 1. The fractional part of
this setting is used to specify this situation. If the fractional digit
is 0, both even and odd fields have the same number of blanking
lines. If the fractional digit is 5, the odd field has 1 more blanking
line than the even field.
Required Setting Required within a major set.
Units Scan Lines
Default Value 0.0
Value Options Range [0.0 – 4095.0]
Must have one decimal place. Fractional digit can be 0 or 5 only.

IDEA SDK User’s Guide 39

Chapter 3:
Understanding the CHP File

Vertical Frequency

Description The number of video fields transmitted per second for an

interlaced signal or the number of video frames transmitted per
second for a non-interlaced video signal.
The vertical frequency can be calculated as the result of dividing
the Horizontal Frequency by the Vertical Total; this is the number
of video frames per second. If the video signal is interlaced, the
resulting value should be doubled to determine the number of
video fields per second.
Note This setting is provided for informational purposes only. Changing
the value does not affect the frame grabber board.
Required Setting No
Units Hz
Default Value Not Specified
Value Options Range [0 – 300000]

Vertical Start

Description The vertical start address of the image data storage in frame
grabber (video board) memory. This is used for frame grabber
memory management in board handle mode only. This setting is
not used in image handle mode and is ignored if specified.
Note Foresight Imaging does not recommend specifying this setting. If
specified, it should be set to 0.
Required Setting No
Units Scan Lines (frame grabber coordinates)
Default Value Defined at time of CHP creation.

Vertical Sync Type

Description Specifies the type of sync information that is available during the
vertical sync and vertical front porch periods. This setting
overrides bit 15 of the Video Attributes setting. This is the
preferred way to specify vertical sync attributes.
Required Setting Yes
Default Value NORMAL

40 IDEA SDK User’s Guide

 Chapter 3:
Understanding the CHP File

Value Options NORMAL Fairly common format. Serration or regular

horizontal sync pulses are present during vertical
sync.
BLOCK Most common format. Serration pulses and
horizontal sync information is not available during
vertical sync. During image grab, coast through
vertical sync only.
STRAY Least common format. Video signal falls apart during
vertical front porch. This setting implies block sync
also. During image grab, coast through both vertical
front porch and vertical sync.

Video Channel

Description Specifies the video acquisition channel.

Required Setting Yes
Default Value CA1
Value Options Video Acquisition Channel CHP Value Programming Value
Composite video, channel 1 CA1 HDCHAN_CA1
Composite video, channel 2 CA2 HDCHAN_CA2
Composite video, channel 3 CA3 HDCHAN_CA3
Composite video, channel 4 CA4 HDCHAN_CA3

White Reference

Description This specification is part of the second stage of video amplitude and
level control. See the description for the Gain range specification for
a complete explanation of this video control process. White
Reference (WRef) permits fine adjustment of the white voltage level
specification with little effect on the black voltage level.
For example, say that you have set up for acquisition with BLevel
and Gain set, BRef=O.0000 and WRef=1.0000. But based on
histogram data from actual 10-bit captures, black is yielding pixel
codes of 0 and white is yielding 1015. If the intended pixel code
range is 0 to 1023, then the correction can be made with
adjustments to either the first stage (BLevel and Gain) or the
second stage (BRef and WRef). For this case, use of the second
stage is simpler. Decreasing the WRef to 0.9922, the current
white code value (1015) divided by the pixel value range (1023-0)
makes the captures correct.

IDEA SDK User’s Guide 41

Chapter 3:
Understanding the CHP File

Note See the description of Gain for additional information concerning

the two stages of video amplitude and level control.
Required Setting Yes
Units Gain Value Ratio (qv)
Default Value 1.0000 (As WRef is decreased, the image becomes lighter and has
more contrast.)
Value Options Range [0.0500 – 1.0200]
Can be specified with up to four decimal places.

Detailed [I-RGB] Video Setting Descriptions

The following are detailed descriptions of all [I-RGB] CHP settings, ordered
alphabetically, by setting name. This includes AccuStream as well.

ActiveInterface

Description Specifies whether the board will operate in analog or digital

mode. This only applies to the AccuStream board which can
capture analog or DVI digital signals. If the value is “None” then
the library will determine the type of signal.
Default Value “Analog”
Value Options “Analog”
“Digital”
“None”

Cable

Description Specifies the cabling for the I-RGB board. Prior to revision 1D,
changes to the cable type also required modifications to the
jumpers on the board.
Default Value “DVI-to-BNC”
Value Options “DVI-to-BNC”
“DVI-to-VGA (D Shell)”
“DVI-to-VGA (5 BNC)”
“DVI-to-DVI”

42 IDEA SDK User’s Guide

 Chapter 3:
Understanding the CHP File

“DVI-To-BNC” refers to the 7 BNC cable numbered 030083. This cable is not
compatible with the AccuStream boards. “DVI-To-VGA (D-Shell)” is the cable
numbered 030085. “DVI-to-VGA (5 BNC)” is the cable numbered 030093. Both
“DVI-to-VGA” cables are functionally equivalent. “DVI-to-DVI” should only be
used for connecting to a digital output video source.

ClampMode

Description Controls whether the A/D clamps to full scale or mid-scale. This is
used for switching between RGB and YPbPr video inputs. It is only
supported by the AccuStream boards.

Default Value “RGB”

Value Options “RGB”

FinePhaseAdjust

Description Controls the fine tuning of the phase value used to read pixel
values. The 32 values of FinePhaseAdjust are converted to degree
offsets by the frame grabber.

Default Value 0
Value Options 0 to 31

PixelMode

Description Specifies if the board is to capture RGB or monochrome. If the

pixel mode is “Mono” and the incoming signal has composite sync
on the video channel then the “Composite Sync Source” entry
must match in the sync channel. See the addendum on capturing
monochrome video.

Default Value “RGB”

Value Options “RGB”
“Mono”

IDEA SDK User’s Guide 43

Chapter 3:
Understanding the CHP File

Detailed [I-RGB Calibration] Video Setting

Descriptions
The following are detailed descriptions of all CHP settings related to color
calibration. This applies to all boards.

RED_GAIN_CALIB,
GREEN_GAIN_CALIB,
BLUE_GAIN_CALIB

Description Adjusts the “natural” gain calibration values of the board,

allowing the color range to be recentered based on the
characteristics of the video source. This value can be set using the
White Balance feature of Auto-SYNC or manually adjusted. A
value of 0 represents the factory default calibration value.
Default Value 0
Value Options 0 to 255

RED_OFFSET_CALIB,
GREEN_OFFSET_CALIB,
BLUE_OFFSET_CALIB

Description Adjusts the “natural” offset (black level) calibration values of the
board, allowing the color range to be recentered based on the
characteristics of the video source. This value can be set using the
White Balance feature of Auto-SYNC or manually adjusted. A
value of 0 represents the factory default calibration value.
Default Value 0
Value Options 0 to 255

44 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

CHAPTER 4:
C Function Listings
This chapter describes the C functions currently available to program the
Foresight Imaging boards from the IDEA Library. The first section, called
Function Table, lists each function, alphabetically (without the prefixes), with a
brief description and the page that function is discussed further.
The second section, called Function Descriptions, discusses the functions with
more detail.

Function Table
This section lists each function with a brief description and the page that
function is discussed.

Name Description
bHD_CommandDone Returns status of Command Done.
bhHP_Claim I-Series: Sets up board at the specified slot number.
This function also sets up access to the board’s Frame
Grabber..
bHP_CommandDone Returns status of Command Done.
bHP_CommandReady Returns status of Command Ready.
bHP_CSyncDetect Reports status of video sync.
eHP_Close Prohibits IDEA access to the specified Open Data
structure.
eHP_Command Sets up specified command (wCommand) for a specified
board.
eHP_CommandDone Waits up to wTimeout_mS milliseconds for Command Done
then returns. Error condition is generated on timeout.
Timeout value may be defaulted by specifying
VIDEOTIMEOUT.
eHP_CommandReady Waits up to wTimeout_mS milliseconds for Command
Ready then returns. Error condition is generated on
timeout. Timeout value may be defaulted by specifying
VIDEOTIMEOUT.
eHP_DisableTriggerEvent Disables events on trigger signals

IDEA SDK User’s Guide 45

Chapter 4:
C Function Listings

Name Description
eHP_EnableTriggerEvent Enables events on trigger signals
eHP_FBFastRead Copies a block of data from the IDEA frame grabber
memory into fpwBuf. Column and line numbers start at
zero.
eHP_FBHisto Accumulates histogram data from pixel values in frame
grabber memory. Column and line numbers start at zero.
The accumulation starts at column wColumn, line wLine in
frame grabber memory. This array is never zeroed by
eHP_FBHisto( ).

eHP_GetBoardCaps Returns a 32-bit value containing a bitmap describing the

board’s capabilities.
eHP_GetBoardIDString Retrieve a string to describe a particular frame grabber.
eHP_GetControlValue Gets a control value.
eHP_GetInfoStruct Get a pointer to the board’s information structure.
eHP_Open Prepares a board for use by associating it with an Open
Data structure.
eHP_RSET_FRead Reads the contents of a file containing IDEA video settings
data. Before calling this routine, fopen( ) must be called
to prepare the IDEA Configuration file (*.CHP) for reading.
This routine decodes the ASCII data in the *.CHP file and
performs various syntax checking. If no errors are found,
structure *prset is returned with a binary form of the
*.CHP data.
eHP_RSET_FWrite Writes the IDEA board configuration data to an ASCII file.
eHP_RSET_Set Configures a Foresight frame grabber board. Data should
already be loaded into *prset with a call to
eHP_RSET_FRead( ).
eHP_SetBlackLevel Sets the Black Level.
eHP_SetChannel Sets the current video signal channel.
eHP_SetControlValue Sets a control value or performs some specified function.
eHP_SetGain Sets the Gain Range.
eHD_Command Executes the specified command as set up in the specified
image handle.
eHD_Deallocate Makes a previously allocated image buffer in the frame
grabber memory available and invalidates the image handle.

46 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

Name Description
eHD_DeallocateAll Invalidates all image handles assigned to the specified board.
This releases all use of the board’s memory and permits
board-handle-based calls to the board.
eHD_FBFastReadPixel Transfers any rectangular section of a captured image
from the image buffer in frame grabber memory to the
application buffer.
eHD_FBHistoPixel Accumulates pixel code histogram data from any
rectangular section of a captured image from the image
buffer in frame grabber memory to the application buffer
fpwBuf. Neither eHD_FBHistoPixel( ) nor eHP_FBHisto( )
ever initialize (zero) the histogram array.
eHD_GetStreamBuffer Retrieve the most recent buffer filled by streaming
eHD_LiveDisplayInit Prepare library to display live video in a window.
eHD_LiveDisplayMode Begin or end live video display.
eHD_LiveStreamInit Prepare Library for streaming to buffers.
eHD_LiveStreamMode Begin, end or pause live streaming operation.
eHD_LiveStreamClose Clean up and unlock streaming buffers.
eHD_ReleaseStreamBuffer Release the buffer to be filled by a subsequent streaming
operation
eHD_RSET_Check Checks an RSET structure against mode-specific criteria.
eHD_RSET_Get Gets the RSET currently in use by an image handle.
eHD_RSET_Set Configures an image handle for use with a Foresight frame
grabber board.
eHD_SetChannel Changes the channel used with a specified image handle.
eHD_SetWhiteBalance Store balanced gain and offset levels among R,G and B
channels
eHD_SnapToBuffer Grab a frame and transfer it to a user buffer.

eHD_TestWhiteBalance Survey R,G and B channels for balanced gain and offset
values.
fine_abswait Returns at a specified date and time (or very soon
thereafter – system conditions permitting).
fine_add Adds two millisecond time values. It is assumed that at
least one of the values is a time interval.
fine_ascii_local Converts absolute date/times or elapsed days/
milliseconds to an ASCII string.

IDEA SDK User’s Guide 47

Chapter 4:
C Function Listings

Name Description
fine_delta Adds the specified number of milliseconds (either positive
or negative – the second argument) to the time value
pointed to by the first argument.
fine_later Adds the specified number of milliseconds (second
argument) to the current time and stores this value in the
first argument. Adjustments are made to accommodate
timer limitations.
fine_now Stores the current date and time at the location specified
in the first argument.
fine_subtract Subtracts the second argument from the value pointed to
by the first argument. FINE_TIME structures may refer to
absolute date/times or to elapsed days/milliseconds.
fine_wait Returns after waiting the specified number of
milliseconds.
_HP_Error Declares that Error wError has been encountered while
processing the board handle.
HP_UnClaim Releases possible claim on a board.
ihHD_Allocate Allocates frame grabber memory space for a specified image
format and assigns an image handle to it.
nHP_ClaimAll Scans for up to 15 Foresight boards and claims all of them.
This preempts all claims made by bhHP_Claim( ).
nHP_ErrMessage Formats a string to describe an error code.
nHP_GetBoardInfo Retrieves specified board information.
nHP_Report Provides a list of Foresight boards found at system start-
up. This should be called before boards are claimed or
opened.
eHD_GetMaxBuffers Return an approximation of the maximum number of
buffers that can be allocated.

Function Descriptions
This section discusses the IDEA SDK functions with more detail. Prototypes for
these functions are provided in the files called HDP_LIB.H and HP_FTIME.H.

48 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

bHD_CommandDone

BOOLs APPTYPE bHD_CommandDone (ImageHandle ih)

Description This function always returns TRUE. It’s only maintained for backwards
compatibility.
Parameters ih Image handle.
Returns TRUE Command is done.

bhHP_Claim

BoardHandle APPTYPE bhHP_Claim ( WORD wIOAddr, DWORD dw4KMem)

Description Sets up board at the specified slot number.

Parameters wIOAddr PCI Slot number assigned by the system BIOS. This
must be OR’d with the value of the HD_PCI slot.
dw4KMem This parameter is only kept for compatibility with
earlier software. It should be set to zero.
Returns Returns a positive value if successful. This value is the board handle
needed for subsequent access to the board.
Returns a negative value if unsuccessful and indicates the problem.
This routine is unusual in its error handling. This is necessary, since
this routine must be called before eHP_Open( ) and therefore there is
no Open Data structure for posting errors.
The possible error return values are:
HPCLAIM_ALLOC Memory Allocation error occurred while
attempting to ready board.
HPCLAIM_IN_USE The specified board is in use by another
program.
HPCLAIM_NO_HDP There is no Foresight board at the
specified I/O address.
HPCLAIM_NO_VXD Device driver not available and/or
unusable.
HPCLAIM_PARAM Invalid parameters passed to
bhHP_Claim.
HPCLAIM_TOOMANY The maximum number of boards that
can be readied is 15.
HPCLAIM_VXD_REV Device driver and DLL revision
mismatch.

IDEA SDK User’s Guide 49

Chapter 4:
C Function Listings

bHP_CommandDone

BOOLs APPTYPE bHP_CommandDone (BoardHandle bh)

Description This function always returns TRUE.

Parameters bh Handle to a specific board.

Returns TRUE Command is done.

bHP_CommandReady

BOOLs APPTYPE bHP_CommandReady (BoardHandle bh)

Description This function always returns TRUE. It is only maintained for backward
compatibility.

Parameters bh Handle to a specific board.

Note In general, Command Ready goes to TRUE before Command Done.
Returns TRUE Ready for next command.

bHP_CSyncDetect

BOOLs APPTYPE bHP_CSyncDetect (BoardHandle bh)

Description Reports status of video syncs.

Parameters bh Handle to a specific board.

Note As of the 1.6 release of IDEA, this function correctly identifies sync on
the current configuration.
Returns TRUE Composite sync detected.
FALSE Composite sync not detected.

50 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

eHP_Close

ERRTYPE APPTYPE eHP_Close (HP_OpenData *pOD)

Description Prohibits IDEA access to the specified Open Data structure.
Parameters pOD The Open Data structure as filled in by the call to
eHP_Open. Contains the following elements:
HP_OpenData *psParent: Internal use only
(provision for nested
opens).
HPE_CALLBACK fpcbHPE: Pointer to application
routine for handling
errors.
ERRTYPE eError: Error code for last error
detected (or zero).
ERRTYPE eErrorList[3]: Error codes for previous
three errors (or zero).
ERRTYPE eLibMax: Max error # to library
message list.
FILE *fpErrSrc: Application message file
(used if e>eLibMax).
Returns 0 (zero) if successful
HPERR_CLOSENEST
HPERR_CLOSE

eHP_Command

ERRTYPE APPTYPE eHP_Command ( BoardHandle bh, WORD wCommand)

Description Sets up specified command (wCommand) of specified board.

NOTE: This function CANNOT be used in conjunction with functions that use
image handles. If image handles have been used on the board, they must
be deallocated before this function can be used. This deallocation can be
done either individually or with a call to eHD_DeallocateAll( ).

Parameters bh Handle to a specific board.

wCommand May be any of these:
HPCMD_GRAB: Grabs an image.
HPCMD_GRAB_ON_TRIG: The function waits to
return until an external

IDEA SDK User’s Guide 51

Chapter 4:
C Function Listings

hardware trigger
occurs. Refer to the
Foresight Imaging
Installation and User’s
Guide for information
concerning triggers.
HPCMD_IDLE: Idle.

Returns 0 (zero) if successful

HPERR_COMMAND_CODE
HPERR_COMMAND_READY
HPERR_HANDLE
HPERR_TIMEOUT This is returned if the video signal
can not be captured in synchronous
mode.
HPERR_USING_IHANDLES Image handles were used but not
deallocated before this function was
called. This deallocation can be
done either individually or with a
call to eHD_DeallocateAll( ). See
the note in this function’s
description.

eHP_CommandDone

ERRTYPE APPTYPE eHP_CommandDone ( BoardHandle bh, WORD wTimeout_mS)

Description Waits up to wTimeout_mS milliseconds for Command Done, then
returns. Error condition is generated on timeout. Timeout value may
be defaulted by specifying VIDEOTIMEOUT.
Parameters bh Handle to a specific board.
wTimeout_mS Time to wait until timeout occurs.
Returns 0 (zero) if successful
HPERR_COMMAND_CODE
HPERR_HANDLE

eHP_CommandReady

ERRTYPE APPTYPE eHP_CommandReady ( BoardHandle bh, WORD wTimeout_mS)

Description This function always returns zero.

52 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

Parameters bh Handle to a specific board.

wTimeout_mS Time to wait until timeout occurs.
Returns 0

eHP_DisableTriggerEvent

ERRTYPE APPTYPE eHP_DisableTriggerEvent ( BoardHandle bh, HANDLE hEvent )

Description Disables the ability for the application to receive a WIN32 event
notification when the board has received a trigger signal. See
eHP_EnableTriggerEvent.

Parameters bh Handle to the specified board.

hEvent A Windows event handle. It must match the handle used in
eHP_EnableTriggerEvent.
Returns (0) Zero if successful.
HPERR_HANDLE if the board handle is invalid.

eHP_EnableTriggerEvent

ERRTYPE APPTYPE eHP_EnableTriggerEvent (

BoardHandle bh,
HANDLE hEvent,
BOOL bOneShot )

Description Enables the application to receive a WIN32 notification event when

the board receives a trigger signal. The hEvent handle should be
created by the Win32 API CreateEvent(). After it is finished with the
event handle, the application should free it with a call to the Win32
API CloseHandle().

Parameters bh Handle to the specific board.

HEvent Event handle that the application will wait on.
bOneShot True if the application only wants to receive on trigger
event. False if the application want to receive continuous
event notifications.
Returns 0 (zero) if successful.
HPERR_HANDLE if the board handle is not valid.

IDEA SDK User’s Guide 53

Chapter 4:
C Function Listings

eHP_FBFastRead

ERRTYPE APPTYPE eHP_FBFastRead (

BoardHandle bh,
WORD wColumn,
WORD wLine,
short nWide,
short nHigh,
WORD *fpwBuf)
Description Copies a block of data from the IDEA frame grabber memory into
fpwBuf. Column and line numbers start at zero.

NOTE: This function CANNOT be used in conjunction with functions that use
ImageHandles. If image handles have been used on the board, they must
be deallocated before this function can be used. This deallocation can be
done either individually or with a call to eHD_DeallocateAll( ).

Parameters bh Handle to a specific board.

wColumn Specifies the horizontal location in the image where
the transfer of pixels start. Column numbers are
always zero or positive and are relative to the left
edge of the image. If the entire image is being
transferred, wColumn should be zero.
Value must be a multiple of 32.
wLine Specifies the vertical location in the image where the
transfer of pixels start. Line numbers are always zero
or positive and are relative to the top edge of the
image. So if the entire image is being transferred,
wLine should be zero.
nWide Specifies the width of the rectangular area that is to
be transferred in pixels. nWide must be positive and
the sum of nWide and wColumn must not exceed the
width of the image.
Value must be a multiple of four.
nHigh Specifies the height of the rectangular area that is to
be transferred in lines. nHigh must be positive and the
sum of nHigh and wLine must not exceed the height of
the image.
fpwBuf Points to the destination area in host memory for the
transfer. For example, the application may have
created this with the call fpwBuf=(WORD *)malloc
(2*nWide*nHigh). This pointer must be DWORD aligned.
Returns 0 (zero) if successful

54 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

HPERR_FG_LINE_LIMIT The maximum width of a line is

determined by the pitch currently in
use. The pitch may be either 1024
or 2048. An attempt to transfer
data outside the limits of the line
(wColumn+nWide>=pitch) results in
this error code.
HPERR_HANDLE
HPERR_IMAGE_BOUNDS Specified image size is out of
bounds.
HPERR_MEMORY_ALLOC Out of system memory.
HPERR_USING_IHANDLES Image handles were used but not
deallocated before this function was
called. This deallocation can be
done either individually or with a
call to eHD_DeallocateAll( ). See
the note in this function’s
description.

eHP_FBHisto

ERRTYPE APPTYPE eHP_FBHisto (

BoardHandle bh,
WORD wColumn,
WORD wLine,
short nWide,
short nHigh,
DWORD *fpdwHisto)
Description Accumulates histogram data from pixel values in frame grabber
memory. Column and line numbers start at zero. The accumulation
starts at column wColumn, line wLine in frame grabber memory. This
array is never zeroed by eHP_FBHisto( ). This means that histogram
data can be accumulated into the same array with multiple calls to
eHP_FBHisto( ). It also means that the application program must zero
(or otherwise initialize the array) before calling this routine.

Note This function CANNOT be used in conjunction with functions that

use ImageHandles. If image handles have been used on the board,
they must be deallocated before this function can be used. This
deallocation can be done either individually or with a call to
eHD_DeallocateAll( ).

Parameters bh Handle to a specific board.

IDEA SDK User’s Guide 55

Chapter 4:
C Function Listings

wColumn Column to start accumulation at in frame grabber

memory.
wLine Line to start accumulation at in frame grabber memory.
nWide Width, in number of pixels across, of the rectangular
region to be scanned.
nHigh Height, in number of lines high, of the rectangular
region to be scanned.
fpdwHisto Specifies an array of 256 DWORDs.
Note There are no WORD or DWORD alignment restrictions on the use of this
routine. However, there is a slight improvement in performance if the
histogram array is WORD aligned.
Returns 0 (zero) if successful
HPERR_FG_LINE_LIMIT
HPERR_HANDLE
HPERR_MEMORY_ALLOC
HPERR_ODD_FB_ALIGN
HPERR_PARAM_BAD_PARAMETER
HPERR_USING_IHANDLES Image handles were used but not
deallocated before this function was
called. This deallocation can be
done either individually or with a
call to eHD_DeallocateAll( ). See
the note in this function’s
description.

eHP_GetBoardCaps

DWORD APPTYPE eHP_GetBoardCaps (int nBoardType)

Description This function will return a 32 bit value containing a bitmap describing
the board’s capabilities. Each bit is defined in hdp_lib.h as a define
beginning with FSCAPS_. Applications can use the capabilities to
determine what action the application needs to perform. For example,
if theboard has FSCAPS_ONBOARD_YCBCR_CONV set, then it does not
need to do software conversion of a YCbCr input signal.
Parameters nBoardType The board type as returned in the report structure. For
example, HIDEF_ACCUSTREAM_170_PLUS.
Returns value The 32 bit capabilities value.

56 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

eHP_GetBoardIDString

ERRTYPE APPTYPE eHP_GetBoardIDString (BoardIDString *BoardID )

Description Returns a string to describe the particular frame grabber.

Parameters BoardID Pointer to a BoardIDStringStructure. This structure
contains the following elements:
Int nType; the type of board as found in
boardReport.bra[n].nType
char *pIDString the string to be returned. It must not
be NULL and it must point to a buffer
big enough to hold the full ID string.
Note For example if pBoardID->nType == HIDEF_ACCUSTREAM_170 then the
string returned pBoardID->pIDString = “ACCUSTREAM 170”

eHP_GetControlValue

ERRTYPE APPTYPE eHP_GetControlValue

(BoardHandle bh,
char *szControl,
size_t OutputSize,
void *pOutput)

Description Gets a value depending on the control string passed. Using control
strings rather than using a separate function for each control allows
the interface to be extended without affecting backward
compatibility.
Parameters bh Handle to the specific board.
szControl Specifies what the application would like returned.
OutputSize The size, in bytes, of the output data.
pOutput A pointer to a buffer to accept the output.
Notes There are two modes in which an application can call this function:
Mode1: In the first mode, OutputSize is set to zero and pOutput is
a pointer to a DWORD. In this case, the function
determines the output size for the control value and
returns it in pOutput.

IDEA SDK User’s Guide 57

Chapter 4:
C Function Listings

Mode2: In the second mode, OutputSize is the size of the buffer

pointed to by pOutput. In this case, the function fills
pOutput with the value of the passed-in control string.
Capitalization is not significant in the control specification.
See eHP_SetControlValue(…) for the values for szControl.

Returns 0 for success.

HPERR_BOARDFEATURE Passed-in board handle does not
refer to an I-Color.
HPERR_HANDLE Board handle is not valid.
HPERR_MEMORYLOCK Internal error and should be
reported to Foresight Imaging
Customer Service.
HPERR_NOT_IMPLEMENTED Passed-in string is not a
recognized control.
HPERR_PARAM Passed-in pOutput is NULL or the
specified size is too small for the
output.

eHP_GetInfoStruct

ERRTYPE APPTYPE eHP_GetInfoStruct ( BoardHandle bh, IDEA_INFO **pInfo )

Description Returns a pointer to the board’s internal information structure.

Parameters pInfo IDEA_INFO Data structure. Contains the following

elements:
DWORD dwSize Size of the structure.
HANDLE hInfoEvent Event handle.
Void *pInfoCallaback Pointer to a callback
function. Not used
DWORD dwInfoCode Code to explain the
event. Only one
currently implemented is
IDEA_INFO_SYNC.
DWORD dwInfoExtra Extra information about
the event.
Char szInfo[256] Text Message about the
event. Currently

58 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

supported are “Sync

valid” or “Sync lost”
BOOL bNewInfo Indicates whether the
information has changed
since the last event.
BOOL bFirstEvent Indicates whether this is
the first event fired in
this process.
Returns 0 (zero) if successful
HPERR_PARAM if the board handle is not valid.

eHP_Open

ERRTYPE APPTYPE eHP_Open ( BoardHandle bh, HP_OpenData *pod)

Description Prepares a board for use by associating it with an Open Data structure.

Parameters pod The Open Data structure. Contains the following

elements:
HP_OpenData *psParent Internal use only
(provision for nested
opens).
HPE_CALLBACK fpcbHPE Pointer to application
routine for handling
errors.
ERRTYPE eError Error code for last error
detected (or zero).
ERRTYPE eErrorList[3] Error codes for previous
three errors (or zero).
ERRTYPE eLibMax Max error # to library
message list.
FILE *fpErrSrc Application message file
(used if e>eLibMax).
Returns 0 (zero) if successful
HPERR_HANDLE

IDEA SDK User’s Guide 59

Chapter 4:
C Function Listings

eHP_RSET_FRead

ERRTYPE APPTYPE eHP_RSET_FRead (

BoardHandle bh,
char *pszCHP,
RSET *prset,
BOOLs bStrict)
Description Reads the contents of a file containing IDEA video settings data. This
routine decodes the ASCII data in the *.CHP file and performs various
syntax checking. If no errors are found, structure *prset is returned
with a binary form of the *.CHP data.

Parameters bh Handle to the specific board.

pszCHP The fully qualified path name to the CHP file.
prset Data structure where data is stored.
bStrict If TRUE, then unrecognized field names result in an error
message being reported. If FALSE, fields with
unrecognized names are ignored.
Returns 0 (zero) if successful
HPERR_CHP_HEXPT
HPERR_CHP_JUNK
HPERR_CHP_READ
HPERR_CHP_SYMBOL
HPERR_CHP_SYNTAX
HPERR_CHP_TAG

eHP_RSET_FWrite

ERRTYPE APPTYPE eHP_RSET_FWrite (

BoardHandle bh,
char *pszCHP,
RSET *prset)
Description Writes the IDEA video settings data to an ASCII file. This routine
encodes the data in the RSET structure to the ASCII *.CHP format and
writes the data, a line at a time, to the file specified by pszCHP.

Parameters bh Handle to the specific board.

pszCHP The fully qualified path name to the CHP file.
prset Data structure where data is stored.

60 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

Note Does not access the frame grabber board in any way. The first line
written by this routine is always the section identifier "[HIDEFPLUS]".
Returns HPERR_ENCODE_REG
HPERR_FILEP_PARAM

eHP_RSET_Set

ERRTYPE APPTYPE eHP_RSET_Set ( BoardHandle bh, RSET *prset)

Description Configures a frame grabber board. Data should already be loaded into
*prset with a call to eHP_RSET_FRead( ).

NOTE: This function CANNOT be used in conjunction with functions that use
image handles. If image handles have been used on the board, they must
be deallocated before this function can be used. This deallocation can be
done either individually or with a call to eHD_DeallocateAll( ).

Parameters bh Handle to the specific board.

prset Contents are used to configure the specified board.
Note Because the eHP_RSET_Fread and eHP_RSET_Set functions are
separate, the board configuration can be switched among several
configurations rapidly by reading in the configurations ahead of time
and setting them as needed.
Returns 0 (zero) if successful
HPERR_BLEVEL_RANGE
HPERR_CHANNEL_RANGE
HPERR_HANDLE
HPERR_PARAM Bad parameter.
HPERR_RSET_HBPTIME Horizontal back porch less than
minimum.
HPERR_RSET_HEND Horizontal end maximum exceeded.
HPERR_RSET_MAINSET All or none of main settings are
specified.
HPERR_RSET_NEEDMAIN Supplemental settings are specified
with no main settings.
HPERR_RSET_ODD_ILACE Interlaced signal must have even
height.
HPERR_RSET_VEND Vertical end maximum exceeded.
HPERR_RSET_ZWIDTH Zoom width exceeds maximum.
HPERR_RSET_ZHEIGHT Zoom height exceeds maximum.

IDEA SDK User’s Guide 61

Chapter 4:
C Function Listings

HPERR_RSETD_PFREQ Invalid frequency in dual pass mode.

HPERR_RSETD_HTOT Invalid HTotal in dual pass mode.
HPERR_RSETS_PFREQ Invalid frequency in single pass
mode.
HPERR_RSETS_HTOT Invalid HTotal in single pass mode.
HPERR_SETGAIN_RANGE
HPERR_USING_IHANDLES Image handles were used but not
deallocated before this function was
called. This deallocation can be
done either individually or with a
call to eHD_DeallocateAll( ). See
the note in this function’s
description.

eHP_SetBlackLevel

ERRTYPE APPTYPE eHP_SetBlackLevel (

BoardHandle bh,
short nBlackLevel)
Description Sets the Black Level.

NOTE: This function CANNOT be used in conjunction with functions that use
image handles. If image handles have been used on the board, they must
be deallocated before this function can be used. This deallocation can be
done either individually or with a call to eHD_DeallocateAll( ).

Parameters bh Handle to the specific board.

nBlackLevel This value is in terms of 1/1000 of the Gain range. A
value of 0 specifies a Black Level voltage as sampled
just after (approximately 200nsec) the start of the
Horizontal Back Porch (rising edge ending sync
pulse). Positive values increase the reference
voltage level (lighten the image) and negative values
decrease it (darken the image).
Range [-900 ... +900].
Returns 0 (zero) if successful
HPERR_BLEVEL_RANGE
HPERR_HANDLE
HPERR_USING_IHANDLES Image handles were used but not
deallocated before this function was
called. This deallocation can be
done either individually or with a

62 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

call to eHD_DeallocateAll( ). See

the note in this function’s
description.

eHP_SetChannel

ERRTYPE APPTYPE eHP_SetChannel (

BoardHandle bh,
WORD wChannel)
Description Sets the current video signal channel.

NOTE: This function CANNOT be used in conjunction with functions that use
image handles. If image handles have been used on the board, they must
be deallocated before this function can be used. This deallocation can be
done either individually or with a call to eHD_DeallocateAll( ).

Parameters bh Handle to the specific board.

wChannel Specifies which of the four analog input channels is
connected to the video source of interest.
Range [1 ... 4].
Returns 0 (zero) if successful
HPERR_CHANNEL_RANGE
HPERR_HANDLE
HPERR_SETGAIN_RANGE
HPERR_USING_IHANDLES Image handles were used but not
deallocated before this function was
called. This deallocation can be
done either individually or with a
call to eHD_DeallocateAll( ). See
the note in this function’s
description.

IDEA SDK User’s Guide 63

Chapter 4:
C Function Listings

eHP_SetControlValue

ERRTYPE APPTYPE eHP_SetControlValue

(BoardHandle bh,
char *szControl,
size_t InputSize,
void *pInput)
Description Sets a value or performs a function depending on the control string
passed. Using control strings rather than using a separate function for
each control allows the interface to be extended without affecting
backward compatibility.
Parameters bh Handle to the specific board.
szControl Specifies the name of the control.
OutputSize
pOutput
Notes There are two modes in which an application can call this function:
Mode1: In the first mode, InputSize is set to zero and pInput is a
pointer to a DWORD. In this case, the function returns the
input size for the control value at the location pointed to
by pInput.
Mode2: In the second mode, InputSize is the size of the buffer
pointed to by pInput. In this case, the function uses the
data pointed to by pInput to set the control. In some cases
there is no data required where this call causes the
function to be executed.
Capitalization is not significant in the control specification.
(See GetControlValue, SetControlValue Functions for a complete
description of each control.)
The following are the supported control strings for szControl:

ActiveMode Page 94
CameraHelpFile Page 95
CameraModes Page 95
CurrentCameraMode Page 96
ExposureDelay Page 96
ExposureDelayTime Page 96
ExposureDuration Page 96
ExposureDurationTime Page 96

64 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

ExposurePolarity Page 96
FinePhaseAdjust Page 43
ForceTrigger Page 96
ForceTriggerAll Page 97
HardReset Page 97
IcolorChannel Page 98
IntegrationFrames Page 98
IntegrationTime Page 98
IO_Line (eHP_SetControl only) Page 98
IO_Syncs Page 98
IRGBCable Page 98
IRGBLut Page 98
MonoCapture Page 98
RedGain,GreenGain,BlueGain Page 99
RedOffset,GreenOffset,BlueOffset Page 99
RetriggerDelay Page 100
RetriggerDelayTime Page 100
StrobeDelay Page 101
StrobeDelayTime Page 101
StrobeDuration Page 101
StrobeDurationTime Page 101
StrobePolarity Page 101
SyncGeneratorHPolarity Page 101
SyncGeneratorHTotal Page 101
SyncGeneratorHWidth Page 101
SyncGeneratorVPolarity Page 101
SyncGeneratorVTotal Page 101
SyncGeneratorVWidth Page 101
SyncFilter Page 101
TriggerFilterTime Page 101

IDEA SDK User’s Guide 65

Chapter 4:
C Function Listings

TriggerPolarity Page 101

TriggerState Page 101
YUVClamp Page 102
VideoFormatEx Page 164
IRGBCableList Page 98
MaximumPixels Page 103
SaturationYPbPr Page 102
SignalInfo Page 102
VideoHeaders Page 103

Returns 0 for success.

HPERR_BOARDFEATURE Passed-in board handle does not
refer to an I-Color.
HPERR_HANDLE Board handle is not valid.
HPERR_MEMORYLOCK Internal error and should be
reported to Foresight Imaging
Customer Service.
HPERR_NOT_IMPLEMENTED Passed-in string is not a
recognized control.
HPERR_PARAM Passed-in pOutput is NULL or the
specified size is too small for the
output.

eHP_SetGain

ERRTYPE APPTYPE eHP_SetGain ( BoardHandle bh, WORD wGain)

Description Sets Gain Range.

NOTE: This function CANNOT be used in conjunction with functions that use
image handles. If image handles have been used on the board, they must
be deallocated before this function can be used. This deallocation can be
done either individually or with a call to eHD_DeallocateAll( ).

Parameters bh Handle to the specific board.

wGain Specifies the millivolt range used by Black Level, Black
Reference, and White Reference. It should be no less
than the peak-to-peak voltage over the video signal
range (peak signal voltage minus pedestal voltage).

66 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

Range [600 … 2500].

Returns 0 (zero) if successful
HPERR_HANDLE
HPERR_SETGAIN_RANGE
HPERR_USING_IHANDLES Image handles were used but not
deallocated before this function was
called. This deallocation can be
done either individually or with a
call to eHD_DeallocateAll( ). See
the note in this function’s
description.

eHD_Command

ERRTYPE APPTYPE eHD_Command (

ImageHandle ih,
WORD wCommand,
HDOP_HDL *phh)
Description Executes the specified command as set up in the specified image handle.
Parameters ih Image handle where the image data resides. The image
handle was created in a call to eHD_Allocate( ).
wCommand May be any of these:
HPCMD_GRAB: Grabs an image.
HPCMD_GRAB_ON_TRIG: The function waits
to return until an
external hardware
trigger occurs. Refer
to the I-Series/
HI*DEF Installation
and User’s Guide
for information
concerning triggers.
HPCMD_IDLE: Idle.

phh Pointer to a HDOP_HDL structure which will allow the

application to perform the command asynchronously,
and receive a notification on completion of the
command.
Returns 0 (zero) if successful
HPERR_COMMAND_CODE
HPERR_COMMAND_READY

IDEA SDK User’s Guide 67

Chapter 4:
C Function Listings

HPERR_HANDLE
HPERR_TIMEOUT This is returned if the video signal
can not be captured in synchronous
mode.

eHD_Deallocate

ERRTYPE APPTYPE eHD_Deallocate (ImageHandle ih)

Description Makes a previously allocated image buffer in the frame grabber memory
available and invalidates the image handle.
Parameters ih Handle to image buffer acquired with ihHD_Allocate( ).
Returns 0 (zero) if successful
HPERR_HANDLE

eHD_DeallocateAll

ERRTYPE APPTYPE eHD_DeallocateAll (BoardHandle bh)

Description Invalidates all image handles assigned to the specified board. This
releases all use of the board’s memory and permits board-handle-based
calls to the board.
Parameters bh Handle to a specific board.
Returns 0 (zero) if successful
HPERR_HANDLE

68 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

eHD_FBFastReadPixel

ERRTYPE APPTYPE eHD_FBFastReadPixel (

ImageHandle ih,
WORD wControl,
HDOP_HDL *phh,
WORD wColumn,
WORD wLine,
short nWide,
short nHigh,
WORD *fpwBuf)
Description Transfers any rectangular section of a captured image from the image buffer in
frame grabber memory to the application buffer fpwBuf.
AccuStream: 24 or 32 bit RGB 888 pixels and 8-bit MONO pixels can be
transferred.
Parameters ih Image handle where the image data resides. The image
handle was created in a call to eHD_Allocate( ).
wControl Contains flags to specify the type of data transfer and
the disposal of the image buffer contents after the
transfer. These flags can be bitwise OR’d (|) for
combinations. They are listed here:

HDXFR_PIXEL_8, Performs an 8-bit transfer. Each pixel occupies

HDXFR_PIXEL_MONO_8, one byte.

HDXFER_YONLY_8
HDXFR_PIXEL_RGB, Performs a 32 bit transfer of RGB data with a
HDXFR_PIXEL_RGB888_32 zero fill in the alpha byte. To be compatible with
Windows bitmaps, this data is in BGR format.
Do not combine with HDXFR_PIXEL_8 or
HDXFR_PIXEL_10
HDXFR_PIXEL_RGB555_16 Performs a 16-bit transfer of RGB 555 data.
HDXFR_PIXEL_RGB565_16 Performs a 16-bit transfer of RGB 565 data.
HDXFR_PIXEL_RGB888_24 Performs a 24-bit transfer of RGB data. To be
compatible with Windows bitmaps, this data is
in BGR format.
HDXFR_PIXEL_YCBCR422_16 Performs a 16-bit transfer of the YCbCr data.
HDXFR_FGMEM_RETAIN Default.Does not allow contents of the image
buffer (in frame grabber memory) to be
destroyed. You may not want these contents to
be destroyed because they may still be
important after this transfer.

IDEA SDK User’s Guide 69

Chapter 4:
C Function Listings

phh This argument is for signaling the application on

completion of an asynchronous transfer operation.
wColumn Specifies the horizontal location in the image where
the transfer of pixels start. Column numbers are
always zero or positive and are relative to the left
edge of the image. If the entire image is being
transferred, wColumn should be zero.
Value must be a multiple of 32.
wLine Specifies the vertical location in the image where the
transfer of pixels start. Line numbers are always zero
or positive and are relative to the top edge of the
image. So if the entire image is being transferred,
wLine should be zero.
nWide Specifies the width of the rectangular area that is to
be transferred in pixels. nWide must be positive and
the sum of nWide and wColumn must not exceed the
width of the image.
Value must be a multiple of four.
nHigh Specifies the height of the rectangular area that is to
be transferred in lines. nHigh must be positive and the
sum of nHigh and wLine must not exceed the height of
the image.
fpwBuf Points to the destination area in host memory for the
transfer. For example, the application may have
created this with the call fpwBuf=(WORD
*)malloc(2*nWide*nHigh). This pointer must be DWORD
aligned.
Returns 0 (zero): Successful.
HPERR_HANDLE Parameter ih is not a valid image
handle.
HPERR_PIXEL_TYPE The board associated with image
handle ih cannot supply the requested
pixel format. For example, 32-bit
pixels cannot be produced from the I-
Series monochrome boards.
HPERR_ODD_FB_ALIGN The DMA must start on a multiple of
32 boundary and transfers four pixels
at a time. These restrictions have not
been followed.

70 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

eHD_FBHistoPixel

ERRTYPE APPTYPE eHD_FBHistoPixel(

ImageHandle ih,
WORD Control,
HDOP_HDL *phh,
WORD wColumn,
WORD wLine,
short nWide,
short nHigh,
DWORD *pdwHisto)
Description Accumulates pixel code histogram data from any rectangular section of a
captured image from the image buffer in frame grabber memory to the
application buffer fpwBuf. Either 8-bit or 10-bit pixel codes can be
histogrammed. Neither eHD_FBHistoPixel( ) nor eHP_FBHisto( ) ever initialize
(zero) the histogram array. So multiple calls can be made to these routines to
accumulate histogram data from different rectangular regions of different
images. However, the application must zero the histogram array before
making the first of these histogram calls.
Parameters ih Image handle where the image data resides. This image
handle was created in a call to eHD_Allocate( ).
wControl Contains flags to specify the type of data transfer and
the disposal of the image buffer contents after the
accumulation. These flags can be bitwise OR’d (|) for
combinations. They are listed here:
HDXFR_PIXEL_10: Default = Performs a ten-bit transfer.
Each pixel value occupies one 16-bit
word with the high-order bits zeroed.
This parameter must not be
combined with HDXFR_PIXEL_8.
HDXFR_PIXEL_8: Performs an 8-bit transfer. Each
pixel occupies one byte. This
parameter must not be
combined with HXFER_PIXEL_10.
HDXFR_PIXEL_RGB: Performs a 32 bit transfer. Each
pixel occupies 4 bytes.
HDXFR_FGMEM_RETAIN: Default = Does not allow
contents of the image buffer (in
frame grabber memory) to be
destroyed. You may not want
these contents to be destroyed
because they may still be
important after this transfer.

IDEA SDK User’s Guide 71

Chapter 4:
C Function Listings

phh This argument is for signaling the application on

completion of an asynchronous transfer operation.
wColumn Specifies the horizontal location in the image where the
transfer of pixels start. Column numbers are always
zero or positive and are relative to the left edge of the
image. If the entire image is being transferred,
wColumn should be zero.
Value must be a multiple of 32.
wLine Specifies the vertical location in the image where the
transfer of pixels start. Line numbers are always zero or
positive and are relative to the top edge of the image.
So if the entire image is being transferred, wLine should
be zero.
nWide Specifies the width of the rectangular area that is to be
transferred in pixels. nWide must be positive and the
sum nWide+wColumn must not exceed the width of the
image.
Value must be a multiple of four.
nHigh Specifies the height of the rectangular area that is to be
transferred in lines. nHigh must be positive and the sum
nHigh+wLine must not exceed the height of the image.
pdwHisto This is a pointer to an array of 256 DWORDs if 8 bit
pixels are specified or 1024 if 10 bit pixels are
specified. This array must be zeroed before the call to
this routine. See the description of parameter wControl,
value HDXFR_PIXEL_* for additional details. CAUTION:
Memory overwrites or page faults may occur if this array
is not allocated properly.
Returns 0 (zero) if successful
HPERR_FG_LINE_LIMIT
HPERR_HANDLE
HPERR_ODD_FB_ALIGN
HPERR_PIXEL_TYPE

72 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

eHD_GetStreamBuffer

ERRTYPE APPTYPE eHD_GetStreamBuffer(

ImageHandle ih,
HDVID_HEADER **pBufferHeader )

Description Retrieves the next buffer header from a live streaming operation. The
application can then use this buffer header to access the image data
and the frame number. This function is used in conjunction with
eHD_ReleaseStreamBuffer to manage buffer lists used by streaming
operations.
Parameters ih The current image handle.
pBufferHeader Pointer to buffer header pointer to be filled in by
this function.

Notes HDVID_HDEADER is defined as:

typedef struct {
DWORD dwFrameN
void *pBuffer;
DWORD dwBufferN;
} HDVID_HEADER;
where:
dwFrameN = the frame counter
pBuffer = a pointer to the most recently filled buffer
dwBufferN = an index indicating which buffer in the list was most
recently filled.
By monitoring dwFrameN, an application can tell if the frame
grabber has dropped any frames during this streaming sequence.

eHD_LiveDisplayInit

ERRTYPE APPTYPE eHD_LiveDisplayInit (

ImageHandle ih,
LIVEDISPLAY_INFO *pLiveDisplayInfo )

Description Prepares the library to display live video in a window. The frame
grabber must be capable of displaying live video, i.e. it’s an I-Series,
I-Color, I-RGB or AccuStream. Note that as of the IDEA Release 1.6,
this is the preferred method for displaying live video, as opposed to
calling LiveVideoInit()…LiveVideoMode().

Parameters ih Previously allocated image handle.

IDEA SDK User’s Guide 73

Chapter 4:
C Function Listings

pLiveDisplayInfo
Pointer to a LIVEDISPLAY_INFO structure (defined in
hdp_lib.h ) that contains information describing the video
source and destination.
Returns 0 (zero) if successful.
HPERR_HANDLE if the image handle is not valid.
HPERR_PARAM if pLiveDisplayInfo is NULL or contains invalid members.
HPERR_BOARDFEATURE if the board is an ACCURA which isn’t capable
of displaying live video.
HPERR_TIMEOUT if something is wrong with the video signal, or if no
video is connected.

Notes: As of the IDEA 1.6 release, LIVEDISPLAY_INFO is defined as follows:

typedef struct {
DWORD dwSize;
void *pDestination;
DWORD dwPitch;
BOOL bFieldUpdate;
int nDecimateX;
int nDecimateY;
int nDecimateFrames;
long hLUT;
int nTop;
int nBottom;
int nLeft;
int nRight;
int nMode;
} LIVEDISPLAY_INFO;
Where:
dwSize The size of the structure. It must be sizeof(
LIVEDISPLAY_INFO ).
pDestination A pointer to the DMA destination. This is usually
the virtual address of the DirectDraw overlay
surface.
dwPitch The pitch in bytes of the destination surface.
bFieldUpdate True if updating by fields. False if updating by
frames.
nDecimateX The number of pixels in the X direction to
decimate the image by. I-Series boards can
decimate in the X direction by 2 pixels. I-Color, I-
RGB and AccuStream can not decimate in the X
direction.
nDecimateY The number of lines to decimate in the Y
direction. All streaming boards are capable of Y
decimation.

74 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

nDecimateFrames The number of frames to skip between grabs. Set

to zero if each frame is to be displayed.
hLUT A handle to a look up table for on the fly color
conversion.
nTop, nBottom, nLeft, nRight
Rectangular coordinates of the video source for
transferring an area of interest.
nMode Internal flag indicating the current run state.
Application should leave this zeroed.

eHD_LiveDisplayMode

ERRTYPE APPTYPE eHD_LiveDisplayMode ( ImageHandle ih, int nMode )

Description Starts or stops display of live video. Note that as of the IDEA Release
1.6, this is the preferred method for displaying live video, as opposed
to calling LiveVideoInit()…LiveVideoMode().

Parameters ih Previously allocated image handle.

nMode One of :
LVM_RUN – begin live display.
LVM_TRIGGER_RUN : begin live display on a trigger signal.
LVM_SNAP : Grab and display a single frame.
LVM_PAUSE : Pause live display.
LVM_STOP : Cease live display and clean up.
LVM_TRIGGER_RUN_STOP : Begin live video display on a
trigger. Stop live display on the next trigger.
Returns 0 (zero) if successful.
HPERR_HANDLE if the image handle is not valid.
HPERR_PARAM if pLiveDisplayInfo is NULL or contains invalid members.

IDEA SDK User’s Guide 75

Chapter 4:
C Function Listings

eHD_LiveStreamInit

ERRTYPE APPTYPE eHD_LiveStreamInit (

ImageHandle ih,
LIVESTREAM_INFO *pLiveStreamInfo )

Description Prepares the library to stream live video to a series of buffers that
may then be saved in an AVI file. The frame grabber must be capable
of streaming live video. Note that as of the IDEA Release 1.6, this is
the preferred method for streaming live video, as opposed to calling
LiveVideoInit()…LiveVideoMode().

Parameters ih Previously allocated image handle.

pLiveStreamInfo
Pointer to a LIVESTREAM_INFO structure (defined in
hdp_lib.h ) that contains information describing the video
source and destination.
Returns 0 (zero) if successful.
HPERR_HANDLE if the image handle is not valid.
HPERR_PARAM if pLiveDisplayInfo is NULL or contains invalid members.
HPERR_TIMEOUT if something is wrong with the video signal, or if no
video is connected.

Notes: As of the IDEA 1.6 release, LIVESTREAM_INFO is defined as follows:

typedef struct {
DWORD dwSize;
void **pBufferList;
DWORD dwNumberOfBuffers;
int nDataType;
BOOL bDIBTarget;
int nDecimateX;
int nDecimateY;
int nDecimateFrame;
BOOL bFieldUpdate;
long hLUT;
int nTop;
int nBottom;
int nLeft;
int nRight;
int nMode;
HD_LIVEVIDEO *pLiveVideoDescriptors;
HDVID_HEADER *pVidHeaders;
HANDLE hBufferEvent;
HANDLE hStartEvent;
HANDLE hStopEvent;
HANDLE hErrorEvent;
} LIVESTREAM_INFO;
Where:

76 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

dwSize – the size of the structure. It must be sizeof( LIVEDISPLAY_INFO

).
pBufferList – a pointer to the DMA destination buffers.
dwNumberOfBuffers – The number of buffers in the buffer list.
nDataType - The destination pixel type. One of:
IDEA_TYPE_MONO_8 – 8 bit monochrome
IDEA_TYPE_YONLY_8: 8 luma bits of YCbCr.
IDEA_TYPE_YONLY_16: 16 luma bits.
IDEA_TYPE_YCBCR_16: 16 bits of YCbCr.
IDEA_TYPE_RGB_24: 24 bits of RGB 888.
IDEA_TYPE_RGB_32: 32 Bits of RGB 888 plus alpha.

bDIBTarget True if transferring to a DIB format. In this case the

data will be bottom-up. If False, then the data is
written top-down.
nDecimateX The number of pixels in the X direction to decimate
the image by. I-Series boards can decimate in the X
direction by 2 pixels. I-Color, I-RGB and AccuStream
can not decimate in the X direction.
nDecimateY The number of lines to decimate in the Y direction.
All streaming boards are capable of Y decimation.
nDecimateFrame The number of frames to skip between transfers. Set
to zero if every frame is to be captured.
BFieldUpdate If TRUE, then place fields in the buffers. If FALSE
then frames are placed in the receiving buffers.
hLUT a handle to a look up table for on the fly color
conversion.
nTop, nBottom, nLeft, nRight
rectangular coordinates of the video source for
transferring an area of interest.
nMode Internal flag indicating the current run state.
Application should leave this blank.
pLiveVideoDescriptors
Not required – should be set to 0.
pVidHeaders Pointer to structures describing the state of the
buffers.
hBufferEvent Handle to an event that will be signaled when each
buffer receives a frame of video data. May be left as
zero.

IDEA SDK User’s Guide 77

Chapter 4:
C Function Listings

hStartEvent Handle to an event that the library will signal when

the streaming commences. May be left as zero.
hStopEvent Handle to an event that the library will signal when
the streaming ceases. May be left as zero.
hErrorEvent Handle to an event that the library will signal if an
error occurs during the streaming operation. May be
left as zero.

eHD_LiveStreamMode

ERRTYPE APPTYPE eHD_StreamMode (

ImageHandle ih,
Int nMode )

Description Starts or stops streaming of live video. Note that as of the IDEA
Release 1.6, this is the preferred method for streaming live video, as
opposed to calling LiveVideoInit()…LiveVideoMode().

Parameters ih Previously allocated image handle.

nMode One of :
LVM_RUN – begin live display.
LVM_TRIGGER_RUN : begin live display on a trigger signal.
LVM_SNAP : Grab and display a single frame.
LVM_PAUSE : Pause live display.
LVM_STOP : Cease live display and clean up.
LVM_TRIGGER_RUN_STOP : Begin live video display on a
trigger. Stop live display on the next trigger.
Returns 0 (zero) if successful.
HPERR_HANDLE if the image handle is not valid.
HPERR_PARAM if pLiveDisplayInfo is NULL or contains invalid members.

eHD_ReleaseStreamBuffer

ERRTYPE APPTYPE eHD_ReleaseStreamBuffer (

ImageHandle ih,
HDVID_HEADER * pBufferHeader)

Description Releases the buffer indicated by pBufferHeader for use by streaming

operations.

78 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

Parameters ih Previously allocated image handle.

pBufferHeader Pointer to the HDVID_HEADER structure
used in the eHD_GetStreamBuffer call.
Notes If the application is streaming to a circular set of buffers, then it must
call eHD_ReleaseStreamBuffer after retrieving the data. The library
will not overwrite a valid buffer that has not been released.

eHD_LiveStreamClose

ERRTYPE APPTYPE eHD_StreamClose (

ImageHandle ih,
LIVESTREAM_INFO *pLiveInfo )

Description Cleans up internal structures after streaming live video. Note that as
of the IDEA Release 1.6, this is the preferred method for streaming
live video, as opposed to calling LiveVideoInit()…LiveVideoMode().

Parameters ih Previously allocated image handle.

pLiveInfo Pointer to the LIVESTREAM_INFO structure used in the
LiveStreamInit call.
Returns 0 (zero) if successful.
HPERR_HANDLE if the image handle is not valid.
HPERR_PARAM if the LIVESTREAM_INFO pointer is NULL or contains
invalid data.
HPERR_BOARDFEATURE if the board is note capable of streaming live
video.

eHD_RSET_Check

ERRTYPE APPTYPE eHD_RSET_Check (

BoardHandle bh,
RSET *prset,
short nMode)
Description Checks an RSET structure against mode-specific criteria.

IDEA SDK User’s Guide 79

Chapter 4:
C Function Listings

Parameters bh -1 or a Foresight board handle. If a board handle is

specified, it is used for error reporting and potentially for
determining the type of Foresight board to check the RSET
against.
prset Pointer to the register set to be checked. Also, if the Main
register subset is specified and no errors are detected,
this routine determines the appropriate pitch and/or pass
mode when these parameters are not specified explicitly.
Other unspecified values, such as VATTR, may also be
filled in where possible. However, the corresponding bits
are left zero so the fields remain unspecified.
nMode Specifies the criteria that the RSET is checked against. If
nMode is –1, then a board handle must be specified and
will be used to determine the criteria. Otherwise, this
parameter must be one of the following values ( as
defined in hdp_lib.h):
MODE_HDP_1PASS
MODE_HDP_2PASS
MODES_HDP
MODE_HD4_1PASS
MODE_HD4_2PASS
MODES_HD4
MODE_HDI25
MODE_HDI50
MODE_HDI60
MODE_HDI75
MODE_HDIRGB25
MODE_HDIRGB50
MODE_HDIRGB75
When MODES_HDP or MODES_HD4 is specified, an error is
reported only if neither single pass or dual pass can be
used.
Returns 0 (zero) Register set is valid for the specified mode or
modes.
HPERR_PARAM Bad parameter.
All HPERR_RSET*_* return values can be
returned. Refer to the Appendix for a list of
errors.

80 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

eHD_RSET_Get

ERRTYPE APPTYPE eHD_RSET_Get ( ImageHandle ih, RSET *prset)

Description Gets the RSET currently in use by an image handle.
Parameters ih Image handle.
prset Contents are used to configure the specified board.
Returns 0 (zero), successful
HPERR_HANDLE

eHD_RSET_Set

ERRTYPE APPTYPE eHD_RSET_Set (

ImageHandle ih,
RSET *prset,
WORD wControl)
Description Configures an image handle for use with Foresight board.
Parameters ih Image handle.
prset Contents are used to configure the specified board.
wControl Contains flags that specify options for the “Set”
functions. The current flags include:
HDSET_SYNCHR_OFF New channel values are
used the next time an
operation such as SET or
GRAB is issued but these
values are not set
immediately.
HDSET_SYNCHR_ON New channel values are
made ready to use the
next time a SET or GRAB
is issued. In addition, the
board will be set up using
the entire RSET for this
image handle (with the
new channel settings) so
that the board indicator
lights immediately reflect
the change and function
bHP_CSyncDetect( ) can
be used. This board set up
always completes before
returning from this
routine and persists until

IDEA SDK User’s Guide 81

Chapter 4:
C Function Listings

any other operation is

performed with the board
using this or any other
image handle.
Returns 0 (zero) Register set is valid for the specified
mode or modes.
HPERR_PARAM Bad parameter.
HPERR_RSET_HBPTIME Horizontal back porch less than
minimum.
HPERR_RSET_HEND Horizontal end maximum exceeded.
HPERR_RSET_MAINSET All or none of main settings are
specified.
HPERR_RSET_NEEDMAIN Supplemental settings are specified
with no main settings.
HPERR_RSET_ODD_ILACE Interlaced signal must have even
height.
HPERR_RSET_VEND Vertical end maximum exceeded.
HPERR_RSET_ZWIDTH Zoom width exceeds maximum.
HPERR_RSET_ZHEIGHT Zoom height exceeds maximum.
HPERR_RSETD_PFREQ Invalid frequency in dual pass mode.
HPERR_RSETD_HTOT Invalid HTotal in dual pass mode.
HPERR_RSETS_PFREQ Invalid frequency in single pass
mode.
HPERR_RSETS_HTOT Invalid HTotal in single pass mode.
HPERR_TIMEOUT If HDSET_SYNCHR_ON is set in wControl, then this
error is returned if signal is not detected on the given channel.

eHD_SetChannel

ERRTYPE APPTYPE eHD_SetChannel (

ImageHandle ih,
long lVChan,
long lCChan,
WORD wControl)
Description Changes the channel used with a specified image handle.
Parameters ih Image handle of the FG frame to be modified.
lVChan New video channel value or –1 if there is to be no
change. If a video channel is specified, it must be one of
the following:
HDCHAN_CA1

82 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

HDCHAN_CA2
HDCHAN_CA3
HDCHAN_CA4
lCChan New horizontal and vertical sync source or –1 if the sync
sources are not to be changed. Any of the HDCHAN_*
definitions may be used for this parameter.
wControl Only one bit of this is used. It may be either of two
values:
HDSET_SYNCHR_OFF New channel values are used
the next time an operation
such as SET or GRAB is issued
but these values are not set
immediately.
HDSET_SYNCHR_ON New channel values are made
ready to use the next time a
SET or GRAB is issued. In
addition, the board is set up
using the entire RSET for this
image handle (with the new
channel settings) so that the
board indicator lights
immediately reflect the
change.
Sync detection is provided
with the board by using this
control value and checking
for HPERR_TIMEOUT.
This board set up always
completes before returning
from this routine and persists
until any other operation is
performed with the board
using this or any other image
handle.
Returns 0 (zero) if successful
HPERR_CHANNEL_RANGE Channel parameter out of valid
range.
HPERR_HANDLE
HPERR_TIMEOUT If HDSET_SYNCHR_ON is set in wControl, then this
error is returned if signal is not detected on the given channel.

IDEA SDK User’s Guide 83

 Chapter 4:
C Function Listings

eHD_SetWhiteBalance

ERRTYPE APPTYPE eHD_SetWhiteBalance (

ImageHandle ih,
RSET *prset,
HD_WBALDATA *pWBD )

Description Updates the current I-RGB/AccuStream gain/offset calibration values

based on the data in the HD_WBALDATA structure. Can be used to set
new calibration values or to reset calibration to factory pre-set values.
Values are usually set through a call to eHD_TestWhiteBalance().
NOTE: This function should not be called while live video or streaming
is active.
Parameters ih Current image handle.
prset Register set to be updated.
pWBD Pointer to an HD_WBALDATA structure as defined in hdp_lib.h
that contains information about the calibration data and
control flags. If pWBD->dwMode is 0, the I-RGB/AccuStream
calibration registers are updated from the "new" values in
pWBD that were generated by eHD_TestWhiteBalance(). If
pWBD->dwMode is 1, the I-RGB/AccuStream calibration
registers are reset to the original values in pWBD that were in
use prior to calling eHD_TestWhiteBalance(). If pWBD-
>dwMode is 2, the I-RGB/AccuStream calibration registers are
reset to the factory calibration settings from the board’s
EEPROM.
Returns 0 (zero) if successful.
HPERR_PARAM if any of the input parameters are NULL pointers
HPERR_HANDLE if the board handle is not valid
HPERR_BOARDFEATURE if the board handle is not for an I-RGB or an
AccuStream.
HPERR_MEMORY_ALLOC if there is insufficient system memory

eHD_SnapToBuffer

ERRTYPE APPTYPE eHD_SnapToBuffer ( ImageHandle ih, SNAP_CONTROL *pSC )

Description Grabs a single frame of video data and transfers it to an application

buffer. Allows various levels of control as specified by the pSC
parameter. This function can be called to snap an individual frame if
displaying live video or streaming live video to a series of buffers. It
cannot be called if both types of streaming operations are already in

84 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

progress. If a completion event handle is specified in the pSC

parameter, then the function will return immediately and the
application should wait on the completion event before accessing the
data.

Parameters ih Previously allocated image handle.

pSC Pointer to a SNAP_CONTROL structure defined in
hdp_lib.h.
Returns 0 (zero) if successful.
HPERR_HANDLE if the image handle is not valid.
HPERR_PARAM if the receiving buffer pointer is NULL.
HPERR_BOARDFEATURE if the board is note capable of streaming live
video.
Notes: As of the IDEA 1.6 Release, SNAP_CONTROL is defined as:
typedef struct {
size_t stSize;
BYTE *pRecvBuf;
WORD wFormat; /* HDXFR_PIXEL_8, HDXFR_PIXEL_RGB etc.
*/
/* could also include HDXFR_YMODE_DIB,
and YSKIP */
HANDLE hCompleteEvent
int nDecimateX;
int nDecimateY;
long hLUT;
BOOL bTrigger;
int nTrigType;
ERRTYPE eRetCode;
RECT *pAOIRect;
} SNAP_CONTROL;
where:
stSize - must be sizeof( SNAP_CONTROL )
pRecvBuf – a pointer to the application buffer.
wFormat – destination pixel format. Values are one of;
HDXFR_PIXEL_8 : 8 bit monochrome data
HDXFR_PIXEL_10 : 16 bit YCbCr data.
HDXFR_PIXEL_RGB888_32: 32 bit RGB 888 data in
BGR format.
HDXFR_PIXEL_RGB888_24: 24 bit RGB data in BGR
format.
HDXFR_PIXEL_RGB555_16: 16 bit RGB 555 data.
HDXFR_PIXEL_RGB565_16: 16 bit RGB 565 data.
HDXFR_PIXEL_YONLY_8: 8 bit Y-Only data.
HDXFR_PIXEL_YCBCR422_16: 16 bit YCbCr data.
Could be Or’d with HDXR_YMODE_DIB and YSKIP.

IDEA SDK User’s Guide 85

Chapter 4:
C Function Listings

hCompleteEvent Handle to an application defined event that the

library will signal when the buffer is filled with data.
Could be left as zero.
nDecimateX Number of pixels to decimate in the X direction. Can
only be a zero or a two. Only supported for I-Series
frame grabbers.
nDecimate Number of lines to decimate in the Y direction.
hLUT Handle to a look up table for color conversion.
bTrigger True if the grab is to commence on a trigger signal.
nTriggerType – 1 Trigger on rising edge, 0 = trigger on the falling edge
eRetCode Store the error code.
pAOIRect Pointer to a rectangle for the area of interest, in
absolute coordinates.

eHD_TestWhiteBalance

ERRTYPE APPTYPE eHD_TestWhiteBalance (

ImageHandle ih,
RSET *prset,
HD_WBALDATA *pWBD )

Description Retrieves the current AccuStream white balance gain and offset
register and calibration values and calculates a new set of calibration
values based on the current gain/black level values and the video
image. Original and newly calibrated data are written to the
HD_WBALDATA structure to be passed to eHD_SetWhiteBalance(). This
function should not be called while live video or streaming is active.
Parameters ih Current image handle.
prset Register set to be updated.
pWBD Pointer to the white balance data structure. This a large
structure of internally used information. An application
must set all structure members to zero before calling
eHD_TestWhiteBalance.
Returns 0 (zero) if successful.
HPERR_PARAM if any of the input parameters are NULL pointers
HPERR_HANDLE if the board handle is not valid
HPERR_MEMORY_ALLOC if there is insufficient system memory

86 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

fine_abswait

void APPTYPE fine_abswait (FINE_TIME ft)

Description Returns at the specified date and time (or very soon thereafter -
system conditions permitting).

fine_add

pFINE_TIME APPTYPE fine_add ( pFINE_TIME pft, FINE_TIME ft)

Description Adds two millisecond time values. It is assumed that at least one of
the values is a time interval.
Returns Returns the first argument, a pointer to the result.

fine_ascii_local

char *APPTYPE fine_ascii_local ( char *cpBuff, FINE_TIME ft )

Description Converts absolute date/times or elapsed days/milliseconds to an ASCII
string:
"Mon May 8 18:56:27.226 1995\n"
The character array must be large enough to receive exactly 30 bytes
of data (including a terminating null).
Returns Returns the first argument.

fine_delta

pFINE_TIME APPTYPE fine_delta ( pFINE_TIME pft, long lDelta)

Description Adds the specified number of milliseconds (either positive or negative
- the second argument) to the time value pointed to by the first
argument.
Returns Returns the first argument (pFINE_TIME).

fine_later

pFINE_TIME APPTYPE fine_later ( pFINE_TIME pft, DWORD dwMSec)

Description Adds the specified number of milliseconds (second argument) to the
current time and stores this value in the first argument. Adjustments
are made to accommodate hardware timer limitations.

IDEA SDK User’s Guide 87

Chapter 4:
C Function Listings

Returns Returns the first argument (pFINE_TIME).

fine_now

DWORD APPTYPE fine_now (pFINE_TIME pft)

Description Stores the current date and time at the location specified in the first
argument.
Returns Returns the number of milliseconds since the last midnight.

fine_subtract

long APPTYPE fine_subtract (

pFINE_TIME,
FINE_TIME)
Description Subtracts the second argument from the value pointed to by the first
argument. FINE_TIME structures may refer to absolute date/times or
to elapsed days/milliseconds. If both arguments deal with the same
type of data (both absolute or both elapsed), the result is an elapsed
time. If the first points to an absolute time and the second is an
elapsed time, the result is an absolute time.
Returns The value returned is useful only if the result is an elapsed time. In
that case it represents the millisecond difference (either positive or
negative) between the two time values. If overflow occurs, then the
long value is pinned at the largest positive or negative value it can
hold.

fine_wait

void APPTYPE fine_wait (DWORD dwMSec)

Description Returns after waiting the specified number of milliseconds.

_HP_Error

void APPTYPE _HP_Error ( BoardHandle bh, WORD wError)

Description Declares that ERROR wError has been encountered while processing
board bh.

88 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

Parameters bh Handle to board being processed when the error was

encountered. If bh is zero, no error processing is done.
wError The number of the error condition being reported.

HP_UnClaim

void APPTYPE HP_UnClaim (BoardHandle bh)

Description Releases possible claim on a board.

Parameters bh Handle to the specific board.

Returns 0

ihHD_Allocate

ImageHandle APPTYPE ihHD_Allocate ( BoardHandle bh, WORD wCtrl, RSET *prset)

Description Allocates frame grabber memory space for a specified image format
and assigns an image handle to it.
Parameters bh The handle of the board where the images will be captured.
wCtrl This contains a flag to specify whether an attempt to
defragment frame grabber memory should be attempted.
HDAL_DEFRAG: Permit frame grabber memory
defragmentation. This is the default.
HDAL_DEFRAG_STOP: Do not defragment frame grabber
memory. The new memory allocation is restricted to
currently unused portions of frame grabber memory.
prset Pointer to an RSET structure which describes the video
format for the image. The amount of frame grabber memory
that must be allocated is determined from this structure.
Returns If successful, returns a positive value. That value is the image handle
used for capturing images and retrieving captured image data.
Otherwise it returns one of the following error codes:
HPCLAIM_ALLOC
HPCLAIM_IN_USE
HPCLAIM_NO_HDP
HPCLAIM_NO_VXD
HPCLAIM_PARAM
HPCLAIM_PITCH

IDEA SDK User’s Guide 89

Chapter 4:
C Function Listings

HPCLAIM_TOOMANY
HPCLAIM_VXD_REV

nHP_ClaimAll

short APPTYPE nHP_ClaimAll ( DWORD dw4KMem, short nMaxBoards)

Description Scans for up to 15 Foresight boards and claims ALL of them. This
preempts all claims made by bhHP_Claim( ).
Parameters dw4Kmem Obsolete parameter. Should be set to zero.
nMaxBoards Maximum number of boards should be less than of
equal to 15.
Returns Returns the number of boards found. The board handles for the newly
claimed boards are 1 through N where N is the number returned by
this routine.
If the return value is negative, it is one of the return codes listed for
bhHP_Claim( ):
HPCLAIM_NO_HDP
HPCLAIM_TOOMANY
HPCLAIM_IN_USE
HPCLAIM_ALLOC
HPCLAIM_PARAM
HPCLAIM_DOSMEM

nHP_ErrMessage

short APPTYPE nHP_ErrMessage (

ERRTYPE e,
short nSize,
char *pszEMsg )
Description Formats a string to describe the error code.

Parameters e The error code as returned from a library function.

NSize The size of the buffer being passed in.
pszEMsg The buffer to receive the formatted error message.
Note The text of the message can be found in hperror.dat.

90 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

nHP_GetBoardInfo

short APPTYPE nHP_GetBoardInfo (

BoardHandle bh,
short nFld,
short nMaxBytes,
void *pFld)
Description Retrieves specified board information.

Parameters bh Handle to the specific board.

nFld Value that specifies the information being requested.
Below are possible values:
HPEE_BOARD_REV: Foresight Imaging board
revision code.
HPEE_BOARD_TYPE: Foresight Imaging board type.
HPEE_FORMAT_REV: Library revision number
used at manufacturing
time.
HPEE_HD2_POTS: HI*DEF II emulated
Potentiometer values
(Black level & Gain).
HPEE_PARTNO: Foresight Imaging part
number.
HPEE_PHASE_ADJ: Phase adjust.
HPEE_PIXEL_BITS: Returns an integer (WORD
value) with the maximum
number of bits per pixel
that the board is capable
of.
HPEE_PORT_ASC: Returns a string in the
form: “SLOT XX”, where XX
is the ASCII-encoded PCI
slot number where the
board is located.
HPEE_PORT_BIN: Base I/O address for this
board in binary (16 bits).
HPEE_SERIAL_NO: Board serial number.
nMaxBytes Maximum number of bytes that pFld can hold including
the terminating NULL.
pFld Contains the field data left justified in a field of nulls.
Note One way of accommodating any size of data is to perform the
following sequence:

IDEA SDK User’s Guide 91

Chapter 4:
C Function Listings

1. Call nHP_GetBoardInfo with nMaxBytes equal to zero and pFld

as NULL. This does not transfer any data, but it does check for
errors and return the number of bytes it has available.
2. Allocate the array using the value returned in step 1.
3. Call nHP_GetBoardInfo( ) a second time with nMaxBytes as the
size of the newly allocated memory and pFld as a pointer to
that memory.
Returns Returns the number of bytes of data available.
Returns a -1 (minus one) if the
specified field is not available.

nHP_Report

short APPTYPE nHP_Report (

WORD wChecks,
short nRptSize,
HD_sReport *phrpt)
Description Provides a list of Foresight boards found at system start-up. This can
be called before boards are claimed or opened.
Parameters wChecks Obsolete – set to zero.
nRptSize Reports the size of HD_sReport.
phrpt Points to the HD_sReport structure:
typedef struct {
HIDEF_TYPE nType; /* Accura, I-25, etc */
unsigned short wID /* PCI slot number */
unsigned short wIO; /* Base IO address. */
char cID; /* Character ID assigned
in registry */
char cResv; /* Forcing WORD alignment */
char szSerial[8];/* ASCII Serial Number, if available
BoardHandle bh; /* Handle if claimed else
0 */
short bClaim;/* True if claimed by any process */
unsigned long dwFeatures; /* feature
capabilities of this
board. */
} HD_sBoard;
typedef struct {
unsigned long e;
unsigned short wRev;
short nBrdCount;
short nBrdList;
unsigned short w32BitDriver
unsigned long dwFragDMA;
unsigned long dwFragHisto;
HD_sBoard bra[15];
} HD_sReport;
Note See additional information on using this function and diagnostic
checking in Chapter 6 of this document.

92 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

Returns Greater than 0 (zero) Number of boards available to report.

Less than 0 (zero)Reporting failed:
HPCLAIM_NO_VXD IDEA device driver not installed.
HPCLAIM_PARAM Invalid specified parameters.
HPCLAIM_VXD_REV IDEA device
driver and DLL revisions do not
match.

eHD_GetMaxBuffers

int APPTYPE eHD_GetMaxBuffers (

ImageHandle ih,
WORD wSuggest,
WORD wPixelSize )
Description Returns an approximation of the maximum number of buffers that can
be allocated for streaming based on the image size and the amount of
memory in the system.
Parameters ih The current image handle allocated by ihHD_Allocate
wSuggest The maximum number of buffers that the application
would like to allocate.
wPixelSize The type of pixel being captured. Could
HPXFR_PIXEL_MONO_10, HDXFR_PIXEL_RGB_888_32,
HDXFR_PIXEL_RGB_888_24, etc.
Returns The number of images that will fit in approximately 80% of system
memory. This can be used as a starting point for applications that
want to allocate and lock a lot of buffers. You may not be able to lock
this number of buffer in memory for the streaming DMA operations, in
which case eHD_LiveStreamInit will fail with an error code of 661. In
this case start reducing the number of buffers until
eHD_LiveStreamInit will succeed.

GetControlValue, SetControlValue Functions

The GetControlValue and SetControlValue functions are new to the Version 1.4
Release of IDEA. Virtually all functions that are specific to I-Color, I-RGB,
AccuStream and machine vision boards are accessed through the
GetControlValue/SetControlValue function interface. As described in the previous
section, each call to GetControlValue/SetControlValue takes a board handle, a
string describing the function, a size parameter and a variable pointer which will
either pass values to the function, or receive values from the function.

IDEA SDK User’s Guide 93

Chapter 4:
C Function Listings

Many of the functions are passed a pointer to an UpdateVideoSetting or an

UpdateVideoSettingLong structure. This structure is defined as follows:
typedef struct tagUpdateVideoSetting
BYTE bValue;
RSET *pRSet;
} UpdateVideoSetting;
typedef struct tagUpdateVideoSetting {
long lValue;
RSET *pRSet;
} UpdateVideoSettingLong;

The bValue member is the actual value that you want to send or retrieve from
the function, for instance to get or set the brightness. The pRSet is a pointer to
your currently active RSET. If this pointer is not null, then the function will
update your currently active RSET to hold the new value. If the RSET member
pointer is null, then the new setting will be passed to the board, but not made
persistent. If you do not pass an RSET pointer then you will be out of sync with
the current settings and will not be able to save the values in a CHP file. This
also means that the pRSet member must either be null, or point to a valid RSET
structure or undefined behavior will result.

The following sections describe each string value that can be passed to these
functional interfaces.

ActiveMode

eHP_SetControlValue( BoardHandle, “ActiveMode”, sizeof(UpdateVideoSettingLong),

UpdateVideoSettingLong *pUVS )
eHP_GetControlValue( BoardHandle, “ActiveMode”, sizeof( UpdateVideoSettingLong ),
UpdateVideoSettingLong *pUVS )

Description This retrieves or sets the active video mode setting from the
AccuStream. This is used to determine if the incoming video is analog
or digital. In most cases, digital mode is detected automatically and
this allows an application to adjust accordingly.
The lValue member of the pUVS parameter can be an Or’d
combination of the following values:
HD_ACTIVE_INTERFACE_ANALOG
HD_ACTIVE_INTERFACE_DIGITAL
HD_ACTIVE_INTERFACE_UNSPECIFIED
HD_DIGITAL_INTERFACE_DETECTED
HD_ANALOG_SYNC_DETECTED

94 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

HD_ANALOG_VSYNC_DETECTED
HD_DIGITAL_SYNC_DETECTED

Brightness

eHP_SetControlValue( BoardHandle, “Brightness”, sizeof(UpdateVideoSetting),

UpdateVideoSetting *pUVS )
eHP_GetControlValue( BoardHandle, “Brightness”, sizeof( UpdateVideoSetting ),
UpdateVideoSetting *pUVS )

Description Adjust or retrieve the AccuStream 50a, 75a, 205a board’s standard
video section brightness. The bValue member is a linear value from 0
to 255 in which 0 is darkest and 255 is the brightest setting.

Notes AccuStream 50a, 75a, 205a only.

ClampDuration

eHP_SetControlValue( BoardHandle, “ClampDuration”, sizeof(UpdateVideoSettingLong),

UpdateVideoSettingLong *pUV )
eHP_GetControlValue( BoardHandle, “Clamp ClampDuration”, sizeof(
UpdateVideoSettingLong), UpdateVideoSettingLong *pUV )

Description Sets or retrieves the duration of the mid-scale clamp. This is useful for
component YPbPr input. For such component input, set the lValue
member of pUV to a 1 to 255.

ClampPlacement

eHP_SetControlValue( BoardHandle, “ClampPlacement”,

sizeof(UpdateVideoSettingLong), UpdateVideoSettingLong *pUV )
eHP_GetControlValue( BoardHandle, “ClampPlacement”, sizeof(
UpdateVideoSettingLong), UpdateVideoSettingLong *pUV )

Description Sets or retrieves the positioning of the mid-scale clamp. This is useful
for component YPbPr input. For such component input, set the lValue
member of pUV to a 1 yto 255.

IDEA SDK User’s Guide 95

Chapter 4:
C Function Listings

Contrast

eHP_SetControlValue( BoardHandle, “Contrast”, sizeof(UpdateVideoSetting),

UpdateVideoSetting *pUVS )
eHP_GetControlValue( BoardHandle, “Contrast”, sizeof( UpdateVideoSetting ),
UpdateVideoSetting *pUVS )

Description Adjust or retrieve the AccuStream 50a, 75a, 205a board’s contrast.
The bValue member is a linear value from 0 to 255 in which 0 is the
lowest contrast and 255 is the highest contrast setting.

Notes AccuStream 50a, 75a, 205a only.

FinePhaseAdjust

eHP_SetControlValue(BoardHandle, “FinePhaseAdjust”, sizeof(UpdateVideoSettingLong),

UpdateVideoSettingLong *pUvl)
eHP_GetControlValue(BoardHandle, “FinePhaseAdjust”,
sizeof(UpdateVideoSettingLong), UpdateVideoSettingLong *pUvl)

Description Sets the phase value of the AccuStream board. This is a true pixel
phase in 11.5° increments. Values can range from 0 to 31.

ForceTrigger

eHP_SetControlValue(BoardHandle, “ForceTrigger”, sizeof(DWORD), DWORD *pVal)

Description Simulates a hardware trigger event on an IO line. The pVal parameter

is not used and should be set to null.

96 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

ForceTriggerAll

eHP_SetControlValue(BoardHandle, “ForceTriggerAll”,sizeof(DWORD), DWORD *pVal)

Description This will simulate a hardware trigger event on all boards in a system.
This is useful when you have multiple boards attached to multiple
video sources and you want them all to snap the same frame.
This will only force triggers for boards under the control of the current
application. If multiple boards are under the control of multiple
applications, then each application will have to call ForceTriggerAll.

HardReset

eHP_SetControlValue(BoardHandle, “HardReset”, sizeof(DWORD), DWORD *pVal)

Description Resets the frame grabber and forces a re-load of the FPGA.

Notes After calling this, the board is in an unknown state, therefore you
must re-load the RSET before attempting to capture an image.

HorizontalPosition

eHP_SetControlValue(BoardHandle, “HorizontalPosition”, sizeof(UpdateVideoSetting),

UpdateVideoSetting *pVal)
eHP_GetControlValue(BoardHandle, “HorizontalPosition”, sizeof(UpdateVideoSetting),
UpdateVideoSetting *pVal )

Description Provides fine tuning of the left edge of an image.

Hue

eHP_SetControlValue( BoardHandle, “Hue”, sizeof(UpdateVideoSetting),

UpdateVideoSetting *pUVS )
eHP_GetControlValue( BoardHandle, “Hue”, sizeof( UpdateVideoSetting ),
UpdateVideoSetting *pUVS )

IDEA SDK User’s Guide 97

Chapter 4:
C Function Listings

Description Adjust or retrieve the AccuStream 50a, 75a, 205a board’s hue. The
bValue member is a linear value from 0 to 255. These values cover the
range from -180° to +178.59°. “Normal” hue is a value of about 127.

Notes AccuStream 50a, 75a, 205a only.

IRGBCable

eHP_SetControlValue(BoardHandle, “IRGBCable”, sizeof(UpdateVideoSettingLong),

UpdateVideoSettingLong *pVal)
eHP_GetControlValue(BoardHandle, “IRGBCable”, sizeof(UpdateVideoSettingLong),
UpdateVideoSettingLong *pVal )

Description This sets the sync configuration for an AccuStream board for the
particular input cable type. The lValue member of the
UpdateVideoSettingLong member contains a value that will specify the
cable type as follows:
0 = DVI to BNC
1 = DVI to VGA
2 = DVI to DVI
Normally, an application will not have to alter this control setting
since it is initialized by the library according to the CABLE value in the
I-RGB section of the CHP file.

MonoCapture

eHP_GetControlValue( BoardHandle, “MonoCapture”, sizeof(UpdateVideoSettingLong),

UpdateVideoSettingLong *pUV )

Description Retrieves a flag to indicate if the AccuStream is capturing

monochrome video on one of its red, green, or blue channels.
The lValue member of pUV is returned as 1 (one) if the board is
capturing monochrome data, 0 (zero) if it is capturing RGB data.

98 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

RedGain,GreenGain,BlueGain

eHP_SetControlValue(BoardHandle, “RedGain”, sizeof(UpdateVideoSettingLong),

UpdateVideoSettingLong*pVal)
eHP_SetControlValue(BoardHandle, “GreenGain”, sizeof(UpdateVideoSettingLong),
UpdateVideoSettingLong*pVal)
eHP_SetControlValue(BoardHandle, “BlueGain”, sizeof(UpdateVideoSettingLong),
UpdateVideoSettingLong*pVal)

eHP_GetControlValue(BoardHandle, “RedGain”, sizeof(UpdateVideoSettingLong),

UpdateVideoSettingLong*pVal )
eHP_GetControlValue(BoardHandle, “GreenGain”, sizeof(UpdateVideoSettingLong),
UpdateVideoSettingLong*pVal )
eHP_GetControlValue(BoardHandle, “BlueGain”, sizeof(UpdateVideoSettingLong),
UpdateVideoSettingLong*pVal )

Description Provides fine tuning of the gain calibration value for each of the
channels. The lValue member of the UpdateVideoSettingLong contains
a value of 0-255 that gets scaled internally by the library.

RedOffset,GreenOffset,BlueOffset

eHP_SetControlValue(BoardHandle, “RedOffset”, sizeof(UpdateVideoSettingLong),

UpdateVideoSettingLong *pVal)
eHP_SetControlValue(BoardHandle, “GreenOffset”, sizeof(UpdateVideoSettingLong),
UpdateVideoSettingLong *pVal)
eHP_SetControlValue(BoardHandle, “BlueOffset”, sizeof(UpdateVideoSettingLong),
UpdateVideoSettingLong *pVal)

eHP_GetControlValue(BoardHandle, “RedOffset”, sizeof(UpdateVideoSettingLong),

UpdateVideoSettingLong *pVal )
eHP_GetControlValue(BoardHandle, “GreenOffset”, sizeof(UpdateVideoSettingLong),
UpdateVideoSettingLong *pVal )
eHP_GetControlValue(BoardHandle, “BlueOffset”, sizeof(UpdateVideoSettingLong),
UpdateVideoSettingLong *pVal )

Description Provides fine tuning of the offset calibration value for each of the
channels. The lValue member of the UpdateVideoSettingLong contains
a value of 0 to 255 that gets scaled internally by the library.

IDEA SDK User’s Guide 99

Chapter 4:
C Function Listings

RetriggerDelay

eHP_SetControlValue(BoardHandle, “ReTriggerDelay”, sizeof(DWORD), DWORD *pVal)

eHP_GetControlValue(BoardHandle, “ReTriggerDelay”,sizeof(DWORD),DWORD *pVal )

Description Adjust or retrieve the time that the machine vision board will not
detect another trigger after one has already been detected. This time
commences at the end of the trigger pulse. The time is measured in
12.8 microsecond increments. The formula is:
Retrigger delay = Value written to this register x 12.8 microseconds.

RetriggerDelayTime

eHP_SetControlValue(BoardHandle, “ReTriggerDelayTime”, sizeof(DWORD), DWORD

*pVal)
eHP_GetControlValue(BoardHandle, “ReTriggerDelayTime”,sizeof(DWORD),DWORD *pVal
)

Description Adjust or retrieve the time that the machine vision board will
not detect another trigger after one has already been detected. This time
commences at the end of the trigger pulse. The time is in microseconds.

Saturation

eHP_SetControlValue( BoardHandle, “Saturation”, sizeof(UpdateVideoSetting),

UpdateVideoSetting *pUVS )
eHP_GetControlValue( BoardHandle, “Saturation”, sizeof( UpdateVideoSetting ),
UpdateVideoSetting *pUVS )

Description Adjust or retrieve the AccuStream 50a, 75a, 205a board’s saturation.
The bValue member is a linear value from 0 to 255 in which 0 is the
lowest saturation and 255 is the highest saturation setting.

Notes AccuStream 50a, 75a, 205a only.

100 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings

SyncFilter

eHP_SetControlValue(BoardHandle, “SyncFilter”, sizeof(UpdateVideoSetting),

UpdateVideoSetting *pVal)
eHP_GetControlValue(BoardHandle, “SyncFilter”, sizeof(UpdateVideoSetting),
UpdateVideoSetting *pVal )

Description The bValue member of the UpdateVideoSetting parameter will either

turn the sync filter on if it’s a 1 or off it’s a zero. This is only effective
on boards with an Actel revision of 5 or greater.

TriggerFilterTime

eHP_SetControlValue(BoardHandle, “TriggerFilterTime”, sizeof(DWORD), DWORD *pVal)

eHP_GetControlValue(BoardHandle, “TriggerFilterTime”,sizeof(DWORD),DWORD *pVal )

Description Adjust or retrieve the time in which the circuitry will recognize a
trigger edge. The granularity is in microseconds.

Notes This is useful for filtering false edges if the trigger circuitry contains a
bounce.

TriggerState

eHP_SetControlValue(BoardHandle, “TriggerState”, sizeof(DWORD), DWORD *pVal)

eHP_GetControlValue(BoardHandle, “TriggerState”, sizeof(DWORD), DWORD *pVal )

Description Retrieves the current state of the trigger input. Returns a 1 for a high
level, and a zero for a low level.

Notes This is a “get” only control.

IDEA SDK User’s Guide 101

Chapter 4:
C Function Listings

YUVClamp

eHP_SetControlValue( BoardHandle, “YUVClamp”, sizeof(UpdateVideoSettingLong),

UpdateVideoSettingLong *pUV )
eHP_GetControlValue( BoardHandle, “YUVClamp”, sizeof(UpdateVideoSettingLong),
UpdateVideoSettingLong *pUV)

Description Sets or retrieves a flag controlling how the A/D converter on the
AccuStream sets its mid-scale clamp. This is useful for component
YPbPr input. For such component input, set the lValue member of pUV
to a 1. Note that the application will have to convert the resulting
YPrPb values to RGB for display.

SaturationYPbPr

eHP_SetControlValue( BoardHandle, “SaturationYPbPr”,

sizeof(UpdateVideoSettingLong), UpdateVideoSettingLong *pUV)
eHP_GetControlValue( BoardHandle, “VideoFormat”, sizeof(UpdateVideoSettingLong),
UpdateVideoSettingLong *pUVL)

Description Sets or retrieves the saturation value when capturing YPbPr video
signals.

Signalinfo

eHP_SetControlValue( BoardHandle, “Signalinfo”, sizeof(SIGNAL_INFO), SIGNAL_INFO

*pSignalinfo)
eHP_GetControlValue( BoardHandle, “Signalinfo”, sizeof(SIGNAL_INFO), SIGNAL_INFO
*pSignalInfo)

Description Retrieves information about the current input video signal.

SIGNAL_INFO is defined as:
typedef struct {
DWORD dwInfoSize;
DWORD dwChannel;
BOOL bChannelValid;
BOOL bSyncValid;
BOOL bDigital;
BOOL bInterlaced;
BOOL bPositiveHSync;
BOOL bPositiveVSync;
DWORD dwSyncChannel;
DWORD dwMaxLines;
DWORD dwHFreq;

102 IDEA SDK User’s Guide

 Chapter 4:
C Function Listings
DWORD dwVFreq;
DWORD dwPFreq;
DWORD dwHTotal;
DWORD dwVTotal;
DWORD dwWidth;
DWORD dwHeight;
} SIGNAL_INFO;

You should initialize all structure elements to zero except dwInfoSize,

which should be set to the size of the structure and dwChannel which
should be set to the input video channel.

VideoHeaders

eHP_GetControlValue( BoardHandle, “VideoHeaders”, sizeof(VideoHeaderList),

VideoHeaderList *pVL)

Description Retrieves the list of video headers created by the library in the call to
eHD_LiveStreamInit. By retrieving these headers, the application can
poll them to determine if a frame of video has been captured during a
streaming operation. This can be used instead of waiting for a frame-
ready event.
VideoHeaderList is defined as :

typedef struct tagVideoHeaderList {

int nNumHeaders;
HDVID_HEADER *pHeaders;
} VideoHeaderList;

MaximumPixels

eHP_GetControlValue( BoardHandle, “MaximumPixels”, sizeof(long), long*pMP)

Description Returns the maximum number of pixels supported by the board.

Usually, this will be 4 million, but for certain high-frequency signals,
this will be reduced to 2 million.

IRGBCableList

eHP_GetControlValue( BoardHandle, “IRGBCableList”, sizeof(FsiCableList), FsiCableList

*pCL)

IDEA SDK User’s Guide 103

Chapter 4:
C Function Listings

Description Returns a list of the supported cable types. An application can use this
if implementing its own version of Auto-SYNC and needs to present a
list of cable types to the user.
FSICableList is defined as:
typedef struct tagFsiCableList {
int iNumEntries;
char **pList;
} FsiCableList;
Where iNumEntries will contain the number of entries in the list. Then
each pList[i] is a pointer to a zero terminated string for the cable
type.

SoftReset

eHP_SetControlValue( BoardHandle, “SoftReset”, sizeof(DWORD), DWORD *pdw)

Description Performs a soft reset on the board. This merely clears the FIFO in the
PCI interface as a fast means of returning the board to a stable state.
This may be necessary if the video signal has become unstable during
a streaming or live display operation. This is much faster than the hard
reset which causes the boards FPGA to be reloaded and requires a
complete re-initialization of the board’s register set.

104 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

CHAPTER 5:
ActiveX Function Listings
This chapter describes three IDEA ActiveX controls: IdeaBoardInfo, IdeaFG and
IdeaDisplay. These are contained in IdeaCtls.ocx and are registered during the
installation program.
The ActiveX controls offer an easier-to-use, higher-level interface than direct
calls to the IDEA API. By using the ActiveX control, many common, but
complicated, operations are reduced to simple, language-independent method
calls.
If you have an existing application that used earlier versions of the IDEA
ActiveX control, you may wish to skip right to the migration sections at the end
of this chapter, in order to get your application running with the new version
first.

Using the Controls in an Application

Before you can use a control, you must first make them available to the
application. The exact method for how to do this depends on your programming
environment. The current release of IDEA no longer supports Visual C++ 6.0.
When using Visual Studio 2005 to import the ActiveX Control into a VB.NET
application peform the following steps in a command-prompt window:
1. If not already registered, enter:
Regsvr32 ideactls.ocx
2. Using the correct 32- or 64-bit version of aximp from the .NET SDK,
enter:
aximp ideactls.ocx
3. Enter:
regtlib ideactls.ocx

From inside Visual Studio 2005 for the application project:

1. Select Project|Add Reference.
2. From the COM tab select idea ActiveX Control Module.
3. From the Browse tab, go to the ..\idea\ActiveX folder and select
AxIdeaCTLSLib.dll.

IDEA SDK User’s Guide 105

Chapter 5:
ActiveX Function Listings

1. Select IdeaFG Control or IdeaBoardInfo Control. Choose the IdeaBoardInfo

Control if you only need information about the board but will not be using
its frame grabber features; otherwise choose the IdeaFG Control.
2. Optional: Select IdeaDisplay Control. Select this only if you want automatic
display of images.
MFC: When asked Insert this component?, click OK.
Icons for the 3 controls should now be available in your component gallery.
You may select them for use graphically, or you can utilize the classes that
MFC/ VB.NET creates to support them.

To update the ActiveX controls from a previous version, the procedure depends
on whether the interface has changed. If the interface has not changed, then
the new ActiveX controls need only be installed and registered. If the interface
has changed, then the applications using them must be rebuilt with the new
ActiveX controls.
Normally the interface will only change for a major release, not a point
release. The release notes will warn if, when, and how any changes are made
to the interface. While it is recognized that it is important to maintain stability
as much as possible, it is also important to continue to deliver new features
and technologies as they evolve.
For Visual Basic, simply recompile and re-make the .EXE executable if there is
one. That is all there is to do.
For MFC, delete any of these files, if they are in your project: ideadisplay.cpp,
ideadisplay.h, ideafg.cpp, ideafg.h, ideaboardinfo.cpp, and ideaboardinfo.h.
These are wrapper files and they will be regenerated when you re-import the
control(s). Delete them from both the project files list in Visual Studio and
from the project folder.
Next, re-import the ActiveX controls by following the same steps outlined
above for importing them the first time, then rebuild the application. If the
“CPicture” class appears during step 3, uncheck the checkbox for it because it
should not be re-imported.

Definitions
The definitions of some terms used in the ActiveX control interface are given
below:
sequencing Generating a lot of images, successive grabs

106 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

streaming Generating a lot of images, at real-time speeds

live Displaying video at real-time rates (e.g., "live
video" or "live display")
preview Displaying video at the same time as streaming
TV board Frame grabber board designed for specific
video formats like NTSC, PAL, and SECAM (e.g.,
I-Color)
This leads to compound descriptions like "streaming to AVI" or "streaming to
memory" or "streaming to AVI with preview enabled".
These names form the roots of some of the member function names.

Include Files
There are several files located in the \Foresight\Idea\Include directory that
may be helpful for writing applications that use the ActiveX controls.
IdeaOCX.bas, which may be added to Visual Basic projects, and IdeaOCX.h,
which may be #included in Visual C++ source files both contain definitions of
some important constants, enumerations, etc. that are used in the properties
and methods of the ActiveX controls. Also, Hdp_Lib.h and Hdp_Lib.bas are
located in that directory which contain many definitions for the IDEA Library
API, many of which are also used by the properties and methods of the ActiveX
controls.
For MFC, you will need to create an EVENTSINK_MAP in order to use events.
There is a template for one of these with instructions in the IdeaOCX.h header
file for you to copy and paste into your application.

Programmer’s Guide
This section details topics for using the IDEA ActiveX controls. These are how-to
tutorials for quickly writing code to perform basic operations using the IDEA
ActiveX Controls.
The controls are designed so that the most general operations such as snapping
and displaying, snapping and saving, streaming, live display, and so on, may be
programmed very quickly and with very little code, but while still providing the
full capabilities of all of the most common features. Initialization can be as
simple as calling the “Open” method. Snapping can be as easy as calling the
“Snap” method.
For example, the Visual Basic sample application for snapping and displaying an
image contains a trivially simple form and less than twenty lines of code. Yet,
it still supports multiple boards, multiple channels, triggering, brightness and

IDEA SDK User’s Guide 107

Chapter 5:
ActiveX Function Listings

contrast adjustments, decimation, automatic resizing, and so on by using the

built-in dialogs and relying on the ActiveX controls to do most of the work.
Even so, the controls also have methods, properties, and events available for
an enormous number of different situations so that they can be as flexible as
possible for the needs of many different types of applications.
An unfortunate result of this is that there are around 300 methods, properties,
and events which is a lot to have to look through. Therefore, a major goal of
this guide is to organize them to aid the developer in sorting out which of these
he or she can use to accomplish particular operations.
Use this guide in conjunction with the sample source code supplied in the
\Idea\Samples folder that is in the IDEA installation, and the demos in the
\Idea\Demo folder. Also, there is a programmer’s reference for each control
following this guide, with detailed specifications for every supported method,
property, and event in the ActiveX controls.
Most of the topics in this guide pertain to the use of the IdeaFG control, but
some also involve using the IdeaDisplay control to display the snapped images
or live video. The following categories of operations are described:

• Board selection and information

• Initialization and error reporting
• Video settings
• Configuration and data persistence
• Snapping and displaying images
• Retrieving and saving snapped images
• Live display
• Streaming

Board Selection and Information

Multiple Boards
When the IdeaFG control is first instantiated, it chooses by default the first
board it finds to be the currently selected board to be used. Normally, the
default is acceptable and the end-user may choose a board from the
Configuration Dialog.

108 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

However, if multiple boards are installed, the application may at that time
select a board prior to initializing the control (see Preselecting a Board below).
IdeaFG identifies boards by an index (the “CurrentBoardIndex” property) which
is an integer between zero and the number of installed boards (the
“BoardCount” property) minus one, inclusive.
Preselecting a Board (Multiple Boards)
If the application knows the index of the board it wants to select, it may simply
set the “CurrentBoardIndex” property to that value.
If the application knows the serial number of the board it wants to select, it
can get the index of that board by passing the serial number (a character
string) to the “GetIndex” method.
The application may also choose a board of a particular type by examining the
“NthBoardType” property for each board index from zero up to the number of
boards given by the “BoardCount” property minus one.
To let the end-user select a board prior to initialization, the application may
display a built-in dialog for doing this by calling the
“ShowBoardSelectionDialog” method. After this modal dialog returns, the
“CurrentBoardIndex” property will be already set to the user-selected board.
Custom Board Preselection (Multiple Boards)
The application may also create its own board selection dialog and populate a
list of boards from which to choose, by using information from the
“BoardCount”, “NthBoardDescription”, “NthBoardType”,
“NthBoardTypeString”, and “NthSerialNumber” properties.
User-Defined Board Names
The Board Selection Dialog, described above, has a “User-Defined Names”
button. This option will bring up another dialog that allows the user to choose a
(character string) description for the board that gets stored in the
“NthUserDefinedBoardName” property for that board’s index.
To hide this button, pass the BOARD_SELECTION_NO_NAMES flag to the
“ShowBoardSelectionDialog” method.
The Configuration Dialog also has a “User-Defined Names” button. To hide this
button, pass the CONFIG_DIALOG_NO_NAMES flag to the “ShowConfigDialog”
method.
To set a user-defined board name from the application, pass it as an ordinary
character string to the “NthUserDefinedBoardName” property for that board’s
index.

IDEA SDK User’s Guide 109

Chapter 5:
ActiveX Function Listings

To retrieve a descriptive character string for display purposes that includes the
board type, serial number, and any user-defined name, use the
“NthBoardDescription” property for that board’s index.
About Box and Copyright Information
The application may display a modeless “About” dialog box by calling the
“AboutBox” method.
The application may retrieve copyright information as a multiline string from
the “CopyrightNotices” property.
List of Board Information Methods and Properties
A number of methods and properties are available for selecting and obtaining
information about the boards currently installed on the system. Unlike most of
the methods and properties in the IdeaFG control, all of these are allowed to
be called even before initializing. They are listed below.

110 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Board Selection and Information

Methods IsColorBoard Page 182

IsMonoBoard Page 183
IsTVBoard Page 184
IsRGBBoard Page 183
IsDigitalBoard Page 183
IsStreamingBoard Page 183
IsHighSpeedRGBBoard Page 183
GetIndex Page 173
ShowBoardSelectionDialog Page 199
ShowUserDefinedBoardNamesDialog Page 202
AboutBox Page 164
Is64BitBoard Page 184
Properties CurrentBoardIndex Page 146
DefaultBoardIndex Page 148
BoardCount Page 141
BoardLocation Page 142
BoardType Page 168
BoardTypeString Page 168
SerialNumber Page 156
NthBoardDescription Page 152
NthBoardType Page 175
NthSerialNumber Page 175
NthBoardTypeString Page 175
NthUserDefinedBoardName Page 153
CopyrightNotices Page 145

IDEA SDK User’s Guide 111

Chapter 5:
ActiveX Function Listings

Initialization and Error Reporting

Initializing the IdeaFG Control

In the simplest case, assuming that IdeaFG is managing its own configuration
settings, the application only needs to call the “Open” method to initialize.
The first time it is run, the Open will not put the control into a fully initialized
state, because no CHP file has been identified. The end-user can then bring up
the Configuration Dialog (described below in the Settings section), select a
board to use, and set the CHP file(s) and other options such as the output pixel
type, triggering, etc. Setting the CHP file will cause the control to
automatically reopen into a fully initialized state.
On subsequent runs, with the settings (esp. the CHP file path) saved, the Open
call will always fully initialize the control; and it will be immediately ready to
snap, stream, display live video, etc.
After IdeaFG is opened, the application may call the “IsVideoDetected” method
to determine if it can proceed with video capture.
If the application is to manage its own settings, see the discussion of this topic
under the Settings section below. Detailed instructions are provided there.
Initializing the IdeaDisplay Control with IdeaFG
First, call the “SetDisplayWindow” method of the IdeaFG control, and pass it
the handle to the IdeaDisplay control (from the “hWnd” property of
IdeaDisplay).
Next, call the “SetImageHandle” property of the IdeaDisplay control, and pass
it the board’s image handle (from the “GetImageHandle” method of IdeaFG).
Finally, you may need to size the window for display. The “GetSnapWidth”,
“GetSnapHeight”, “GetLiveWidth”, and “GetLiveHeight” methods of IdeaFG
are useful for those calculations. Alternatively, the IdeaDisplay window may be
used as a fixed-size window. The application may choose whether or not to
have the image automatically scaled by IdeaDisplay to fit the window, using
IdeaDisplay’s “FitToSize” property.
Calling the IDEA Native Library
Many functions in the IDEA Native Library API may be called from an application
while it is using the IdeaFG control. These functions usually require either a
board handle or an image handle. After the IdeaFG control has been initialized,
they may be retrieved from the “BoardHandle” property and the
“GetImageHandle” method.

112 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

For functions requiring an RSET, one may be obtained by calling the

eHD_RSET_Get( ) library API function and passing it the Image Handle.
For VB, functions in the IDEA Native Library API may be wrapped using the
“Public Declare Function …” syntax and then called from the application. See
the Microsoft Visual Basic Documentation for details.
Using Suspend Mode to Call the IDEA Tools Library
Like the IDEA Native Library, the IDEA Tools Library API may also be called from
an application while it is using the IdeaFG control. These functions usually
require a board handle. However, for these functions, the IdeaFG control must
be put into “suspend mode”; and cannot perform snaps, streaming, live
display, VESA detection, etc. while in this mode. Setting suspend mode will
halt any such ongoing operations as would a call to the Close method.
To put IdeaFG into suspend mode, set the SuspendMode property equal to 1.
Doing this is equivalent to calling the Close method, but it leaves the currently
selected board claimed. As above, the board handle may be retrieved from the
BoardHandle property to pass to library functions.
While IdeaFG is in suspend mode, the application may call functions in the IDEA
Tools Library, or any IDEA Native Library functions that require a board handle
but do not allow, for example, an image handle to be allocated at the time.
After calling these functions, set the SuspendMode property equal to 0. This is
equivalent to calling the Open method, but where IdeaFG assumes that the
board is already claimed.
The IDEA Audio-Video (C++) demo contains an example of the use of suspend
mode to call the IDEA Tools Library to perform some AutoSYNC functions.
Error Reporting
The level of error reporting for the IdeaFG control may be set using the
“Verbosity” property. Set this property to VERBOSITY_SILENT to disallow all
popup messages, dialogs, etc. Set it to VERBOSITY_DIALOGS to show dialogs
only, and only when the methods to display those dialogs are called. Set it to
VERBOSITY_ERRORS to show dialogs and error messages. Set it to
VERBOSITY_WARNINGS to also show warning messages. Set it to
VERBOSITY_INFO to show everything, including diagnostic information.
Use the “MessageCaption” property (character string) to set the title bar in
popup messages displayed by the IdeaFG control.
The “LastError” property (short integer) will return the error code from the
last failed operation, if any. Pass this value to the “GetErrorText” method to
retrieve the user-friendly text (character string) for this error code.
Information Notification Message Events

IDEA SDK User’s Guide 113

Chapter 5:
ActiveX Function Listings

The IdeaFG control uses the “OnNotificationMessage” event to convey

information to the application. This information may include errors, warnings,
or specific notifications that might be relevant to the application. The event
supplies two parameters: a message code and a message parameter (that is
specific to each message code).
The application can create an event handler that processes certain message
codes that it is interested in, and ignores the rest. Future versions of the
IdeaFG control may always add new message codes and message parameters
without changing its interface or requiring the application to have more event
handlers.
Hard Reset
The IdeaFG control provides a “HardReset” method and a “Hard Reset” button
on the Configuration Dialog (described below in the Settings section). The hard
reset, if supported on the board, will fully reinitialize the board as if the
system had been power cycled. The situation in which a hard reset might be
used is only in the case of a rare, transient problem, perhaps with the video
source, from which the board cannot recover. Then the hard reset is preferable
over power cycling the whole system.

Initialization and Error Reporting

Methods Open Page 185

Close Page 165
GetImageHandle Page 172
IsVideoDetected Page 184
ResetBoard Page 187
ResetBoardFast Page 187
GetErrorText Page 169
Properties BoardHandle Page 142
SuspendMode Page 158
Verbosity Page 162
MessageCaption Page 152
LastError Page 152
Events OnNotificationMessage Page 210

114 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Video Settings

Common Hardware Profile (CHP) files

Chapter 3 describes the Common Hardware Profile (CHP) file which contains
the information detailing the video source, calibration, cabling, etc. for a
particular channel on a particular board. CHP files are created by the IDEA
Auto-SYNC application and the IDEA Tools API which is described in Chapter 6.
Here, we refer to the information in the CHP files as “video settings” (and
“control settings” for machine vision).
Adjusting Video Settings
The IdeaFG control has methods and properties for retrieving and modifying
video settings programmatically at run-time, as well as an end-user dialog for
changing certain settings such as brightness and contrast. This dialog is
modeless and so can be used, for example, in between snaps or while running
live display, for instant feedback on the changes being made. The Video
Settings dialog may be displayed by calling the “ShowVideoAdjustments”
method.
Saving Video Settings
Changes to video settings will persist only while the current instance is still
running, unless explicitly saved back to the CHP file by clicking the “Save”
button on the dialog, or by calling the “SaveVideoSettings” method.
VESA detection
The IdeaFG control also has a feature called VESA detection for I-RGB and
AccuStream boards connected to standard VESA mode sources (i.e., most
computer display cards). It runs much faster than Auto-SYNC and automatically
produces a CHP file that is ready to use. When finished running VESA detection,
IdeaFG is ready to snap, stream, display live, etc. VESA detection can be run by
pressing the “VESA Detect….” button on the Configuration Dialog or by calling
the “ShowVesaDetectDialog” method.
Automatic Signal Detection
The IdeaFG control also has a feature called Automatic Signal Detection for
high-speed I-RGB and AccuStream boards (I-RGB 165 and higher) which, if
selected using the “AutoSignalDetection” property, will run VESA detection
silently and automatically when detecting a loss of sync/reacquiring of sync (as
occurs when unplugging the cable from one computer and replugging it into
another).
List of Methods and Properties

IDEA SDK User’s Guide 115

Chapter 5:
ActiveX Function Listings

The following table lists the methods and properties of the IdeaFG control that
can be used for retrieving and modifying video settings. There is also a
separate table listing the control settings used on our machine vision boards.

Video Adjustments Settings

Methods ShowVideoAdjustments Page 203

ShowVesaDetectDialog Page 202
ShowIRGBCableTypeDialog Page 201
GetNumberOfCableTypesIRGB Page 176
GetCableTypeListIRGB Page 169
WhiteBalance Page 207
SaveVideoSettings Page 189
GetImageSizeInBytes Page 173
GetImageWidth Page 173
SetImageWidth Page 192
GetImageHeight Page 172
SetImageHeight Page 192
GetBlackLevel Page 167
SetBlackLevel Page 189
GetBlackReference Page 167
SetBlackReference Page 189
GetGain Page 169
SetGain Page 190
GetHorzBackPorch Page 170
SetHorzBackPorch Page 191
GetHorzBackSync Page 170
SetHorzBackSync Page 191
GetHorzFrequency Page 171
SetHorzFrequency Page 191
GetHorzStart Page 171

116 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

SetHorzStart Page 191

GetHorzTotal Page 171
SetHorzTotal Page 192
GetHorzSyncWidth Page 171
SetHorzSyncWidth Page 192
GetInterlace Page 173
SetInterlace Page 193
GetPassMode Page 176
SetPassMode Page 196
GetPhaseDelay Page 176
SetPhaseDelay Page 196
GetPitch Page 177
SetPitch Page 196
GetVertBackPorch Page 180
SetVertBackPorch Page 197
GetVertStart Page 180
SetVertStart Page 197
GetVertSyncType Page 180
SetVertSyncType Page 197
GetVertTotal Page 181
SetVertTotal Page 197
GetWhiteReference Page 181
SetWhiteReference Page 198
GetHorizontalPosition Page 170
SetHorizontalPosition Page 190
GetOutputFormat Page 176
SetOutputFormat Page 196
GetVideoFormat Page 181
SetVideoFormat Page 198
IsYPbPrInput Page 184

IDEA SDK User’s Guide 117

Chapter 5:
ActiveX Function Listings

Properties DigitalMode Page 148

AutoSignalDetection Page 139
VesaChpPath Page 163
CableTypeIRGB Page 143
CableTypeIndexIRGB Page 143
DefaultCableTypeIRGB Page 148

Configuration and Data Persistence

Managing Configuration Settings Using the IdeaFG Control

One of the features of the IdeaFG control is that it will manage configuration
settings, both its own and the calling application's values. These are settings
such as the CHP file pathnames, the currently selected board’s index, the pixel
type, the AVI file path for streaming, etc.
Note that, with the exception of the video and sync channels, the IdeaFG
control’s configuration settings are distinct from the video settings described
above that are stored in the CHP files.
The IdeaFG control provides user dialogs for setting the known values, as well
as methods and properties for setting known and custom values
programmatically. It uses the Windows registry for persistence.
The fastest and easiest way to write an application that takes advantage of the
full capabilities of the IdeaFG control is to let IdeaFG manage the configuration
settings and have the application’s user interface call the “ShowConfigDialog”
method to display the Configuration Dialog that is built into IdeaFG.
Anatomy of the Configuration Dialog
The Configuration Dialog is a property sheet with six property pages: Video,
Input Source, Live, Snaps, Streaming, and About. The Video page is for
selection of the board, output pixel type, and certain board options; and it
displays useful information about the currently selected board.
The Input Source page is for selecting the default channel and the CHP file to
be used for each channel on the board. For I-RGB and AccuStream boards, VESA
detection may be run from this page; and there is a checkbox for the
Automatic Signal Detection feature on the high-speed boards.

118 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

The Live page is for setting options that only pertain to live display. The Snaps
page is for setting options that only pertain to snaps; and the Streaming page is
for setting options that only pertain to streaming. There is also an About page,
which contains version, system, support, and copyright information.
The application may wish to suppress certain features, either to make the
dialog simpler or to prevent the end-user from having access to those features.
An application which does not do snaps or sequential snaps may specify the
“CONFIG_DIALOG_NO_SNAPS” flag in the Flags parameter to the
“ShowConfigDialog” method. An application which does not do streaming may
specify the “CONFIG_DIALOG_NO_STREAMING” flag. An application which
streams but does not stream to DICOM may specify the
“CONFIG_DIALOG_NO_DICOM” flag. An application which does not do live
display may specify “CONFIG_DIALOG_NO_LIVE”.
The Configuration Dialog only displays options that are possible at that time.
For example, if the “Enable Audio” checkbox is not checked, all the other
options for streaming with audio are disabled. If there is no sound card
installed, then the entire group box containing audio settings is hidden. If the
currently selected board is not capable of streaming, then the entire Streaming
page is removed.
Using the Configuration Dialog While Displaying
The Configuration Dialog is a modeless dialog. End-users may change a number
of options such as the currently selected board, channel, pixel type, area of
interest, or decimation which may change the size of the snapped or live
images or the manner in which they are displayed.
To avoid improperly displaying snapped images or live display, the application
should handle the OnNotificationMessage event and look for the MessageCode,
“IDEA_INFO_DIALOG_ACTION” with a MessageParameter equal to
“DIALOG_UPDATE_DISPLAY”, and take appropriate action when this is received.
For snapped images, the display window may need to be resized for the next
snap; and live display may need to be stopped and restarted.
Data Persistence in the IdeaFG Control
The IdeaFG control caches configuration settings in its own member variables
(i.e. properties). They are in effect until they are changed again or the
application is closed. To save these settings for the next time it is run they
must be stored in the Windows registry. The “WriteConfiguration” method
saves all of the settings at once to the registry. This method is called
automatically when the end-user clicks “Apply” or “OK” in the Configuration
Dialog.
The “ReadConfiguration” method loads all of the settings at once from the
registry into the IdeaFG member variables. This method is called automatically

IDEA SDK User’s Guide 119

Chapter 5:
ActiveX Function Listings

when the “Open” method is called to initialize, unless the

"ControlManagesConfiguration" property is first set to FALSE. The
“ReadConfiguration” is also called automatically when the end-user clicks
“Cancel” in the Configuration Dialog, to undo the users changes to settings by
overwriting them with the old values from the registry.
Location in the Registry
The IdeaFG control always uses the following key for storing configuration
settings:
HKEY_LOCAL_MACHINE\Software\Foresight\IDEA\<section>
In this key, the “<section>” part is a user-definable string that may be set using
the “RegistrySection” property. The “RegistrySection” property defaults to the
value, “Applications”. The application may choose to store in the "Applications"
section in order to share user settings with other applications, or to use their
own unique sections and not share information. The difference depends on
whether, when the end-user makes changes (e.g., the default board, or the
output pixel type, or turning on audio for streaming), will they expect to still
have their changes in effect when they run a different application or will they
be surprised that a change in the settings for one application has caused an
unwanted change in another.
Under the <section> key, values which are global are stored directly. Most
values, however, are board-specific. These are set under a sub-key which is a
five-character string containing the board’s serial number. The settings for a
particular board on a system will be remembered even if the board is removed
and later reinstalled.
Storing and Retrieving Individual Values
Besides the “WriteConfiguration” and “ReadConfiguration” methods, IdeaFG
also has methods for storing and retrieving values individually. There are only
two data types allowed by IdeaFG for storage in the registry, strings (null-
terminated character strings) and DWORDs (32-bit unsigned integers). All
settings stored by IdeaFG have a Name (which is a character string) and a Value
(which is either a string or a DWORD).
The methods for storing and retrieving named values for the currently selected
board are called “WriteConfigXxx” and “ReadConfigXxx”, where”Xxx” is either
“String” or “Dword”. The methods for storing and retrieving named values
without regard to the currently selected board are called
“WriteConfigGlobalXxx” and “ReadConfigGlobalXxx”, where”Xxx” is either
“String” or “Dword”.
Saving Application Settings Using IdeaFG

120 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

For convenience and simplicity, an application may wish to take advantage of

the IdeaFG control’s simple methods for storing and retrieving individual values
by making up its own values and using those methods to save them, on a global
or per-board basis, to store and retrieve its own configuration settings. Doing
this is fully welcomed and supported. Just remember, the “WriteConfiguration”
and “ReadConfiguration” methods will not store or retrieve your values.
Writing Your Own Configuration Dialog
If the application is to use its own dialog to input configuration settings (still
using IdeaFG to manage the settings’ persistence) it can do so, with the
following recommendations.
• Use the values entered by the end-user into the dialog’s controls to set
the corresponding properties in the IdeaFG control.
• From the handlers for the “OK” and “Apply” buttons, call the IdeaFG
control’s “WriteConfiguration” method to save the user’s settings in
the registry. Also, from there call any “WriteConfigXxx” methods
needed to save individual application settings.
• From the handler for the “Cancel” button, call the IdeaFG control’s
“ReadConfiguration” method to restore the user’s settings from the
registry. Also, from there call any “ReadConfigXxx” methods needed to
restore individual application settings.
Managing Your Own Configuration Settings
To write an application that manages its own configuration settings and does
not use those features of the IdeaFG control, you should do the following:
• Set the property "ControlManagesConfiguration" = FALSE.
• Set the property "CurrentBoardIndex" to the index value (1, 2, 3...) of
the board to start with initially. If you do not know the index, call the
method "GetIndex" with the serial number of the board as a string, to
retrieve the index. If you do not assign any value to
"CurrentBoardIndex", it will default to the first board found.
• Set the following properties in any order, as needed, and as
appropriate for the selected board:
"VideoChannel"
"SyncChannel"
"CA1Path", "CA2Path", ..., "SVideo2Path", etc.
"PixelType"
• Call the "Open" method.

IDEA SDK User’s Guide 121

Chapter 5:
ActiveX Function Listings

• Set any other properties you may need for snaps, live, streaming, etc.
The OCX is ready to go at this point.
• Do not set the "HardwareProfile" property at any time.
To change boards when managing your own configuration, call the "Close"
method and then follow steps 2, 3, and 4 above. Also, change any properties
you may have set in step 5 above, but this is only necessary if they are
different for the new board (e.g., if using a different "AVIFile" pathname for
each board).

Configuration and Data Persistence

Methods ShowConfigDialog Page 200

ShowAreaOfInterestDialog Page 198
ReadConfiguration Page 186
WriteConfiguration Page 208
ReadConfigDword Page 185
ReadConfigString Page 186
WriteConfigDword Page 207
WriteConfigString Page 208
ReadConfigGlobalDword Page 186
WriteConfigGlobalDword Page 208
WriteConfigGlobalString Page 208
ReadConfigGlobalString Page 186
Properties HardwareProfile Page 150
CA1Path Page 143
VideoChannel Page 41
SyncChannel Page 158
UseSyncChannelFromCHP Page 162
PixelType Page 153
BitsPerPixel Page 141
BytesPerPixel Page 143
ApplicationNotBusyEvent Page 137

122 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

ControlManagesConfiguration Page 145

RegistrySection Page 154

Snapping and Displaying Images

Snapping an Image
The IdeaFG control has a “Snap” method for snapping a single image. The
“Snap” method will not return until the snap is complete or an error has
occurred. If triggering is enabled for snaps, the “Snap” method will not return
until after the trigger.
Snap to IdeaDisplay Control
See the section, “Initializing the IdeaDisplay Control With IdeaFG” above.
Essentially, the application just needs to tell the controls about each other and
then the image goes from IdeaFG to IdeaDisplay automatically via Windows
messaging on each snap. The display control window may need to be sized for
the image.
Snap to Other Controls
After calling the “Snap” method to snap a single image, call the “GetImageDIB”
method to retrieve a handle to the image DIB, or call the “GetImagePicture”
method to retrieve an LPPICTUREDISP pointer, depending on what the display
control expects. The display control window may need to be sized for the
image.
Asynchronous Snaps With Events
The “Snap” method does not return until the snap is completed. This might be
undesirable in case, for example, if triggering is enabled. To perform a snap in
a separate thread, call the “SnapInThread” method instead. To cancel a snap
that is in progress, call the “SnapCancel” method.
If a snap is executing in a separate thread, it may be necessary to know when
the snap has completed, in order to process the image or take other actions,
such as allowing the end-user to snap again. To receive the “OnSnap” event
when the snap is completed, set the “FireSnapEvent” property to TRUE,
otherwise set it to FALSE.
Triggered Snaps
To use a hardware trigger for snaps or sequential snaps, set the “UseTriggers”
property to TRUE or check the “Enable Triggered Snaps” checkbox in the
Configuration Dialog. There is also a “TriggerMethod” property that may be set

IDEA SDK User’s Guide 123

Chapter 5:
ActiveX Function Listings

to zero for triggering on the rising edge of the trigger pulse or one for
triggering on the falling edge of the trigger pulse.
If the triggered snap or triggered sequential snaps are running in a separate
thread (recommended), then they may be canceled by using the
“ForceTrigger”, “AbortTrigger”, or “SnapCancel” methods. The difference is
that “ForceTrigger” forces the completion of the snap and returns an image,
whereas the other two methods are for aborting the snap.
NOTE: at the time of this writing, the IDEA Native Library does not have an
abort trigger implementation, so the “AbortTrigger” function currently does
the same thing as “ForceTrigger”.
Sequential Snaps
To perform multiple snaps, set the SequenceCount property to the number of
snaps desired, then call the SnapSequence method. The SnapSequence method
does not return until all of the requested snaps are completed, or an error
occurs.
All of the methods and properties described above for triggered snaps also
apply to triggered sequential snaps.
If the FireSnapEvent property is TRUE, the application will receive the OnSnap
event after each snap.
Asynchronous Sequential Snaps With Events
To perform multiple snaps in a separate thread, call the SnapSequenceInThread
method instead of SnapSequence.
The SnapSequenceInThread method takes a single parameter called SnapEvent.
If the SnapEvent parameter is set to zero, the method will take a snap as soon
as the last snap is completed. Otherwise, it is assumed that the SnapEvent
contains an event handle created by the application to be used to indicate
when the application wishes to signal the next snap. The typical way this is
used is as follows: 1) application sets the SnapEvent event; 2) IdeaFG snaps; 3)
IdeaFG fires the OnSnap event; 4) application receives the OnSnap event and
processes the image; 5) application sets the SnapEvent event again; etc.
The application may call the SnapSequenceCancel method at any time after
calling SnapSequenceInThread to terminate the snap sequence, regardless of
the number of snaps specified in the SequenceCount property. To use
SnapSequenceCancel as the sole method of terminating the snap sequence, tell
the IdeaFG control to snap forever by setting the SequenceCount property
equal to –1.
Getting a Histogram

124 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

To get a histogram, first snap an image using one of the methods described
above, then call the GetHistogram method. The GetHistogram method returns
a VARIANT containing a reference to a SAFEARRAY of long integers (signed, 32-
bit values) which are the histogram data for each possible pixel value. The size
of the array is determined by the pixel depth, and is returned to the caller in
the NumPoints parameter, which is a pointer to a long integer.
The histogram returned is calculated from the most recently snapped image,
which could be from a single snap or the most recent of a sequence of snaps.
To manage histograms in a sequence of snaps, it would be best to do so using
asyncronous sequential snaps and to process it in the event handler for the
OnSnap event, and to use a SnapEvent event to signal IdeaFG when the
application is done with the histogram (and the image). This is because both
the image and the histogram are no longer valid once the next snap has begun.

IDEA SDK User’s Guide 125

Chapter 5:
ActiveX Function Listings

Snapping and Displaying Images

Methods Snap Page 203

SnapInThread Page 204
SnapCancel Page 204
SnapSequence Page 204
SnapSequenceInThread Page 204
SnapSequenceCancel Page 204
InitRgb3 Page 182
GetSnapWidth Page 178
GetSnapHeight Page 177
ForceTrigger Page 96
AbortTrigger Page 164
GetHistogram Page 170
GetSnapAOI Page 177
SetSnapAOI Page 194
Properties ImageDIBBitsSizeInBytes Page 151
DecimateSnapHorizontal Page 147
DecimateSnapVertical Page 147
SequenceCount Page 155
SequenceGrabDelay Page 155
UseTriggers Page 162
TriggerMethod Page 161
TriggerDelay Page 159
FireSnapEvent Page 149
SnappedImageOrientation Page 156
ForceMonoSnapsTo24Bit Page 149
CopySnapToClipBoard Page 145
Events OnSnap Page 209
OnSequenceTermination Page 210

126 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Retrieving and Saving Snapped Images

How IdeaFG Returns Snapped Images

When an image is snapped -- whether it is from a single snap, snapped
sequence, or a snap or sequence in continuous capture mode -- the original, or
raw data from the frame grabber board is captured into a buffer called the
“raw buffer”. The data in the raw buffer is then converted by software into DIB
format (in the “DIB buffer”). The software conversion algorithm is determined
by the pixel type, and is usually trivial, as for 24- and 32-bit RGB; but may be
more complex, as for YCbCr, which must be color-space converted to RGB to
display in DIB format. Software conversion is usually not performed for
streaming video, which is time-critical; and cannot be performed for Direct
Draw live display.
Getting the Snapped Image DIB
After an image has been snapped, call the “GetImageDIB” method to retrieve a
handle to the image DIB, or call the “GetImagePicture” method to retrieve an
LPPICTUREDISP pointer. The image is valid and available after it has been
snapped, and until the next snap has begun. To ensure that the application is
using the image during the time it is valid and available, coordinate with the
IdeaFG control using events, as described above.
Saving an Image DIB
To save an image to Windows Bitmap (BMP) or JPEG format, call the
“SaveImageToFile” method. The first parameter to this method is a DIB handle,
as returned from the “GetImageDIB” method. There are two ways of using this
parameter.
If the parameter is set to zero, then the most recently snapped image is saved.
In this case, IdeaFG has all of the information necessary to save it exactly
according to the selected pixel type. Thus, calling “GetImageDIB” is not
necessary. The advantage is that the application, or the end-user, has control
over the format in which the image is saved, if saving to a BMP file. The
disadvantage is that only the most recently snapped image may be saved this
way. For an example of this, look at the sample code in VbSnapAndSave.
If the parameter is set to a DIB handle, then the DIB referenced by that handle
is saved. In this case, IdeaFG only has available the information that is stored
by Windows in the DIB. As a result, the “SaveImageToFile” method will only
save the image as a 24-bit RGB image if it is saving to BMP format. The
advantage to this is that the application can snap any number of images, copy
the DIBs (e.g., using the clipboard to make copies and displaying them in a
window), and then save them at a later time. The disadvantage is that the

IDEA SDK User’s Guide 127

Chapter 5:
ActiveX Function Listings

application, or the end-user, has less control over the saved format of the
image, if it is being saved to a BMP file. For an example of this, look at the
code in the IDEA Visual Basic Demo.
The format of the image is irrelevant if it is being saved to a JPEG format file.
To specify the file format, use the third parameter. For Windows BMP format,
set it to IIF_IMAGE_FORMAT_BMP, or to IIF_IMAGE_FORMAT_JPEG for JPEG
format. Set it to –1 to let the file suffix (.jpg or .bmp) determine the format.
Getting the Snapped Image Raw Data Buffer
After an image has been snapped, call the “GetPixelData” method to retrieve a
VARIANT containing a reference to a SAFEARRAY of BYTEs that is the raw image
buffer, unconverted to DIB format. The image is valid and available after it has
been snapped, and until the next snap has begun. To ensure that the
application is using the image during the time it is valid and available,
coordinate with the IdeaFG control using events, as described above.
Saving 10-bit Images as 16-bit PNG
Since the Windows DIB, Windows Bitmap (BMP) and JPEG format files, and
standard display software and hardware, do not allow 10-bit images, the image
pixel data in 10-bit format is only available in the raw buffer. The IdeaFG
control provides a method for saving 10-bit monochrome to 16-bit monochrome
(where the least significant 6 bits are zero) in the PNG file format.
To save to PNG, call the SavePixelDataToFile method with the PixelData buffer
returned from the “GetPixelData” method, the image dimensions (from the
“GetSnapWidth” and “GetSnapHeight” methods and the “BitsPerPixel”
property), the save file pathname, and the file type (ignored for now – only
PNG is allowed).
This method will also save 8-bit monochrome as 8-bit monochrome PNG.
For an example of saving images to PNG format, see the sample code in
VbSnapAndSave.

Retrieving and Saving Snapped Images

Methods GetImageDIB Page 172

GetImagePicture Page 172
SaveImageToFile Page 187
GetPixelData Page 177
SavePixelDataToFile Page 188

128 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Properties SaveToJpegQuality Page 154

Live Display

Direct Draw Live Display

The way Direct Draw live display works using the IDEA ActiveX Controls is by a
cooperation between the IdeaFG control, which sets up the board and the
video, and the IdeaDisplay control, which provides the display window and
window management.
To initialize the controls for DD live display, see the section, “Initializing the
IdeaDisplay Control With IdeaFG” above. Essentially, the application just needs
to tell the controls about each other and then the live display goes from the
currently selected board to the display surface automatically via Direct Draw.
The display control window may need to be sized for the live video.
To start live display, first set the “LiveDisplay” property of IdeaDisplay to TRUE
to tell it to use Direct Draw. Then, optionally, set the color key to an RGB
value appropriate to the application (the default is black, which is unobtrusive
but may result in some video “bleed-through” if another window containing
black overlaps the Direct Draw surface). Finally, start the video by calling the
IdeaFG method, “LiveVideo”, with the single boolean parameter “StartLive”
equal to TRUE.
To stop live display, call the IdeaFG method, “LiveVideo”, with the “StartLive”
parameter equal to FALSE.
For examples of Direct Draw live display, see the sample code in VbLive and
CppLive.
Area of Interest and Decimation
To set the area of interest (AOI) programmatically, call the “SetLiveAOI”
method. To set the AOI using the Configuration Dialog, click the “Area of
Interest…” button on the “Live” property page. This brings up the Area of
Interest dialog which displays a single snap with the current AOI rectangle
drawn on it. The four AOI coordinates, which represent the non-negative
distance from the left, right, top, and bottom edges of the frame, are
displayed in edit boxes and may be changed directly or by using the spin
controls.
To set the horizontal and/or vertical decimation values, set the
“DecimateLiveHorizontal” and/or “DecimateLiveVertical” properties. The
allowable values are 1 for no decimation or 2 for decimation by 2 (half-size in

IDEA SDK User’s Guide 129

Chapter 5:
ActiveX Function Listings

that dimension). To set decimation using the Configuration Dialog, check the
“2x Width Decimation” and/or “2x Height Decimation” checkboxes on the
“Live” property page.
Note that area of interest is always applied before horizontal and vertical
decimation. Also, note that color boards cannot decimate in the horizontal
direction for live display.
To set frame decimation, set the “DecimateFrameRate” property to a value
between 1 and 256, or set this value in the “Frame Rate Decimation” edit box
on the “Video” property page of the Configuration Dialog. The source frame
rate will be divided by this value to produce the decimated frame rate.
Note that the decimated frame rate applies to both Direct Draw live display
and streaming – frame rate decimation cannot be set independently for these
two operations.
Updating the Live Display Window
To force an update of the live display surface in IdeaDisplay, call the IdeaFG
method, “LiveVideo” with the “StartLive” parameter set equal to TRUE while
the live display is running, as if starting the live video again.
To receive notification of updates such as a change of selected board, CHP file,
etc., see the above section, “Using the Configuration Dialog While Displaying”.
The application will handle the OnNotificationMessage event and respond to
certain codes by stopping and restarting live display, and possibly resizing the
display window in between.
Multiple Monitor Direct Draw
Direct Draw live display to multiple monitors on the same computer is possible
by using separate application instances accessing different IDEA frame grabber
boards. Certain system requirements also apply. First, the system must be
Windows XP and must be running at least Direct Draw 8.1. A multi-monitor
graphics display card supporting Direct Draw 8.1 on these operating systems is
also required. Also, a special version of the IDEA ActiveX controls with multiple
monitor support is required; this version will not run on earlier operating
systems such as Windows 98 or NT, so it is not part of the general release.
Finally, there may be other restrictions imposed by the particular multi-
monitor graphics card. Contact Foresight Imaging’s sales department for more
information if you are interested in this feature.
GDI Live Display
While most people prefer Direct Draw live display for its performance and
other features, GDI live display is also available for IDEA frame grabber boards
that are not capable of Direct Draw, or other reasons for choosing GDI. The
IDEA ActiveX controls implements GDI live display, sometimes called “pseudo-

130 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

live display”, essentially as a threaded sequence of snaps that are sent directly
from IdeaFG to IdeaDisplay (in fact, you could do that yourself using the
SnapSequenceInThread method, but this is a bit easier).
To do GDI live display, follow the steps in the above section, “Direct Draw Live
Display”, except that instead of setting IdeaDisplay’s property “LiveDisplay” to
TRUE, set it to FALSE. IdeaDisplay will then prepare a GDI window instead of a
Direct Draw window and tell IdeaFG to send it sequential snaps instead of
initiating Direct Draw live mode. For an example of this code, which does both
Direct Draw and GDI live mode, see the IDEA Visual Basic demo.

Live Display

Methods LiveVideo Page 184

GetLiveAOI Page 173
SetLiveAOI Page 193
GetLiveWidth Page 174
GetLiveHeight Page 174
SetDisplayWindow Page 190
Properties DecimateLiveHorizontal Page 147
DecimateLiveVertical Page 147
FieldUpdateLive Page 149

Streaming

CODECs and Compression Settings

Before the IdeaFG control can begin streaming compressed data, the
appropriate CODEC must be identified and initialized. There are several ways
to do this, using the available methods, properties, and dialogs in IdeaFG.
To prepare the CODEC programmatically, call the “CodecLoad” method with
the name of the CODEC DLL and the FourCC code identifying the compression.
For no compression, set the CODEC DLL to an empty string and pass the FourCC
code for “DIB ” as a DWORD (note the space character in the fourth position).

IDEA SDK User’s Guide 131

Chapter 5:
ActiveX Function Listings

Several dialogs are also available. The “ShowCompressionDialog” method will

bring up a modeless dialog that allows the end-user to select from several
known and tested CODECs using radio buttons. The currently selected CODEC
and 4CC code are displayed in edit boxes which the user may change, then
press the “Set” button to apply the changes.
The Compression Dialog also has buttons for listing “All Installed” CODECs and
for listing CODECs “By Pixel Type”. These buttons bring up system dialogs that
display the CODECs currently registered in Windows. The application may also
display these dialogs programmatically by using the “CodecChooseFromList”
and “CodecChooseByFormat” methods, respectively.
Finally, the Compression Dialog has buttons for displaying the currently
selected CODEC’s own Configure and About dialogs, if it has them. The
button(s) will be grayed out if either or both of them are not present. To do
this programmatically, the application may call the methods
“CodecHasConfigure” and “CodecHasAbout” to determine their presence or
absence; and the methods “CodecConfigure” and “CodecAbout” to display the
dialog(s), if present.
Streaming Performance, Buffers and Other Options
There are several configurable options for streaming. One of them is the
number of frame buffers to use. This may be set programmatically by assigning
the “StreamingBuffers” property or by setting it in the Configuration Dialog in
the “Buffers” edit box.
The value chosen (default is 16) should be slightly more than what is needed to
cover the delay between when the streaming thread receives a buffer from the
board and when the writing thread outputs the buffer to the disk and is
finished with it. In simpler terms, the value should be high enough so that
frames are not dropped and low enough so that the system doesn’t run out of
memory.
The value to choose is dependent on many factors, including the size of the
video format and frame rate, processor and disk I/O speed, the efficiency of
the selected CODEC, the bandwidth of the PCI bus, and the amount of memory
on the system, and what else is running on the system during streaming.
In terms of performance, each of these variables will contribute to determining
whether the system can keep up with the streaming. If it cannot, then frames
will be dropped. In the best case, there are an adequate supply of buffers and
the streaming will run at full frame rate. If full frame rate is not possible, and
a limited number of frames are required, and there is enough memory to do so,
then setting the number of buffers equal to the number of frames requested
may allow the stream to complete, with the buffers filling up at full frame rate
and then the disk I/O catching up a bit later. But in the worst case, there is

132 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

simply not enough bandwidth to stream into the buffers, or there are not
enough buffers, and then frames will be dropped.
In this case, it is recommended that frame rate decimation be used to reduce
the frame rate to the point where frames are not dropped. To set frame
decimation, set the “DecimateFrameRate” property to a value between 1 and
256, or set this value in the “Frame Rate Decimation” edit box on the “Video”
property page of the Configuration Dialog. The source frame rate will be
divided by this value to produce the decimated frame rate.
Note that the decimated frame rate applies to both Direct Draw live display
and streaming – frame rate decimation cannot be set independently for these
two operations.
Another option available for streaming is the “StreamingLogFile” property,
which corresponds to the “Log File” edit box on the “Streaming” property page
in the Configuration Dialog. Setting this value to the pathname of a text file
will cause a human-readable log file to be generated during streaming. This log
file will be necessary if any streaming-related problems are to be reported to
Technical Support. Setting this property to an empty string will cause IdeaFG to
not generate a log file.
Streaming to AVI Files
To stream to an AVI file, the pathname of the file must first be set either by
setting the “AVIFile” property, or by setting the pathname in the “AVI File”
edit box in the Configuration Dialog on the “Streaming” property page. Then,
call the “StreamToAvi” method passing the number of frames to stream.
For examples of streaming to an AVI file, see the sample code in VbStream or
CppStream.
Streaming to Memory Buffers
There may be cases where an application needs to implement its own
“StreamToAvi” or “StreamToDicom”; or it needs to stream to some other
format; or for some other reason needs to receive streamed image buffers and
process them itself. For these cases, a “StreamToMemory” method is provided
which does essentially what “StreamToAvi” and “StreamToDicom” do, except it
does not output to a file and it does not delete the buffers when it is finished.
For streaming to memory, some additional methods are added to give the
application control over the video buffers in a flexible manner. A
“MemoryHandle” parameter is returned from each call to “StreamToMemory”
which identifies the set of video buffers from that particular stream. Keep in
mind that if the number of frames streamed exceeds the number of buffers
allocated, then the buffers are treated as a ring (i.e., after they are all filled

IDEA SDK User’s Guide 133

Chapter 5:
ActiveX Function Listings

the streaming reuses them starting again with the first buffer). In other words,
the application will need to be fast enough to keep up with the streaming.
To access a buffer, the application can use the “FramePointer” parameter in
the OnFrameReady event, which is a pointer to a VARIANT containing a
reference to a SAFEARRAY of BYTEs. This event also returns a “FrameNumber”
parameter. This is most useful for an application doing a long stream and
processing every frame sequentially (as it is ready).
Additionally, there is a “GetBuffer” method which takes a “MemoryHandle”
and a “FrameNumber” parameter. This is most useful for an application that
will stream N frames into N buffers, perhaps several times, and then go back
and access the buffers in any order.
When the application is finished with the buffers from a particular stream, it
should call the “ReleaseBuffers” method to free the buffers’ memory that is
associated with a particular memory handle, or call “ReleaseAllBuffers” to free
all buffer memory.
For an example of streaming to memory, see the code in the IDEA Visual Basic
Demo.
Triggered Streaming
To control streaming using a hardware trigger, set the “TriggeredStreaming”
property to one of the values TRIGGER_START_STOP_LOW,
TRIGGER_START_STOP_HIGH, TRIGGER_RUN_LOW, TRIGGER_RUN_HIGH,
depending on the trigger polarity and whether it is desired to start and stop
streaming with a trigger click, or while holding or releasing the trigger.
The “TriggerFilterTime” property is useful for debouncing trigger switches to
eliminate double triggers.
Streaming to Multiple Files
With triggered streaming it is possible to redirect the output to different AVI
files with each change in trigger state by ORing the “Flags” parameter of the
“StreamToAvi” method with the STREAMING_TERMINATE_ON_TRIGGER_STOP
flag. This flag will cause streaming to terminate after a single trigger. Then, in
the “OnStreamingTermination” event handler, the application can change the
“AVIFile” parameter to the pathname of a different AVI file, and call
“StreamToAvi” again.
For an example of streaming to multiple files, see the IDEA Visual Basic Demo.
Streaming with Start, Pause, and Cancel Events
Streaming may be started, paused/resumed, and canceled using user created
events. Create and pass any or all of these three event handles to the
streaming method in the “StartEvent”, “PauseEvent”, and “CancelEvent”

134 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

parameters, respectively. If a zero is passed in any of these parameters, then

that event is not used.
For an example of streaming with start, pause, and cancel events, see the IDEA
Visual Basic Demo.
Streaming to AVI with Audio
Four properties are provided to set options for streaming to AVI files with
audio. Set the “AudioEnabled” property to TRUE to stream with audio or FALSE
to stream without audio. If streaming with audio, the “AudioChannels”,
“AudioSampleRate”, and “AudioBitsPerSample” properties may be set to
control the quality vs. speed and file size of the audio. Each of these properties
has a corresponding control in the “Audio” group box on the “Streaming”
property page in the Configuration Dialog.

IDEA SDK User’s Guide 135

Chapter 5:
ActiveX Function Listings

Streaming

Methods StreamToAvi Page 205

StreamToMemory Page 206
GetBuffer Page 168
ReleaseBuffers Page 187
ReleaseAllBuffers Page 186
GetStreamAOI Page 179
SetStreamAOI Page 164
GetStreamWidth Page 180
GetStreamHeight Page 179
CodecLoad Page 166
CodecChooseFromList Page 165
CodecChooseByFormat Page 165
CodecHasConfigure Page 166
CodecHasAbout Page 166
CodecConfigure Page 166
CodecAbout Page 165
ShowCompressionDialog Page 199
ShowDicomDialog Page 201
Properties TriggeredStreaming Page 161
TriggerFilterTime Page 101
DecimateFrameRate Page 146
DecimateStreamHorizontal Page 147
DecimateStreamVertical Page 148
StreamingLogFile Page 157
StreamingBuffers Page 157
CodecDLL Page 144
CodecFourCCType Page 144
CodecVideoQuality Page 144
KeyFrameRate Page 152
AVIFile Page 141
AudioEnabled Page 138

136 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Methods StreamToAvi Page 205

AudioSampleRate Page 139
AudioChannels Page 138
AudioBitsPerSample Page 138
FieldUpdateStream Page 149
FrameRateMeasured Page 150
FrameRateTheoretical Page 150
TriggerStartFrameDelay Page 159
TriggerStopFrameDelay Page 160
Events OnFrameReady Page 209
OnStreamingTermination Page 209

IdeaFG Control Reference

CIdeaFG is the primary interface for accessing the board. Through this
interface, an application is able to access the hardware to initialize the board,
perform video-tuning operations and access the video data.
The following are behavioral characteristics of this control:
ƒ Invisible at runtime.
ƒ Displays an About box listing copyright and version information.
ƒ Does not have a property pages dialog.
ƒ Has properties that can be set at design or runtime.
ƒ Does not subclass any standard window classes.

Properties

ApplicationNotBusyEvent Property

Description Sets or returns the handle to an event that the application should fire
to indicate that it is not currently performing operations such as
snapping, streaming, live display, user dialogs, etc. Setting this event
signals that the application is ready for the IdeaFG control to proceed
with some operation.
This property is currently used for Automatic Signal Detection.
Type long

IDEA SDK User’s Guide 137

Chapter 5:
ActiveX Function Listings

Syntax Visual Basic

Object.ApplicationNotBusyEvent = Value
Value = Object. ApplicationNotBusyEvent
C++
Object.SetApplicationNotBusyEvent(long Value)
long Value = Object.GetApplicationNotBusyEvent( )

AudioBitsPerSample Property

Description Sets or returns the sample size in the AVI file for playback. Usual
values are 16 (CD quality) or 8 bits.
This property is used when streaming both audio and video to an AVI
file.
Type long
Syntax Visual Basic
Object.AudioBitsPerSample = Value
Value = Object.AudioBitsPerSample
C++
Object.SetAudioBitsPerSample(long Value)
long Value = Object.GetAudioBitsPerSample( )

AudioChannels Property

Description Sets or returns the number of channels to be recorded in the AVI file.
Must be 1 for monaural or 2 for stereo.
This property is used when streaming both audio and video to an AVI
file.
Type long
Syntax Visual Basic
Object.AudioChannels = Value
Value = Object.AudioChannels
C++
Object.SetAudioChannels(long Value)
long Value = Object.GetAudioChannels( )

AudioEnabled Property

Description Enables or disables audio recording for the current board.

138 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

This property is used when streaming to an AVI file.

Type boolean
Syntax Visual Basic
Object.AudioEnabled = Value
Value = Object.AudioEnabled
C++
Object.SetAudioEnabled(bool Value)
bool Value = Object.GetAudioEnabled( )

AudioSampleRate Property

Description Sets or returns the sample rate in the AVI file for playback. Usual
values are 44100 (CD quality), 22050, and 11025.
This property is used when streaming both audio and video to an AVI
file.
Type long
Syntax Visual Basic
Object.AudioSampleRate = Value
Value = Object.AudioSampleRate
C++
Object.SetAudioSampleRate(long Value)
long Value = Object.GetAudioSampleRate( )

AutoSignalDetection Property

Description Sets or returns the Automatic Signal Detection flag. A value of zero
means disabled, a value of one means enabled.
Automatic Signal Detection is a feature which, when enabled, will
cause the IdeaFG control to detect a loss of signal, as from
disconnection of the video cable, and a reaquisition of signal, as from
reconnection of the video cable (presumably to a different video
source), and then automatically run VESA scanning to reconfigure the
board to the new video signal.
On disconnection, the application will receive an
OnNotificationMessage event, with a MessageCode equal to
IDEA_INFO_CONNECTION and a MessageParameter equal to
IDEA_CONNECTION_LOST. The application should, upon receiving this
event, terminate live display and disable any controls or menu items
that may cause action in the IdeaFG control, such as snaps, streaming,

IDEA SDK User’s Guide 139

Chapter 5:
ActiveX Function Listings

live display, or configuration. The application may need to notify the

user of the loss of video.
On reconnection, the application will first receive an
OnNotificationMessage event, with a MessageCode equal to
IDEA_INFO_CONNECTION and a MessageParameter equal to
HD_ANALOG_SYNC_DETECTED if an analog signal is present or
HD_DIGITAL_SYNC_DETECTED if a digital signal is present.
Next, the application will receive one of several
OnNotificationMessage events. If the board is not a high-speed I-RGB
or AccuStream board, it will receive a MessageCode equal to
IDEA_INFO_VESA_SCAN_DONE and a MessageParameter equal to
VESA_SCAN_INVALID_BOARD. If the AutoSignalDetection property is
zero (disabled), it will receive a MessageCode equal to
IDEA_INFO_VESA_SCAN_DONE and a MessageParameter equal to
VESA_SCAN_NOT_RUN. In these cases, the application may resume
normal functioning. Otherwise, it will receive a MessageCode equal to
IDEA_INFO_VESA_SCAN_READY and a MessageParameter equal to zero.
The application may need to notify the user that VESA scanning is in
progress.
At this point, if the ApplicationNotBusyEvent property is non-zero,
having been set to a valid event handle, the IdeaFG control will wait
for that event to be set by the application to indicate that the
application is ready to begin VESA scanning. This is useful if the
application needs a significant amount of time to complete some
operation or otherwise get into a state where it is ready to wait for
VESA scanning, or if it simply needs to guarantee that VESA scanning
will not begin before the application is ready. If the event handle is
zero, VESA scanning will begin automatically. The application will next
receive an OnNotificationMessage event, with a MessageCode equal to
IDEA_INFO_VESA_SCAN_START and a MessageParameter equal to zero
when VESA scanning begins.
After VESA scanning, which is performed in “silent” mode (unlike the
“interactive” mode of VESA scanning which uses dialogs and a progress
bar), the application will receive an OnNotificationMessage event,
with a MessageCode equal to IDEA_INFO_VESA_SCAN_DONE and a
MessageParameter equal to the error return code (zero if successful).
When finished, the application may need to notify the user, reenable
controls and menu items, and/or restart live display, as appropriate.
See the Idea Visual Basic demo source code for an example of handling
this entire process.
Type long
Syntax Visual Basic
Object.AutoSignalDetection = Value
Value = Object. AutoSignalDetection

140 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

C++
Object.SetAutoSignalDetection(long Value)
long Value = Object.GetAutoSignalDetection( )

AVIFile Property

Description Sets the pathname of the AVI file to be used by the StreamToAvi
method for streaming video and playback.
Type string
Syntax Visual Basic
Object.AVIFile = Value
Value = Object.AVIFile
C++
Object.SetAVIFile(LPCTSTR Value)
CString Value = Object.GetAVIFile( )

BitsPerPixel Property

Description Shows the resolution of the frame grabber in bits per pixel, according
to the output format currently defined by the PixelType property. This
is a READ-ONLY property.
Type long
Syntax Visual Basic
Value = Object.BitsPerPixel
C++
long Value = Object.GetBitsPerPixel( )

BoardCount Property

Description Determines the number of boards in the system. This is a READ-ONLY

property.
Type long
Syntax Visual Basic
Value = Object.BoardCount

C++
long Value = Object.GetBoardCount( )

IDEA SDK User’s Guide 141

Chapter 5:
ActiveX Function Listings

BoardHandle Property

Description Returns the board handle for the current board so that IDEA library
functions may be called if necessary -- even while using the ActiveX
control for everything else. This is a READ-ONLY property.
Type long
Syntax Visual Basic
Value = Object.BoardHandle
C++
long Value = Object.GetBoardHandle( )

BoardLocation Property

Description Displays the location of the board as determined by the device driver.
This is a READ-ONLY property that is filled in by the OCX when the
board-handle is determined. For I-Series frame grabbers, this property
displays a Slot designation.
Type string
Syntax Visual Basic
Value = Object.BoardLocation
C++
CString Value = Object.GetBoardLocation( )

Brightness Property

Description Changes or retrieves the brightness of the incoming image. The value
is in the range of 1 to 100 and is computed internally from the board’s
Black Level, Gain, Black Reference and White Reference values. For
AccuStream 50a, 75a, and 205a boards.
Type long
Syntax Visual Basic
Object.Brightness = [Value as Long]
C++
Object.SetBrightness(long Value)
Value = Object.GetBrightness( )

142 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

BytesPerPixel Property

Description Shows the resolution of the frame grabber in bytes per pixel,
according to the output format currently defined by the PixelType
property. This is a READ-ONLY property.
Type long
Syntax Visual Basic
Value = Object.BytesPerPixel
C++
long Value = Object.GetBytesPerPixel( )

CableTypeIndexIRGB Property

Description Sets or returns the index into the list of valid cable types, of the
currently selected cable type for the currently selected board.
This property returns –1 if an error occurs.
Type long
Syntax Visual Basic
Object.CableTypeIndexIRGB = Value
Value = Object.CableTypeIndexIRGB
C++
Object.SetCableTypeIndexIRGB(long Value)
long Value = Object.GetCableTypeIndexIRGB( )

CableTypeIRGB Property

Description Sets or returns the name of the currently selected cable type for the
currently selected board.
This property returns an empty string if an error occurs
Type string
Syntax Visual Basic
Object.SetCableTypeIRGB(Value)
Value = Object.GetCableTypeIRGB
C++
Object.SetCableTypeIRGB(LPCTSTR Value)
CString Value = Object.GetCableTypeIRGB( )

IDEA SDK User’s Guide 143

Chapter 5:
ActiveX Function Listings

CodecDLL Property

Description Gets the path to the DLL containing a user-defined CODEC for
compressing streamed data. This is a READ-ONLY property. Use the
CodecLoad method to set this value.
Type string
Syntax Visual Basic
Value = Object.CodecDLL
C++
CString Value = Object.GetCodecDLL( )

CodecFourCCType Property

Description Gets the FourCC code used by the CODEC for compressing streamed
data. This is a READ-ONLY property. Use the CodecLoad method to set
this value.
Type long
Syntax Visual Basic
Value = Object.CodecFourCCType
C++
long Value = Object.GetCodecFourCCType( )

CodecVideoQuality Property

Description When streaming to AVI, this property is passed to the CODEC to

control compression quality. The actual value to be used is CODEC-
dependent and should be chosen based upon the documentation for
the CODEC. The value is simply passed through to the CODEC's
interface by the ActiveX control.
Type long
Syntax Visual Basic
Object.CodecVideoQuality = Value
Value = Object.CodecVideoQuality
C++
Object.SetCodecVideoQuality(long Value)
long Value = Object.GetCodecVideoQuality( )

144 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Contrast Property

Description Changes or retrieves the contrast of the incoming image. The value is
in the range of 1 to 100 and is computed internally from the board’s
Black Level, Gain, Black Reference and White Reference values. For
AccuStream 50a, 75a, and 205a boards.
Type long
Syntax Visual Basic
Value = Object.Contrast
Object.Contrast = Value
C++
long Value = Object.GetContrast( )
Object.SetContrast(long Value)

ControlManagesConfiguration Property

Description Tells the IdeaFG ActiveX control that it will manage user-defined
configuration settings. Default value is TRUE. See Configuration and
Data Persistence, earlier in this chapter, for a detailed discussion on
the usage of this property to manage your own confiiguration settings.
Type Boolean

CopySnapToClipboard Property

Description Sets an internal boolean value to determine if snapped images should

automatically be copied to the Windows clipboard. This is useful if an
application wants to retrieved the images from the clipboard.
Type long
Syntax Visual Basic
Object.CopySnapToClipboard = Value
C++
Object.CopySnapToClipboard(long Value)
long Value = Object.CopySnapToClipboard( )

IDEA SDK User’s Guide 145

Chapter 5:
ActiveX Function Listings

CopyrightNotices Property

Description Gets the copyright notices for the IDEA ActiveX controls, as a
formatted string.
Type long
Syntax Visual Basic
Value = Object.CopyrightNotices
C++
CString Value = Object.GetCopyrightNotices( )

CurrentBoardIndex Property

Description The index of the currently selected board. The first board has index 0,
second board has index 1, third board has index 2, etc. This property
is not valid if there are no boards in the system.
Type long

DecimateFrameRate Property

Description Sets or returns the frame rate decimation value for both streaming
and live display. The value must be between 1 and 256. The video
frame rate is divided by the frame decimation value to give the
effective frame rate.
To set the frame rate decimation from the Configuration Dialog
screen, bring up the Video Options tab and enter a value in the "Frame
Rate Decimation" text box.
Type long
Syntax Visual Basic
Object.DecimateFrameRate = Value as long
Value = Object.DecimateFrameRate

146 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

DecimateLiveHorizontal Property

Description The horizontal decimation factor for live video display. Allowable
values are: 1=no decimation, 2=decimation by 2. This property is not
valid on color boards.
Type long

DecimateLiveVertical Property

Description The vertical decimation factor for live video display. Allowable values
are: 1=no decimation, 2=decimation by 2.
Type long

DecimateSnapHorizontal Property

Description The horizontal decimation factor for snaps. Allowable values are: 1=no
decimation, 2=decimation by 2. Snap decimation is performed in
software.
Type long

DecimateSnapVertical Property

Description The vertical decimation factor for snaps. Allowable values are: 1=no
decimation, 2=decimation by 2. Snap decimation is performed in
software.
Type long

DecimateStreamHorizontal Property

Description The horizontal decimation factor for video streaming. Allowable

values are: 1=no decimation, 2=decimation by 2. This property is not
valid on color boards.
Type long

IDEA SDK User’s Guide 147

Chapter 5:
ActiveX Function Listings

DecimateStreamVertical Property

Description The vertical decimation factor for video streaming. Allowable values
are: 1=no decimation, 2=decimation by 2.
Type long

DefaultBoardIndex Property

Description The index of the board to select at startup.

Type long

DefaultCableTypeIRGB Property

Description Sets or returns the default cable type that is to be used when running
VESA scanning in silent mode.
Type long
Syntax Visual Basic
Object.DefaultCableTypeIRGB = Value
Value = Object.DefaultCableTypeIRGB
C++
Object.SetDefaultCableTypeIRGB(long Value)
long Value = Object.GetDefaultCableTypeIRGB( )

DigitalMode Property

Description This is a READ-ONLY property that returns a value indicating whether

the board is operating in digital mode. This property is only valid for
AccuStream boards with a digital video interface.
Type long
Syntax Visual Basic
Object.DigitalMode = Value
Value = Object.DigitalMode
C++
Object.SetDigitalMode(long Value)
long Value = Object.GetDigitalMode( )
Digital Mode Values

148 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Value Constant Description

0 HD_ACTIVE_INTERFACE_ANALOG Analog
1 HD_ACTIVE_INTERFACE_DIGITAL Digital
2 HD_ACTIVE_INTERFACE_UNSPECIFIED Unspecified

FieldUpdateLive Property

Description Set to 1 to enable field update during live display, 0 to disable.

Type long

FieldUpdateStream Property

NOTE: This is not currently implemented.

Description Set to 1 to enable field update during video streaming, 0 to disable.

Type long

FireSnapEvent Property

Description Informs the control whether or not to fire an event when completing a
Snap operation. The application must define a receiving function in
order to receive the event. Refer to the Events section later in this
chapter for more information about events.
Type boolean
Syntax Visual Basic
Object.FireSnapEvent = (Value as Boolean)
C++
Object.SetFireSnapEvent (long Value)
Value = Object.GetFireSnapEvent ( )

ForceMonoSnapsTo24Bit Property

Description Sets or returns a flag to indicate that the DIB returned from snaps
should contain 24-bit RGB data instead of 8-bit palettized data. This
property is useful if the palettized data is producing undesirable
effects, such as when the palette is lost or the wrong palette is used.

IDEA SDK User’s Guide 149

Chapter 5:
ActiveX Function Listings

Generally, using this flag will result in a larger (nearly 3x) buffer and
image file.
Valid values are 0=don’t force mono snaps to 24-bit, non-zero=do
force nono snaps to 24-bit.
This property is only valid for monochrome pixel types (8-bit or 10-bit
on mono boards or 8-bit YCbCr Y-only on color boards).
Type long
Syntax Visual Basic
Object.ForceMonoSnapsTo24Bit = Value
Value = Object.ForceMonoSnapsTo24Bit
C++
Object.SetForceMonoSnapsTo24Bit(long Value)
long Value = Object.GetForceMonoSnapsTo24Bit( )

FrameRateMeasured Property

Description Returns the current actual frame rate as measured by the control.
This property is only valid during multiple frame captures, such as
sequential capture, streaming, and continuous capture mode. This
property is not reliable during the first one second of video capture.
This is a READ-ONLY property.
Type long
Syntax Visual Basic
Value = Object.FrameRateMeasured
C++
long Value = Object.GetFrameRateMeasured( )

FrameRateTheoretical Property

Description Returns the current frame rate of the video source according to the
configuration values in the CHP file. This is a READ-ONLY property.
Type long
Syntax Visual Basic
Value = Object.FrameRateTheoretical
C++
long Value = Object.GetFrameRateTheoretical( )

150 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

HardwareProfile Property

NOTE: The application should not set this property. Rather, set the appropriate
CHP pathname property for the intended channel; i.e., CA1Path, CA2Path,
…, SVideo1Path, etc. This property will likely become READ-ONLY at some
time in the future.

Description This property is the complete path to the Common Hardware Profile
database. This is a READ-WRITE property that is initially filled in by
the OCX. The default value is read the first time from the registry.
After the control has been filled in and saved, subsequent values will
reflect that saved value.
Type string
Syntax Visual Basic
Value = Object.HardwareProfile
C++
CString Value = Object.GetHardwareProfile( )

Hue Property

Description Changes or retrieves the hue of the incoming image. The value is in
the range of 0 to 255. For AccuStream 50a, 75a, and 205a boards.
Type long
Syntax Visual Basic
Object.Hue = Value
C++
Object.SetHue(long Value)
Value = Object.GetHue( )

ImageDIBBitsSizeInBytes Property

Description Returns the size in bytes of the image DIB buffer (returned from the
GetImageDIB or GetImagePicture methods) from a snap. This is a
READ-ONLY property.
Type long
Syntax Visual Basic
Value = Object.ImageDIBBitsSizeInBytes
C++
long Value = Object.GetImageDIBBitsSizeInBytes( )

IDEA SDK User’s Guide 151

Chapter 5:
ActiveX Function Listings

KeyFrameRate Property

Description Sets or returns the keyframe rate which is the rate at which frames
being streamed to AVI will be designated as keyframes; e.g, specifying
a value of 5 means that every fifth frame will be designated as a
keyframe. The default value is 1, which means that every frame is a
keyframe.
Type long
Syntax Visual Basic
Object.KeyFrameRate = Value
Value = Object.KeyFrameRate

LastError Property

Description Returns the error code from the last IDEA library call which returned a
non-zero error. May be passed to the GetErrorText method to obtain a
displayable message string.
Syntax Visual Basic
Value = Object.LastError

C++
short Value = Object.GetLastError()

MessageCaption Property

Description This property sets the caption to be displayed in message boxes

reported from the control.
Type string
Syntax Visual Basic
Object.MessageCaption = Value
C++
Object.SetMessageCaption(LPCTSTR Value)

NthBoardDescription Property

Description Returns a formatted string containing the board type, serial number,
and user-defined board name (if there is one) suitable for display,
based on the zero-based board index.

152 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Syntax Visual Basic

Value = Object.NthBoardDescription(Index as
Integer)

C++
CString Value =
Object.GetNthGetBoardDescription(short Index)

NthUserDefinedBoardName Property

Description Sets or returns a string containing a name or description for the board,
defined by the user, based on the zero-based board index.
Syntax Visual Basic
Value = Object.NthUserDefinedBoardName(Index as
Integer)

C++
CString Value =
Object.GetNthGetUserDefinedBoardName(short Index)

PixelType Property

Description Sets the output pixel type. Valid values are given in the table below
and are defined in ideaocx.h and ideaocx.bas. Values starting with
“PT_MONO” are valid only for mono boards; values starting with
“PT_COLOR” are valid only for color boards.
Type long
Syntax Visual Basic
Object.PixelType = Value
Value = Object.PixelType
C++
Object.SetPixelType(long Value)
long Value = Object.GetPixelType( )
Pixel Type Values
Value Constant Description
0 PT_MONO_GRAY_8 8 Bit Grayscale
1 PT_MONO_GRAY_10 10 Bit Grayscale
2 PT_MONO_RGB3CH 24 Bit RGB (3 Channel)
3 PT_COLOR_YCBCR_YONLY 8 Bit Grayscale

IDEA SDK User’s Guide 153

Chapter 5:
ActiveX Function Listings

4 PT_COLOR_YCBCR YCbCr 4:2:2

5 PT_COLOR_RGB32 32 Bit RGB
6 PT_COLOR_RGB24 24 Bit RGB
7 PT_COLOR_RGB16_565 NOT SUPPORTED
8 PT_COLOR_RGB16_555 16 Bit RGB (5-5-5)
9 PT_COLOR_WEBSAFE_PALETTE 8 bit color with a web safe
palette
10 PT_YPBPR_YONLY YPbPr input, Y Only output
11 PT_YPBPR_YCBCR YPbPr input YCbCr output
12 PT_YPBPR_RGB32 YPbPr input RGB 32 output
13 PT_YPBPR_RGB24 YPbPr input RGB 24 output
14 PT_YPBPR_RGB16_565 YPbPr input RGB 565 output
15 PT_YPBPR_RGB15_555 YPbPr input RGB 555 output
16 PT_YPBPR_RGB8_WEBSAFE_PALE YPbPr input, 8 bit web safe
TTE color output

RegistrySection Property

Description This property sets the name of an arbitrary section, or location, in the
registry, for the storage of information. The default section is
"Applications". Best results will likely be achieved by setting this
property before calling the "Open" method.
Type string
Syntax Visual Basic
Object.RegistrySection = Value
C++
Object.SetRegistrySection(LPCTSTR Value)

SaveToJpegQuality Property

Description Sets or returns the quality factor that will be used when saving a
snapped image to a JPEG file, using the SaveImageToFile method.
Type long
Syntax Visual Basic
Object.SaveToJpegQuality = Value
Value = Object.SaveToJpegQuality

154 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

C++
Object.SetSaveToJpegQuality(long Value)
long Value = Object.GetSaveToJpegQuality( )

Saturation Property

Description Changes or retrieves the saturation of the incoming image. The value
is in the range of 0 to 255. For AccuStream 50a, 75a, and 205a boards.
Type long
Syntax Visual Basic
Object.Saturation = Value
C++
Object.SetSaturation(long Value)
Value = Object.GetSaturation( )

SequenceCount Property

Description Tells the object how many frames to snap when performing a
SnapSequence operation.
Type long
Syntax Visual Basic
Object.SequenceCount = Value
C++
Object.SetSequenceCount(long Value)
Value = Object.GetSequenceCount( )

SequenceGrabDelay Property

Description Controls the number of milliseconds that should be delayed between

grabs when doing sequential grabs. This property is only used when
the SequenceCount property has a value of greater than 1.
Type long
Syntax Visual Basic
Object.SequenceGrabDelay = Value
C++
Object.SequenceGrabDelay(long Value)

IDEA SDK User’s Guide 155

Chapter 5:
ActiveX Function Listings
Value = Object.GetSequenceGrabDelay( )

SerialNumber Property

Description Shows the board serial number. This is passed as a string and is useful
for identification purposes only. This is a READ-ONLY property that is
filled in by the OCX when the board-handle is determined.
Type string
Syntax Visual Basic
Value = Object.SerialNumber
C++
CString Value = Object.GetSerialNumber( )

SnappedImageOrientation Property

Description Determines the orientation of the snapped image, whether normal or

vertically flipped (upside-down). In some cases, this property may be
used to correct an image which is flipped undesirably, such as for non-
DIB formats. This property determines the orientation of the image by
controlling the order of data transfer from the hardware, so there is
no performance loss no matter which way the property is set.
Type long
Syntax Visual Basic
Object.SnappedImageOrientation = Value
Value = Object.SnappedImageOrientation
C++
Object.SetSnappedImageOrientation(long Value)
long Value = Object.GetSnappedImageOrientation( )
Setting
Value Constant Description
0 ORIENTATION_NORMAL Right-side-up
1 ORIENTATION_VFLIP Upside-down

SnapFieldMode Property

Description Determines the type of the snap whether it’s the even field, odd field
or both.

156 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Type long
Syntax Visual Basic
Object.SnapFieldMode = Value
Value = Object.SnapFieldMode
C++
Object.SetSnapFieldMode (long Value)
long Value = Object.GetSnapFieldMode( )
Setting

NOTE: The only currently accepted value for this is 0 (zero), which indicates a full
frame of video is to be captured.

Value Constant Description

0 IMA_FRAME Full Frame
1 IMA_EFIELD Even Field
2 IMA_OFIELD Odd Field

StreamingBuffers Property

Description Changes or retrieves the number of buffers to use for streaming. The
number of buffers to use should be enough to hold all streamed frames
that have not yet been written to disk, i.e., enough to cover the
maximum lag in frames between streaming and writing to disk. There
must be enough lockable memory available to allocate that many
buffers. If there are too many buffers, the allocation will fail. If there
are too few buffers, frames will be dropped. The default is 16 buffers.
Type long
Syntax Visual Basic
Object.StreamingBuffers = Value
C++
Object.SetStreamingBuffers(long Value)
long Value = Object.GetStreamingBuffers( )

StreamingLogFile Property

Description Sets or gets the pathname of the log file to use while recording
streaming video. This log file may be used by Technical Support to
diagnose problems that may occur during streaming. The default is an
empty string which means to not use logging.

IDEA SDK User’s Guide 157

Chapter 5:
ActiveX Function Listings

Type string
Syntax Visual Basic
Object.StreamingLogFile = Value
Value = Object.StreamingLogFile
C++
Object.SetStreamingLogFile(LPCTSTR Value)
CString Value = Object.GetStreamingLogFile( )

SuspendMode Property

Description Sets or gets a value indicating whether the control is in suspend mode.
Setting this value = 1 will put the control into suspend mode, which is
equivalent to calling the Close method, except that the currently
selected board is still claimed. While in suspend mode, functions in
the IDEA Tools Library may be called using the board handle retrieved
from the BoardHandle property.
Setting this value = 0 will take the control out of suspend mode, which
is equivalent to calling the Open method, except that it is assumed
that the currently selected board is already claimed.
Type long
Syntax Visual Basic
Object.SuspendMode = Value
Value = Object.SuspendMode
C++
Object.SetSuspendMode(long Value)
long Value = Object.GetSuspendMode( )

SyncChannel Property

Description Changes the sync source. May cause the entire video parameter set to
be reinitialized. This is not applicable to I-Color, I-RGB or AccuStream
boards. This property is ignored if the UseSyncChannelFromCHP
property is non-zero.
Type long
Syntax Visual Basic
Object.SyncChannel = Value
C++
Object.SetSyncChannel(long Value)
Value = Object.GetSyncChannel( )

158 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Setting Value Constant Description

0 HDCHAN_CA1 Composite Video, analog channel 1

1 HDCHAN_CA2 Composite Video, analog channel 2

2 HDCHAN_CA3 Composite Video, analog channel 3

3 HDCHAN_CA4 Composite Video, analog channel 4

4 HDCHAN_SS12 Separated horizontal and vertical

sync, neither inverted. Horizontal on
CT1, Vertical on CT2
5 HDCHAN_SS12H Separated sync on CT1 and CT2,
Horizontal inverted
6 HDCHAN_SS12V Separated sync on CT1 and CT2,
Vertical inverted
7 HDCHAN_SS12I Separated sync on CT1 and CT2, both
inverted
8 HDCHAN_CT1 Composite sync on channel CT1

9 HDCHAN_CT2 Composite sync on channel CT2

10 HDCHAN_CT3 Composite sync on channel CT3

11 HDCHAN_CT4 Composite sync on channel CT4

12 HDCHAN_CT1I Composite sync on channel CT1,

inverted
13 HDCHAN_CT2I Composite sync on channel CT2,
inverted
14 HDCHAN_CT3I Composite sync on channel CT3,
inverted
15 HDCHAN_CT4I Composite sync on channel CT4,
inverted

TriggerStartFrameDelay Property

Description Sets or returns the trigger delay value. This is the number of frames to
wait before initiating stream capture, after a trigger has been
encountered.
Type long
Syntax Visual Basic
Object.TriggerStartFrameDelay = Value
C++

IDEA SDK User’s Guide 159

Chapter 5:
ActiveX Function Listings
Object.SetTriggerStartFrameDelay(long Value)
long Value = Object.GetTriggerDelay( )

TriggerStopFrameDelay Property

Description Sets or returns the trigger delay value. This is the number of frames to
wait before terminating stream capture, after a trigger has been
encountered.
Type long
Syntax Visual Basic
Object.TriggerStopFrameDelay = Value
C++
Object.SetTriggerStopFrameDelay(long Value)
long Value = Object.GetTriggerStopFrameDelay( )

TriggerFilterTime Property

Description Sets or returns the trigger filter time value for triggered streaming.
This feature should significantly reduce reliability problems often
encountered with mechanical trigger switches. The trigger filter time
is the amount of time (in microseconds) that a trigger pulse must be
held to be considered valid. A value of at least 25000 is
recommended. A value of 0 will disable this feature.
To set the trigger filter time from the Configuration Dialog screen,
bring up the Streaming Options tab and enter a value in the "Trigger
Filter Time" text box in the Triggering group box.
Type long
Syntax Visual Basic
Object.TriggerFilterTime = Value as long
Value = Object.TriggerFilterTime

160 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

TriggerMethod Property

Description Sets or returns the trigger method value for triggered snaps (0 =
trigger on falling edge, 1 = trigger on rising edge).
Type long
Syntax Visual Basic
Object.TriggerMethod = Value
C++
Object.SetTriggerMethod(long Value)
long Value = Object.GetTriggerMethod( )

TriggeredStreaming Property

Description Sets or returns the trigger value for triggered streaming. In the
configuration dialog, these five options are available as radio buttons
on the "Streaming Options" page.
The "start/stop" options make the trigger act like a "click" switch that
takes effect when the user presses and releases. The "run" options
make the trigger act like a "hold" switch that runs when the user
presses it and stops when the user releases it (or vice versa).
The "low/high" options allow control of the trigger polarity.
These options may be used in conjunction with the trigger input BNC
on the standard cables. For custom cabling, the trigger input must be
on pin 4, with a ground connection on any one of pins 8, 9, 11, 12, 20,
or 23.
Type long
Syntax Visual Basic
Object.TriggeredStreaming = Value
C++
Object.SetTriggeredStreaming(long Value)
long Value = Object.GetTriggeredStreaming( )

Setting Value Constant Description

0 TRIGGER_OFF Off

1 TRIGGER_START_STOP_LOW Start/stop when going

low
2 TRIGGER_START_STOP_LOW Start/stop when going
high

IDEA SDK User’s Guide 161

Chapter 5:
ActiveX Function Listings

3 TRIGGER_RUN_LOW Run while low

4 TRIGGER_RUN_HIGH Run while high

UseSyncChannelFromCHP Property

Description Tells the control whether to use the SyncChannel property or the sync
channel value in the CHP file. This flag should be set to 1 if using the
sync channel value in the CHP file or 0 if using the SyncChannel
property.
Type long
Syntax Visual Basic
Object.UseSyncChannelFromCHP = Value
C++
Object.SetUseSyncChannelFromCHP(long Value)
long Value = Object.GetUseSyncChannelFromCHP( )

UseTriggers Property

Description Changes or retrieves the triggering state. This flag should be set to 1 if
using triggering or 0 if not using triggering.
Type long
Syntax Visual Basic
Object.UseTriggers = Value
C++
Object.SetUseTriggers(long Value)
long Value = Object.GetUseTriggers( )

Verbosity Property

Description Changes or retrieves the message reporting state. Valid values for this
property are given in the table below and defined in ideaocx.h and
ideaocx.bas. This property affects displayed items only, not written
files such as log files.
Type long

162 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Syntax Visual Basic

Object.Verbosity = Value
C++
Object.SetVerbosity(long Value)
long Value = Object.GetVerbosity( )

Verbosity
Value Constant Description
0 VERBOSITY_SILENT Silent mode: show nothing
1 VERBOSITY_DIALOGS Show dialogs only, if asked
2 VERBOSITY_ERRORS Show dialogs and errors
3 VERBOSITY_WARNINGS Show dialogs, errors, warnings
4 VERBOSITY_INFO Show everything, including
diagnostic information

VesaChpPath Property

Description Sets or returns the pathname of the CHP file created by or to be

created by VESA detection.
Type string
Syntax Visual Basic
Object.VesaChpPath = Value
Value = Object.VesaChpPath
C++
Object.SetVesaChpPath(LPCTSTR Value)
CString Value = Object.GetVesaChpPath( )

VideoChannel Property

Description Changes the video input channel. May cause the entire video
parameter set to be reinitialized.
Type long
Syntax Visual Basic
Object.VideoChannel = Value
C++
Object.SetVideoChannel(long Value)
Value = Object.GetVideoChannel( )

IDEA SDK User’s Guide 163

Chapter 5:
ActiveX Function Listings

Setting Value Constant Description

0 HDCHAN_CA1 Analog channel 1

1 HDCHAN_CA2 Analog channel 2

2 HDCHAN_CA3 Analog channel 3

3 HDCHAN_CA4 Analog channel 4

0 SVIDEO_1 I-Color S-Video1

1 SVIDEO_2 I-Color S-Video2

2 COMPOSITE_1 I-Color Composite1

3 COMPOSITE_2 I-Color Composite2

4 COMPOSITE_3 I-Color Composite3

5 COMPOSITE_4 I-Color Composite4

Methods

AbortTrigger Method

NOTE: This method is currently implemented the same as ForceTrigger. The

currently pending triggered grab will be completed, not aborted.

Description This function will abort a triggered grab if it is pending. This feature
may be useful if a hardware trigger mechanism is unavailable or not
working.
Return Value none
Syntax Visual Basic
Object.AbortTrigger( )

C++
Object.AbortTrigger( )

AboutBox Method

Description Displays an “About” box containing support, version, copyright, and

other useful information.

164 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Return Value None.

Close Method

Description Closes access to the board. All resources associated with the board are
released.
Return Value A boolean is returned. The value is TRUE if the board was previously
opened and no errors occurred while deallocating resources. It returns
FALSE if the board was not previously opened or some error occurred
while deallocating resources.

CodecAbout Method

Description Displays a dialog for viewing information about the currently selected
CODEC, if any, for streaming. The dialog is provided by the CODEC
itself, and may or may not exist. Use the CodecHasAbout method to
determine whether the CODEC has an about dialog.
Return Value None.

CodecChooseByFormat Method

Description Displays a dialog for viewing a list of the CODECs currently installed on
the system that will work for the currently selected Pixel Type. The
dialog also allows the user to choose one of those CODECs, and, if
chosen, stores its DLL name and FourCC code in the CodecDLL and
CodecFourCCType properties and automatically calls the CodecLoad
method for them. Returns TRUE if successful.
Return Value Boolean.

CodecChooseFromList Method

Description Displays a dialog for viewing a list of all CODECs currently installed on
the system. The dialog also allows the user to choose one of those
CODECs, and, if chosen, stores its DLL name and FourCC code in the
CodecDLL and CodecFourCCType properties and automatically calls
the CodecLoad method for them. Returns TRUE if successful.
Return Value Boolean.

IDEA SDK User’s Guide 165

Chapter 5:
ActiveX Function Listings

CodecConfigure Method

Description Displays a dialog for setting and configuring the currently selected
CODEC, if any, for streaming. The dialog is provided by the CODEC
itself, and may or may not exist. Use the CodecHasConfigure method
to determine whether the CODEC has a configuration dialog.
Return Value None.

CodecHasAbout Method

Description Returns TRUE if the currently selected CODEC has an about dialog that
can be displayed using the CodecAbout method.
Return Value Boolean.

CodecHasConfigure Method

Description Returns TRUE if the currently selected CODEC has a configuration

dialog that can be displayed using the CodecConfigure method.
Return Value Boolean.

CodecLoad Method

Description Prepares the IdeaFG control for compressed streaming by loading the
specified Codec DLL and FourCC code. The current values can be
obtained from the CodecDLL and CodecFourCCType properties.
Parameters CodecDLL Specifies the path to the DLL containing a user-
defined CODEC for compressing streamed data. This
should be set to an empty string (default) if not using
a CODEC (if streaming uncompressed).
CodecFourCC Specifies the FourCC code used by the CODEC for
compressing streamed data. This should be set to the
result of a macro to create a FourCC code, e.g.,
MmioFOURCC(‘M’,’J’,’P’,’G’) for motion JPEG, or
MmioFOURCC(‘D’,’I’,’B’,’ ‘) for uncompressed.
Return Value A Boolean indicating whether or not the operation completed
successfully
Syntax Visual Basic

166 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings
Object.CodecLoad(CodecDLL as String, CodecFourCC as
Long)
C++
Object.CodecLoad(LPCTSTR CodecDLL, long CodecFourCC)

ForceTrigger Method

Description This function will cause a software-generated trigger if a triggered

grab is pending. This feature may be useful if a hardware trigger
mechanism is unavailable or not working.
Return Value none
Syntax Visual Basic
Object.ForceTrigger( )
C++
Object.ForceTrigger( )

GetBlackLevel Method

Description Returns the black level value.

Return Value long
Syntax Visual Basic
Value = Object.GetBlackLevel
C++
long Value = Object.GetBlackLevel( )

GetBlackReference Method

Description Returns the black reference value.

Return Value long
Syntax Visual Basic

IDEA SDK User’s Guide 167

Chapter 5:
ActiveX Function Listings
Value = Object.GetBlackReference
C++
long Value = Object.GetBlackReference( )

GetBoardType Method

Description Returns the type of the currently selected board as a long integer.
Return Value long
Syntax Visual Basic
Value = Object.GetBoardType
C++
long Value = Object.GetBoardType( )

GetBoardTypeString Method

Description Returns the type of the currently selected board as a string.

Return Value string
Syntax Visual Basic
Value = Object.GetBoardTypeString
C++
CString Value = Object.GetBoardTypeString( )

GetBuffer Method

Description This method is used to retrieve a buffer from the ring of buffers
created during StreamToMemory. The method returns a VARIANT
containing a SAFEARRAY of BYTEs containing the raw image data of
the specified frame.
Parameters MemoryHandle The handle to the memory buffers returned from a
particular call to the StreamToMemory method, or from the
StreamToDicom or StreamToAvi method with the 0x0040 flag turned
on.
FrameNumber The number of the frame to return from the
set of buffers.

168 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

GetCableTypeListIRGB Method

Description Returns the I-RGB cable type corresponding to the given index, as a
string. This method is useful for loading an edit box dialog or other list
with entries for selecting cable types.
Return Value string
Parameters Index A short integer from 0 to the maximum number of cable types
- 1. Use the GetNumberOfCableTypesIRGB method to get the
maximum number of cable types.
Syntax Visual Basic
Value = Object.GetCableTypeListIRGB(Index as Integer)
C++
CString Value = Object.GetCableTypeListIRGB(short Index)

GetErrorText Method

Description Returns a displayable string corresponding to an error code.

Parameter ErrorCode Specifies an error code returned from a call to an
IDEA library or tools library function, or from the LastError property,
or from an OnNotificationMessage event.
Return Value string
Syntax Visual Basic
Value = Object.GetErrorText
C++
CString Value = Object.GetErrorText( )

GetGain Method

Description Returns the gain value.

Return Value long
Syntax Visual Basic

IDEA SDK User’s Guide 169

Chapter 5:
ActiveX Function Listings
Value = Object.GetGain
C++
long Value = Object.GetGain( )

GetHistogram Method

Description Returns a pointer to a VARIANT containing a SAFEARRAY of long

integers containing the histogram data from the last image snapped.
Parameters long * NumPoints Pointer to a long that is to receive the number of
data points returned in the histogram, that is, the size of the
SAFEARRAY
Return Value VARIANT

GetHorizontalPosition Method

Description Returns the horizontal position value.

Return Value long
Syntax Visual Basic
Value = Object.GetHorizontalPosition
C++
long Value = Object.GetHorizontalPosition( )

GetHorzBackPorch Method

Description Returns the horizontal back porch value.

Return Value long
Syntax Visual Basic
Value = Object.GetHorzBackPorch
C++
long Value = Object.GetHorzBackPorch( )

GetHorzBackSync Method

Description Returns the horizontal back sync value.

Return Value long
Syntax Visual Basic

170 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings
Value = Object.GetHorzBackSync
C++
long Value = Object.GetHorzBackSync( )

GetHorzFrequency Method

Description Returns the horizontal frequency value.

Return Value long
Syntax Visual Basic
Value = Object.GetHorzFrequency
C++
long Value = Object.GetHorzFrequency( )

GetHorzStart Method

Description Returns the horizontal start value.

Return Value long
Syntax Visual Basic
Value = Object.GetHorzStart
C++
long Value = Object.GetHorzStart( )

GetHorzSyncWidth Method

Description Returns the horizontal sync width value.

Return Value long
Syntax Visual Basic
Value = Object.GetHorzSyncWidth
C++
long Value = Object.GetHorzSyncWidth( )

GetHorzTotal Method

Description Returns the horizontal total value.

Return Value long

IDEA SDK User’s Guide 171

Chapter 5:
ActiveX Function Listings

Syntax Visual Basic

Value = Object.GetHorzTotal
C++
long Value = Object.GetHorzTotal( )

GetImageDIB Method

Description Returns a handle to the current bitmap. This is a DIB formatted

bitmap containing data from the last image snapped. The actual
format of the bitmap depends on the pixel type and the pixel size.
You can use the returned HBITMAP to display the image, or to save the
image to a file.
Return Value A long, which should be cast to a HBITMAP.

GetImageHandle Method

Description Returns the ImageHandle which may be subsequently used to call

directly to IDEA API functions.
Return Value long

GetImageHeight Method

Description Returns the height of the image in the video signal, in pixels. To get
the height of the image for the purpose of buffer allocation, display
window dimensions, etc., use the specific methods GetLiveHeight,
GetSnapHeight, or GetStreamHeight, as appropriate. Those methods
give the actual size after taking into account adjustments for vertical
decimation, AOI, etc.
Return Value long

GetImagePicture Method

Description Returns a pointer to a picture object containing DIB formatted data

from the last image snapped. The returned pointer is an OLE picture
as created by OleCreatePictureIndirect( ). This picture object can be
placed in a Visual Basic or Visual C++ Picture Object.
Return Value LPPICTUREDISP

172 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

GetImageSizeInBytes Method

Description Returns the number of bytes needed to hold the last image snapped at
the currently selected pixel format.
Return Value long

GetImageWidth Method

Description Returns the width of the image in the video signal, in pixels. To get
the width of the image for the purpose of buffer allocation, display
window dimensions, etc., use the specific methods GetLiveWidth,
GetSnapWidth, or GetStreamWidth, as appropriate. Those methods
give the actual size after taking into account adjustments for
horizontal decimation, AOI, etc.
Return Value long

GetIndex Method

Description Returns the index of the board with the given serial number.
Return Value long

GetInterlace Method

Description Returns the interlace setting.

Return Value long
Syntax Visual Basic
Value = Object.GetInterlace
C++
long Value = Object.GetInterlace( )

GetLiveAOI Method

Description Returns the four values, or coordinates, defining a rectangular area of

interest (AOI) of the image to be used for live display. Default values
are Left=0, Right=0, Top=0, Bottom=0, meaning the AOI is the entire
image. AOI is always determined and applied before any horizontal
and/or vertical decimation. Be sure to use the GetLiveHeight and

IDEA SDK User’s Guide 173

Chapter 5:
ActiveX Function Listings

GetLiveWidth methods to obtain the height and width of the image for
live display.
Return Value none
Parameters long *Left, long *Right, long *Top, long *Bottom
Left is the distance, in pixels of the AOI from the left side of the
image. Valid values are from 0 to the width of the original image.
Right is the distance, in pixels of the AOI from the right side of the
image. Valid values are from 0 to the width of the original image.
Top is the distance, in pixels of the AOI from the top of the image.
Valid values are from 0 to the height of the original image.
Bottom is the distance, in pixels of the AOI from the bottom of the
image. Valid values are from 0 to the height of the original image.
Syntax Visual Basic
Object.GetLiveAOI ByRef Left As Long, ByRef Right As
Long, ByRef Top As Long, ByRef Bottom As Long
C++
Object.GetLiveAOI(long *Left, long *Right, long *Top,
long *Bottom)

GetLiveHeight Method

Description Returns the height of the image for live display. This method takes
into account any differences from the original size of the image in the
source video signal, such as decimation, AOI, etc.
Return Value long
Syntax Visual Basic
Value = Object.GetLiveHeight
C++
long Value = Object.GetLiveHeight( )

GetLiveWidth Method

Description Returns the width of the image for live display. This method takes into
account any differences from the original size of the image in the
source video signal, such as decimation, AOI, etc.
Return Value long
Syntax Visual Basic

174 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings
Value = Object.GetLiveWidth
C++
long Value = Object.GetLiveWidth( )

GetNthBoardType Method

Description Returns a board type based on the zero-based board index. This allows
the application to step through all of the boards in the system to find
a particular board.
Syntax Visual Basic
Value = Object.GetNthBoardType(Index as Integer)
C++
long Value = Object.GetNthBoardType(short Index)

GetNthBoardTypeString Method

Description Returns a string representing the board type based on the zero-based
board index.
Syntax Visual Basic
Value = Object.GetNthBoardTypeString(Index as Integer)
C++
CString Value = Object.GetNthBoardTypeString(short
Index)

GetNthSerialNumber Method

Description Returns a board’s serial number string based on the zero-based board
index. This allows the application to step through all of the boards in
the system to find a particular board.
Syntax Visual Basic

IDEA SDK User’s Guide 175

Chapter 5:
ActiveX Function Listings
Value = Object.GetNthSerialNumber(Index as Integer)
C++
CString Value = Object. GetNthSerialNumber(short Index)

GetNumberOfCableTypesIRGB Method

Description Returns the maximum number of cable types. Usually this will be 3 for
VGA, BNC, DVI but it may be more.
Return Value long
Syntax Visual Basic
Value = Object.GetNumberOfCableTypesIRGB
C++
long Value = Object.GetNumberOfCableTypesIRGB( )

GetOutputFormat Method

Description Returns the output format value.

Return Value long
Syntax Visual Basic
Value = Object.GetOutputFormat
C++
long Value = Object.GetOutputFormat( )

GetPassMode Method

Description Returns the pass mode. This should always be single pass since no
currently supported Foresight boards implement dual-pass.
Return Value long
Syntax Visual Basic
Value = Object.GetPassMode
C++
long Value = Object.GetPassMode( )

GetPhaseDelay Method

Description Returns the phase delay value.

176 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Return Value long

Syntax Visual Basic
Value = Object.GetPhaseDelay
C++
long Value = Object.GetPhaseDelay( )

GetPitch Method

Description Returns the pitch value.

Return Value long
Syntax Visual Basic
Value = Object.GetPitch
C++
long Value = Object.GetPitch( )

GetPixelData Method

Description Returns a pointer to a VARIANT containing a SAFEARRAY of BYTEs

containing the raw data from the last image snapped.
Return Value VARIANT

GetSerialNumber Method

Description Returns the serial number of the currently selected board as a string.
Return Value string
Syntax Visual Basic
Value = Object.GetSerialNumber
C++
CString Value = Object.GetSerialNumber( )

GetSnapAOI Method

Description Returns the four values, or coordinates, defining a rectangular area of

interest (AOI) of the image to be used for snapping images. Default
values are Left=0, Right=0, Top=0, Bottom=0, meaning the AOI is the
entire image. AOI is always determined and applied before any
horizontal and/or vertical decimation. Be sure to use the

IDEA SDK User’s Guide 177

Chapter 5:
ActiveX Function Listings

GetSnapHeight and GetSnapWidth methods to obtain the height and

width of the image for snaps.
Return Value none
Parameters long *Left, long *Right, long *Top, long *Bottom
Left is the distance, in pixels of the AOI from the left side of the
image. Valid values are from 0 to the width of the original image.
Right is the distance, in pixels of the AOI from the right side of the
image. Valid values are from 0 to the width of the original image.
Top is the distance, in pixels of the AOI from the top of the image.
Valid values are from 0 to the height of the original image.
Bottom is the distance, in pixels of the AOI from the bottom of the
image. Valid values are from 0 to the height of the original image.
Syntax Visual Basic
Object.GetSnapAOI ByRef Left As Long, ByRef Right As
Long, ByRef Top As Long, ByRef Bottom As Long
C++
Object.GetSnapAOI(long *Left, long *Right, long *Top,
long *Bottom)

GetSnapHeight Method

Description Returns the height of the image for snaps. This method takes into
account any differences from the original size of the image in the
source video signal, such as decimation, AOI, etc.
Return Value long
Syntax Visual Basic
Value = Object.GetSnapHeight
C++
long Value = Object.GetSnapHeight( )

GetSnapWidth Method

Description Returns the width of the image for snaps. This method takes into
account any differences from the original size of the image in the
source video signal, such as decimation, AOI, etc.
Return Value long
Syntax Visual Basic

178 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings
Value = Object.GetSnapWidth
C++
long Value = Object.GetSnapWidth( )

GetStreamAOI Method

Description Returns the four values, or coordinates, defining a rectangular area of

interest (AOI) of the image to be used for streaming. Default values
are Left=0, Right=0, Top=0, Bottom=0, meaning the AOI is the entire
image. AOI is always determined and applied before any horizontal
and/or vertical decimation. Be sure to use the GetStreamHeight and
GetStreamWidth methods to obtain the height and width of the image
for streaming.
Return Value none
Parameters long *Left, long *Right, long *Top, long *Bottom
Left is the distance, in pixels of the AOI from the left side of the
image. Valid values are from 0 to the width of the original image.
Right is the distance, in pixels of the AOI from the right side of the
image. Valid values are from 0 to the width of the original image.
Top is the distance, in pixels of the AOI from the top of the image.
Valid values are from 0 to the height of the original image.
Bottom is the distance, in pixels of the AOI from the bottom of the
image. Valid values are from 0 to the height of the original image.
Syntax Visual Basic
Object.GetStreamAOI ByRef Left As Long, ByRef Right As
Long, ByRef Top As Long, ByRef Bottom As Long
C++
Object.GetStreamAOI(long *Left, long *Right, long *Top,
long *Bottom)

GetStreamHeight Method

Description Returns the height of the image for streaming. This method takes into
account any differences from the original size of the image in the
source video signal, such as decimation, AOI, etc.
Return Value long
Syntax Visual Basic

IDEA SDK User’s Guide 179

Chapter 5:
ActiveX Function Listings
Value = Object.GetStreamHeight
C++
long Value = Object.GetStreamHeight( )

GetStreamWidth Method

Description Returns the width of the image for streaming. This method takes into
account any differences from the original size of the image in the
source video signal, such as decimation, AOI, etc.
Return Value long
Syntax Visual Basic
Value = Object.GetStreamWidth
C++
long Value = Object.GetStreamWidth( )

GetVertBackPorch Method

Description Returns the vertical back porch value.

Return Value long
Syntax Visual Basic
Value = Object.GetVertBackPorch
C++
long Value = Object.GetVertBackPorch( )

GetVertStart Method

Description Returns the vertical start value.

Return Value long
Syntax Visual Basic
Value = Object.GetVertStart
C++
long Value = Object.GetVertStart( )

GetVertSyncType Method

Description Returns the vertical sync type value.

180 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Return Value long

Syntax Visual Basic
Value = Object.GetVertSyncType
C++
long Value = Object.GetVertSyncType( )

GetVertTotal Method

Description Returns the vertical total value.

Return Value long
Syntax Visual Basic
Value = Object.GetVertTotal
C++
long Value = Object.GetVertTotal( )

GetVideoFormat Method

Description Returns the video format string.

Return Value string
Syntax Visual Basic
Value = Object.GetVideoFormat
C++
CString Value = Object.GetVideoFormat( )

GetWhiteReference Method

Description Returns the white reference value.

Return Value long
Syntax Visual Basic

IDEA SDK User’s Guide 181

Chapter 5:
ActiveX Function Listings
Value = Object.GetWhiteReference
C++
long Value = Object.GetWhiteReference( )

InitRgb3 Method

Description Allows the user to programmatically initialize the parameters for an

Rgb3 grab. The application can specify that the parameters can come
from the registry. There will be a way through the properties to also
specify this action. This method should not be used with an I-Color, I-
RGB or AccuStream frame grabbers.
Call InitRgb3(long UseRegistry, LPCTSTR RPath, LPCTSTR GPath, LPCTSTR
BPath, long SyncChan)
Parameters UseRegistry 1 = Read paths to R, G and B channel from the
registry. 0 = Use RPath, GPath, and BPath for CHP
files.
RPath Path to the CHP file for the Red channel.
GPath Path to the CHP file for the Green channel.
BPath Path to the CHP file for the Blue channel.
SyncChan Channel where sync can be found. If this is not
specified, then the sync channel must come from the
register set.
Example Application calls to retrieve the paths to the separate video channels:
r$ = GetChpPath(0)
g$ = GetChpPath(1)
b$ = GetChpPath(2)
Initialize for an RGB grab; sync can be found on CT1:
LiveVideoEnabled = IdeaFG1.InitRgb3(False, r$, g$, b$,
8)

IsColorBoard Method

Description Returns a boolean value indicating whether the current board is color
or monochrome.
Return Value True if the current board is a color board. False if the current board is
a monochrome board (e.g., I-Series).

182 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

IsDigitalBoard Method

Description Returns a boolean value indicating whether the currently selected

board is a digital AccuStream board (TRUE) or not a digital AccuStream
board (FALSE).
Return Value True if the current board is a digital AccuStream board. FALSE if the
current board is not a digital AccuStream board.

IsHighSpeedRGBBoard Method

Description Returns a boolean value indicating whether the currently selected

board is a high-speed AccuStream board (TRUE) or not a high-speed
AccuStream board (FALSE).
Return Value True if the current board is a high-speed AccuStream board. FALSE if
the current board is not a high-speed AccuStream board.

IsMonoBoard Method

Description Returns a boolean value indicating whether the currently selected

board is a monochrome capture board (TRUE) or not a mono board
(FALSE).
Return Value True if the current board is a monochrome capture board. FALSE if the
current board is not a mono board.

IsRGBBoard Method

Description Returns a boolean value indicating whether the currently selected

board is an AccuStream board (TRUE) or not an AccuStream board
(FALSE).
Return Value True if the current board is an AccuStream board. FALSE if the current
board is not an AccuStream board.

IDEA SDK User’s Guide 183

Chapter 5:
ActiveX Function Listings

IsStreamingBoard Method

Description Returns a boolean value indicating whether the currently selected

board is a streaming board (TRUE) or not a streaming board (FALSE). A
streaming board is a board that is capable of streaming video and
direct draw live display.
Return Value True if the current board is a streaming board. FALSE if the current
board is not a streaming board.

Is64BitBoard

Description Returns a boolean value indicating whether the currently selected

board is a capable of 64 bit transfers.
Return Value True if the current board is capable of 64 bit transfers. FALSE if the
current board is not a 64 bit board.

IsVideoDetected Method

Description Returns a Boolean based on whether or not video is detected on the

currently specified video channel/sync channel combination.
Depending on the type of board, this operation may perform an image
snap, so it should be considered to be a destructive operation.
Return Value True if sync is detected on the given video/sync channel combination.
False if sync is not detected.

IsYPbPrInput

Description Returns a Boolean based on whether or not input signal is a YPbPr

format.
Return Value True if sync is detected on the given video/sync channel combination.
False if sync is not detected.

LiveVideo Method

Description Starts/stops the display of live video in the IdeaDisplay window whose
handle was passed in a previous call to SetDisplayWindow. LiveVideo

184 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

will attempt to display using Direct Draw, but will use GDI (sequential
snaps) for display if Direct Draw fails. Performance may be
unacceptably slow when using GDI.
If Direct Draw live video is already started when this method is called
and the StartLive parameter is non-zero, this will be interpreted to
mean the caller wishes to update or repaint the display window.
Parameters StartLive 0 = stop live video, non-zero = start live video.
Return Value A Boolean indicating whether or not the method was successful.

Open Method

Description Takes a handle as returned in the GetDeviceInfo call and defined in

the BoardHandle property and opens the board for access. Each
interface allows only one board to be open at a time. To access
multiple boards requires multiple interface pointers, or a reset of the
board handle property. Only one interface may open a particular
board. Before calling "Open", the application may need to test the
"BoardCount" property to see if there are any boards recognized, or to
set the "RegistrySection" property to create a unique location in the
registry for saving user settings.
Return Value A Boolean indicating whether or not the board is successfully opened.
Example Visual Basic
IdeaFG1.Open
C++
m_pIdeaFG = new CIdeaFG;
m_pIdeaFG->Create( “ “, 0, rcVideo, this, 0x100 );
if( m_pIdeaFG->Open( ) == FALSE ) {
AfxMessageBox( “Unable to open Foresight Imaging
frame grabber” );
return 0;
}

ReadConfigDword Method

Parameters LPCTSTR Name, long Default

Description This method may be used to retrieve, by name, an application-defined
numeric value in the registry, that is associated with the currently
selected board. A default value may be provided to be returned if
unable toretrieve the value from the registry.

IDEA SDK User’s Guide 185

Chapter 5:
ActiveX Function Listings

ReadConfigGlobalDword Method

Parameters LPCTSTR Name, long Default

Description This method may be used to retrieve, by name, an application-defined
numeric value in the registry, that is not associated with the currently
selected board. A default value may be provided to be returned if
unable to retrieve the value from the registry.

ReadConfigString Method

Parameters LPCTSTR Name, LPCTSTR Default

Description This method may be used to retrieve, by name, an application-defined
string value in the registry, that is associated with the currently
selected board. A default value may be provided to be returned if
unable to retrieve the value from the registry.

ReadConfigGlobalString Method

Parameters LPCTSTR Name, LPCTSTR Default

Description This method may be used to retrieve, by name, an application-defined
string value in the registry, that is not associated with the currently
selected board. A default value may be provided to be returned if
unable to retrieve the value from the registry.

ReadConfiguration Method

Parameters none
Description This method retrieves all of the predefined properties listed below,
plus the audio properties listed above, from the registry. From the
user dialog(s) for getting and setting these properties call this method
when the user selects "Cancel" to reset the values from the registry.

ReleaseAllBuffers Method

Description This method is used to free the memory resources of all buffers
previously allocated from all calls to the StreamToMemory method,
and from all calls to the StreamToDicom and StreamToAvi methods
with the 0x0040 flag turned on.

186 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Parameters none

ReleaseBuffers Method

Description This method is used to free the memory resources of buffers

previously allocated from a particular call to the StreamToMemory
method, or from the StreamToDicom and StreamToAvi method with
the 0x0040 flag turned on.
Parameters MemoryHandle The handle to the memory buffers returned from a
particular call to the StreamToMemory method, or from the
StreamToDicom or StreamToAvi method with the 0x0040 flag turned
on.

ResetBoard Method

Description Performs a “hard reset” of the currently selected board. This method
may be used in the case where the board has gotten into an
unresponsive state that could only otherwise be corrected by
rebooting the system. This could occur, for example, if there has been
a problem with the video source or cable resulting in a lockup. The
ResetBoard method will reload the board’s firmware and reinitialize
the software.
Return Value none
Syntax Visual Basic
Object.ResetBoard
C++
Object.ResetBoard( )

ResetBoardFast Method

Description Performs a “soft reset” of the currently selected board. This method
may be used in the case where the board has gotten into an
unresponsive state that could only otherwise be corrected by
rebooting the system. This could occur, for example, if there has been
a problem with the video source or cable resulting in a lockup. This
method merely clears the FIFO of the PCI interface chip and does not
reload the board’s FPGA.
Return Value none
Syntax Visual Basic

IDEA SDK User’s Guide 187

Chapter 5:
ActiveX Function Listings
Object.ResetBoardFast
C++
Object.ResetBoardFast( )

SaveImageToFile Method

Description Save an image to a file. Formats that can be saved include Windows
Bitmaps (BMP) and JPEG. For JPEG, use the SaveToJpegQuality property
to adjust the quality vs. file size tradeoff, or ignore it and accept the
default value which is generally considered quite reasonable.
Call SaveImageToFile(HBITMAP hbm, LPCSTR FilePath, Long FileType)
Parameters hbm If hbm is zero, then the control uses the last image
snapped. If the file type is BMP, the image will be saved
according to the currently selected pixel type (except
10-bit will be converted to 8-bit, and YCbCr will be
converted to 24-bit RGB).
If hbm is non-zero, it is assumed to be a handle to a DIB,
as returned from a call to the GetImageDIB method. In
this case, it will not be able to save the image exactly
according to the chosen pixel type. Instead, the image
will always be saved as 24-bit RGB.
FilePath Pathname of the destination file.
FileType Indicates the type of file to save. If FileType is a ‘–1’,
then the file type is extracted from the extension of the
file name. Currently supported values are
IIF_IMAGE_FORMAT_BMP and IIF_IMAGE_FORMAT_JPEG.
Example Visual Basic
Object.SaveImageToFile frm.DisplayImage.Picture.Handle,
“MyPict.BMP”, -1
C++
Object.SaveImageToFile(Picture.Handle, “MyPict.BMP”, -
1);

SavePixelDataToFile Method

Description Saves monochrome pixel data to a PNG file

Call saveOk = Object.SavePixelDataToFile( pvData, Width, Height, Bpp,
FilePath, Flags );
Parameters:
pvData Pointer to variant data. Usually this is created from
a call to GetPixelData and SafeArrayAccessData.

188 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Width The width of the image in pixels

Height The height of the image in scan lines
Bpp Bits per pixel, either 8 or 10.
FilePath Fully qualified path of the output PNG file.
Flags Unused, set to zero.
Return Value BOOL
Syntax Visual Basic
Value = Object.SavePixelDataToFile( data, w, h, bpp,
“pixeldat.png”, 0 )
C++
BOOL Value = Object.SavePixelDataToFile( pvdata, w, h, bpp, “pixeldat.png”,
0 )

SaveVideoSettings Method

Description Saves the current RSET values to the specified CHP file.
Return Value A Boolean indicating whether or not the save operation completed
successfully
Syntax Visual Basic
Object.SaveVideoSettings(Path as String, Comments as
String)
C++
Object.SaveVideoSettings(LPCTSTR Path, LPCTSTR Comments)

SetBlackLevel Method

Description Sets the black level value.

Return Value none
Syntax Visual Basic
Object.SetBlackLevel(Value as Long)
C++
Object.SetBlackLevel(long Value)

SetBlackReference Method

Description Sets the black reference value.

Return Value none

IDEA SDK User’s Guide 189

Chapter 5:
ActiveX Function Listings

Syntax Visual Basic

Object.SetBlackReference(Value as Long)
C++
Object.SetBlackReference(long Value)

SetDisplayWindow Method

Description Passes the handle of a CideaDisplay window to the frame grabber

control to enable continuous and automatic update of the display.
Return Value none
Syntax Visual Basic
Object.SetDisplayWindow(Value as Long)
C++
Object.SetDisplayWindow(long Value)

SetGain Method

Description Sets the gain value.

Return Value none
Syntax Visual Basic
Object.SetGain(Value as Long)
C++
Object.SetGain(long Value)

SetHorizontalPosition Method

Description Sets the horizontal position value.

Return Value none
Syntax Visual Basic

190 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings
Object.SetHorizontalPosition(Value as Long)
C++
Object.SetHorizontalPosition(long Value)

SetHorzBackPorch Method

Description Sets the horizontal back porch value.

Return Value none
Syntax Visual Basic
Object.SetHorzBackPorch(Value as Long)
C++
Object.SetHorzBackPorch(long Value)

SetHorzBackSync Method

Description Sets the horizontal back sync value.

Return Value none
Syntax Visual Basic
Object.SetHorzBackSync(Value as Long)
C++
Object.SetHorzBackSync(long Value)

SetHorzFrequency Method

Description Sets the horizontal frequency value.

Return Value none
Syntax Visual Basic
Object.SetHorzFrequency(Value as Long)
C++
Object.SetHorzFrequency(long Value)

SetHorzStart Method

Description Sets the horizontal start value.

Return Value none

IDEA SDK User’s Guide 191

Chapter 5:
ActiveX Function Listings

Syntax Visual Basic

Object.SetHorzStart(Value as Long)
C++
Object.SetHorzStart(long Value)

SetHorzSyncWidth Method

Description Sets the horizontal sync width value.

Return Value none
Syntax Visual Basic
Object.SetHorzSyncWidth(Value as Long)
C++
Object.SetHorzSyncWidth(long Value)

SetHorzTotal Method

Description Sets the horizontal total value.

Return Value none
Syntax Visual Basic
Object.SetHorzTotal(Value as Long)
C++
Object.SetHorzTotal(long Value)

SetImageHeight Method

Description Sets the image height value.

Return Value long
Syntax Visual Basic
Object.SetImageHeight(Value as Long)
C++
Object.SetImageHeight(long Value)

SetImageWidth Method

Description Sets the image width value.

Return Value long

192 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Syntax Visual Basic

Object.SetImageWidth(Value as Long)
C++
Object.SetImageWidth(long Value)

SetInterlace Method

Description Sets the interlace setting.

Return Value none
Syntax Visual Basic
Object.SetInterlace(Value as Long)
C++
Object.SetInterlace(long Value)

SetLiveAOI Method

Description Sets the four values, or coordinates, defining a rectangular area of

interest (AOI) of the image to be used for live display. Default values
are Left=0, Right=0, Top=0, Bottom=0, meaning the AOI is the entire
image. AOI is always determined and applied before any horizontal
and/or vertical decimation. Be sure to use the GetLiveHeight and
GetLiveWidth methods to obtain the height and width of the image for
live display. To selectively change only one or more of the four
coordinates, set the other coordinates that are not being changed to –
1.
Return Value none
Parameters long Left, long Right, long Top, long Bottom
Left is the distance, in pixels of the AOI from the left side of the
image. Valid values are from 0 to the width of the original image. A
value of –1 will leave this coordinate unchanged.
Right is the distance, in pixels of the AOI from the right side of the
image. Valid values are from 0 to the width of the original image. A
value of –1 will leave this coordinate unchanged.
Top is the distance, in pixels of the AOI from the top of the image.
Valid values are from 0 to the height of the original image. A value of
–1 will leave this coordinate unchanged.
Bottom is the distance, in pixels of the AOI from the bottom of the
image. Valid values are from 0 to the height of the original image. A
value of –1 will leave this coordinate unchanged.
Syntax Visual Basic

IDEA SDK User’s Guide 193

Chapter 5:
ActiveX Function Listings
Object.SetLiveAOI Left As Long, Right As Long, Top As
Long, Bottom As Long
C++
Object.SetLiveAOI(long Left, long Right, long Top, long
Bottom)

SetSnapAOI Method

Description Sets the four values, or coordinates, defining a rectangular area of

interest (AOI) of the image to be used for snapping images. Default
values are Left=0, Right=0, Top=0, Bottom=0, meaning the AOI is the
entire image. AOI is always determined and applied before any
horizontal and/or vertical decimation. Be sure to use the
GetSnapHeight and GetSnapWidth methods to obtain the height and
width of the image for snaps. To selectively change only one or more
of the four coordinates, set the other coordinates that are not being
changed to –1.
Return Value none
Parameters long Left, long Right, long Top, long Bottom
Left is the distance, in pixels of the AOI from the left side of the
image. Valid values are from 0 to the width of the original image. A
value of –1 will leave this coordinate unchanged.
Right is the distance, in pixels of the AOI from the right side of the
image. Valid values are from 0 to the width of the original image. A
value of –1 will leave this coordinate unchanged.
Top is the distance, in pixels of the AOI from the top of the image.
Valid values are from 0 to the height of the original image. A value of
–1 will leave this coordinate unchanged.
Bottom is the distance, in pixels of the AOI from the bottom of the
image. Valid values are from 0 to the height of the original image. A
value of –1 will leave this coordinate unchanged.
Syntax Visual Basic

194 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings
Object.SetSnapAOI Left As Long, Right As Long, Top As
Long, Bottom As Long
C++
Object.SetSnapAOI(long Left, long Right, long Top, long
Bottom)

SetStreamAOI Method

Description Sets the four values, or coordinates, defining a rectangular area of

interest (AOI) of the image to be used for streaming. Default values
are Left=0, Right=0, Top=0, Bottom=0, meaning the AOI is the entire
image. AOI is always determined and applied before any horizontal
and/or vertical decimation. Be sure to use the GetStreamHeight and
GetStreamWidth methods to obtain the height and width of the image
for streaming. To selectively change only one or more of the four
coordinates, set the other coordinates that are not being changed to –
1.
Return Value none
Parameters long Left, long Right, long Top, long Bottom
Left is the distance, in pixels of the AOI from the left side of the
image. Valid values are from 0 to the width of the original image. A
value of –1 will leave this coordinate unchanged.
Right is the distance, in pixels of the AOI from the right side of the
image. Valid values are from 0 to the width of the original image. A
value of –1 will leave this coordinate unchanged.
Top is the distance, in pixels of the AOI from the top of the image.
Valid values are from 0 to the height of the original image. A value of
–1 will leave this coordinate unchanged.
Bottom is the distance, in pixels of the AOI from the bottom of the
image. Valid values are from 0 to the height of the original image. A
value of –1 will leave this coordinate unchanged.
Syntax Visual Basic

IDEA SDK User’s Guide 195

Chapter 5:
ActiveX Function Listings
Object.SetStreamAOI Left As Long, Right As Long, Top As
Long, Bottom As Long
C++
Object.SetStreamAOI(long Left, long Right, long Top,
long Bottom)

SetOutputFormat Method

Description Sets the output format value.

Return Value none
Syntax Visual Basic
Object.SetOutputFormat(Value as Long)
C++
Object.SetOutputFormat(long Value)

SetPassMode Method

Description Sets the pass mode.

Return Value none
Syntax Visual Basic
Object.SetPassMode(Value as Long)
C++
Object.SetPassMode(long Value)

SetPhaseDelay Method

Description Sets the phase delay value.

Return Value none
Syntax Visual Basic
Object.SetPhaseDelay(Value as Long)
C++
Object.SetPhaseDelay(long Value)

SetPitch Method

Description Sets the pitch value.

196 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Return Value none

Syntax Visual Basic
Object.SetPitch(Value as Long)
C++
Object.SetPitch(long Value)

SetVertBackPorch Method

Description Sets the vertical back porch value.

Return Value none
Syntax Visual Basic
Object.SetVertBackPorch(Value as Long)
C++
Object.SetVertBackPorch(long Value)

SetVertStart Method

Description Sets the vertical start value.

Return Value none
Syntax Visual Basic
Object.SetVertStart(Value as Long)
C++
Object.SetVertStart(long Value)

SetVertSyncType Method

Description Sets the vertical sync type value.

Return Value none
Syntax Visual Basic
Object.SetVertSyncType(Value as Long)
C++
Object.SetVertSyncType(long Value)

SetVertTotal Method

Description Sets the vertical total value.

IDEA SDK User’s Guide 197

Chapter 5:
ActiveX Function Listings

Return Value long

Syntax Visual Basic
Object.SetVertTotal(Value as Long)
C++
Object.SetVertTotal(long Value)

SetVideoFormat Method

Description Sets the video format string.

Return Value none
Syntax Visual Basic
Object.SetVideoFormat(Value as String)
C++
Object.SetVideoFormat(LPCTSTR Value)

SetWhiteReference Method

Description Sets the white reference value.

Return Value none
Syntax Visual Basic
Object.SetWhiteReference(Value as Long)
C++
Object.SetWhiteReference(long Value)

ShowAreaOfInterestDialog Method

Description Displays a dialog for selecting the area of interest (AOI) for live display
or streaming.
Use of the built-in dialogs instead of creating your own has the
advantages of reducing your implementation, maintenance and
support costs, keeping your application smaller, avoiding managing
your own registry settings if you need persistent data, and
automatically gaining access to new features as they are released
without additional work on your part.
Parameters long Flags
Return Value none
Syntax Visual Basic

198 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings
Object.ShowAreaOfInterestDialog(Flags as Long)
C++
Object.ShowAreaOfInterestDialog(long Flags)
Flags
Value Constant Description
0x0001 AOI_DIALOG_ON Show dialog
0x0100 AOI_DIALOG_LIVE Select live AOI
0x0200 AOI_DIALOG_STREAMING Select streaming AOI
0x0400 AOI_DIALOG_SNAP Select Snap AOI

ShowBoardSelectionDialog Method

Description Displays a dialog for selecting the board to use, if there are more than
one boards on the system.
Use of the built-in dialogs instead of creating your own has the
advantages of reducing your implementation, maintenance and
support costs, keeping your application smaller, avoiding managing
your own registry settings if you need persistent data, and
automatically gaining access to new features as they are released
without additional work on your part.
Parameters long Flags
Return Value none
Syntax Visual Basic
Object.ShowBoardSelectionDialog(Flags as Long)
C++
Object.ShowBoardSelectionDialog(long Flags)
Flags
Value Constant Description
0x0001 BOARD_SELECTION_ON Show dialog
0x0100 BOARD_SELECTION_NO_NAMES Don’t show user
defined board names.

ShowCompressionDialog Method

Description Displays a dialog for setting and configuring the compression method
for streaming.

IDEA SDK User’s Guide 199

Chapter 5:
ActiveX Function Listings

Use of the built-in dialogs instead of creating your own has the
advantages of reducing your implementation, maintenance and
support costs, keeping your application smaller, avoiding managing
your own registry settings if you need persistent data, and
automatically gaining access to new features as they are released
without additional work on your part.
Parameters long Flags
Return Value none
Syntax Visual Basic
Object.ShowCompressionDialog(Flags as Long)
C++
Object.ShowCompressionDialog(long Flags)
Flags
Value Constant Description
0x0001 COMPRESS_OPTIONS_ON Show dialog

ShowConfigDialog Method

Description Displays a dialog for configuring IDEA board parameters and saving
those values in the registry.
Use of the built-in dialogs instead of creating your own has the
advantages of reducing your implementation, maintenance and
support costs, keeping your application smaller, avoiding managing
your own registry settings if you need persistent data, and
automatically gaining access to new features as they are released
without additional work on your part.
Parameters long Flags
Return Value none
Syntax Visual Basic
Object.ShowConfigDialog(Flags as Long)
C++
Object.ShowConfigDialog(long Flags)
Flags
Value Constant Description
0x0001 CONFIG_DIALOG_ON Show dialog
0x0002 CONFIG_DIALOG_WIZARD Display as wizard
0x0100 CONFIG_DIALOG_NO_LIVE Hide live options
0x0200 CONFIG_DIALOG_NO_SNAPS Hide snap options

200 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

0x0400 CONFIG_DIALOG_NO_STREAMING Hide streaming

options
0x0800 CONFIG_DIALOG_NO_DICOM Hide DICOM options
0x1000 CONFIG_DIALOG_NO_NAMES Hide user board
names options

ShowDicomDialog Method

Description Displays a dialog for entering DICOM options.

Parameters long Flags
Return Value none
Syntax Visual Basic
Object.ShowDicomDialog(Flags as Long)
C++
Object.ShowDicomDialog(long Flags)
Flags
Value Constant Description
0x0001 DICOM_OPTIONS_ON Show dialog

ShowIRGBCableTypeDialog Method

Description Displays a dialog for selecting the I-RGB cable type.

Use of the built-in dialogs instead of creating your own has the
advantages of reducing your implementation, maintenance and
support costs, keeping your application smaller, avoiding managing
your own registry settings if you need persistent data, and
automatically gaining access to new features as they are released
without additional work on your part.
Parameters long Flags
Return Value none
Syntax Visual Basic
Object.ShowIRGBCableTypeDialog(Flags as Long)
C++
Object.ShowIRGBCableTypeDialog(long Flags)
Flags
Value Constant Description
0x0001 CABLE_TYPE_DIALOG_ON Show dialog

IDEA SDK User’s Guide 201

Chapter 5:
ActiveX Function Listings

ShowUserDefinedBoardNamesDialog Method

Description Displays a dialog for assigning a user-defined name, description, or

other string to any board or boards in the system for later display in
the Configuration dialog, Board Selection dialog, or return in the
NthBoardDescription property.
Use of the built-in dialogs instead of creating your own has the
advantages of reducing your implementation, maintenance and
support costs, keeping your application smaller, avoiding managing
your own registry settings if you need persistent data, and
automatically gaining access to new features as they are released
without additional work on your part.
Parameters long Flags
Return Value none
Syntax Visual Basic
Object.ShowUserDefinedBoardNamesDialog(Flags as Long)
C++
Object.ShowUserDefinedBoardNamesDialog(long Flags)
Flags
Value Constant Description
0x0001 USER_BOARD_NAMES_ON Show dialog

ShowVesaDetectDialog Method

Description Displays a dialog for running VESA scanning.

Use of the built-in dialogs instead of creating your own has the
advantages of reducing your implementation, maintenance and
support costs, keeping your application smaller, avoiding managing
your own registry settings if you need persistent data, and
automatically gaining access to new features as they are released
without additional work on your part.
Parameters long Flags
Return Value none
Syntax Visual Basic
Object.ShowVesaDetectDialog(Flags as Long)
C++
Object.ShowVesaDetectDialog(long Flags)
Flags

202 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Value Constant Description

0x0001 VESA_DIALOG_ON Show dialog
0x0100 VESA_DIALOG_SILENT Run VESA scan
without a dialog

ShowVideoAdjustments Method

Description Displays a modeless dialog for configuring IDEA video adjustment

parameters and optionally saving those values in the CHP file.
Use of the built-in dialogs instead of creating your own has the
advantages of reducing your implementation, maintenance and
support costs, keeping your application smaller, avoiding managing
your own registry settings if you need persistent data, and
automatically gaining access to new features as they are released
without additional work on your part.
Parameters long Flags
Return Value none
Syntax Visual Basic
Object.ShowVideoAdjustments(Flags as Long)
C++
Object.ShowVideoAdjustments(long Flags)
Flags
Value Constant Description
0x0001 VIDEO_ADJUST_ON Show dialog

Snap Method

Description Causes a single frame or field to be snapped into the frame grabber
memory. The type of snap depends on the property SnapFieldMode.
This method automatically retrieves the data from the frame grabber
on the completion of the snap and packages it in a DIB. The
application can retrieve the data by either calling the
GetImagePicture, GetImageDIB or the GetPixelData methods. If the
FireSnapEvent property is set to TRUE then this method fires the
event to notify the application that the snap has completed and the
data is available.
Return Value A Boolean indicating whether or not the snap operation completed
successfully.

IDEA SDK User’s Guide 203

Chapter 5:
ActiveX Function Listings

SnapCancel Method

Description Cancels a currently executing snap.

Return Value none.

SnapInThread Method

Description Lauches a thread which causes a single frame or field to be snapped

into the frame grabber memory. The type of snap depends on the
property SnapFieldMode. This method automatically retrieves the
data from the frame grabber on the completion of the snap and
packages it in a DIB. The application can retrieve the data by calling
the GetImagePicture, GetImageDIB or GetPixelData methods. If the
FireSnapEvent property is set to TRUE then this method fires the
event to notify the application that the snap has completed and the
data is available.
Return Value A Boolean indicating whether or not the thread was successfully
launched.

SnapSequence Method

Description Cause a sequence of images to be snapped and transferred to a system

buffer. The property SequenceCount determines how many images
are snapped and transferred. The property FrameGrabDelay affects
the delay between successive snaps. Returns the number of frames
snapped. Like the Snap method, this method issues an event
notification upon the completion of each snap, so the application may
retrieve the data. This method does not return until all of the frames
are snapped.
Return Value A long indicating the number of frames snapped in the sequence.

SnapSequenceCancel Method

Description Cancels a currently executing snap sequence.

Return Value none.

204 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

SnapSequenceInThread Method

Description Cause a sequence of images to be snapped and transferred to a system

buffer. The property SequenceCount determines how many images
are snapped and transferred. The property FrameGrabDelay affects
the delay between successive snaps. Returns the number of frames
snapped. Like the Snap method, this method issues an event
notification upon the completion of each snap, so the application may
retrieve the data. This method does returns immediately and all of the
frames are snapped in a separate thread of execution.
Parameters long SnapEvent
SnapEvent is a handle to an event created by the calling application.
If zero, this parameter will be ignored. Otherwise, the thread will wait
for the event before capturing the next image.
Return Value A BOOL indicating success or failure in launching the thread.

StreamToAVI Method

Description This method will capture an image stream and save it to the AVI file
specified in the AVIFile property.
For more information, see also the AVIFile, StreamingBuffers,
StreamingLogFile, TriggeredStreaming, and DecimateFrameRate
properties, the OnFrameReady, OnNotificationMessage, and
OnStreamingTermination events, and the CodecLoad method.
Parameters long FrameCount, long Flags, long StartEvent, long PauseEvent, long
CancelEvent, long *MemoryHandle
FrameCount is the number of frames to capture and store.
A frame count of -1 will cause the frame count to be ignored and
streaming to continue until the cancel event is received (an error will
occur if the frame count is -1 and no cancel event is specified). This is
useful if it is desired to terminate streaming on a cancel event or the
end of triggered capture, and not on a certain number of frames.
The Flags are as follows:
0x0001 Notify the application with an event when each frame is
captured. See the section describing the OnFrameReady Event.
0x0002 Notify the application when the last frame is captured. See
the section describing the OnStreamingTermination event.
0x0040 Do not delete memory buffers.
0x0100 Applies to triggered streaming only; has no effect if triggering
is not specified. Terminate streaming after capturing the first series of
frames, instead of resetting for the next trigger event. This flag is

IDEA SDK User’s Guide 205

Chapter 5:
ActiveX Function Listings

useful for creating multiple files instead of appending to one single

file.
0x0200 Terminate on dropped frame(s).
0x1000 Preserve log file since last run; do not overwrite.
These flags may be OR’d together.
If StartEvent is zero, then the method will block until it has captured
and written all the frames to the file. If StartEvent is non-zero, then
the method will set up the necessary structures and return. The
application will then signal the event to commence the capture and
saving. The application can toggle pause/resume by signaling the
PauseEvent if it is non-zero. The PauseEvent is not recommended for
use in conjunction with triggered streaming because it may produce
unexpected results. The application can cancel the operation by
signaling the non-zero CancelEvent. The StartEvent, PauseEvent and
CancelEvent are handles to events as created by the Win32 function
CreateEvent(). They are signaled via the Win32 function call
SetEvent(). Set any of the event handles to zero to not use that event.
MemoryHandle is a pointer to a long integer that is returned by the
function for later use by the GetBuffer or ReleaseBuffer method(s).
This parameter is not used unless the 0x0040 flag is turned on.

StreamToMemory Method

Description This method will capture an image stream into a ring of memory
buffers.
For more information, see also the StreamingBuffers,
StreamingLogFile, TriggeredStreaming, and DecimateFrameRate
properties, the OnFrameReady, OnNotificationMessage, and
OnStreamingTermination events, and the CodecLoad method.
Parameters long FrameCount, long Flags, long StartEvent, long PauseEvent, long
CancelEvent, long *MemoryHandle
FrameCount is the number of frames to capture and store.
A frame count of -1 will cause the frame count to be ignored and
streaming to continue until the cancel event is received (an error will
occur if the frame count is -1 and no cancel event is specified). This is
useful if it is desired to terminate streaming on a cancel event or the
end of triggered capture, and not on a certain number of frames.
The Flags are as follows:
0x0001 Notify the application with an event when each frame is
captured. See the section describing the OnFrameReady Event.
0x0002 Notify the application when the last frame is captured. See
the section describing the OnStreamingTermination event.

206 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

0x0040 Do not delete memory buffers. This flag is turned on

automatically by the method.
0x0100 Applies to triggered streaming only; has no effect if triggering
is not specified. Terminate streaming after capturing the first series of
frames, instead of resetting for the next trigger event. This flag is
useful for creating multiple files instead of appending to one single
file.
0x0200 Terminate on dropped frame(s).
0x1000 Preserve log file since last run; do not overwrite.
These flags may be OR’d together.
If StartEvent is zero, then the method will block until it has captured
and written all the frames to the file. If StartEvent is non-zero, then
the method will set up the necessary structures and return. The
application will then signal the event to commence the capture and
saving. The application can toggle pause/resume by signaling the
PauseEvent if it is non-zero. The PauseEvent is not recommended for
use in conjunction with triggered streaming because it may produce
unexpected results. The application can cancel the operation by
signaling the non-zero CancelEvent. The StartEvent, PauseEvent and
CancelEvent are handles to events as created by the Win32 function
CreateEvent(). They are signaled via the Win32 function call
SetEvent(). Set any of the event handles to zero to not use that event.
MemoryHandle is a pointer to a long integer that is returned by the
function for later use by the GetBuffer or ReleaseBuffer method(s).

WhiteBalance Method

Description Perform white balance.

Return Value none
Syntax Visual Basic
Object.WhiteBalance
C++
Object.WhiteBalance( )

WriteConfigDword Method

Parameters LPCTSTR Name, long Value

Description This method may be used to store, by name, an application-defined
numeric value in the registry, that is associated with the currently
selected board.

IDEA SDK User’s Guide 207

Chapter 5:
ActiveX Function Listings

WriteConfigGlobalDword Method

Parameters LPCTSTR Name, long Value

Description This method may be used to store, by name, an application-defined
numeric value in the registry, that is not associated with the currently
selected board.

WriteConfigString Method

Parameters LPCTSTR Name, LPCTSTR Value

Description This method may be used to store, by name, an application-defined
string value in the registry, that is associated with the currently
selected board.

WriteConfigGlobalString Method

Parameters LPCTSTR Name, LPCTSTR Value

Description This method may be used to store, by name, an application-defined
string value in the registry, that is not associated with the currently
selected board.

WriteConfiguration Method

Parameters none
Description This method stores all of the predefined properties listed below, plus
the audio properties listed above, into the registry. From the user
dialog(s) for getting and setting these properties call this method
when the user selects "Apply" or "OK" to make the values permanent in
the registry.

Events
Events are the mechanism by which the control notifies an application that an
action has occurred. The IdeaFG control supports several notification events.

208 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

How an application receives the event depends on the programming

environment:
1. Visual Basic: Dim With events Variable
2. Visual C++: The event handlers must be wrapped in an MFC event map. See
the Visual Documentation for BEGIN_EVENTSINK_MAP and ON_EVENT.
3. Inprise C++ Builder: From the Property Sheet select the event notification
and type in a notification handling function.

OnSnap Event

Description The control fires an OnSnap event on the completion of an image grab
during a Snap( ) method. This event will be fired if there has been a
previous call to the SetFireSnapEvent method with a parameter of
TRUE.
This is Event ID 2.
This event has one parameter as follows:
short Status: error return code or 0 for no error
It is up to the application to retrieve the image from the IdeaFG
control for example by a GetImageDIB, GetImagePicture or
GetPixelData method call.

OnFrameReady Event

Description This event gets fired when each frame is grabbed during a streaming
capture, if the proper NotifyFlag is set. Bit zero of the NotifyFlags
parameter for the StreamToAvi method will cause this event to be
fired.
This is event ID 5.
The event handler for this event will receive the following
parameters:
long FrameNumber: the number of the frame in this sequence.

OnStreamingTermination Event

Description This event will get fired at the completion of a streaming operation if
the NotifyFlags parameter passed to the streaming method has bit 1
set. This will be fired either after the last frame has been captured, or
it may be fired early if an error has occurred.

IDEA SDK User’s Guide 209

Chapter 5:
ActiveX Function Listings

This is event ID 3.
This event has two parameters as follows:
short Status: error return code or 0 for no error
long NumberFrames: the number of frames captured

OnSequenceTermination Event

Description This event will get fired at the completion of a snap sequence
operation. This will be fired either after the last frame has been
captured, or it may be fired early if an error has occurred.
This is event ID 4.
This event has two parameters as follows:
short Status: error return code or 0 for no error
long NumberFrames: the number of frames captured

OnNotificationMessage Event

Description This event is fired to provide the calling application with information
at the time the information becomes available. This generic event
allows the application to receive numerous kinds of information with a
single event handler; and new kinds may be added without changing
the interface to the ActiveX control.
This is event ID 1.
This event has two parameters as follows:
short MessageCode: A 16-bit code identifying the message.
The values for MessageCode are defined in hdp_lib.h and hdp_lib.bas
as follows:
Message Codes
Val Constant Description
0 IDEA_INFO_NONE No information
1 IDEA_INFO_ERROR Error message
2 IDEA_INFO_WARNING Warning message
3 IDEA_INFO_CONNECTION Not used
4 IDEA_INFO_SYNC Sync detection
5 IDEA_INFO_LOCK Not used
6 IDEA_INFO_DROPPED_FRAMES Frame(s) dropped
7 IDEA_INFO_TRIGGER_START Trigger start

210 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

8 IDEA_INFO_TRIGGER_STOP Trigger stop

9 IDEA_INFO_VESA_SCAN_READY Ready to start VESA scan
10 IDEA_INFO_VESA_SCAN_START Starting VESA scan
11 IDEA_INFO_VESA_SCAN_DONE Finished VESA scan
12 IDEA_INFO_DIALOG_ACTION Message from dialog box
13 IDEA_INFO_LIVE_DISPLAY_START Live display to a DirectDraw
surface has commenced
14 IDEA_INFO_LIVE_DISPLAY_STOP Live display to a DirectDraw
surface has stopped.
15 IDEA_INFO_LIVE_DISPLAY_SURFACE_G The DirectDraw display
ONE surface has been deleted

long MessageParameter: A 32-bit value whose meaning is determined

by the MessageCode.
The values for MessageParameter are as follows:
Message Parameters
Message Code Message Parameter
IDEA_INFO_NONE Nono
IDEA_INFO_ERROR Error code (use GetErrorText)
IDEA_INFO_WARNING Warning code (use GetErrorText)
IDEA_INFO_CONNECTION -1 = lost, -2 = regained
IDEA_INFO_SYNC 1 = sync; 0 = no sync
IDEA_INFO_LOCK None
IDEA_INFO_DROPPED_FRAMES Number of frame(s) dropped
IDEA_INFO_TRIGGER_START None
IDEA_INFO_TRIGGER_STOP None
IDEA_INFO_VESA_SCAN_READY None
IDEA_INFO_VESA_SCAN_START None
IDEA_INFO_VESA_SCAN_DONE Error code (use GetErrorText)
IDEA_INFO_DIALOG_ACTION See table below

The values for the MessageParameter corresponding to the

MessageCode IDEA_INFO_DIALOG_ACTION are defined in ideaocx.h and
ideaocx.bas as follows:
Message Codes
Val Constant Description
0 CONFIG_DIALOG_OK Ok button pressed
1 CONFIG_DIALOG_CANCEL Cancel button pressed

IDEA SDK User’s Guide 211

Chapter 5:
ActiveX Function Listings

2 CONFIG_DIALOG_APPLY Apply button pressed

100 DIALOG_UPDATE_DISPLAY A change was made that may
require the application to
update the display of live or
snapped images, or
recalculate buffer sizes

IdeaBoardInfo Control Reference

CIdeaBoardInfo is an overview control that provides the application with
information about how many and what kinds of boards are present in the
system. This control is useful if the board information is all that is needed by
the application. This control is not necessary if using the IdeaFG control, which
contains all of IdeaBoardInfo’s methods and properties.
The following are behavioral characteristics of this control:
Invisible at runtime.
Able to display an About box listing copyright and version information.
Does not have a property pages dialog.
Has properties that can be set at design or runtime.
Does not subclass any standard window classes.

Properties

BoardCount Property

Description Determines the number of boards in the system. This is a READ-ONLY

property.
Type long
Syntax Visual Basic

212 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings
Value = Object.BoardCount

C++
long Value = Object.GetBoardCount( )

Methods

AboutBox Method

Description Displays an “About” box containing support, version, copyright, and

other useful information.
Return Value None.

GetNthBoardType Method

Description Returns a board type based on the zero-based board index. This allows
the application to step through all of the boards in the system to find
a particular board.
Syntax Visual Basic
Value = Object.GetNthBoardType(Index as Integer)

C++
long Value = Object.GetNthGetBoardType(short Index)

GetNthSerialNumber Method

Description Returns a board’s serial number string based on the zero-based board
index. This allows the application to step through all of the boards in
the system to find a particular board.
Syntax Visual Basic
Value = Object.GetNthSerialNumber(Index as Integer)

C++
BSTR Value = Object. GetNthSerialNumber(short Index)

IdeaDisplay Control Reference

CIdeaDisplayWnd is the interface that an application uses to create a live video
window or a pseudo live video window. This interface controls passing data

IDEA SDK User’s Guide 213

Chapter 5:
ActiveX Function Listings

from the frame grabber into a DirectDraw overlay surface where it is displayed.
There are two basic modes in which the CIdeaDisplay operates: GDI or
DirectDraw. In GDI mode, the display window receives the image from the
frame grabber control, performs any application defined graphical operations
on the image and then displays the image using normal Win32 GDI commands.
This method results in a pseudo live display.
In DirectDraw mode, an overlay surface is created. If capable, the frame
grabber DMA’s the image data directly into the overlay buffer on the video
card. Graphical mixing and color keying depend on the capabilities and the
video drivers for the display card. This results in true live video display.
The following are behavioral characteristics of this control:
• Visible at runtime.
• Able to display an About box listing copyright and version information.
• Has a property pages dialog.
• Has properties that can be set at design or runtime.
• Subclasses.

Properties

BackColor Property

Description Determines the default background color of the display window when
no image data is being displayed. The value is an RGB value as defined
in the WIN32 SDK.
Syntax Visual Basic
Object.BackColor = Value
C++
Object.BackColor(long Value)

BorderStyle Property

Description Sets the style of the border of the video window.

Syntax Visual Basic
Object.BorderType = Value
C++

214 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings
Object.BorderType(long Value)

ColorKey Property

Description Sets the value of the color key when the display mode is using a
DirectDraw overlay surface.
Syntax Visual Basic
Object.ColorKey = Value
C++
Object.SetColorKey(long Value)
Value = Object.GetColorKey( )

DisplayMode Property

Description Possible values are:

0 GDI – Automatic display is done across the bus using standard GDI
calls.
1 DirectDraw – Automatic display is done by DMA of data across the
bus directly into a DirectDraw overlay surface. The color key and
the background color determine what displays. This requires that
the display card support DirectDraw overlay surfaces.

Syntax Visual Basic

Object.DisplayMode = Value
C++
Object.SetDisplayMode(long Value)
Value = Object.GetDisplayMode( )

HWnd Property

Description Read-only property to retrieve the Windows style window handle for
the display window.
Syntax Visual Basic
hWnd = Object.HWnd
C++
long hWnd = Object.GetHWnd( )

IDEA SDK User’s Guide 215

Chapter 5:
ActiveX Function Listings

FitToSize Property

Description Determines if the video in the window is scaled to the size of the
window or only displays the portion of the video that fits in the
window. If the video is not scaled and the window is smaller than the
video size, scroll bars are displayed in either the X or the Y-direction
to allow the application to pan and scroll through the active video.
Syntax Visual Basic
Object.FitToSize(Value as Boolean)
Object.FitToSize = Value
C++
bool Value = Object.GetFitToSize( )
Object.SetFitToSize(bool Value)

MessageCaption Property

Description This property sets the caption to be displayed in message boxes

reported from the control.
Type string
Syntax Visual Basic
Object.MessageCaption = Value
C++
Object.SetMessageCaption(LPCTSTR Value)

Verbosity Property

Description Changes or retrieves the message reporting state. Valid values for this
property are given in the table below and defined in ideaocx.h and
ideaocx.bas. This property affects displayed items only, not written
files such as log files.
Type long
Syntax Visual Basic
Object.Verbosity = Value
C++
Object.SetVerbosity(long Value)
long Value = Object.GetVerbosity( )

Verbosity

216 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Value Constant Description

0 VERBOSITY_SILENT Silent mode: show nothing
1 VERBOSITY_DIALOGS Show dialogs only, if asked
2 VERBOSITY_ERRORS Show dialogs and errors
3 VERBOSITY_WARNINGS Show dialogs, errors, warnings
4 VERBOSITY_INFO Show everything, including
diagnostic information

Methods

AboutBox Method

Description Displays an “About” box containing support, version, copyright, and

other useful information.
Return Value None.

SetImageHandle Method

Description Takes the image handle from the frame grabber object and uses it to
retrieve the image for display.

Migration From IDEA 2.4 or Earlier

IDEA 2.5 no longer supports Visual C++ 6.0 as a development environment. This
release supports Visual Studio 2005 in order to provide support for both 32- and
64-bit Windows development. All of the demonstration applications contain
build configurations for both 32- and 64-bit environments.
The biggest difference is found in using the ActiveX control to develop a
VB.NET application. The control must be wrapped in a .NET assembly before
VB.NET can use it. The installation process does not do this, so a developer
must do it manually by using the following commands in a command-prompt
window:
1. If not already registered, enter:
Regsvr32 ideactls.ocx
2. Using the correct 32- or 64-bit version of aximp from the .NET SDK,
enter:

IDEA SDK User’s Guide 217

Chapter 5:
ActiveX Function Listings

aximp ideactls.ocx
3. Enter:
regtlib ideactls.ocx

From inside Visual Studio 2005 for the application project:

1. Select Project|Add Reference.
2. From the COM tab select idea ActiveX Control Module.
3. From the Browse tab, go to the ..\idea\ActiveX folder and select
AxIdeaCTLSLib.dll.
If you are moving from IDEA 2.4, you MUST update the hardware device driver.
From the Hardware Device Manager find the entry. This is probably in the
entry for Sound, video and game controllers, although the new hardware
installation will put it under Imaging devices. Select your Foresight frame
grabber. From the Driver tab of the Properties dialog, select Update Driver.
Then use the INF file from the appropriate 32 or 64 bit folder in the Drivers
folder. You will have to restart after installing this driver.

Migration From IDEA 2.3 or Earlier

The IDEA ActiveX control (ideactls.ocx) underwent numerous enhancements for
the Version 1.6 release of IDEA. It added a richer interface that covers more of
the available features of the IDEA library.
Of course, the ActiveX control still returns a board handle and an image handle
so that IDEA library functions may be called if necessary -- even while using the
ActiveX control for everything else.
If you have an existing application that used earlier versions of the IDEA
ActiveX control (imactls.ocx), you may wish to skip right to General Guidelines,
in order to get your application running with the new version first.

Persistence of Data
Applications may now use the IdeaFG control to store and retrieve user data in
the registry instead of managing it themselves. The ReadConfiguration and
WriteConfiguration methods may be used to read and write most parameters
used by the IdeaFG control to and from the registry. Also, user-defined
parameters may be read and written as well, on a global or board-specific
basis. See the ReadConfig… and WriteConfig… methods defined and described
in this manual.

218 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Improved Board Identification and Multiple Boards

Support
Previously, the IdeaFG control loaded with no knowledge of what boards, if
any, are present, nor of which board should be selected when multiple boards
are found on a system. The application had to set the board handle in the
IdeaFG control to get it to initialize that board. The IdeaFG control claimed all
of the boards in order to guarantee that the board handle would be a
predictable number, i.e., 1=first board, 2=second board, etc.
In the new IdeaFG control, the board handle is a read-only property, like the
image handle, to be retrieved and used if and when an application needs to
call IDEA library functions directly, without going through the ActiveX control.
The new ActiveX control only claims the board it is currently using.
Applications should now identify boards either by their serial number (a
character string) or by an index number. The index number is used the way the
board handle was previously, but is zero-based. Methods are provided for
converting an index number to a serial number, and vice versa.
The index number will change if boards are swapped around in a system, the
serial number will not.
C++ Example: In the old ActiveX control, the following code would initialize a
board:
m_pIdeaFG->SetBoardHandle( wBoardNumber + 1);
In the new ActiveX control, the equivalent call would be:
m_pIdeaFG->SetCurrentBoardIndex( wBoardNumber );
VB Example: In the old ActiveX control, the following code would initialize a
board:
IdeaFG1.BoardHandle = BoardNumber + 1
In the new ActiveX control, the equivalent call would be:
IdeaFG1.CurrentBoardIndex = BoardNumber
However, this call is now completely unnecessary unless the application
actually needs to change the currently selected board to a different board. The
behavior of the IdeaFG control now is that it looks in the registry for a default
board designated to start with initially. If one is not specified, as will be the
case the first time the IdeaFG control is ever called, it will pick the first board
found in the system.
So, now the IdeaFG control has a board chosen already when it first loads. If
there is only one board on the system, this is all that ever needs to happen. If
there might be more than one board present, the application may select a new

IDEA SDK User’s Guide 219

Chapter 5:
ActiveX Function Listings

current board, or change the default board, at any time. The first, best
opportunity to change the current board is after the IdeaFG control is loaded
but before the call to the Open() method.
Additional methods are also available in the IdeaFG control to gain information
about the boards present on the system. This includes all of the methods that
were formerly only available in the IdeaBoardInfo control. Any application that
was using both the controls should remove the IdeaBoardInfo control and the
only use the IdeaFG control.
The IdeaBoardInfo control no longer claims the boards; and therefore the
GetBoardHandle() method has been removed.

Specification of Number of Buffers for Streaming

A new interface is provided to correct a problem when streaming more than a
few (perhaps 90 or so) frames to AVI. The old function, StreamCaptureToAVI,
used the FrameCount parameter to allocate one buffer for each frame, causing
the software to potentially run out of memory.
The new method, StreamToAVI, specifies the number of buffers separately. A
memory handle is returned, which, for now, should be ignored by the
application.

General Guidelines for Migration

Several issues arise when moving C++ or VB applications to the new version of
the ActiveX control. This section provides suggestions to get an application
running on the new ActiveX control quickly. Required changes only are given
below as steps do a quick port. To take full advantage of the ActiveX control's
new features, the entire documentation should be read and used.
1. If the application was using both the ImaFG and ImaBoardInfo controls it
can replace them both with IdeaFG. If it was just using the ImaBoardInfo
control it can be replaced with IdeaBoardInfo.
2. Change calls to set the BoardHandle property to set the CurrentBoardIndex
property instead, and subtract 1 from the value to which it is set because it
is now a zero-based index instead of one-based.
3. Change the BoardType property to NthBoardTypeString to return a string
value instead of a numerical value.
4. Change calls to the BoardType, NthBoardTypeString, NthBitsPerPixel, and
SerialNumber properties to use an index. The CurrentBoard property is
likely the value best to use for the index.

220 IDEA SDK User’s Guide

 Chapter 5:
ActiveX Function Listings

Visual C++ Migration

1. Delete "imafg.cpp", "imafg.h", "imaboardinfo.cpp", "imaboardinfo.h",
"imadisplay.cpp", and "imadisplay.h" from the files list in the file view of
Developer Studio, if any of these are present. Then delete those files from
the project folder.
2. Delete the controls from forms and recreate them, as necessary. From the
menu "Project->Add to Project->Components and Controls...", select
"Registered ActiveX Controls" and insert the IdeaFG, IdeaDisplay and
IdeaBoardInfo controls, as appropriate.
3. Global-replace all occurrences of "imafg", "imaboardinfo", and "imadisplay"
with "ideafg", "ideafg" or "ideaboardinfo", and "ideadisplay", as appropriate
and taking care to match upper- and lower-case values during the
replacement.
4. Global-replace occurrences of method and property names and parameters
that have changed with the new names and parameters from the tables of
name changes in Section below. The easiest way to find them is to use
"Build->Rebuild All" and let the compiler flag them as errors.

Visual Basic Migration

1. Delete the controls from forms and recreate them, as necessary.
2. Global-replace all occurrences of "imafg", "imaboardinfo", and "imadisplay"
with "ideafg", "ideafg" or "ideaboardinfo", and "ideadisplay", as appropriate.
3. Global-replace occurrences of method and property names and parameters
that have changed with the new names and parameters from the tables of
name changes in Section below.

IDEA SDK User’s Guide 221

Chapter 6:
IDEA Tools API Introduction

CHAPTER 6:
IDEA Tools API Introduction
The Foresight Imaging IDEA Tools Library is an extension to the Foresight
Imaging IDEA SDK that allows application programmers to incorporate IDEA
Auto-SYNC™ functionality into their Windows programs for Foresight frame
grabber boards. The AccuStream boards consist of two video sections, an
analog section (some also have a DVI section) and a standard definition
television (SDTV) section. The IDEA Tools API does not support the SDTV video
section of AccuStream 50a, 75a, 205a boards.
The IDEA Tools API provides the applications programmer with routines for:
ƒ Performing internal board checks to verify that the system is properly
accessing each known Foresight Imaging board and that the frame grabber
memory and the bulk of the digital circuitry is working properly.
nHD_Report( ) provides this service.
ƒ Automatically analyzing and recording (Auto-SYNC'ing) the video signals
being provided to a Foresight Imaging board. This service is available
through a sequence of operations including calls to all four of the Tools API
routines.
To support the Foresight Imaging boards, Foresight Imaging provides
HD_AUTO.EXE, a windows application, to verify board setup, automatically
analyze video signals and tune video settings.

Components of the Tools API

Use of the Tools API requires all of the components you normally need for IDEA
Auto-SYNC, as well as others. The following are the components required for
IDEA Auto-SYNC:
1. IDEA System Driver:
Windows XP: FSI.SYS
2. SDK Library DLL (HDPW32.DLL or HDPW64.DLL)
3. Tools Library DLL (IDEATOOLS.DLL or IDEATOOLS64.DLL)
4. ActiveX Controls (IDEACTLS.OCX)
5. Properly specified system registry entries.

222 IDEA SDK User’s Guide

 Chapter 6:
IDEA Tools API Introduction

All the other essential components become apparent when the AS_RGB
demonstration application is examined. These are:
ƒ Include files: IDEATOOLS.H, HDP_LIB.H and GEN_DEF.H.
ƒ Library files: HDPW32.DLL and IDEATOOLS.DLL.

Sample Application Code

The Tools Library and DLL were used to implement the Foresight Imaging IDEA
Auto-SYNC product (HD_AUTO.EXE). Although the IDEA Auto-SYNC API interface
can become very involved, defaults are provided for all parameters for easy
implementation. The following is a very basic piece of sample code. It uses
default settings for everything. It does not set the I-RGB cable configuration,
provides no error handling or user intervention, and does not provide diagnostic
output.
#include "string.h"
#include "ideatools.h"
void main(void)
{
BoardHandle bh;
AS_RUNSTATE *pasr;
ASCH asch;
AS_CHANNEL *pasc;
char szCHPName[12];
bh = (BoardHandle)nHP_ClaimAll(0,1);
if(bh) {
eHD_ASInitiate(bh,ASCMASK_ALL,&pasr);
eHD_SyncSurvey(pasr);
HD_VideoMeasure(pasr);
HD_VideoAlign(pasr);
for(asch=0;asch<=ASCH_CA4;asch++) {
strcpy(szCHPName,"AS_CA1.chp");
szCHPName[5]+=asch;
remove(szCHPName);
pasc = pasr->pasc[asch];
if(pasc->mVideo.e) continue;
eHP_RSET_FWrite(bh,szCHPName,pasc->prset);
}
eHD_ASTerminate(&pasr);
HP_UnClaim(bh);
}
}

The above code defaults everything. There is no error handling, no user

interaction and no generation of diagnostic reports or other provisions for
monitoring the Auto-SYNC operation. The above program simply “goes away” for a
minute or two and exits leaving zero to four “AS_CA*.CHP” files in its wake. When
there is more than one Foresight board in the system, it always selects the first
one.

IDEA SDK User’s Guide 223

Chapter 6:
IDEA Tools API Introduction

Putting Auto-SYNC into Context – Six Guidelines

It is very important to understand what IDEA Auto-SYNC does and how it fits
into the IDEA technical support strategy before designing IDEA Auto-SYNC
functionality into your application. This, along with certain IDEA Auto-SYNC
application guidelines, is provided below. It is possible that these guidelines
should not or cannot be maintained for your application or your IDEA
environment. But, at a minimum, they are points you need to consider.

Guideline 1
Provide an interactive interface for checking and correcting Auto-SYNC
results.

Overview: Provide a means for the operator to examine the image

generated by the initial IDEA Auto-SYNC file. Also provide a
means for making adjustments to the Horizontal Total, Framing
(Width, Height, HBP, VBP), Contrast, Brightness and Phase
Delay settings. The operator may also discover cabling,
connection, power and equipment configuration problems
while examining the IDEA Auto-SYNC results. Therefore a means
for re-running the IDEA Auto-SYNC process should be provided.
Background: The Foresight boards can capture image frames from a wide
variety of video signal formats. This adaptability is provided by
configuration information in an IDEA configuration file (*.CHP).
The “CHP” file describes the video signal format and its
interface to the Foresight board in detail. When a new or
unknown video format is encountered, it cannot be captured
until a CHP file has been generated for it. IDEA Auto-SYNC or
the Auto-SYNC functions in the Tools library are typically the
best way of generating an initial CHP file. In most cases, the
initial untouched CHP file generated by the Auto-SYNC process
produces good to excellent image-capture quality. Also in some
cases, it requires improvement through manual adjustments.

Guideline 2
Make “verbose” log reports routinely available to your field support.

Overview: Provide a means of transmitting a “verbose” log report from the

site. This report can be the starting point for any support call
where a CHP file cannot be produced at all. Most typically, the

224 IDEA SDK User’s Guide

 Chapter 6:
IDEA Tools API Introduction

report is sent to a file that can then be faxed or e-mailed to a

support center.
Background: The typical IDEA installation is at a location remote from
technical support centers and the IDEA Auto-SYNC operator is
not an IDEA or video signal specialist. This is exactly the
environment that IDEA Auto-SYNC is designed to handle.
In cases where IDEA Auto-SYNC cannot create a usable CHP file,
this high level of detail in the log file provides detailed and
reliable information that can be sent back to the support
center.
First, the log information provides a narrative step-by-step
report of what IDEA Auto-SYNC did, what it found and how it
operated. It can be produced in three levels of detail. In the
Foresight Imaging IDEA Auto-SYNC product (HD_AUTO.EXE), the
log information is scrolled out to the display and written to a
log file.

Guideline 3
Make ASB files available to Foresight Imaging customer support.

Overview: Provide a means for optionally generating and transmitting the

ASB information to Foresight Imaging. Most typically the
information is saved to an *.ASB file and then e-mailed or
FTP’ed to Foresight Imaging.
Background: In addition to the log report, there is the option to produce
Auto-SYNC binary (*.ASB) files. Each of these files contains
compressed information about one of the eight analog or video
channels. Although these files are not used routinely, they are
needed in the rare cases when IDEA Auto-SYNC fails to
recognize the sync pattern from a channel that is known to
have good sync. These files are to be interpreted by specially
trained Foresight Imaging Customer Support and Engineering
personnel.

Guideline 4
Make CHP files routinely available to your field support.

Overview: Provide a means for generating and transmitting CHP files.

These should include the IDEA Auto-SYNC execution date and
time, as well as the SDK revision date in the file header. Note

IDEA SDK User’s Guide 225

Chapter 6:
IDEA Tools API Introduction

that the CHP file contains a detailed description of the video

signal and you should routinely retain this information for each
site.
Background: If you have already used the IDEA SDK, you are familiar with
RSETs (see also Chapter 3 within this document). These
structures contain the video configuration information.
Standard SDK calls are provided for loading them to and from
*.CHP files. Actually, the IDEA Auto-SYNC function in the Tools
library produces an RSET, not a CHP file. If the IDEA Auto-SYNC
process gets far enough along to produce the RSET information,
that information can be helpful for remote support.
If the CHP files (which are text files) contain any lines that
begin with a semicolon, these lines are ignored by the IDEA
SDK. Customarily, the application code generates a header for
the CHP files that consists of several comment lines with
details such as the date and time that the file was produced.

Guideline 5
Allow Auto-SYNC to perform a thorough survey.

Overview: Do not disable any channels before the Sync Survey portion of
the IDEA Auto-SYNC process. By performing a complete survey
of all eight channels, you produce log information that
describes everything that is connected to the board. This
report ends any confusion about what each channel has.
Background: From experience, certain information reported from troubled
installation sites is not reliable. Specifically, cabling, signal
configuration and video formatting information can be wrong
even when taken directly from authoritative sources. In all
cases, the IDEA Auto-SYNC process can provide the most
reliable formatting information. It measures what is there.

226 IDEA SDK User’s Guide

 Chapter 6:
IDEA Tools API Introduction

Guideline 6
Document the IDEA Auto-SYNC image content requirements.

Overview: Determine what your application requires in the way of image

content. To the extent that the operators are required to meet
these requirements, make this information available to those
operators.
Background: Finally, it is easy to overlook the fact that IDEA Auto-SYNC
relies on a properly selected image. Included in the IDEA Auto-
SYNC documentation is a list of characteristics that must be
present in the image before IDEA Auto-SYNC can be expected
to correctly recognize a new video format. For example, white
or light gray must be present along all four edges (top, bottom,
left and right) of the image. Failing that, IDEA Auto-SYNC
underestimates the image size.
Of course, your application may be able to relax some of those
rules if it is capable of adjusting the CHP file (or RSET) based
on other information. Or, your application may have some
direct control over the image contents so that selecting an
image is no longer the responsibility of the operator.

IDEA SDK User’s Guide 227

Chapter 7:
Structures in IDEATOOLS.H

CHAPTER 7:
Structures in IDEATOOLS.H
This chapter discusses the more important structures found in the IDEA Tools
API include file called IDEATOOLS.H.

AS_RUNSTATE Structure
Include file, IDEATOOLS.H, declares type AS_RUNSTATE as follows:
typedef struct {
// These first five elements should not be modified by the application
code.
short nThisSize; // Number of bytes in this structure.
DWORD dwID; // Runtime AS_RUNSTATE structure ID ("ARun").
BoardHandle bh; // Board handle for board to Auto-SYNC.
void *pResv; // Reserved for exclusive use of Auto-SYNC.
ASTAGE astage; // How much Auto-SYNC processing is done.
// eHD_ASInitiate( ) sets up defaults for these next elements that can
be changed by your
// application code.
ASLV aslv; // Level of detail to include in Log messages.
long lUser; // Long variable for any application use.
HCB_BUSY *Spinning; // Auto-SYNC progress reporting (% done).
void *pObjSpin; // Object (or data) pointer for Spinning( ).
HCB_LOG *LogReport; // Called with text data for log reporting.
void *pObjLogR; // Object (or data) pointer for LogReport( ).
HCB_ASB *bRawSync; // *.ASB diagnostic data pipe.
void *pObjRawS; // Object (or data) pointer for RawSync( ).
// eHD_ASInitiate( ) allocates these nine structures (per the ASCMASK
argument) and
// eHD_ASTerminate( ) frees them. Treat these pointers as read-only.
AS_CHANNEL *pasc[ASCH_N]; // Array of pointers to channel states.
HDRF wCtrlFlags; // Control flags for the operation

// The following parameters are used only for VESA scanning.

// They are initialized by eHD_ASInitiate() but can be
// changed to increase/decrease tolerances for acceptable
// matches between input video and VESA CHP template files.
long lVESAHTolerance; // HFreq tolerance (in 0.1%)
long lVESAVTolerance; // VFreq tolerance (in 0.1%)
// The following string is the fully qualified path to the
// VESA CHP directory. It is required for VESA mode scanning
// or the operation will fail.
char szVESADir[_MAX_PATH];
char Reserved [_MAX_PATH];
// VESA mode scan return value set by HD_VideoMeasure().
// Represents a count of the matching VESA CHP files; also
// is the count of the number of valid RSETs that were
// generated.
int nVESAStatus;
/*

228 IDEA SDK User’s Guide

 Chapter 7:
Structures in IDEATOOLS.H
// Video Filter Formats are used to prioritize the scoring of
// candidate image formats based on their aspect ratios.
*/
ASFORMATFILTER_INFO ffinfo;
} AS_RUNSTATE;

Structure Elements
Each of the elements of this structure is described in detail below:

pasr->nThisSize
Size of the AS_RUNSTATE structure. It is used by the Tools library to verify that
the structure is intact. Do not modify this value.

pasr->dwID
Contains the character string “ARun”. It is used by the Tools library to verify
that this AS_RUNSTATE structure is intact. Do not modify this value.

pasr->bh
Board handle that you specified in eHD_ASInitiate( ). It specifies the I-Series/
HI*DEF board that the IDEA Auto-SYNC process is using. It is unlikely that you
would ever want to change this value. Changing this value from one type of
Foresight board to another causes IDEA Auto-SYNC to fail.

pasr->pResv
Reserved value. The Auto-SYNC process uses this. Changing it causes the Auto-
SYNC process to fail. Do not modify this value.

pasr->aStage
Indicates how much progress has been made in the IDEA Auto-SYNC processing.
The possible values are:
ASTAGE_INIT: Only eHD_ASInitiate( ) has been called.
ASTAGE_SURVEY: eHD_SyncSurvey( ) has been called.
ASTAGE_MEASURE: HD_VideoMeasure( ) has been called.
ASTAGE_ALIGN: Processing is complete except for eHD_ASTerminate( ).
You can use this value to control user interface options. Do not modify this
value.

IDEA SDK User’s Guide 229

Chapter 7:
Structures in IDEATOOLS.H

pasr->aslv
Set this value to indicate which log message reports are of interest to your
application. The default value is ASLV_NORMAL. The possible values are:
ASLV_TERSE: Sends only critical or summary messages.
ASLV_NORMAL: Maintains extensive progress reporting.
ASLV_VERBOSE: Maintains detailed progress reporting.
ASLV_ASB: Same as ASLV_VERBOSE but with *.ASB file data.

pasr->lUser
Pass this value to the callback routines for the logging messages and the *.ASB
file information. Set it to any value that is useful to your application. The
default value is zero.

pasr->Spinning
Since the IDEA Auto-SYNC process can take a minute or two, you may want to
provide some signal to the operator that all is still going well. The default
value is NULL which results in no callback.
In IDEA Auto-SYNC, progress is shown with a bar that slowly advances towards
an indication of 100% completion. To provide this type of reporting to your UI,
write a callback procedure that takes two arguments and set this value
(Spinning) to point to it. This routine is called frequently during Auto-SYNC
processing. The first argument to your routine is the value you specify in pasr-
>pObjSpin (see next item) and the second argument is a value from 0 to 100
indicating the approximate percentage of Auto-SYNC completion.

pasr->pObjSpin
This is the first argument to the pasr->Spinning callback routine. The default
value is zero.
If you are coding in C++, you may want to put your “this” pointer here so you
can restore context in your callback.

pasr->LogReport
Based on the setting of pasr->aslv, the IDEA Auto-SYNC process prepares
narrative reports indicating what it has found and what it is doing. These
reports are often critical for offsite support during system installation and
upgrades. You should code a callback routine to save these reports to a file
that can be printed and faxed or otherwise transmitted to a support center.

230 IDEA SDK User’s Guide

 Chapter 7:
Structures in IDEATOOLS.H

The default value is NULL which results in no callback.

HCB_LOG
The prototype for this callback function is based on type HCB_LOG:
typedef void HCB_LOG (void *pThis, long lUser, ASLV aslv, char *pszMsg);
pThis: Value you specify in pasr->pObjLogR (see next item).
lUser: Value you specify in pasr->lUser (see above).
aslv: Indicates the attention level of the message (ASLV_TERSE,
etc).
pszMsg: Pointer to the null-terminated log message.

pasr->pObjLogR
This is the first argument to the pasr->LogReport callback routine. If you are
coding in C++, you may want to put your “this” pointer here so that you can
restore context in your callback.
The default value is zero.

pasr->RawSync
During eHD_SyncSurvey( ), the IDEA Auto-SYNC process prepares binary
diagnostic reports indicating what is processed on each of the eight channels.
These reports are occasionally critical for offsite support during system
installation and upgrades. You should code a callback routine to permit these
reports to be saved to a file that can be transmitted to a support center.
The default value is NULL which results in no callback.

HCB_ASB
The prototype for this callback function is based on type HCB_ASB:
typedef BOOL HCB_ASB (void *pThis, long lUser, ASCH chan, long lNBytes,
BYTE *pbyData);
pthis: Value you specify in pasr->pObjRawS (see next item).
lUser: Value you specify in pasr->lUser (see above).
chan: Specifies which channel (ASCH_CA1, etc) is being reported.
INBytes and pbyData: These change purpose as data from each channel
is transmitted in consecutive calls to your callback routine. The
sequence for each channel is:

IDEA SDK User’s Guide 231

Chapter 7:
Structures in IDEATOOLS.H

lNBytes = -1; pbyData points to the suggested filename for

this channel.
lNBytes = Number of bytes in ASCII portion of header;
pbyData points to ASCII header.
lNBytes = Number of bytes in binary portion of header;
pbyData points to binary header.
lNBytes = Number of bytes in binary record; pbyData points
to binary record.
…
lNBytes = Number of bytes in binary record; pbyData points
to binary record.
lNBytes = -1; pbyData is NULL. This flags the end of data for
this channel.
The callback routine should create a file of the specified name, write
all of the header and data to it sequentially, and then close the file on
receipt of pbyData==NULL.
Your callback routine can terminate receipt of ASB data for the current
channel at any time by returning FALSE. To receive the full report for a
channel, return TRUE after every message.

pasr->pObjRawS
This is the first argument to the pasr->RawSync callback routine. If you are
coding in C++, you may want to put your “this” pointer here so that you can
restore context in your callback.
The default value is zero.

pasr->pasc[ASCH_N]
Array of AS_CHANNEL pointers, one for each channel selected from processing
in the call to eHD_ASInitiate( ). Pointers for unselected channels are NULL. All
control and monitoring for each channel is controlled by its AS_CHANNEL
structure as described in the next section. Do not modify these values.
When VESA mode scanning is used, the array contains RSETs that were
generated from the VESA CHP template files. All of the VESA RSETs will have
the same video channel setting so there will no longer be a correspondence
between the index into the pasc[] array and the video channel number. In this
case, the index is simply between 0 and (pasr->nVESAStatus-1).

232 IDEA SDK User’s Guide

 Chapter 7:
Structures in IDEATOOLS.H

pasr->wCtrlFlags
This sets some control parameters for the Auto-SYNC process; these parameters
are global and not channel-specific. A symbol has been defined for each of the
flags as follows:
Symbol Description
HDRF_DIGITAL The Tools Library sets this flag to indicate that
digital video input has been detected during a sync
survey. When this flag is set, the call to
HD_VideoMeasure() will attempt to match the video
with the VESA standard formats. This flag is
provided for informational purposes and programs
should not set this flag.
HDRF_KEEPFINEPHASE Don't reset the fine phase adjustment value for
AccuStream boards when performing the Sync
Survey. This value is otherwise reset to its default
prior to a Sync Survey operation.
HDRF_NOSTRAYSYNC Don’t allow stray sync pulses when testing for
horizontal sync on a video channel.
HDRF_STOP Set this flag to signal an Auto-SYNC session to stop.
Depending on the operation in progress, it may take
several seconds for processing to stop.
HDRF_STOPPED This flag value is set by the library in response to
detecting the HDRF_STOP flag value. If
HDRF_STOPPED is set, the library has stopped
processing and it is safe to call eHD_ASTerminate().
HDRF_MONO This flag is set to indicate that the AccuStream is
capturing a monochrome signal on one of its red,
green or blue input channels.

For ready testing of these values, two macros have been created:
#define HDRF_ON(v,f) ( (v##wCtrlFlags & HDRF_##f) == HDRF_##f) // Tests for
the flag
present.
#define HDRF_OFF(v,f) ( (v##wCtrlFlags & HDRF_##f) != HDRF_##f) // Tests for
the flag NOT
present.
Both of the above macros return a Boolean value. Each takes two arguments,
the AS_RUNSTATE pointer with a trailing "." or "->" and the HDRF symbol name
without the "HDRF_". For example, to specify that stray syncs are allowed, use
the code HDRF_ON(pasr->,NOSTRAYSYNC).
The flags may be used throughout the Auto-SYNC process.

IDEA SDK User’s Guide 233

Chapter 7:
Structures in IDEATOOLS.H

pasr->lVESAHTolerance
Sets the percentage (measured in 0.1%) that the video signal's horizontal
frequency must match the horizontal frequency in the VESA CHP template file
in order for the signals to be considered a match. A usable default is set by
eHD_ASInitiate() and should not be changed lightly.

pasr->lVESAVTolerance
Sets the percentage (measured in 0.1%) that the video signal's vertical
frequency must match the vertical frequency in the VESA CHP template file in
order for the signals to be considered a match. A usable default is set by
eHD_ASInitiate() and should not be changed lightly.

pasr->szVESADir
The fully qualified pathname to the VESA CHP template directory. IDEA
normally installs this directory below the CHP directory and stores the path the
CHP directory in the Windows Registry in the key
"HKEY_LOCAL_MACHINE\Software\Foresight\Idea\Common\CHP_DIR". Append
"\\VESACHP" and you will usually have the right directory.
VESA mode scanning does not function if this directory is set incorrectly.

pasr->nVESAStatus
The return value from HD_VideoMeasure() when VESA mode scanning is
enabled. If the value is 0 or less, the VESA scan failed. Otherwise, the VESA
scan has created RSETs corresponding to one or more VESA CHP template files.
The RSETs are stored in pasc[n]->prset, where n = 0..(pasr->nVESAStatus - 1).
Other values in the pasc[] AS_CHANNEL structures (such as error status) should
be ignored when using VESA mode scanning.

pasr->ffinfo
This structure is passed into HD_VideoMeasure to provide hints as to the
preferred aspect ratio of the image.

234 IDEA SDK User’s Guide

 Chapter 7:
Structures in IDEATOOLS.H

AS_CHANNEL Structure
AS_CHANNEL is a structure for control and survey of an analog channel. There
is one of these structures for each channel. Include file, IDEATOOLS.H, declares
type AS_CHANNEL as follows:
Structure Element Data Code
typedef struct {
short nThisSize; 1
ASCMD ascmd; 1 2 3 M S V
ASPHASEL asph; 3 A
ASMODES mVideo; 1 2 M S
ASMODES mode[MODES_HIDEF_N]; 1 2 M V
DWORD dwHorFreq; S
short nHL_Field; S
short nMaxLines; S
DWORD dwHPulse_nsec; S
DWORD dwVPeriod; S
HDVF wVideoFlags; S
ASCMASK ascmBestCS; 1 S
ASCMASK ascmHDP_CS; S
ASCMASK ascmHD4_CS; S
ASCH aschCS; 2 A M S
TOTWID twMin; 2 3 A M
TOTWID twMax; 2 3 A M
TOTWID tw; 2 3 A M
WORD wHeight; A M
PIXELD PD; 2 A M
RSET *prset; 1 A V
WORD wCtrlFlags; 2 M
short nRGBCableType 1
char szComment[255]; 1
WORD wBlankFilter;
2 M
} AS_CHANNEL;
The following are descriptions of the data codes listed above:

Data Code Data Description

1 Set by the user to control the sync sources board survey
function eHD_SyncSurvey( ).
2 Can be changed before calling HD_VideoMeasure( ).
3 Set or changed before calling HD_VideoAlign( ).
A Used only with the analog channels (CA1-4).
M Set or changed by HD_VideoMeasure( ).
S Set or changed by eHD_SyncSurvey( ).
V Set or changed by HD_VideoAlign( ).

IDEA SDK User’s Guide 235

Chapter 7:
Structures in IDEATOOLS.H

Each element of this structure is described in detail below. Keep in mind that
“pasc” is a pointer to the AS_CHANNEL structure that occurs for each channel.
It is set from an array of these pointers in structure *pasr.

pasc->nThisSize
Size of the AS_CHANNEL structure (number of bytes). The Tools library uses this
to verify that the structure is intact. Do not modify this value.

pasc->ascmd
Control specifications. The default value is ASCMD_ENABLE.
This parameter is reserved for Auto-SYNC control flags for the channel.
Currently only ASCMD_ENABLE is used with this variable. Setting this flag to
zero can terminate processing of a channel.

pasc->asph
Phase delay determination method.

pasc->mVideo
Deals with the availability of analog video image data signal on this channel
and is used only with the analog channels (CA1 to CA4). The mVideo values for
the “CT” channels should be left at their default values.
This is the first ASMODES structure. ASMODES structures deal with a particular
use of a video signal and are described in a separate section later.
These values are only used during the early phases of Auto-SYNC processing
while image and sync video data is processed separately. Once the video and
sync data has been merged, only the pasc->mode value is used.

This switch-over from mVideo to mode is shown in the following table:

Auto-SYNC Description
Processing Phase mVideo (Analog only) mode[ ]
Initialization All CAn set to Mode for the board in use is
“interest”. required. Others are set to
interest.
Application (1) Set.
Sync Survey Affects reporting.
Application (2) Match and/or drop Video & C-Sync sources.

236 IDEA SDK User’s Guide

 Chapter 7:
Structures in IDEATOOLS.H

Auto-SYNC Description
Processing Phase mVideo (Analog only) mode[ ]
Video Measure Copy mode[ ] from C-Sync to video
channels. Affects reports.
Application (3) Check, drop, and adjust.
Video Alignment Affects reporting.
Application (4) Check final results.
Termination

pasc->mode[MODES_HIDEF_N]
Target board mode states.
This is an array of ASMODES structures. ASMODES structures deal with a
particular use of the video signal on this channel. One of them, mVideo is
described above. The structures are described in general terms in a section of
their own later in this document.
Each element of this array describes a particular board-type/pass-mode
combination. Symbols have been defined for use as indexes to this array, one
for each of the six IDEA modes. Those six symbols and the IDEA modes are:
1. MODE_HDP_1PASS: Single pass operation of the HI*DEF Plus.
2. MODE_HDP_2PASS: Dual pass operation of the HI*DEF Plus.
3. MODE_HD4_1PASS: Single pass operation of the I-Series/HI*DEF Accura.
4. MODE_HD4_2PASS: Dual pass operation of the I-Series/HI*DEF Accura.
5. MODES_HDP: Any HI*DEF Plus operation (dual or single pass).
6. MODES_HD4: Any I-Series/HI*DEF Accura operation (dual or single
pass).
As an example, the ASMODES structure for dual pass mode on HI*DEF Plus for
channel CT3 could be accessed starting with a pointer to the AS_RUNSTATE
structure 'pasr' with the following code:

{
AS_RUNSTATE *pasr;
ASMODES *pmode;
...
pmode=pasr->pasc[ASCH_CT3]->mode+MODE_HDP_2PASS;
...
}

IDEA SDK User’s Guide 237

Chapter 7:
Structures in IDEATOOLS.H

The last two of the six symbols (MODES_HDP and MODES_HD4) specify mode
combinations rather than individual modes. Use them to specify that the final
RSET must be usable (degree of interest is "required") with a particular
I-Series/HI*DEF board type even though neither of the pass modes is
specifically required (degree of interest being "unnecessary" or "interesting").
If you have not already read the description for pasc->mVideo, review it now. It
includes a description and a chart showing the period of Auto-SYNC processing
where mVideo is used. But there is one more wrinkle to that description which
affects the use of pasc->mode.
At the beginning of the Auto-SYNC process, Auto-SYNC is working with eight
real channels (CA1-4, CT1-4) and one virtual channel (separated sync S S). If a
channel is not compatible with a mode, it is one of these nine channels that
are dropped. By the end of the Auto-SYNC process, Auto-SYNC is working with
at most four channels (CA1-4). The transition occurs when matches are made
between video sources and composite sync sources. When that happens, it is
the ASMODES information from the C-Sync channel, not the video channel that
is retained. This occurs at the very start of the Video Measurement phase. For
consistency, the other ASMODES structure (pmode->mVideo) is set up for each
of the analog channels to control reporting of pre-sync video detection. That
structure is set up during initialization and used in the Sync Survey phase. The
copying of the mode[ ] data from the sync source to the analog video channel
marks the end of mVideo's usefulness. Use of these ASMODES structures as
Auto-SYNC transitions from phase to phase is shown in the diagram at the end
of subsection pasc->mVideo.

pasc->dwHorFreq
Reports the measured horizontal frequency of a channel with C-Sync or H-Sync
information.
This is reported at the end of the eHD_SyncSurvey( ). The units are Hertz.

pasc->nHL_Field
Reports the number of half lines in a vertical field.
A progressive (non-interlaced) video signal is twice the number of line periods
in a frame period. An interlaced video signal is the number of line periods in a
frame period. The phrase “line periods in a frame period” is used because
these line counts include V-Sync lines even when block sync is used.
This is reported at the end of eHD_SyncSurvey( ) for channels with Composite
Sync information.

238 IDEA SDK User’s Guide

 Chapter 7:
Structures in IDEATOOLS.H

pasc->nMaxLines
Reports the number of lines in a frame of video excluding blanking. Only lines
which could (but may or may not) include video are counted. Specifically, lines
with serration or equalization pulses are excluded.
This is reported at the end of eHD_SyncSurvey( ) for channels with Composite
Sync information.

pasc->dwHPulse_nsec
Reports the width of a normal horizontal sync pulse, in nanoseconds, for this
video signal.
This is reported at the end of the eHD_SyncSurvey( ) for channels with
Composite or Horizontal Sync information.

pasc->dwVPeriod
Reports the precise duration of a video field expressed in tenths of
microseconds (10-7 seconds).
This is reported at the end of the eHD_SyncSurvey( ) for channels with
Composite or Vertical Sync information.

pasc->wVideoFlags
This reports some of the characteristics of the video signal discovered on this
channel. A symbol has been defined for each of these characteristics as
follows:

Symbol Description
HDVF_INTERLACE Signal is interlaced.
HDVF_POS_HS H-Sync polarity is reversed (pos.).
HDVF_POS_VS V-Sync polarity is reversed (pos.).
HDVF_POS Reverse both H-Sync and V-Sync polarity.
HDVF_VIDEO Video or sync detected.
HDVF_HSYSC Horizontal sync pulses detected.
HDVF_VSYNC Vertical sync pulses detected.
HDVF_CSYNC Composite sync pulses detected.
HDVF_BLOCKSYNC Block sync used.

IDEA SDK User’s Guide 239

Chapter 7:
Structures in IDEATOOLS.H

For ready testing of these values, two macros have been created:
#define HDVF_ON(v,f) ( (v##wVideoFlags & HDVF_##f) == HDVF_##f) // Tests for
the condition
present.
#define HDVF_OFF(v,f) ( (v##wVideoFlags & HDVF_##f) != HDVF_##f) // Tests for
the condition
NOT present.
Both of the above macros return a Boolean value. Each takes two arguments,
the AS_CHANNEL name with a trailing “.” or “->” and HDFV symbol name
without the “HDFV_”. For example, to check this channel for non-interlaced,
use the code HDVF_OFF(pasc->,INTERLACE).
This is reported at the end of the eHD_SyncSurvey( ) for all channels.

pasc->ascmBestCS
Reports which of the nine possible composite sync sources would most likely be
correct for this channel. Symbols have been declared for these bit values in
this “mask”. When the bit is set, the corresponding channel is a likely
composite sync source for this channel. Those symbols are:
ASCMASK_CA1 to ASCMASK_CA4
ASCMASK_CT1 to ASCMASK_CT4
ASCMASK_SS (separated sync)
These values are set only for the four analog channels and only for analog
channels where a video signal has been detected. They are reported at the end
of eHD_SyncSurvey( ).

pasc->ascmHDP_CS
Reports which of the nine possible composite sync sources can be used with a
HI*DEF Plus board.
On the HI*DEF Plus board, a composite sync source on channels CT1 to CT4 can
only be used for the correspondingly numbered analog channel. So for example,
if C-Sync is found on CT3, it can only be matched with CA3.
Symbols have been declared for these bit values in this “mask”. When the bit is
set, the corresponding channel is a likely composite sync source for this
channel. Those symbols are:
ASCMASK_CA1 to ASCMASK_CA4
ASCMASK_CT1 to ASCMASK_CT4
ASCMASK_SS (separated sync)

240 IDEA SDK User’s Guide

 Chapter 7:
Structures in IDEATOOLS.H

These values are set only for the four analog channels and only for analog
channels where a video signal has been detected. They are reported at the end
of eHD_SyncSurvey( ).

pasc->ascmHD4_CS
This reports which of the nine possible composite sync sources could be used
with an I-Series/HI*DEF Accura board.
Symbols have been declared for these bit values in this “mask”. When the bit is
set, the corresponding channel is a likely composite sync source for this
channel. Those symbols are:
ASCMASK_CA1 to ASCMASK_CA4
ASCMASK_CT1 to ASCMASK_CT4
ASCMASK_SS (separated sync)
These values are set only for the four analog channels and only for analog
channels where a video signal has been detected. They are reported at the end
of eHD_SyncSurvey( ).

pasc->aschCS
Sets the C-Sync source (channel number) for the video on this channel.
This must be set (or left defaulted) between the calls to eHD_SyncSurvey( ) and
HD_VideoMeasure( ). If a valid default is available, it is selected from
pasc->ascmBestCS.

NOTE: This one of the more important values for your application to check and
perhaps correct. There can be many situations where the default can be
wrong and unusable. If left to an unusable default, Auto-SYNC processing
continues without detecting the error and ultimately generates a RSET file
that produces useless images.

pasc->twMin
Sets the minimum permitted HTOTAL and image width.
Function eHD_ASInitiate( ) sets both of these values to zero indicating that
there is no minimum width or HTOTAL for this channel.
Your application can change these defaults before calling HD_VideoMeasure( )
to prevent the Auto-SYNC process (and more specifically, the pixel detection
process) from considering HTOTAL or width values that you know to be too
small. If the Auto-SYNC process discovers that the values you provided
eliminate any possibility of capturing an image, it overrides them.

IDEA SDK User’s Guide 241

Chapter 7:
Structures in IDEATOOLS.H

If you leave either the HTOTAL or width value zero, the Auto-SYNC process sets
it during HD_VideoMeasure( ) to reflect IDEA limitations for the video signal on
this channel.

pasc->twMax
Sets the maximum permitted HTOTAL and image width.
Function eHD_ASInitiate( ) sets both of these values to zero indicating that
there is no maximum width or HTOTAL for this channel.
Your application can change these defaults before calling HD_VideoMeasure( )
to prevent the Auto-SYNC process (and more specifically, the pixel detection
process) from considering HTOTAL or width values that you know to be too
large. If the Auto-SYNC process discovers that the values you provided
eliminate any possibility of capturing an image, it will override them.
If you leave either the HTOTAL or width value zero, the Auto-SYNC process sets
it during HD_VideoMeasure( ) to reflect IDEA limitations for the video signal on
this channel.

pasc->tw
Sets the preferred HTOTAL and image width.
Default values are computed for at least one of these during HD_VideoMeasure( ).
The primary chore of your application, between the HD_VideoMeasure( ) and
HD_VideoAlign( ) calls, is to finalize these values. If you fail to correct these at
that time, the RSET will have to be corrected after Auto-SYNC processing is
complete.
To assist your application in determining a correct result, HD_VideoMeasure( )
leaves pasc->twMin and pasc->twMax with the most pasc->tw limit data.
Also, if pixel detection is used and successful, pasc->PD.peaks[…].tw contains
candidate pasc->tw values. In fact, the default value has to be selected from
among those candidate values.
If you specify or default a non-zero HTOTAL (pasc->tw.wHTOTAL), it is used. If
you specify or default a non-zero width (pasc->tw.wWidth), it is used only if
wHTOTAL is zero.

pasc->wHeight
Reports the measured height (in lines) of the image during HD_VideoMeasure( ).
It is not available before this time. This value can be useful in choosing correct
pasc->tw values when an approximate image width-to-height is known.

242 IDEA SDK User’s Guide

 Chapter 7:
Structures in IDEATOOLS.H

pasc->PD
Used before HD_VideoMeasure( ), selects and controls pixel detection. Used
after HD_VideoMeasure( ), chooses an HTOTAL and/or width value. See PIXELD
Structure later in this chapter for more details.

pasc->prset
This is a pointer to a structure of type RSET. That structure is documented in
the SDK section of this manual. This is the final output of the Auto-SYNC
process.
In VESA scanning mode, the data in *prset may be a valid RSET that represents
a match against a VESA CHP template file upon completion of the
HD_VideoMeasure() call. The validity of the RSET is determined by the value of
the nVESAStatus element of the AS_RUNSTATE structure.
In normal scan mode, the data in *prset is valid only after HD_VideoAlign() and
before eHD_ASTerminate(). Therefore, save this RSET data before calling
eHD_Terminate().

pasc->wCtrlFlags
This sets some control parameters for the Auto-SYNC process. The flags may
also be used to return values from the functions. A symbol has been defined for
each of the flags as follows:

Symbol Description
HDCF_FRODD Force the generated RSET to use ODDUP field ordering.
HDCF_FREVENODD Force the generated RSET to use ON_EVENODD field
ordering.
HDCF_FRODDEVENODD Force the generated RSET to use ODDUP_EVENODD field
ordering.
HDCF_VESAMODE Force the Auto-SYNC process to use VESA mode scanning.
HDCF_REFRAME Set this flag to force an Auto-SYNC session to reframe
the image after setting the phase. Reframing is
automatic for all VESA mode scanning and all Auto-SYNC
sessions using high-speed I-RGB boards.
HDCF_FILTERBLANKING Set this flag to filter blanking lines that appear at the
top of the image.

IDEA SDK User’s Guide 243

Chapter 7:
Structures in IDEATOOLS.H

For ready testing of these values, two macros have been created:
#define HDCF_ON(c,f) ( (c##wCtrlFlags & HDCF_##f) == HDCF_##f) // Tests for
the flag
present.
#define HDCF_OFF(c,f) ( (c##wCtrlFlags & HDCF_##f) != HDCF_##f) // Tests for
the flag NOT
present.
Both of the above macros return a Boolean value. Each takes two arguments,
the AS_CHANNEL name with a trailing “.” or “->” and HDCF symbol name
without the “HDCF_”. For example, to specify this channel to use ODDUP field
ordering, use the code HDCF_ON(pasc->,FRODD).
The HDCF_VESAMODE flag is used to initiate VESA mode scanning. It must be
set on all AS_CHANNEL structures on all video channels, regardless of whether
they have video input.
The flags set are used by the eHD_SyncSurvey( ) function for all channels.

pasc->nRGBCableType
This specifies the cable type that is used; cable types are only significant for
AccuStream boards. The value should be in the range of 0…maxCables, where
maxCables is a system-dependent constant.
The following code sample shows how to retrieve the value of maxCables and
the list of cable types.
//
// Retrieve the active list from the IDEA library.
// Start by finding out how many list items there are.
//
int n, maxCables;
char *pC;
ERRTYPE e
FsiCableList cableList;

memset( &cableList, 0, sizeof(FsiCableList));

e = eHP_GetControlValue(bh, "IRGBCableList", sizeof(cableList),
&cableList);
if (e == 0)
{
//
// Allocate storage for the cable list entries
//
maxCables = cableList.iNumEntries;
cableList.pList
= (char **) malloc( cableList.iNumEntries * sizeof( char *));
for (n = 0; n < maxCables; n++)
{
pC = new char[255];
cableList.pList[n] = pC;
pC = NULL;
}

244 IDEA SDK User’s Guide

 Chapter 7:
Structures in IDEATOOLS.H
e = eHP_GetControlValue( bh, "IRGBCableList", sizeof(cableList),
&cableList);
if (e == 0)
{
//
// The types of I-RGB cable are in cableList.pList[0..maxCables].
// You can do whatever you want with them…
//
...........
}
}
//
// Free any allocated storage
//
for (n = 0; n < cableList.iNumEntries; n++)
{
if (cableList.pList[n] != NULL)
{
delete cableList.pList[n];
cableList.pList[n] = NULL;
}
}
free( cableList.pList);
cableList.pList = NULL;
..........
The following code sample shows how to set and get the current I-RGB cable
type.
//
// Get the current I-RGB Cable Type value. It’s an index into the
cable type
list.
//
UpdateVideoSettingLong uvsl;

uvsl.lValue = 0;
uvsl.pRSet = &rset;
e = eHP_GetControlValue( bh, "IRGBCable", sizeof( uvsl),
(void*)&uvsl
);
//
// If (e == 0), eHP_GetControlValue() returned without an error and
the current
// cable type value is stored in uvsl.lValue.
//
.........
//
// Set the I-RGB Cable Type value to the value in the variable
nCableType.
//
UpdateVideoSettingLong uvsl;

if ((nCableType < 0) || (nCableType >= maxCables))

return; // Don’t change it to an illegal value
uvsl.lValue = (long) nCableType;
uvsl.pRSet = &rset;
e = eHP_SetControlValue( bh, "IRGBCable", sizeof( uvsl),
(void*)&uvsl
);
//
// If (e == 0), eHP_SetControlValue() returned without an error and
the cable
type
// value has been changed.

IDEA SDK User’s Guide 245

Chapter 7:
Structures in IDEATOOLS.H
//
.........

pasc->szComment
A NULL-terminated character array containing a comment line read from a
VESA CHP template file. This may be descriptive text (read from the first
comment line in the CHP file) or it may be generated from the CHP filename (if
no comment was present). It can be used to provide user-friendly descriptions
of the matching VESA template.
The comment string is set after a call to HD_VideoMeasure() returns from a
successful VESA mode scan. If VESA mode scanning was not enabled or if the
scan was unsuccessful, the comment string is invalid.

pasc->wBlankFilter
Used to specify the number of lines to skip in blanking.

ASMODES Structure
Multiple ASMODES structures occur in the AS_CHANNEL structure. Each holds
data relating to the usability or suitability of the video signal on a particular
channel for a particular purpose. The use of these structures is detailed in this
section.
By default, the Auto-SYNC process will check all channels for video and sync
signals and fill RSET structures specifically intended for the Foresight board
type that IDEA Auto-SYNC is using. If possible, that RSET will be made usable by
the other board type as well. By default, IDEA Auto-SYNC also shows a bias
toward single pass mode in situations where both modes are possible for a
given board type. Also by default, the log messages issued by IDEA Auto-SYNC
show no partiality to any particular channel. In all cases, a failure to detect or
recognize a signal on a channel is treated as routine and a notification is logged
but no error is reported.
Your application may want to modify this default operation, for example,
directing the Auto-SYNC process to examine specific channel/mode
combinations while skipping others. Changing the default settings of ASM_N
values in ASMODES structures controls this channel/mode selection process.
The ASM_N values allow you to indicate your "degree-of-interest" in a
channel/mode combination. There are a total of five possible degrees-of-
interest (drop, unnecessary, interesting, required and preferred) that are
described in detail later.

246 IDEA SDK User’s Guide

 Chapter 7:
Structures in IDEATOOLS.H

Although the most critical function of the degree of interest (ASM_N) values is
to disable channel/mode combinations, there are other effects. More
generally, these other ASM_N effects are on the:
1. Actions taken when Auto-SYNC recognizes that a particular IDEA mode
cannot be used with the signal on a particular channel.
2. Selection of measurements and analysis performed on the signal.
3. Values in the final RSET structure.
As IDEA Auto-SYNC proceeds, the application also needs to monitor which
channel/mode combination is still in the running and which has been
eliminated. It may also need to know why combinations have been eliminated.
The ASMODES structures are used to report this information.
This is particularly useful when it is time to match video to composite sync
sources and near the end of the Auto-SYNC process when it is time to save or
use the RSET information.
There is one of these ASMODES structures (shown below) for each of the 54
channel/mode combinations (6 different modes times 9 different channels).
The six modes, nine channels, and method of access are described later.
Each structure contains three elements:
ASM_N anNeed Indicates your level of interest in the signal.
ASM_A aaAvail Returned by Auto-SYNC processing to report signal
suitability.
ERRTYPE e If non-zero, cause for non-suitability.
The ASM_N value “anNeed” is set (or left defaulted) by the application to
control the degree of interest for each channel/mode combination. The ASM_A
value “aaAvail” is set by Auto-SYNC to report the availability (described later)
for each channel/mode combination. The ERRTYPE value 'e' is left zero until a
combination has been eliminated (dropped) and then it is set by Auto-SYNC to
an error code (HPERR_*) specifying the cause for the drop. Only the first error
code is saved. After that, the combination is dropped and cannot be revived
without restarting the Auto-SYNC process. The application code should treat
values “aaAvail” and “e” as read-only. Modifying them could produce difficult
to interpret log entries and other anomalies.
These elements are further detailed in the following subsections. The variable
name “pmode” is used in those sections as the name of a pointer to type
ASMODES (i.e. ASMODES *pmode).

IDEA SDK User’s Guide 247

Chapter 7:
Structures in IDEATOOLS.H

pmode->anNeed
Your application sets this value to indicate its level of interest in the “pmode”
signal use. The following value can be specified:
ASM_N_SKIP: Do not process for this mode at all. This causes
pmode->aaAvail to be set to ASM_A_NOTAVAIL and for
pmode->e to be set to HPERR_TOOL_SKIPPED.
ASM_N_NONEED: No need to support this board/mode combination.
Continue processing for it but do not bias signal
analysis in its favor. If it is eliminated, log the cause
only as a "verbose" notification.
ASM_N_INTEREST: Board/mode of interest for this channel. Fit the signal
recognition to this board/mode if possible. If it
becomes eliminated, log the cause as a "normal" error
notification.
ASM_N_REQUIRED: Board/mode required for this channel. Fit the signal
recognition to this board/mode if possible. If it
becomes eliminated, log the cause as a "terse" error
notification and stop all processing for this channel.
Should this occur, all other non-zero ‘e’ codes (for
other ASMODES structures) for this channel would be
set to HPERR_TOOL_SKIPPED.
ASM_N_PREFERRED: Specifies all the same conditions as ASM_N_REQUIRED
and one more, that this pass mode (single or dual) is
preferred over the other for this channel. This value
can only be applied to one of the MODE_H*
board/mode selections to indicate that for the
particular Foresight board type the particular pass
mode (single or dual) is preferred over the other. If
two conflicting pass modes (single and dual pass for
the same board type) both specify ASM_N_PREFERRED,
they are both downgraded to ASM_N_REQUIRED. Also,
if ASM_N_PREFERRED is applied to one of the
MODES_H* combination selections, it is downgraded to
ASM_N_REQUIRED. When this mode is selected (and
not downgraded), the final aaAvail value can be
ASM_A_NOTAVAIL or ASM_A_AVAILABLE but never
ASM_A_NOTCHOSEN. This selection becomes noted in
the RSET structure as preferred.

248 IDEA SDK User’s Guide

 Chapter 7:
Structures in IDEATOOLS.H

pmode->aaAvail
Value is maintained by the Auto-SYNC functions to indicate the availability of
this board/mode combination for this channel. The possible values are:
ASM_A_NOTAVAIL: Channel cannot be processed with this board/mode
combination. The cause for its elimination is
specified in pmode->e.
ASM_A_NOTDONE: Auto-SYNC processing has not completed. The RSET
structure is not ready nor has this board/mode
combination been eliminated for this channel.
ASM_A_NOTCHOSEN: Signal can be processed for this board/mode
combination but the other mode (dual pass or single
pass) has been chosen.
ASM_A_AVAILABLE: RSET structure is complete and supports this
board/mode combination.

pmode->e
If this value is non-zero, the video signal on this channel cannot be used for the
“pmode” purpose. The value of pmode->e is a standard IDEA SDK error code.

PIXELD Structure
Data type PIXELD is a structure which occurs only in the AS_CHANNEL structure
as element pasc->PD. It is your application’s interface to the pixel detection
process which is available in function HD_VideoMeasure( ). It is used by your
application before HD_VideoMeasure( ) to select and control pixel detection
and after HD_VideoMeasure( ) to choose an HTOTAL and/or width value from
among those discovered by the pixel detection process.
The PD structure is only used on the analog channels (CA1 to CA4) and, of
course, only on those that have not been eliminated for lack of a signal or any
other cause.
Each of the elements in this structure is described in detail below.

PD.bEnable
Selects or deselects the pixel detection process for this channel. The extended
name for this variable would be pasc->PD.bEnable, so “this channel” refers to
that “pasc”.

IDEA SDK User’s Guide 249

Chapter 7:
Structures in IDEATOOLS.H

The default value is TRUE which is set in eHD_ASInitiate( ). You would set it
FALSE to prevent the pixel detection process from being applied to the video
signal on this channel.
If this value is non-zero, the video signal on this channel cannot be used for the
“pmode”.

PD.e
If the pixel detection process does not complete successfully, the cause is
reported as a non-zero value to this variable. This is a normal IDEA ERRTYPE.
A zero value means that pixel detection was successful and a list of
HTotal/width pairs have been prepared.

PD.dMaxW2H
You can limit the range of the pixel detection search in terms of the width-to-
height ratio. This value sets the maximum width-to-height ratio. For example,
if this value is 1.5 and the height is measured at 720 lines, then the maximum
image width will be 1.5*720 or 1080 pixels.
The default value is 2.0. Any value greater than PD.dMinW2H and greater than
0.01 can be specified. If the value you specify is not valid, both PD.dMaxW2H
and PD.dMinW2H will be reset to their defaults.

PD.dMinW2H
You can limit the range of the pixel detection search in terms of the width-to-
height ratio. This value sets the minimum width-to-height ratio. For example,
if this value is 0.75 and the height is measured at 720 lines, then the minimum
image width will be 0.75*720 or 540 pixels.
The default value is 0.5. Any positive values less than PD.dMaxW2H and less
than 100 can be specified. If the value you specify is not valid, both
PD.dMaxW2H and PD.dMinW2H will be reset to their defaults.

PD.peaks[HD_PIXDLIST]
This is an array of structures of type PIXPEAKS. This array stores the results
from the pixel detection process. Each entry in this array includes a TOTWID
value “tw” which specifies a candidate HTotal and width value and a double
value “dScore” which indicates the amount of evidence found to support that
candidate value.
If fewer than HD_PIXDLIST candidate width values are found, the unused
“peaks” entries are zeroed.

250 IDEA SDK User’s Guide

 Chapter 7:
Structures in IDEATOOLS.H

The default HTotal and width values (pasc->tw) are selected from this list by
HD_VideoMeasure( ) based on the dScore values and on a bias towards the 4:3
width-to-height ratio. Your application can override this default by replacing
the pasc->tw values based on another combination of criteria.
The dScore values can also be used to evaluate installation test patterns for
use with Auto-SYNC. Test patterns which give high scores (say over 20,000) to
the correct HTotal and width and low scores (less than half the correct score
value) to each incorrect width are providing good input to the pixel detection
process. The “RESOLVE” test pattern is exceptionally good for this purpose. For
a 520x648 format, it gives a score of 120,000 to the correct choice and less
than 10,000 to incorrect choices.

ASPHASEL Structure
Type ASPHASEL is used in the AS_CHANNEL structure to specify how the phase
delay determination for that channel is performed. Type ASPDMETHOD is used
in the ASPHASEL structure to specify which basic phase delay determination
method is used.

typedef enum {
ASPD_STDEV=O,
ASPD_SHARP,
ASPD_MEAS5,
ASPD_EXAM5
} ASPDMETHOD;
typedef struct {
ASPDMETHOD aspd;
long lParam;
long lHunt;
} ASPHASEL;

Before the phase detection method is applied, a range of HBP/Phase Delay

combinations are determined. These combinations are the candidate values.
The purpose of the phase delay determination method is to select the best
combination from among those candidates. In making this determination these
candidates are "surveyed". Several survey types are possible. The fastest type
of survey is a "fast measurement" survey - where about 17% of the candidates
are examined and only summary information is collected. Once the fast
measurement survey is completed, a "measurement hunt" may be performed in
an attempt to find a candidate with a better phase delay score. These hunts
can range from a fraction of a second to half a minute depending on the extent
of the hunt (lHunt) and the video frame rate. Setting lHunt to 254 or greater
turns the measurement hunt into a “thorough measurement” survey (next).

IDEA SDK User’s Guide 251

Chapter 7:
Structures in IDEATOOLS.H

Alternatively, a "thorough measurement" or "thorough examination" survey may

be performed. In both cases every candidate is surveyed. In a thorough
measurement, only summary information is collected. In a thorough
examination, complete image data is collected and processed. A thorough
measurement survey will take tens of seconds depending on the video format.
A thorough examination survey will take from 1 to 5 minutes (per channel)
depending on the video format.
Listed below is a brief description of each phase delay determination method
and how it uses the parameter values lParam and lHunt (also part of the
ASPHASEL structure).

ASPD_STDEV
A fast measurement survey followed by a measurement hunt is performed in an
attempt to locate the candidate with the lowest pixel value standard
deviation. This candidate falls very close to the midpoint of the pixel edge. The
candidate who falls lParam degrees beyond this edge is then used. A full pixel
period represents 360 degrees. In the default case, ASPD_STDEV is used with
lParam set to 240 and lHunt set to 10. This provides a fairly quick and
reasonably good selection with a wide range of image/format combinations.

ASPD_SHARP
A fast measurement survey followed by a measurement hunt is performed in an
attempt to locate the candidate with the sharpest histogram peaks. This
method provides very good results when the image consists entirely or almost
(>90%) entirely of an alternating-white-pixel-black-pixel pattern. Such patterns
include "resolve" which is mostly a large checker board with one pixel per
square and the 1 pixel “vgrill” which is alternating black and white vertical
stripes one pixel wide. Note that a resolve-like pattern is very good for pixel
detection and phase delay determination but is very poor for black white
adjustments.
If lParam is from 5 to 630, it specifies that this method is to be filtered using
the standard deviation method. This filtering is based on the fact that the
candidate that produces the minimal pixel standard deviation (StDevMin) is in
the midst of the worse candidate values. Those values need not be considered.
When filtering is on (5<=lParam<=630), a range of candidates are eliminated.
The range starts 0.5nSec before StDevMin. The end of the range is a specified
period of time after StDevMin. This time period is specified with lParam in 0.1
nSec units, but is never less than 0.5nSec or greater than half a pixel period.
Depending on the situation, specifying filtering may speed up or slow down the
phase delay determination process. More importantly, it makes the results of

252 IDEA SDK User’s Guide

 Chapter 7:
Structures in IDEATOOLS.H

ASPD SHARP more reliable especially when a substantial portion of the image is
not resolve-like.

ASPD_MEAS5
This method involves a thorough measurement survey of the candidates and is
therefore typically slower than methods ASPD_STDEV and ASPD_SHARP.
However, it is also more precise and reliable than those methods for most
image/format combinations.
Since this method does not employ "hunting", parameter lHunt is not used and
should be set to zero. Parameter lParam specifies filtering and is used exactly
as it is with ASPD_SHARP. When filtering is used with this method, it improves
reliability but has no affect on speed.

ASPD_EXAM5
This method involves a thorough examination survey of the candidates and is
therefore the slowest of the methods. This method requires a minimal amount
of edge information in the image and its selection process is precise and
definitive. The biggest drawback to using this method is that it is usually slower
than picking the phase delay value manually.
This method uses the image data to precisely measure the image stability at
each candidate value. It then selects the most stable. The resulting selection
will produce repeatable results with resilience to changes in temperature and
image content. Based on these criteria, its results are better than can be
selected by eye.
Neither lHunt nor lParam are used and both should be set to zero. Filtering
does not improve the selection results of this method and is not available for
it.

AS_VESAINFO Structure
The IDEATOOLS.H header file declares the AS_VESAINFO structure as follows:
typedef struct {
int nVideoChannel; // Video channel
int nSyncChannel; // sync channel
DWORD dwHFreq; // Horz Frequency measured in Hz
DWORD dwVFreq; // Vert Frequency measured in .01Hz
DWORD dwVTotal; // Vertical Total
BOOL bInterlaced; // TRUE if video is interlaced
BOOL bPosHSync; // TRUE if HSync polarity reversed (pos)
BOOL bPosVSync; // TRUE if VSync polarity reversed (pos)
} AS_VESAINFO;

IDEA SDK User’s Guide 253

Chapter 7:
Structures in IDEATOOLS.H

Each of the elements of this structure are described in detail below:

pVESA->nVideoChannel
The input video channel index. For VESA scanning, this value must be
ASCH_CA1.

pVESA->nSyncChannel
The input video sync channel index. This could be the usual “composite on
green” or more likely, one of the separate sync channel designations.

pVESA->dwHFreq
The horizontal frequency of the video signal, measured in Hz.

pVESA->dwVFreq
The vertical frequency of the video signal, measured in .01Hz.

pVESA->dwVTotal
The vertical total of the video signal, measured in lines.

pVESA->bInterlaced
TRUE if the video is interlaced.

pVESA->bPosHSync
TRUE if the HSYNC has its polarity reversed (positive).

pVESA->bPosVSync
TRUE if the VSYNC has its polarity reversed (positive).

254 IDEA SDK User’s Guide

 Chapter 7:
Structures in IDEATOOLS.H

IDEA SDK User’s Guide 255

Chapter 8:
Tools API Functions and Operating Sequence

CHAPTER 8:
Tools API Functions and Operating
Sequence
The Tools API provides five “C” functions that are used in the Auto-SYNC
process as a set in a specific sequence. These functions are listed in the correct
operating sequence below:
1. eHD_ASInitiate( )
2. eHD_SyncSurvey( )
3. HD_VideoMeasure( )
4. HD_VideoAlign( )
5. eHD_ASTerminate( )
See a sample of this sequence in the sample code for AS_RGB.EXE in Chapter 6.
The above sequence and the purpose of each of the five IDEA Tools functions
are described below. Before reading that description, take a look at how the
pointer pasc is used in the AS_RGB application discussed earlier in this
document. That variable is a pointer to structure (AS_CHANNEL), which occurs
for each channel. It is set from an array of these pointers in structure *pasr.
The reason for noting this now is that pasc is used in parts of the description
that follow.
Although it is important to know the purpose of each of these functions, the
real API story is in structure AS_RUNSTATE. Each of these functions takes a
pointer (or a pointer to a pointer) to this structure as an argument and each
one alters this structure. For additional information concerning this structure,
refer to Chapter 7.
The Tools API also provides functions for generating CHP files based on VESA
mode templates and for automatically recalculating the phase delay/fine phase
adjustment. For these operations, the following functions are provided:
1. HD_GetVESAInfo( )
2. eHD_ASLoadVESADB( )
3. eHD_ASAutoPhase( )

Function Descriptions
This section discusses the IDEA Tools Library functions with more detail.

256 IDEA SDK User’s Guide

 Chapter 8:
Tools API Functions and Operating Sequence

eHD_ASInitiate

Before calling this function, you must claim the I-Series/HI*DEF board that
supports the Auto-SYNC operations. The handle to this board is passed as the
first argument. The second argument should always be ASCMASK_ALL indicating
that all channels will be surveyed. If a narrower search is required, other
values (such as ASCMASK_CA1 or ASCMASK_CT1) can be specified. Note
however, that this would violate Guideline #5 in Chapter 6.
void APPTYPE eHD_ASInitiate(
BoardHandle bh,
ASCMASK ascmIn,
AS_RUNSTATE **ppasr);
Description Allocates the AS_RUNSTATE structure complex. Once this structure is
allocated, only eHD_ASTerminate( ) can deallocate it. Do not attempt
to deallocate it any other way.
Parameters bh Handle to the board.
ascmIn Should always be ASCMASK_ALL.
ppasr Returns the pointer to the AS_RUNSTATE structure.
Note Once this routine is called, the log data "verbosity" level (pasr->aslv)
and pointers to your callback routines (pasr->Spinning, etc) can be set.
Note that for each callback routine there is a data object pointer
(such as pasr->pObjSpin). These data pointers can be used in C++ code
to reestablish the "this" pointer.
Returns 0
Non-zero Error condition and pasr is set to NULL. Any structures
that were allocated by eHD_ASInitiate( ) are deallocated
before returning.

eHD_SyncSurvey

void APPTYPE eHD_SyncSurvey(AS_RUNSTATE *pasr);

Description Surveys channels on the Foresight Imaging board looking for composite
sync, horizontal sync, vertical sync, and syncless video sources.
Parameters pasr Pointer returned by eHD_ASInitiate( ).
Note After eHD_SyncSurvey( ) completes successfully, check and correct the
C-Sync assignments for any syncless video channels. The pertinent
values are:
pasc->aschCS: The default composite sync assignment for this
channel. If this value is not correct, change it.

IDEA SDK User’s Guide 257

Chapter 8:
Tools API Functions and Operating Sequence

pasc->ascmBestCS: A set of defines for ASCMASK_CA1 through

ASCMASK_SS are provided in IDEATOOLS.H.
A bit represents each potential C-Sync
source (CA1-4, CT1-4, and SS). If that bit is
on, then that channel is a likely C-Sync
source for this channel.
pasc->ascmHDP_CS: Uses the same bit mask definitions as
ascmBestCS to indicate all possible C-Sync
sources for this channel using a HI*DEF Plus
board.
pasc->ascmHD4_CS: Uses the same bit mask definitions as
ascmBestCS to indicate all possible C-Sync
sources for this channel using a
I-Series/HI*DEF Accura board.
Other important parameters to review at this time involve pixel
detection. Pixel detection is a method employed in the next routine
(HD_VideoMeasure( )) for creating a small list of likely image widths and
corresponding HTOTALs. The only reason for disabling this feature is to
save time. Pixel detection may take 8 or so seconds per analog channel. If
you don't disable it, you may want to modify its search range. By default,
it only considers widths in the range of half to double the image height. If
very wide and short or very tall and narrow images are possible, you want
to expand this range. If you are certain of what the ratio always is (i.e. 4
to 3) you may want to reduce this range (i.e. maximum of 1.45 and
minimum of 1.15). The pertinent values are all in structure pasc->PD.
There are other settings that can be made at this time as well. Those
are described in the detailed descriptions of the AS_RUNSTATE and
AS_CHANNEL structures later in this manual.
Returns 0 (zero)
Non-zero Error code indicating that it is not possible to conduct
the survey. If this error return is generated, it is best to
use eHD_ASTerminate( ) to release the structures and
then (if appropriate) start over. Once the survey is
complete, default video/C-Sync associations are made
and the program returns.

HD_VideoMeasure
void APPTYPE HD_VideoMeasure(AS_RUNSTATE *pasr);

Description Makes a preliminary contrast and brightness adjustment and the top,
bottom, left and right sides of the image are located. The height of
the image is expressed as a number of easily counted lines. The width
is measured as a video signal time period or as a ratio or percentage of
the total horizontal period.

258 IDEA SDK User’s Guide

 Chapter 8:
Tools API Functions and Operating Sequence

Parameters pasr Finalized width information for each channel.

Note Example of calculations: If the horizontal frequency is 50KHz, then the
horizontal period is 20uSec (the inverse of 50KHz). If a horizontal total
of 1200 is used, pixel positions within this range can be numbered 0 to
1199. If actual image data is found at pixel positions 120 to 1139, then
the image width is (1139+1 - 120)=1020 for a horizontal total of 1200.
In other words, the width is 1020/1200 (85%) of the horizontal period.
Since the horizontal period is 20uSec, the image portion of each line
requires 85% of 20uSec or 17uSec of video signal time.
In the example above, the image width period is 17uSec. The analog
video which occurs during that period must be sampled by the
Foresight Imaging board to produce the same number of pixels that
produced the analog signal to begin with.
One process for converting the width from a time value to a pixel
count (and simultaneously converting the horizontal period to a
correct HTOTAL) is called pixel detection. That process attempts to
locate every transition from one pixel gray shade value to another and
then converts those transition times into a pixel count. The process is
critically dependent on image content. The best images contain a lot
of text or other high-contrast, high-density details across the width of
the image. The result of the process is a list of candidate
width/HTotal combinations each with a “score” indicating how much
evidence was found to support that combination.
The list is often very useful because:
ƒ Given a reasonably detailed image, the correct and precise
horizontal total is usually in the list.
ƒ The list is short, no longer than six entries and usually half that.
ƒ The candidate HTotal values are rarely close to each other, so it's
usually an easy pick.
For each channel a default width value is selected. If pixel detection
is in use for the channel (and was successful), the default width is
selected from among the pixel detection list based on score.
Otherwise, a default is computed based on width-to-height ratio with
a 4:3 ratio favored unless it was excluded in pasc->PD.
Again, there are other settings that can be made at this time. They
are described in the detailed descriptions of the AS_RUNSTATE and
AS_CHANNEL in Chapter 7.
Returns Makes available the default HTotal and width for each channel in
pasc->tw. The application program must either accept or modify these
values. The HTotal (pasc->tw.wHTOTAL) takes precedence over the
width (pasc->tw.wWidth). So if you want to specify the image width,
set pasc->tw.wHTOTAL to zero.

IDEA SDK User’s Guide 259

Chapter 8:
Tools API Functions and Operating Sequence

HD_VideoAlign
void APPTYPE HD_VideoAlign(AS_RUNSTATE *pasr);

Description Generates a complete RSET structure and then performs the final
adjustments for framing, pixel phase alignment, contrast and
brightness.
Parameter pasr Finalized width information for each channel.
Return On return from this routine, there is a valid pasc->prset for each
channel that was successfully Auto-SYNC'ed. These RSET's should be
immediately copied or saved to *.CHP files since they are deallocated
by the final call.

eHD_ASTerminate
void APPTYPE eHD_ASTerminate(AS_RUNSTATE **ppasr);

Description Deallocates the entire AS_RUNSTATE, AS_CHANNEL, RSET complex and

completes the Auto-SYNC “session”.
Parameter ppasr The pointer to the pointer to the AS_RUNSTATE structure.

VESA Mode Scanning

As a shortcut to creating a CHP file, the Tools Library provides a method for
comparing the current video signal to the standard VESA formats. This greatly
reduces the computations required to generate a CHP file because it relies on
the VESA specification to derive the video settings.
VESA scanning is an alternative to the normal Auto-SYNC scanning methods.
You can use one method or the other but the Tools Library will not run both
unless you write your code to run one method after another.
The following conditions must be met to use the VESA scanning method:
1. The framegrabber must be an I-RGB or AccuStream board with video on
channel CA1 and separated H and V sync.
2. The framegrabber board must not be claimed by another process.
3. The path to the IDEA CHP directory must be stored in the Windows Registry
in the key
"HKEY_LOCAL_MACHINE\Software\Foresight\Idea\Common\CHP_DIR". The
VESA template files are stored in a subdirectory of this directory path
called "VESACHP".

260 IDEA SDK User’s Guide

 Chapter 8:
Tools API Functions and Operating Sequence

By default, IDEA installs the VESA template CHP files in C:\Program

Files\Foresight\Idea\Chp\VESACHP and sets the registry appropriately.
Once these conditions are met, VESA mode scanning can be used. The
procedure is basically the same as a regular Auto-SYNC operation except some
control flags must be set and some data must be added to the AS_RUNSTATE
structure. The output results must be interpreted differently, too.
The differences in Auto-SYNCing with VESA mode scanning are:
1. After the call to eHD_SyncSurvey(), the caller must OR every active video
channel's wCtrlFlags value with HDCF_VESAMODE. This control flag tells
HD_VideoMeasure() that it must perform the VESA mode scan.
2. The pasr->szVESADir must be set with the fully qualified path to the VESA
CHP directory (for example, "c:\\Program
Files\\foresight\\idea\\chp\\vesachp").
3. After returning from HD_VideoMeasure(), the VESA scanning is complete.
None of the usual Tools Library calls (except eHD_ASTerminate) are
required.
If the function returned an error code, the scan failed.
Otherwise, pasr->nVESAStatus is a count of the number of matching VESA
modes. For each match (possibly 0), a corresponding RSET has been created
at pasr->pasc[0.. pasr->nVESAStatus-1]. The pasr->pasc[]->mVideo.e value
may be invalid so don't rely on it to determine if the RSET is legal.
If VESA mode scanning fails, the Auto-SYNC operation fails and cannot be
continued. You can write your code to provide an alternate control path to
restart the Auto-SYNC operation without VESA mode scanning.
You can create your own CHP files and add them to the VESACHP directory.
They must adhere to the VESA mode scanning requirements (e.g., separated
sync). Be sure to include a comment name for the file; see one of the existing
files for examples of how to insert comment names.
The following code sample demonstrates a basic VESA mode scanning
implementation. It is only supported on the I-RGB or AccuStream framegrabber
boards.
#include "string.h"
#include “hdp_lib.h”
#include "ideatools.h"
void main(char *szVESACHPDir)
{
BoardHandle bh;
AS_RUNSTATE *pasr;
ASCH asch;
AS_CHANNEL *pasc;
char szCHPName[_MAX_PATH];
ERRTYPE e;

IDEA SDK User’s Guide 261

Chapter 8:
Tools API Functions and Operating Sequence

bh = (BoardHandle)nHP_ClaimAll(0,1);
if (bh)
{
//
// Do a normal initialize and sync survey
//
eHD_ASInitiate( bh, ASCMASK_ALL, &pasr);
eHD_SyncSurvey( pasr);
//
// Mark the video channels with a control flag
// to indicate VESA mode scanning
//
for (asch = ASCH_CA1; asch < ASCH_CA4; asch++)
{
pasc = pasr->pasc[asch];
if ((pasc != NULL) && (pasc->mVideo.e == 0))
{
pasc->wCtrlFlags |= HDCF_VESAMODE;
}
}
//
// Save the path to the VESA CHP directory
// to the AS_RUNSTATE structure
//
strcpy( pasr->szVESADir, szVESACHPDir);
//
// Calling HD_VideoMeasure() will do the VESA scan.
// It will return an error code if something goes wrong.
//
e = HD_VideoMeasure( pasr);
if (e)
{
//
// Error occurred. Cleanup and exit.
//
TRACE("Error %d from HD_VideoMeasure\n", e);
eHD_ASTerminate( &pasr);
HP_Unclaim( bh);
return;
}
//
// pasr->nVESAStatus is the number of VESA modes that
// matched. It can be 0...4. The corresponding RSETs are
// stored in the pasr->pasc[asch] structures.
//
if (pasr->nVESAStatus == 0)
{
//
// No matches. Cleanup and exit.
//
TRACE("No VESA mode matched the input video signal\n");
eHD_ASTerminate( &pasr);
HP_Unclaim( bh);
return;
}
//
// Loop through the channels and create CHPs from the RSETs.
//
for (asch=ASCH_0; asch<ASCH_N; asch++)
{
if ((asch - ASCH_0) < pasr->nVESAStatus)
{
//

262 IDEA SDK User’s Guide

 Chapter 8:
Tools API Functions and Operating Sequence
// This is a valid VESA RSET. Write it out
//
strcpy( szCHPName, "AS_CA1.CHP");
szCHPName[5] += asch;
remove( szCHPName);
pasc = pasr->pasc[asch];
eHP_RSET_FWrite( bh, szCHPName, pasc->prset);
}
}
//
// Cleanup the AS_RUNSTATE structure and release the board.
//
eHD_ASTerminate( &pasr);
HP_Unclaim( bh);
}
}
This minimalist code sample is similar to the one in Chapter 6 except that it
performs a VESA scan.

Function Descriptions
This section discusses the VESA mode scanning functions of the IDEA Tools
Library with more detail. These are utility functions that are available from the
library but are not required in order to use VESA scanning.

HD_GetVESAInfo

A utility function used to retrieve video and sync information specific to a

particular video channel; you will probably never need to call this function
yourself. This function requires information in the AS_RUNSTATE be set as it
would be after a call to eHD_SyncSurvey(). Additionally, the caller must modify
the channel information to disable all uninteresting video channels (if there are
more than one).
void APPTYPE HD_GetVESAInfo (
AS_RUNSTATE *pasr,
AS_VESAINFO *pVESA);

Description Retrieves VESA information (H/V Frequencies, sync locations, etc.).

This function assumes there's only one active video channel.
Parameters pasr A pointer to the AS_RUNSTATE structure that defines all
channel configurations and data from a prior sync survey
call.
pVESA A pointer to an AS_VESAINFO structure.
Returns On return, the structure referenced by pVESA will be populated with
information about the video signal.

IDEA SDK User’s Guide 263

Chapter 8:
Tools API Functions and Operating Sequence

eHD_ASLoadVESADB

A function to preload the VESA CHP database. The database is automatically

loaded during the first attempt at VESA scanning. Preloading can save this
startup cost.
ERRTYPE APPTYPE eHD_ASLoadVESADB(
AS_RUNSTATE *pasr);
Description Causes the Tools Library to scan the VESA template CHP files and build
a database of video information. Multiple calls to this function are
ignored and harmless.
Parameters pasr A pointer to the AS_RUNSTATE structure that defines all
channel configurations and data.
Note The path to the VESA CHP directory must be copied to the character
array referenced by pasr->szVESADir or this function will fail. You will
need to read the path to the CHP directory from the registry and
append the "\\VESACHP" directory path to it.
Returns 0
Non-zero Error condition occurred during loading. The error return
value is usually HPERR_ASCHAN_NO_VESA.

Automatic Phase Recalculation

One of the last steps in generating a new CHP file is to determine the proper
phase delay setting. The AccuStream boards support fine phase adjustment and
these values are set automatically during an Auto-SYNC session. The methods
for determining phase are also provided to callers through the Tools Library API
to allow on-the-fly recalculation of phase delay or fine phase adjustment on an
existing RSET structure.
The following conditions must be met to use the automatic phase recalculation
function:
1. The framegrabber must be a monochrome, I-RGB or AccuStream board. I-
Color boards do not use phase delay or fine phase adjustment and are not
supported by this function.
2. The framegrabber board is available for use (i.e., is not claimed by another
process). It must be claimed in non-interrupt mode.
3. An valid CHP file must be loaded into memory and activated via an
eHP_RSET_Set() call.
4. Video and sync must be provided to the framegrabber board on the
channels specified in the RSET. It is helpful if the image is full-screen and

264 IDEA SDK User’s Guide

 Chapter 8:
Tools API Functions and Operating Sequence

includes some rapid horizontal transitions between light and dark (e.g.,
grill pattern, text).
Once these conditions are met, the function is used as shown in the following
code sample.
ERRTYPE RunAutoPhase(
WORD wBoardID, /* ID of board to use */
RSET *pRSET, /* Video settings */
BOOL bIsIRGB /* TRUE if board is I-RGB or AccuStream */
)
{
BoardHandle bh;
int nRGBCableType;
ASPHASEL asph;
ERRTYPE e;
long lOldPhase, lNewPhase;
int nPhaseMethod;
UpdateVideoSettingLong uvsl;
//
// Set nPhaseMethod to a value 0..5 to match the algorithm
// to be used and then load the ASPHASEL with the parameters
// for the type of algorithm to perform. These are the same values
// that the Auto-SYNC application uses.
//
nPhaseMethod = 0; /* Or whatever value you want */
switch( nPhaseMethod)
{
case 1: /* Refined */
asph.aspd = ASPD_MEAS5;
asph.lParam = 630;
asph.lHunt = 0;
break;
case 2: /* Thorough */
asph.aspd = ASPD_EXAM5;
asph.lParam = 0;
asph.lHunt = 0;
break;
case 3: /* Standard deviation; best match */
asph.aspd = ASPD_STDEV;
asph.lParam = 240;
asph.lHunt = 254;
break;
case 4: /* Sharpness with hunting */
asph.aspd = ASPD_SHARP;
asph.lParam = 630;
asph.lHunt = 10;
break;
case 5: /* Sharpness, maximum */
asph.aspd = ASPD_SHARP;
asph.lParam = 630;
asph.lHunt = 254;
break;
case 0: /* Coarse */
default:
asph.aspd = ASPD_STDEV;
asph.lParam = 240;
asph.lHunt = 10;
break;
}
//
// If the board was already claimed, unclaim it
// before executing the following code.

IDEA SDK User’s Guide 265

Chapter 8:
Tools API Functions and Operating Sequence
//
// Claim the board in non-interrupt mode, then run
// the automatic phase algorithm.
//
bh = bhHD_Claim( wBoardID, HDCLAIM_NO_INTR);
if (bh <= 0)
{
TRACE("ERROR: Unable to claim board in HDCLAIM_NO_INTR mode\n");
return;
}
//
// If the board is an I-RGB board, find its cable type
//
nRGBCableType = 0;
if (bIsIRGB)
{
e = eHP_GetControlValue( bh, "IRGBCable",
sizeof( uvsl), (void*)&uvsl);
if (e == 0)
nRGBCableType = (int) uvsl.lValue;
}
//
// If you wanted to have a progress indicator, create a
// dialog box with a CProgressCtrl or other display
// device. You'll need to pass a function and class
// pointer to the eHD_ASAutoPhase() function; it
// uses the same parameters as AS_RUNSTATE to handle
// "spin" controls.
//
// Save the old phase just for reference.
//
lOldPhase = pRSET->lRegs[HPR_PHASE];
e = eHD_ASAutoPhase( bh,
pRSET,
&asph,
nRGBCableType,
wCtrlFlags,
NULL, /* or an HCB_BUSY function pointer */
NULL /* or an object pointer */
);
//
// Returning from the function means it is completed.
// You can close your progress indicator.
//
// Release the board
//
HP_UnClaim( bh);
//
// The RSET is modified with the new phase value. You can
// compare the new phase value with lOldPhase to see if
// they are different. This sample doesn't do anything
// with the values. NOTE: If the board is an I-RGB 165 or
// I-RGB 200, phase will not be modified, but FinePhaseAdjust
// (accessed through eHP_GetControlValue, eHP_SetControlValue)
// is set instead.
//
lNewPhase = pRSET->lRegs[HPR_PHASE];
return e;
}

266 IDEA SDK User’s Guide

 Chapter 8:
Tools API Functions and Operating Sequence

Function Descriptions
This section discusses the phase determination function in more detail.

eHD_ASAutoPhase

Before calling this function, you must claim the Foresight board.
ERRTYPE APPTYPE eHD_ASAutoPhase(
BoardHandle bh,
RSET *pRSET,
ASPHASEL *pasph,
int nRGBCableType,
WORD wCtrlFlags
HCB_BUSY *pfSpinning,
void *pObjSpin);
Description Attempts to automatically adjust for optimal phase. If you want to be
able to return your phase value to its original value (or even to detect
a change), you should save its value prior to calling this function.
The phase determination algorithm is defined by pasph.
If the board supports fine phase adjustment, the phase
algorithm will be ignored and the fine phase adjustment value
will be set instead.
Parameters bh Handle to the board.
pRSET Pointer to the RSET whose phase is to be adjusted.
pasph Pointer to an ASPHASEL structure that defines the phase
determination algorithm and parameters.
nRGBCableType
The cable type index for an I-RGB or AccuStream board
(e.g., 0 = DVI-to-BNC, 1 = DVI-to-VGA, 2 = DVI-to-DVI) or
0 if a non-IRGB board is being used.
wCtrlFlags Flags to control the survey. 1 = YPbPr input, 2 =
Monochrome input on one of the red, green or blue
channels.
pfSpinning
Pointer to a callback function to receive progress status.
See the description of “pasr->Spinning” in Chapter 7 for
additional information.
pObjSpin Object pointer for pfSpinning; can be used to restore
context in the callback. See the description of
"pasr->pObjSpin" in Chapter 7 for additional information.
Returns Non-zero Error condition occurred during processing.

IDEA SDK User’s Guide 267

Appendix A:
IDEA SDK and Tools Library Functional Summary

APPENDIX A:
IDEA SDK and Tools Library
Functional Summary
This Appendix summarizes the functions listed in Chapter 4, C Function Listings,
as well as in Chapter 8, Tools API Functions and Operating Sequence. However,
these tables sort the functions by functional categories:
ƒ Board Information
ƒ Image Data Access
ƒ Image Handle
ƒ Millisecond Timer
ƒ Preparing Board Access
ƒ Register Functions
ƒ Tools
ƒ Video Control

Board Information
Name Description
nHP_GetBoardInfo Retrieves specified board information.

Image Data Access

Name Description
ihHD_Allocate Allocates frame grabber memory space for a specified image
format and assigns an image handle to it.
eHP_FBFastRead Copies a block of data from the IDEA frame grabber memory
into fpwBuf. Column and line numbers start at zero.
eHP_FBHisto Accumulates histogram data from pixel values in frame grabber
memory. Column and line numbers start at zero. The
accumulation starts at column wColumn, line wLine in frame
grabber memory. This array is never zeroed by eHP_FBHisto( ).

268 IDEA SDK User’s Guide

 Appendix A:
IDEA SDK and Tools Library Functional Summary

Image Handle
Name Description
eHD_Command Executes the specified command as set up in the specified
image handle.
bHD_CommandDone Returns status of Command Done.
eHD_Deallocate Makes a previously allocated image buffer in the frame
grabber memory available and invalidates the image handle.
eHD_DeallocateAll Invalidates all image handles assigned to the specified
board. This releases all use of the board’s memory and
permits board-handle-based calls to the board.
eHD_FBFastReadPixel Transfers any rectangular section of a captured image from
the image buffer in frame grabber memory to the
application buffer fpwBuf. Either 8-bit or 10-bit pixels can
be transferred. HI*DEF Plus only: Only 8-bit pixels can be
transferred.
eHD_FBHistoPixel Accumulates pixel code histogram data from any
rectangular section of a captured image from the image
buffer in frame grabber memory to the application buffer
fpwBuf. Either 8-bit or 10-bit pixel codes can be
histogrammed. Neither eHD_FBHistoPixel( ) nor
eHP_FBHisto( ) ever initialize (zero) the histogram array.
eHD_RSET_Get Gets the RSET currently in use by an image handle.
eHD_RSET_Set Configures an image handle for use with a Foresight Imaging
board.
eHD_SetChannel Changes the channel used with a specified image handle.

Millisecond Timer
Name Description

fine_abswait Returns at a specified date and time (or very soon

thereafter – system conditions permitting).
fine_add Adds two millisecond time values. It is assumed that at least
one of the values is a time interval.
fine_ascii_local Converts absolute date/times or elapsed days/milliseconds
to an ASCII string.
fine_delta Adds the specified number of milliseconds (either positive
or negative – the second argument) to the time value
pointed to by the first argument.

IDEA SDK User’s Guide 269

Appendix A:
IDEA SDK and Tools Library Functional Summary

Name Description

fine_later Adds the specified number of milliseconds (second

argument) to the current time and stores this value in the
first argument. Adjustments are made to accommodate
timer limitations.
fine_now Stores the current date and time at the location specified in
the first argument.
fine_subtract Subtracts the second argument from the value pointed to by
the first argument. FINE_TIME structures may refer to
absolute date/times or to elapsed days/milliseconds. If both
arguments deal with the same type of data (both absolute
or both elapsed), the result is an elapsed time. If the first
points to an absolute time and the second is an elapsed
time, the result is an absolute time.
fine_wait Returns after waiting the specified number of milliseconds.

Preparing Board Access

Name Description
bhHP_Claim Sets up board at the specified slot number.
This function also sets up access to the board’s
Frame Grabber memory at the 4K memory block
starting at dw4KMem.
nHP_ClaimAll Scans for up to 15 Foresight Imaging boards and
claims all of them. This preempts all claims
made by bhHP_Claim( ).
eHP_Close Prohibits IDEA access to the specified Open
Data structure.
_HP_Error Declares that Error wError has been
encountered while processing the board handle.
eHP_Open Prepares a board for use by associating it with
an Open Data structure.
HP_UnClaim Releases possible claim on a board.

Register Functions
Name Description
eHD_RSET_Check Checks an RSET structure against mode-specific criteria.

270 IDEA SDK User’s Guide

 Appendix A:
IDEA SDK and Tools Library Functional Summary

Name Description
eHP_RSET_FRead Reads the contents of a file containing IDEA video settings
data. Before calling this routine, fopen( ) must be called to
prepare the IDEA Configuration file (*.CHP) for reading. This
routine decodes the ASCII data in the *.CHP file and
performs various syntax checking. If no errors are found,
structure *prset is returned with a binary form of the *.CHP
data.
eHP_RSET_FWrite Writes the IDEA video settings data to an ASCII file. Before
calling this routine, fopen( ) must be called to prepare the
IDEA Configuration file (*.CHP) for writing. This routine
encodes the data in the RSET structure to the ASCII *.CHP
format and writes the data, a line at a time, to the file
opened on fpCHP. fpCHP is not repositioned before the data
is written. It is therefore possible to write descriptive
comments to the file before calling this routine.
eHP_RSET_Set Configures a Foresight Imaging board. Data should already
be loaded into *prset with a call to eHP_RSET_FRead( ).

Tools
Name Description
eHD_ASInitiate Allocates the AS_RUNSTATE structure complex. Once this
structure is allocated, only eHD_ASTerminate( ) can
deallocate it. Do not attempt to deallocate it any other
way.
eHD_ASTerminate Deallocates the entire AS_RUNSTATE, AS_CHANNEL, RSET
complex and completes the Auto-SYNC "session".
bHP_CSyncDetect Reports status of Command Ready.
nHP_Report Provides a list of I-Series/HI*DEF boards found at system
start-up. This should be called before boards are claimed or
opened.
eHD_SyncSurvey Surveys channels on the I-Series/HI*DEF board looking for
composite sync, horizontal sync, vertical sync, and syncless
video sources.
HD_VideoAlign Generates a complete RSET structure and then performs the
final adjustments for framing, pixel phase alignment,
contrast and brightness.

IDEA SDK User’s Guide 271

Appendix A:
IDEA SDK and Tools Library Functional Summary

Name Description
HD_VideoMeasure Makes a preliminary contrast and brightness adjustment and
the top, bottom, left and right sides of the image are
located. The height of the image is expressed as a number
of easily counted lines. The width is measured as a video
signal time period or as a ratio or percentage of the total
horizontal period.

Video Control
Name Description
eHP_Command Sets up specified command (wCommand) of specified
board.
bHP_CommandDone Returns status of Command Done.
eHP_CommandDone Waits up to wTimeout_mS milliseconds for Command
Done, then returns. Error condition is generated on
timeout. Timeout value may be defaulted by specifying
VIDEOTIMEOUT.
bHP_CommandReady Returns status of Command Ready.
eHP_CommandReady Waits up to wTimeout_mS milliseconds for Command
Ready then returns. Error condition is generated on
timeout. Timeout value may be defaulted by specifying
VIDEOTIMEOUT.
eHP_SetBlackLevel Sets the Black Level.
eHP_SetChannel Sets the current video signal channel.
eHP_SetGain Sets the Gain Range.

Live Video Display and Streaming

Name Description
eHD_LiveDisplayInit Prepare library to display live video in a window.
eHD_LiveDisplayMode Begin or end live video display.
eHD_LiveStreamInit Prepare Library for streaming to buffers.
eHD_LiveStreamMode Begin, end or pause live streaming operation.
eHD_LiveStreamClose Clean up and unlock streaming buffers.

272 IDEA SDK User’s Guide

 Appendix A:
IDEA SDK and Tools Library Functional Summary

Function Return Values

This Appendix lists the messages that you may receive from the functions listed
in Chapter 4, C Function Listings, as well as in Chapter 8, Tools API Functions and
Operating Sequence.

It is recommended that you refer to HDP_ERR.H for an up-to-date listing of

these return values. This file is subject to change with each library revision.
Descriptions for each of these returns can be found in the file called
HDPERROR.DAT.

Function Return Decimal Value

HPERR_NO_VXD 500
HPERR_BAD_ERR_REV 501
HPERR_PARAM 502
HPERR_HANDLE 503
HPERR_EECORRUPT 504
HPERR_EEWRITE 505
HPERR_CLOSENEST 506
HPERR_CLOSE 507
HPERR_CHP_READ 508
HPERR_CHP_EOF 509
HPERR_CHP_SYNTAX 510
HPERR_CHP_TAG 511
HPERR_CHP_HEXPT 512
HPERR_CHP_JUNK 513
HPERR_CHP_SYMBOL 514
HPERR_TIMEOUT 515
HPERR_NO_BOARDS 516
HPERR_RSETV_VCHAN 520
HPERR_RSETV_CSYNC 521
HPERR_RSETV_PCLOCK 522
HPERR_RSETV_RESV0 523
HPERR_RSETV_RESV1 524
HPERR_RSETV_VTOTAL 525
HPERR_RSETV_FR_MSEC 526
HPERR_RSETV_INTERLACE 527
HPERR_RSETV_VSTYPE 528

IDEA SDK User’s Guide 273

Appendix A:
IDEA SDK and Tools Library Functional Summary

Function Return Decimal Value

HPERR_RSETV_VBP 529
HPERR_RSETV_HEIGHT 530
HPERR_RSETV_RESV2 531
HPERR_RSETV_RESV3 532
HPERR_RSETV_HFREQ 533
HPERR_RSETV_HTOTAL 534
HPERR_RSETV_HBS 535
HPERR_RSETV_WIDTH 536
HPERR_RSETV_HS_NSEC 537
HPERR_RSETV_HBP 538
HPERR_RSETV_RESV4 539
HPERR_RSETV_GAIN 540
HPERR_RSETV_BLEVEL 541
HPERR_RSETV_BLACKREF 542
HPERR_RSETV_WHITEREF 543
HPERR_RSETV_PIXSET10 544
HPERR_RSETV_PIXELSET 545
HPERR_RSETV_ZOOMDOWN 546
HPERR_RSETV_RESV5 547
HPERR_RSETV_RESV6 548
HPERR_RSETV_PITCH 549
HPERR_RSETV_PASSMODE 550
HPERR_RSETV_DPDELAY 551
HPERR_RSETV_PHASE2 552
HPERR_RSETV_PHASE 553
HPERR_RSETV_VATTR 554
HPERR_RSETV_CONTROL 555
HPERR_RSETV_IMAPORT 556
HPERR_RSETV_HSTART 557
HPERR_RSETV_VSTART 558
HPERR_RSETV_RESV7 559
HPERR_RSETV_REFPROG 560
HPERR_RSETV_REFBPTYPE 561
HPERR_RSETV_REFBOARD 562
HPERR_RSETV_REF_MPAL 563

274 IDEA SDK User’s Guide

 Appendix A:
IDEA SDK and Tools Library Functional Summary

Function Return Decimal Value

HPERR_RSETV_REF_PLL 564
HPERR_RSET_SYNCFILTER 565
HPERR_RSETV_PIXFREQ 566
HPERR_RSETV_VERTFREQ 567
HPERR_RSETV_RES59 579
HPERR_RSETV_MAINSET 580
HPERR_RSET_NEEDMAIN 581
HPERR_RSETS_PFREQ 582
HPERR_RSETD_PFREQ 583
HPERR_RSETS_HTOT 584
HPERR_RSETD_HTOT 585
HPERR_RSET_ODD_ILACE 586
HPERR_RSET_ZWIDTH 587
HPERR_RSET_ZHEIGHT 588
HPERR_RSET_HEND 589
HPERR_RSET_VEND 590
HPERR_RSET_HBPTIME 591
HPERR_IMAPORT_RANGE 600
HPERR_PHASE_RANGE 601
HPERR_TOPLEFT_VALUES 602
HPERR_GAIN_RANGE 603
HPERR_BWREF_VALUES 604
HPERR_PIXELSET_RANGE 605
HPERR_BLEVEL_RANGE 606
HPERR_CHANNEL_RANGE 607
HPERR_SYNCFILTER_RANGE 608
HPERR_COMMAND_READY 610
HPERK_COMMAND_DONE 611
HPERR_COMMAND_CODE 612
HPERR_ODD_FB_ALIGN 613
HPERR_FG_LINE_LIMIT 614
HPERR_EEDATACHECK 615
HPERR_FILEP_PARAM 616
HPERR_ENCODE_REG 617
HPERR_CONT_DP_LIB 618

IDEA SDK User’s Guide 275

Appendix A:
IDEA SDK and Tools Library Functional Summary

Function Return Decimal Value

HPERR_CONTINUOUS_DP 619
HPERR_PHASEO_MIN 620
HPERR_PHASEO_MAX 621
HPERR_PHASE1_MIN 622
HPERR_PHASE1_MAX 623
HPERR_CSYNC_AWAY 624
HPERR_MEMORY_ALLOC 625
HPERR_USING_IHANDLES 626
HPERR_NOCURRENT_1PASS 627
HPERR_FAULT 628
HPERR_PIXEL_TYPE 629
HPERR_IMAGE_BOUNDS 630
HPERR_BOARDFEATURE 631
HPERR_NOT_IMPLEMENTED 632
HPERR_SYNC_RSET 633
HPERR_ISERIES 634
HPERR_INITIALIZING_INTS 635
HPERR_UNKNOWN_DRIVER_FCTN 636
HPERR_DEVICE_NOT_FOUND 637
HPERR_BIOS_NOT_FOUND 638
HPERR_NOT_OPEN 639
HPERR_NOT_FOUND 640
HPERR_READING_REGISTRY 641
HPERR_ABO_NOT_ASYNC 642
HPERR_ABO_ASYNC 643
HPERR_ABO_QUEUED 644
HPERR_ABO_ON_HOLD 645
HPERR_ABO_SCHEDULED 646
HPERR_ABO_RUNNING 647
HPERR_ABO_CANCELED 648
HPERR_ABO_COMPLETED 649
HPERR_ABO_FAILED 650
HPERR_ABO_EXPIRED 651
HPERR_NOT_ON_HOLD 652
HPERR_INITFAILED 653

276 IDEA SDK User’s Guide

 Appendix A:
IDEA SDK and Tools Library Functional Summary

Function Return Decimal Value

HPERR_NOSSTRACKING 654
HPERR_BOARDSVARY 655
HPERR_SYNCSRCVARY 656
HPERR_IHCONFLICT 657
HPERR_GATEFILEDATA 658
HPERR_MEMORY_LOCK 659
HPERR_MAX_STREAM_IN_PROGRESS 660
HPERR_BUFFER_LOCK 661
HPERR_TOO_MANY_DESCRIPTORS 662
HPERR_FUNCTION_DEPRECATED 663
HPERR_BOARD_DOES_NOT_SUPPORT_S 664
TREAMING

Error Codes for the IDEA Tools Library

Function Return Decimal Value
HPERR_TOOL_SEQUENCE 800
HPERR_TOOL_RSETVIDEO 801
HPERR_TOOL_RSETCSYNC 802
HPERR_TOOL_RSETHTOT1 803
HPERR_TOOL_RSETPFREQ 804
HPERR_TOOL_DLL_REV 805
HPERR_TOOL_DLL_DATE 806
HPERR_TOOL_STOPPED 810

IDEA SDK User’s Guide 277

Appendix A:
IDEA SDK and Tools Library Functional Summary

IDEA Auto-SYNC Channel Elimination Codes

Function Return Decimal Value
HPERR_ASCHAN_VID_NOSYNCS 820
HPERR_ASCHAN_VID_SILENT_HI 821
HPERR_ASCHAN_VID_SILENT_LO 822
HPERR_ASCHAN_VID_MISSING 823
HPERR_ASCHAN_VID_ERATIC 824
HPERR_ASCHAN_VID_SCANT 825
HPERR_ASCHAN_VID_WIDESYNCS 826
HPERR_ASCHAN_SYNC_SCANT 827
HPERR_ASCHAN_SYNC_HIDDEN 828
HPERR_ASCHAN_HSYNC_HIGH 829
HPERR_ASCHAN_OKAY_VSYNC 830
HPERR_ASCHAN_CT2_VSYNC 831
HPERR_ASCHAN_HSYNC_RANGE 832
HPERR_ASCHAN_HSYNC_SCANT 831
HPERR_ASCHAN_HSYNC_UNSTABLE 834
HPERR_ASCHAN_HSYNC_WANDER 835
HPERR_ASCHAN_HSYNC_FADE 836
HPERR_ASCHAN_VSYNC_BOUNCE 837
HPERR_ASCHAN_IMAGE_PHASE 838
HPERR_ASCHAN_IMAGE_HSWIDTH 839
HPERR_ASCHAN_OKAY_HSYNC 840
HPERR_ASCHAN_CT1_HSYNC 841
HPERR_ASCHAN_VSYNC_LONG 842
HPERR_ASCHAN_OKAY_CSYNC 843
HPERR_ASCHAN_SS_CT1HSYNC 844
HPERR_ASCHAN_SS_CT2VSYNC 845
HPERR_ASCHAN_SS_NOVIDEO 846
HPERR_ASCHAN_HIDEFPLUS 847
HPERR_ASCHAN_HIDEF4 848
HPERR_ASCHAN_HIDEF_I25 849
HPERR_ASCHAN_HIDEF_I50 850
HPERR_ASCHAN_HIDEFTYPE 851
HPERR_ASCHAN_NEEDSYNC 852

278 IDEA SDK User’s Guide

 Appendix A:
IDEA SDK and Tools Library Functional Summary

Function Return Decimal Value

HPERR_ASCHAN_SYNCLESS 853
HPERR_ASCHAN_CT4GRAB 854
HPERR_ASCHAN_WIDTHLIMIT 855
HPERR_ASCHAN_MANYSYNCS 856
HPERR_ASCHAN_NO_VESA 860
HPERR_ASCHAN_HIDEF_I60 861
HPERR_ASCHAN_HIDEF_I75 862
HPERR_ASCHAN_HIDEF_IRGB25 863
HPERR_ASCHAN_HIDEF_IRGB50 864
HPERR_ASCHAN_HIDEF_IRGB75 865
HPERR_ASCHAN_HIDEF_IRGB165 866
HPERR_ASCHAN_HIDEF_IRGB200 867
HPERR_ASCHAN_HIDEF_IRGB170 868
HPERR_ASCHAN_HIDEF_IRGBI64_170 869
HPERR_ASCHAN_HIDEF_ACCUSTREAM50 870
HPERR_ASCHAN_HIDEF_ACCUSTREAM75 871
HPERR_ASCHAN_HIDEF_ACCUSTREAMVDR 872

IDEA Auto-SYNC Channel/Mode Elimination

Codes
Function Return Decimal Value
HPERR_ASMODE_SKIPPED 880
HPERR_ASMODE_HFREQ_LO 881
HPERR_ASMODE_HFREQ_HI 882
HPERR_ASMODE_HFREQ 883
HPERR_ASMODE_TTLCSYNC 884
HPERR_ASMODE_CT4GRAB 885
HPERR_ASMODE_HDPCSYNC 886

IDEA Auto-SYNC Pixel Detection Error Codes

Function Return Decimal Value
HPERR_ASPD_SKIPPED 895
HPERR_ASPD_HFREQ 896

IDEA SDK User’s Guide 279

Appendix A:
IDEA SDK and Tools Library Functional Summary

Function Return Decimal Value

HPERR_ASPD_CONTRAST 897
HPERR_ASPD_NOPIXELS 898

280 IDEA SDK User’s Guide

 Three easy ways to get support:
ƒ Email
ƒ Phone/Fax
ƒ WebEx conference

Foresight Imaging
Tel: (001) 978-458-4624
Fax: (001) 978-458-5488

Email:
[email protected]

Web:
www.fi-llc.com

WebEx:
tims.webex.com

282 IDEA SDK User’s Guide