National Instruments NI-IMAQ User Manual

™

IMAQ

NI-IMAQ™for IEEE-1394 Cameras User Manual

Image Acquisition Software

NI-IMAQ for IEEE-1394 Cameras User Manual

March 2001 Edition

Part Number 370362A-01

Worldwide Technical Support and Product Information

ni.com

National Instruments Corporate Headquarters

11500 North Mopac Expressway Austin, Texas 78759-3504 USA Tel: [phone]

Worldwide Offices

Australia 03 9879 5166, Austria 0662 45 79 90 0, Belgium 02 757 00 20, Brazil 011 284 5011,
Canada (Calgary) 403 274 9391, Canada (Ottawa) 613 233 5949, Canada (Québec) 514 694 8521,
Canada (Toronto) 905 785 0085, China (Shanghai) 021 6555 7838, China (ShenZhen) 0755 3904939,
Denmark 45 76 26 00, Finland 09 725 725 11, France 01 48 14 24 24, Germany 089 741 31 30,
Greece 30 1 42 96 427, Hong Kong 2645 3186, India 91805275406, Israel 03 6120092, Italy 02 413091,
Japan 03 5472 2970, Korea 02 596 7456, Mexico 5 280 7625, Netherlands 0348 433466,
New Zealand 09 914 0488, Norway 32 27 73 00, Poland 0 22 528 94 06, Portugal 351 1 726 9011,
Singapore 2265886, Spain 91 640 0085, Sweden 08 587 895 00, Switzerland 056 200 51 51,
Taiwan 02 2528 7227, United Kingdom 01635 523545

For further support information, see the Technical Support Resources appendix. To comment on the
documentation, send e-mail to [e-mail]

Copyright © 2001 National Instruments Corporation. All rights reserved.

Important Information

Warranty

The media on which you receive National Instruments software are warranted not to fail to execute programming instructions, due to defects
in materials and workmanship, for a period of 90 days from date of shipment, as evidenced by receipts or other documentation. National
Instruments will, at its option, repair or replace software media that do not execute programming instructions if National Instruments receives
notice of such defects during the warranty period. National Instruments does not warrant that the operation of the software shall be
uninterrupted or error free.

A Return Material Authorization (RMA) number must be obtained from the factory and clearly marked on the outside of the package before
any equipment will be accepted for warranty work. National Instruments will pay the shipping costs of returning to the owner parts which are
covered by warranty.

National Instruments believes that the information in this document is accurate. The document has been carefully reviewed for technical
accuracy. In the event that technical or typographical errors exist, National Instruments reserves the right to make changes to subsequent
editions of this document without prior notice to holders of this edition. The reader should consult National Instruments if errors are suspected.
In no event shall National Instruments be liable for any damages arising out of or related to this document or the information contained in it.

XCEPT AS SPECIFIED HEREIN,NATIONAL INSTRUMENTS MAKES NO WARRANTIES, EXPRESS OR IMPLIED, AND SPECIFICALLY DISCLAIMS ANY WARRANTY OF

E

MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE

NATIONAL INSTRUMENTS SHALL BE LIMITED TO THE AMOUNT THERETOFORE PAID B Y THE CUSTOMER.NATIONAL INSTRUMENTS WILL NOT BE LIABLE FOR

DAMAGES RESULTING FROM LOSS OF DATA

. This limitation of the liability of NationalInstruments will apply regardless ofthe form of action,whether in contract or tort, including

THEREOF

negligence. Any action against National Instruments must be brought within one year after the cause of action accrues. National Instruments
shall not be liable for any delay in performance due to causes beyond its reasonable control. The warranty provided herein does not cover
damages, defects, malfunctions, or service failures caused by owner’s failure to follow the National Instruments installation, operation, or
maintenance instructions; owner’s modification of the product; owner’s abuse, misuse, or negligent acts; and power failure or surges, fire,
flood, accident, actions of third parties, or other events outside reasonable control.

, PROFITS, USE OF PRODUCTS, OR INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY

Copyright

Under the copyright laws, this publication may not be reproduced ortransmitted in any form, electronic or mechanical, including photocopying,
recording, storing in an information retrieval system, or translating, in whole or in part, without the prior written consent of National
Instruments Corporation.

Trademarks

IMAQ™,LabVIEW™, National Instruments™,ni.com™, and NI-IMAQ™are trademarks of National Instruments Corporation.

Product and company names mentioned herein are trademarks or trade names of their respective companies.

.CUSTOMER’S RIGHT TO RECOVER DAMAGES CAUSED BY FAULT OR NEGLIGENCE ON THE PART OF

WARNING REGARDING USE OF NATIONAL INSTRUMENTS PRODUCTS

(1) NATIONAL INSTRUMENTS PRODUCTS ARE NOT DESIGNED WITH COMPONENTS AND TESTING FOR A LEVEL OF
RELIABILITY SUITABLE FOR USE IN OR IN CONNECTION WITH SURGICAL IMPLANTS OR AS CRITICAL COMPONENTS IN
ANY LIFE SUPPORT SYSTEMS WHOSE FAILURE TO PERFORM CAN REASONABLY BE EXPECTED TO CAUSE SIGNIFICANT
INJURY TO A HUMAN.

(2) IN ANY APPLICATION, INCLUDING THE ABOVE, RELIABILITY OF OPERATION OF THE SOFTWARE PRODUCTS CAN BE
IMPAIRED BY ADVERSE FACTORS, INCLUDING BUT NOT LIMITED TO FLUCTUATIONS IN ELECTRICAL POWER SUPPLY,
COMPUTER HARDWARE MALFUNCTIONS, COMPUTER OPERATING SYSTEM SOFTWARE FITNESS, FITNESS OF COMPILERS
AND DEVELOPMENT SOFTWARE USED TO DEVELOP AN APPLICATION, INSTALLATION ERRORS, SOFTWARE AND
HARDWARE COMPATIBILITY PROBLEMS, MALFUNCTIONS OR FAILURES OF ELECTRONIC MONITORING OR CONTROL
DEVICES, TRANSIENT FAILURES OF ELECTRONIC SYSTEMS (HARDWARE AND/OR SOFTWARE), UNANTICIPATED USES OR
MISUSES, OR ERRORS ON THE PART OF THE USER OR APPLICATIONS DESIGNER (ADVERSE FACTORS SUCH AS THESE ARE
HEREAFTER COLLECTIVELY TERMED “SYSTEM FAILURES”). ANY APPLICATION WHERE A SYSTEM FAILURE WOULD
CREATE A RISK OF HARM TO PROPERTY OR PERSONS (INCLUDING THE RISK OF BODILY INJURY AND DEATH) SHOULD
NOT BE RELIANT SOLELY UPON ONE FORM OF ELECTRONIC SYSTEM DUE TO THE RISK OF SYSTEM FAILURE. TO AVOID
DAMAGE, INJURY, OR DEATH, THE USER OR APPLICATION DESIGNER MUST TAKE REASONABLY PRUDENT STEPS TO
PROTECT AGAINST SYSTEM FAILURES, INCLUDING BUT NOT LIMITED TO BACK-UP OR SHUT DOWN MECHANISMS.
BECAUSE EACH END-USER SYSTEM IS CUSTOMIZED AND DIFFERS FROM NATIONAL INSTRUMENTS' TESTING
PLATFORMS AND BECAUSE A USER OR APPLICATION DESIGNER MAY USE NATIONAL INSTRUMENTS PRODUCTS IN
COMBINATION WITH OTHER PRODUCTS IN A MANNER NOT EVALUATED OR CONTEMPLATED BY NATIONAL
INSTRUMENTS, THE USER OR APPLICATION DESIGNER IS ULTIMATELY RESPONSIBLE FOR VERIFYING AND VALIDATING
THE SUITABILITY OF NATIONAL INSTRUMENTS PRODUCTS WHENEVER NATIONAL INSTRUMENTS PRODUCTS ARE
INCORPORATED IN A SYSTEM OR APPLICATION, INCLUDING, WITHOUT LIMITATION, THE APPROPRIATE DESIGN,
PROCESS AND SAFETY LEVEL OF SUCH SYSTEM OR APPLICATION.

Conventions

The following conventions are used in this manual:

» The » symbol leads you through nested menu items and dialog box options

to a final action. The sequence File»Page Setup»Options directs you to
pull down the File menu, select the Page Setup item, and select Options
from the last dialog box.

This icon denotes a note, which alerts you to important information.

bold Bold text denotes items that you must select or click on in the software,

such as menu items and dialog box options. Bold text also denotes
parameter names.

italic Italic text denotes variables, emphasis, a cross reference, or an introduction

to a key concept. This font also denotes text that is a placeholder for a word
or value that you must supply.

monospace

monospace italic

NI-IMAQ for 1394 NI-IMAQ for 1394 represents the NI-IMAQ for IEEE-1394 Cameras

Text in this font denotes text or characters that you should enter from the
keyboard, sections of code, programming examples, and syntax examples.
This font is also used for the proper names of disk drives, paths, directories,
programs, subprograms, subroutines, device names, functions, operations,
variables, filenames and extensions, and code excerpts.

Italic text in this font denotes text that is a placeholder for a word or value
that you must supply.

software package.

Contents

Chapter 1
Introduction to NI-IMAQ for IEEE-1394 Cameras

About the NI-IMAQ Software....................................................................................... 1-1

Application Development Environments ........................................................1-2

Configuring Your IEEE-1394 Camera............................................................1-2

Fundamentals of Building Applications with NI-IMAQ for 1394 ................................1-3

Architecture .....................................................................................................1-3

The NI-IMAQ Libraries ..................................................................................1-4

Creating an Application...................................................................................1-4

Sample Programs.............................................................................................1-5

Chapter 2
Software Overview

Introduction....................................................................................................................2-1

Generic Functions ..........................................................................................................2-1

High-Level Functions ....................................................................................................2-2

Snap Functions ................................................................................................2-2

Grab Functions ................................................................................................2-2

Sequence Functions .........................................................................................2-3

Trigger Functions ............................................................................................2-3

Miscellaneous Functions .................................................................................2-3

Low-Level Functions.....................................................................................................2-3

Acquisition Functions......................................................................................2-3

Attribute Functions..........................................................................................2-4

Utility Functions..............................................................................................2-5

Chapter 3
Programming with NI-IMAQ for 1394

Introduction....................................................................................................................3-1

High-Level Functions......................................................................................3-1

Low-Level Functions....................................................................................... 3-2

Establishing Interface Connections ...............................................................................3-2

Camera Functions............................................................................................3-2

Camera Attributes .......................................................................................................... 3-3

Scalable Image Size ....................................................................................................... 3-4

© National Instruments Corporation v NI-IMAQ for IEEE-1394 Cameras User Manual

Contents

Introductory Programming Examples ........................................................................... 3-5

High-Level Snap Functions ............................................................................ 3-5

High-Level Grab Functions ............................................................................ 3-6

High-Level Sequence Functions ..................................................................... 3-8

Advanced Programming Examples ............................................................................... 3-9

Performing a Snap Using Low-Level Functions............................................. 3-9

Performing a Grab Using Low-Level Functions............................................. 3-9

Performing a Sequence Acquisition Using Low-Level Functions.................. 3-9

Performing an Asynchronous Snap Using Low-Level Functions .................. 3-10

Performing an Asynchronous Grab using Low-Level Functions ................... 3-10

Chapter 4
Programming with NI-IMAQ for 1394 VIs

Introduction ................................................................................................................... 4-1

Location of NI-IMAQ for 1394 Examples....................................................................4-2

Location of the NI-IMAQ for 1394 VIs........................................................................ 4-2

Common NI-IMAQ for 1394 VI Parameters ................................................................ 4-3

Buffer Management....................................................................................................... 4-4

NI-IMAQ for 1394 Acquisition Types.......................................................................... 4-5

Snap................................................................................................................. 4-5

Grab................................................................................................................. 4-5

Sequence ......................................................................................................... 4-6

Acquisition VIs.............................................................................................................. 4-7

High-Level ...................................................................................................... 4-7

Low-Level....................................................................................................... 4-7

Triggering ......................................................................................................................4-8

Image Display................................................................................................................ 4-8

Camera Attributes..........................................................................................................4-11

Error Handling............................................................................................................... 4-12

Error Code Format......................................................................................................... 4-13

Appendix A
Technical Support Resources

Glossary

Index

NI-IMAQ for IEEE-1394 Cameras User Manual vi ni.com

Introduction to NI-IMAQ for
IEEE-1394 Cameras

This chapter describes the NI-IMAQ for IEEE-1394 software and lists the
application development environments compatible with NI-IMAQ,
describes the fundamentals of creating NI-IMAQ applications for
Windows 2000 and Windows Me/98, describes the files used to build these
applications, and tells you where to find sample programs.

About the NI-IMAQ Software

NI-IMAQ for 1394 gives you the ability to use industrial digital video
cameras with the NI-IMAQ driver software and IMAQ Vision. You can use
cameras with the following output formats:

• Monochrome (8 bits/pixel)

• Monochrome (16 bits/pixel)

• RGB (24 bits/pixel)

• YUV 4:1:1 (12 bits/pixel)

• YUV 4:2:2 (16 bits/pixel)

• YUV 4:4:4 (24 bits/pixel)

1

The cameras may operate at various resolutions and frame rates, depending
on camera capabilities.

NI-IMAQ for 1394 uses a WDM driver to directly access the 1394
interface, so that NI-IMAQ can control all of the available modes of the
digital camera.

© National Instruments Corporation 1-1 NI-IMAQ for IEEE-1394 Cameras User Manual

Chapter 1 Introduction to NI-IMAQ for IEEE-1394 Cameras

Application Development Environments

This release of NI-IMAQ for 1394 supports the following Application
Development Environments (ADEs) for Windows 2000 and
Windows Me/98:

• LabVIEW version 5.1 and higher

• LabWindows/CVI version 5.0 and higher

• Borland C++ Builder 3.0 and higher

• Microsoft Visual C/C++ version 6.0 and higher

Note

Although NI-IMAQ for 1394 has been tested and found to work with these ADEs,

other ADEs may also work.

Configuring Your IEEE-1394 Camera

You can use National Instruments Measurement & Automation Explorer
(MAX) to configure your IEEE-1394 camera.

Set your camera’s properties by right-clicking on your camera in the IMAQ
IEEE-1394 Devices folder in the MAX configuration tree. Select
Properties from the pop-up menu. Adjust your camera’sattributesand
click OK to save the camera file.

The camera information is saved in a camera file, which the LabVIEW VIs
use to select a camera and its supported attributes.

NI-IMAQ for IEEE-1394 Cameras User Manual 1-2 ni.com

Chapter 1 Introduction to NI-IMAQ for IEEE-1394 Cameras

Fundamentals of Building Applications with
NI-IMAQ for 1394

Architecture

A block diagram of the NI-IMAQ for 1394 architecture shown in
Figure 1-1 illustrates the low- and mid-level architecture for IMAQ
devices.

LabVIEW

IMAQ Vision

Application Level

Kernel

OCHI1394.SYS

LabWindows/CVI

Visual C++/Borland

IMAQ Vision

IMAQ1394.DLL

IMAQ1394.SYS

1394BUS.SYS

TILYNX.SYS

Figure 1-1. NI-IMAQ for 1394 Architecture

© National Instruments Corporation 1-3 NI-IMAQ for IEEE-1394 Cameras User Manual

Chapter 1 Introduction to NI-IMAQ for IEEE-1394 Cameras

The NI-IMAQ Libraries

The NI-IMAQ for 1394 for Windows 2000/Me/98 function libraries are
dynamic link libraries (DLLs), which means that NI-IMAQ for 1394
routines are not linked into the executable files of applications. Only the
information about the NI-IMAQ routines in the NI-IMAQ import libraries
is stored in the executable files.

Import libraries contain information about their DLL-exported functions.
They indicate the presence and location of the DLL routines. Depending
on the development tools you are using, you may give the DLL routines
information through import libraries or through function declarations.
Your NI-IMAQ for 1394 software kit contains function prototypes for all
routines.

Creating an Application

This section outlines the process for developing NI-IMAQ for 1394
applications using C for Windows 2000/Me/98. Detailed instructions on
creating project and source files are not included. For information on
creating and managing project files, consult the documentation included
with your particular development environment.

When programming, use the following guidelines:

• Include the
NI-IMAQ functions. Add this file to the top of your source files.

• Add the
environments allow you to add import libraries simply by inserting
them into your list of project files. Other environments allow you
to specify import libraries under the linker settings portion of the
project file.

NI-IMAQ for IEEE-1394 Cameras User Manual 1-4 ni.com

niimaq1394.h

niimaq1394.lib

header file in all C source files that use

import library to your project. Some

Chapter 1 Introduction to NI-IMAQ for IEEE-1394 Cameras

• When compiling, indicate where the compiler can find the NI-IMAQ
header files and shared libraries. You can find most of the files you
need for development under the NI-IMAQ target installation directory.
If you choose the default directory during installation, the target
installation directory is

Instruments\NI-IMAQ for IEEE-1394

files under the
under the

include

lib\<environment>

C:\Program Files\National

. You can find the include

subdirectory. The import libraries are located

subdirectory for the following

platforms.

Sample Programs

Table 1-1.

Import Libraries

Development Environment Directory

Microsoft Visual C++

Borland C++

Please refer to the

readme.txt

file located in your target installation

lib\msvc

lib\borland

directory for the latest details on NI-IMAQ for 1394 sample programs.
These programs are installed in the

sample

subdirectory under the target

installation folder, if you elected to install the sample files.

© National Instruments Corporation 1-5 NI-IMAQ for IEEE-1394 Cameras User Manual

Software Overview

This chapter describes the classes of NI-IMAQ for 1394 functions and
briefly describes each function.

Introduction

NI-IMAQ functions are grouped according to the following classes:

• Generic functions

• High-level functions

– Snap functions

– Grab functions

– Sequence functions

– Trigger functions

• Low-level functions

– Acquisition functions

– Attribute functions

– Utility functions

2

The generic and high-level functions appear within each function class in
the logical order you might need to use them. The low-level functions
appear within each function class in alphabetical order.

Generic Functions

Use generic functions in both high-level and low-level applications.

imaq1394CameraOpen

imaq1394Close

© National Instruments Corporation 2-1 NI-IMAQ for IEEE-1394 Cameras User Manual

Opens a session on a camera by
name.

Closes a session and unlocks and
releases all buffers.

Chapter 2 Software Overview

High-Level Functions

Use high-level functions to quickly and easily capture images. If you need
more advanced functionality, you can mix high-level functions with
low-level functions.

Snap Functions

Snap functions capture all or a portion of a single frame or field to the user
buffer.

Grab Functions

imaq1394SnapImage

imaq1394Snap

Grab functions start a continuous image acquisition to a user buffer. Any
frame or field can be copied from the grab buffer to another user buffer.

imaq1394SetupGrab

imaq1394GrabImage

imaq1394Grab

Performs a single frame
acquisition in an image buffer,
which is allocated using IMAQ
Vision memory management.

Performs a single frame
acquisition in a memory buffer,
which is allocated without using
IMAQ Vision memory
management.

Configures and starts a continuous
acquisition.

Acquires the most current frame
into the specified IMAQ Vision
image buffer. Call this function
only after calling

imaq1394SetupGrab

Acquires the most current frame
into a previously allocated buffer.
Call this function only after calling

imaq1394SetupGrab

.

.

NI-IMAQ for IEEE-1394 Cameras User Manual 2-2 ni.com

Sequence Functions

Chapter 2 Software Overview

Sequence functions start and stop a continuous acquisition of multiple
frames.

imaq1394SetupSequenceImage

imaq1394SetupSequence

Trigger Functions

Trigger functions control the trigger mode of the IEEE-1394 camera.

imaq1394TriggerConfigure

Miscellaneous Functions

Miscellaneous functions return information such as session status.

imaq1394Status

Low-Level Functions

Use low-level functions when you require more direct control of the
acquisition of the images.

Configures and starts a session for
acquiring a full sequence into the
list of buffers managed by
IMAQ Vision.

Configures and starts a session for
acquiring a full sequence in the
buffer list.

Configures an acquisition to start
based on an external trigger.

Gets the current session status.

Acquisition Functions

Use acquisition functions to configure, start, and abort an image
acquisition, or examine a buffer during an acquisition.

imaq1394ConfigureAcquisition

imaq1394StartAcquisition

© National Instruments Corporation 2-3 NI-IMAQ for IEEE-1394 Cameras User Manual

Configures the acquisition
session mode (continuous or
one-shot).

Starts acquisition synchronously
or asynchronously.

Chapter 2 Software Overview

Attribute Functions

imaq1394StopAcquisition

Stops an asynchronous acquisition
or synchronous continuous
acquisition immediately.

imaq1394GetBuffer

Copies a frame buffer to a
user-specified buffer.

imaq1394GetImage

Copies a session’s image datato an
IMAQ Vision image.

imaq1394InstallCallback

Configures an asynchronous
acquisition and installs a callback
function that will be called when
an image is acquired.

Use attribute functions to examine and change NI-IMAQ or camera
attributes.

imaq1394GetAttribute

imaq1394SetAttribute

imaq1394AttributeInquiry

Returns an attribute for a session.

Sets an attribute for a session.

Queries the camera to check that it
supports the specified attribute.

imaq1394GetVideoModes

Retrieves a list of video formats,
modes, and frame rates supported
by the camera.

imaq1394GetFeatures

Retrieves a list of features
supported by the camera.

NI-IMAQ for IEEE-1394 Cameras User Manual 2-4 ni.com

Utility Functions

Chapter 2 Software Overview

Use utility functions to display an image in a window, save an image to a
file, or to get detailed error information.

imaq1394Plot

imaq1394PlotDC

imaq1394SaveBuffer

imaq1394ShowError

Plots a buffer to a window given a
handle to a window.

Plots a buffer to a window given a
handle to a device context.

Saves a buffer of a session to disk
in bitmap, TIFF, or PNG format.

Returns a null-terminated string
describing the error code.

© National Instruments Corporation 2-5 NI-IMAQ for IEEE-1394 Cameras User Manual