Development FAQ

FireAPI™

Debugging and Error Reporting

1. I get a "First-chance" exception message when I run my application in debug mode. If I press "Ignore" I get a dialog that prompts me to enter some characters in a box, in order to evaluate ubCore for my adapter, for a time period of 20 minutes. I have licensed my adapter. What can I do?
   This is an artificial exception and there are exception handlers in the UB1394.DLL code that know how to handle it.  In Visual Studio 2005, the message will look like the one below:
   
   
   Pressing "Ignore" you will get the evaluation dialog that prompts you to enter some letters:
   
   
   In order to avoid this message you must press "Continue" at the first dialog.
   
   You can set Visual Studio 2005 to always react this way to the specific "First-chance" exception, through the "Exceptions" dialog from the "Debug" menu. In the exceptions dialog, you must uncheck the box next to "c0000008 An invalid handle was specified":
   
   
   Visual C++ 6 can also be set that way, through the exceptions dialog from the "Debug" menu. The "c0000008 Invalide Handle" should be set to "Stop if not handled":
   
2. How can I obtain the version number of the drivers I have installed on my system?
   From within an Explorer window, select the executable file in question, right-click on it and select "Properties". Either use the mouse or press CTRL+TAB to switch to the "Version" tab. This tab contains all the version information related to an executable. The string listed to the right of "File Version" is the executable version number. The executable of the FireAPI™ drivers are located in %WINDIR%\SYSTEM32\DRIVERS, except for UB1394.DLL which is in %WINDIR%\SYSTEM32. Alternatively you can execute the version command on the FireCommander.
3. How do I know if a driver executable is the free or the debug version?
   In general the size of debug executables is quite large (usually more than twice as large than the release executable). However you can also find this information by opening the properties page of the executable, switching to the Version tab and then viewing the "Build Type" entry in the "Other Version Information" listbox. Also in the same tab, the "Description" field, under the version number, contains the string "(DBG)" in the debug drivers.
4. What kind of tool can I use in order to view & save the error messages printed by the debug version of the ubCore drivers?
   The are various Freeware and commercial tools available in the market that allow capturing of the messages printed in the debug output. One of the best and most recomended utitlities that can handle such a task is DebugViewer provided free of charge by www.sysinternals.com.
5. Some FireAPI™ function is returning an error code. What should I do?
   When a FireAPI™ funtion fails a ton of debug messages are printed into the debug output. It is recommended that the user has the debug version of the ubCore drivers installed when doing developement and that he captures all the debug messages while running his application. The debug log messages will usually give the user a clue about why his application is failing but will be also be of invaluable help to the FireAPI™ support team when assisting the user.

FireAPI™ Compatibility

6. I have a device and I would like to develop a plug’n play client driver on top of FireAPI™ and the ubCore drivers so that my device can be integrated with the operating system. Is that possible?
   Since version 4.0 the ubCore drivers have become bus manager and power management capable. Devices connected to the a 1394 adapter using the ubCore drivers are automaticaly enumerated in the system and presented in the Windows Device Manager. A plug’n play device driver can be developed for each device thus integrating it with the system. Unibrain has already developed a set of such client drivers for devices like IIDC 1394 cameras, DV camcorders and SPB2 external storage devices which cover the majority of the available 1394 devices in the market. Those drivers are available to the user through the installation of the ubCore Driver Suite.
7. I have written a user mode application for FireAPI™ before the ubCore drivers became plug’n play. What should I do now?
   Nothing! You application will work with the latest version of the plug’n play ubCore drivers without any changes at all. In fact you might not even need to recompile your application in most cases.
8. I want to develop applications for IIDC 1394 digital cameras. Can I do that with FireAPI™?
   FireAPI™ includes the full source code of Fire-i DLL which is a C style DLL based on the user mode version of FireAPI™. Fire-i DLL provides a simple and robust interface that allows 1394 camera enumeration control and preview in a few lines of code. The source code of the Fire-i DLL as well as full documentation and a multitude of source samples can be found in the IIDC folder of the FireAPI™ samples directory. FireAPI™ also provides a WDM compliant IIDC camera driver that can be used along with the generic DirectShow SDK in order to perform basic camera control and preview tasks. Unibrain also provides a more complete and dedicated 1394 camera SDK called Fire-iAPI™.

1394 Asynchronous Programing

9. I am trying to read the configuration ROM of my OHCI adapter using ReadNode and it is failing with the status STATUS_1394_TRANSACTION_FAILED. What is wrong?
   OHCI 1394 adapters allow only quad reads in the configuration ROM. You are probably trying to perform block reads and that is why the ReadNode function is failing. Try reading the config ROM 4 butes at a time.
10. I try to send a broadcast packet from a user mode application C1394WriteNode returns
    STATUS_1394_SIZE_LIMITATION although I only want to send 1024 bytes from a 200Mbps board. What is wrong?
    Broadcasts are always sent at the speed of the slowest device on the bus, so that all nodes can receive it. If you have a device attached on the bus, that operates at 100Mbps (for example a digital mini-camera) then you will only be able to send broadcast packets of maximum size 512 bytes. The same is true when you have a 200Mbps device on a bus with all 400Mbps nodes. In that case the maximum broadcast packet size would be 1024 bytes.
11. How can I manually set the asynchronous transmission speed?
    C1394Read/Write/LockNode() API functions automatically set the transmission speed bwtween two nodes to the maximum possible value. In order to set the transmission speed manually you should use the C1394TransmitPackets() function.
12. In the FireAPI™ User Mode Interface documentation, on page 46, I found that transaction requests in 'Upper Address Space'(offsets ranging from hex 0xFFFF 0000 0000 to 0xFFFF EFFF FFFF) are acknowledged with 'ack_pending'. But this isn't the case. The acknowledge code generated for a write request at an offset within the 'Upper Address Space' is always ACK_COMPLETE.
    Read transactions on that address space are acknowledged with ACK_PENDING by the adapter. For write transactions, the default behaviour is to acknowledge the reception of the packet as soon as the packet arrives with ACK_COMPLETE and in doing so eliminating the need to send a response packet, resulting in much faster transaction. So when we have a Read transaction the following packets are send : Read Request (from the client) Acknowledgment with ACK_PENDING (from the server) Read Response (from the server) Acknowledgment with ACK_COMPLETE (from the client)when we have a write transaction the default behavior is: Write Request (from the client) Acknowledgment with ACK_COMPLETE (from the server)The last sequence is called "Unified transaction" (for more information about "unified transactions" check the IEEE1394-1995 spec. paragraphs 3.6.2.1 & 7.3.2.1).

1394 Isochronous Programing

13. Isochronous receive returns STATUS_1394_DMA_ERROR.
    The most probable reason is a FIFO overrun/underrun problem. Try setting FIFO’s isochronous receive memory to a bigger value, using the FIFO command on the FireCommander or the C1394SetInformation() API function.
    
    Note: If you use an OHCI board then it’s not possible to change FIFO settings. For a more detailed explanation of the DMA Error please refer to this White Paper in this link. For more info on DMA Error click here.

Kernel Mode Programing

14. I am developing a Client driver using your Class driver. Unfortunately there are some errors. I have created a project for VC 5.0 by using SrcToDsp and I built a driver with the base-functions. But when I want to include your functions I get an error:
    

    Linking… init.obj :
error LNK2001: unresolved external symbol _C1394Initialize@0
      .\i386\checked\michidriver.sys
fatal error LNK1120: 1 unresolved externals
Error executing link.exe.
michidriver.sys - 2 error(s), 0 warning(s)

    I have got:

    #include "C1394.h"

    
    It seems as if there was a prototype, but the Linker can’t find the code.
    You will have to link the resulting driver with 1394Initialize.obj which is located inside the FIREAPI\SRC\LIB directory. This is the OBJ containing the code of C1394Initialize for kernel mode drivers. The UBSBM sample project demonstrates how to do this for a project built with BUILD.EXE. That project can be compiled from within VC++ without any problems.Note: In order to link with C1394Initialize.obj, you have both to specify the name of the file, AND specify its path in the library search paths, otherwise the linker will not be able to locate the file. In general even if you work from within the IDE, it is best to compile your drivers with the BUILD utility using some sort of batch file like the DDKBUILD.BAT included with UBSBM.

Fire-i API™

General

1. I want to distribute my application with your drivers, but I would prefer to perform a silent installation of your drivers through mine. How could the installation of your drivers run silently?
   You should perform an installation of ubCore using the switch '/r' in order to produce a setup.iss file that is created in the windows folder.
   Then you should place the installation executable and the setup.iss file in the same folder.
   Running the installation with the '/s' switch, the setup will start in silent mode.
   Please notice that if you install ubCore drivers in silent mode the user does not get prompted to restart the system. You should prompt the user for a restart through your software's installation setup.
2. I want to use the latest versions of the Platform and DirectX SDKs. How should I set the "Include" and "Library" paths for VS2005?
   At first you should get the latest version of our Fire-iAPI SDK, 3.70.

   Concerning the latest version of DirectX SDK, November 2007, you cannot use it, as dxtrans.h is missing and you will not be able to complile our samples. You should use the August 2007 version instead, that you can download from the following location:
   http://www.microsoft.com/downloads/details.aspx?FamilyID=529f03be-1339-48c4-bd5a-8506e5acf571&DisplayLang=en

   You can download the latest version of the Platform SDK "Windows SDK for Windows Server 2008 and .NET Framework 3.5" from the following location:
   http://www.microsoft.com/downloads/details.aspx?FamilyId=F26B1AA4-741A-433A-9BE5-FA919850BDBF&displaylang=en

   You should set the paths of VS2005, as illustrated below:

   Win32 Platform Include files
   
   (The first entry is the path of the sample BaseClasses of the Platform SDK, e.g.
   D:\Program Files\Microsoft SDKs\Windows\v6.1\Samples\Multimedia\DirectShow\BaseClasses)

   Win32 Platform Library files
   

   x64 Platform Include files
   
   (The second entry is the path of the sample BaseClasses of the Platform SDK, e.g.
   D:\Program Files\Microsoft SDKs\Windows\v6.1\Samples\Multimedia\DirectShow\BaseClasses)

   x64 Platform Library files
   

3. I have a DV camera (camcorder) and a 1394 board. Can I use Fire-iAPI™ to control the camera and display the data on screen?
   NO. Fire-iAPI™ is a development kit ONLY for 1394 Digital Cameras, that implement the 1394-based Digital Camera Specification (version 1.20 and up) of the 1394 Trade Association.
4. I see that Fire-iAPI™ has samples and libraries based on 2 different platforms. Which one should I use?
   Fire-i provides 2 different platforms to the user that can be used for 1394 camera application developement. The first platform is a C style DLL called Fire-i DLL which offers a simple and robust interface that allows full camera enumeration, control and preview. Fire-i DLL comunicates directly with the ubCore 1394 adapter drivers bypassing this way any additional driver layers. The other platform that can be used is a camera class that uses the Microsoft DirectShow SDK along with the Fire-i WDM IIDC 1394 camera driver in order to provide full camera control. The class provides functionality for video capture using various system installed codecs, for TCP streaming of video data over the internet and much more since it has the ability to use all available DirectShow components. A managed wrapper is also available for this class so that it can be used with managed languages such as C# and VB.net.

Fire-i DLL Platform

5. I want to make an application that controls cameras connected in 2 different adapters. What should I do?
   In order to locate and open camera handles for the second bus, you should use the extended version of the functions, FiLocateCamerasEx() and FiOpenCameraHandleEx(). As long as you have a handle to a camera then it makes no difference on which bus it is located.
6. I get the data from the Digital Camera, but when I try to display them on the screen I get nonsense.
   1394 Digital Cameras transmit data on YUV format. This is NOT RGB compatible so the proper convention should be applied, so that the data are displayed correctly on screen.
7. I want to control a 1394 Digital Camera and at the same time display the frames. What should I do?
   Controlling a camera and receiving/displaying frames on the screen are two completely different tasks that must run concurrently. So they must be implemented and executed as two different processes or threads.
8. I have instructed the camera to start transmitting in software trigger mode and when I try to capture the frame I get FIREi_STATUS_TIMEOUT. What am I doing wrong?
   The camera has already transmitted the frame, before setting up the isochronous engine. In order to avoid this you should start the isochronous engine prior to ordering the camera to transmit the frame.
9. I have a special camera that implements a custom register. There is no OID for that register. How can I access it?
   First of all you should find out the offset of the register. When you know the complete address of the register you should use FiQuery/SetCameraRegisterEx() to access it. When you use this function, you should take into consideration Endianess. Refer to the manual for more details.
10. I set the FiCreateDisplayWindow() function so that hardware overlay is used, but it doesn’t work.
    Are you sure that your video card supports hardware overlay. Find out if it does prior to blaming the software!!! Many older video cards do not support hardware overlay.
11. I tried to compile Fire-i™ Dialog application and I get the following errors:

    warning C4013: 'SetWindowLongPtr' undefined; assuming extern returning int
error C2065: 'GWLP_USERDATA' : undeclared identifier
warning C4013: 'GetWindowLongPtr' undefined; assuming extern returning int

    What is wrong?
    The problem is due to the incompatibility of headers between different versions of Microsoft’s Platform SDK. Older headers contained SetWindowLong, GetWindowLong and GWL_USERDATA instead of SetWindowLongPtr, GetWindowLongPtr and GWLP_USERDATA respectively. We preferred to use the latter, because it is compatible with both the 32-bit and 64-bit versions of Windows. To solve this problem just change each occurrence of SetWindowLongPtr, GetWindowLongPtr and GWLP_USERDATA with SetWindowLong, GetWindowLong and GWL_USERDATA respectively.
12. Multicamera Application. I run the application, but no image is displayed on screen.
    This application tries to set the cameras to Format 0, Mode 1, 30 fps (320x240 YUV 4:2:2). If the camera does not support this mode, then the application just fails and no image is displayed.
13. How can I access the raw data of the frame captured by a call to FiGetNextCompleteFrame.
    The FIREi_CAMERA_FRAME struct, passed to FiGetNextCompleteFrame, has a pointer to the frame’s raw YUV data transmitted by the camera (the struct member pCameraFrameBuffer). This struct also provides information about the size of the frame buffer and the dimensions of the frame. You can convert this data from YUV to RGB using the function FiYuv2Rgb. CAUTION: Successive calls to FiGetNextCompleteFrame for the same isoch engine can use the same frame buffer.
14. What is Format 7 and could you please tell me if it is possible to use Format 7 with Fire-iAPI™?
    Format_7 is a scalable size, user defined, not-compressed format that is defined in the 1394 camera spec. and supported by some 1394 cameras. In this format the camera gives you the ability to choose the dimensions of the image being captured. Of cource you don’t have unlimited choices of size (the choices depend on camera model).
    Fire-iAPI™ v.2.0 and later supports Format 7.
15. I want to capture from 3 cameras simultaneously. I've writen a small sample in which after I succesfully start the isoch receive engines and succesfully start the cameras I try capturing the frames with the following calling sequence:

    1:FiGetNextCompleteFrame(framebuffer1, isoEng1,timeout)
2:FiGetNextCompleteFrame(framebuffer2,isoEng2, timeout)
3:FiGetNextCompleteFrame(framebuffer3,isoEng3,timeout)

    
    Is this correct?
    Although this would seem like a working solution (meaning that eventually a frame would be captured and returned from each call), depending on the timing with which the frames are transmitted on the bus(when a frame starts to get transmitted and when it ends)you would probably lose frames without any real reason (normal reasons for losing a frame are, a received bad frame or high CPU usage). The problem is that a single thread can only issue one call to FiGetNextCompleteFrame at a time and then gets blocked untill that frame arrives. The solution to this is to start more than one threads for receiving, one for each transmitting camera, and issue one call to FiGetNextCompleteFrame from each of these threads so that each would wait for a frame independantly from the others. In the sample applications that came with Fire-iAPI™ you can find the "SimpleFireisample" that presents the use of multiple threads to receive from multiple cameras.
16. I am writting a console application with Fire-iAPI™. I do not need to display the captured frame: i) I just want to save it to disk as a .bmp using the FiSaveFrame function, or ii) I just need to convert the frame from YUV to RGB using the FiYuv2Rgb function. All the Fire-iAPI™ calls return FIREi_STATUS_SUCCESS but the result is always a blank image.
    You should call the FiInitializeDisplay function before calling the FiSaveFrame or FiYuv2Rgb functions even if you do not intend to display the captured frames. FiInitializeDisplay initializes all the conversion tables for the yuv to rgb conversion and if you do not call FiInitializeDisplay the conversion tables will not be initialized. That is why you are getting a blank image.
17. When I use hardware overlay I get an image drifted to the green spectrum. What is going wrong?
    We have noticed this with some video display cards. Do not use hardware overlays with these adapters.
18. Fire-i™ Application. I have two adapters plugged in on my PC and one 1394 camera connected. I try to see the camera using the Fire-i™ application. No matter how much I try I cannot see the camera.

    You haven’t probably interconnected the two adapters, so there are two different local buses on your PC. Fire-i™ application checks for cameras on the FIRST local bus ONLY. The simplest solution is to connect the two adapters together. Beware: Loop topologies are PROHIBITED by the 1394 specification. Such a topology will result in successive bus resets, until the loop is removed.
19. I try to display camera frames to the screen using hardware overlay, but I get the message FIREi_STATUS_INTERNAL_ERROR.
    Make sure that the display properties are adequate. First of all more than 256 colors should be selected. Secondly the screen resolution must be greater or equal than the camera resolution. If, e.g. camera format is 800x600 and the display is 1024x768 then the frames should be displayed. If the display is 800x600 then the frames should be displayed ONLY on full screen. If the resolution is 640x480 then no frames should be displayed.
20. Using the Fire-i™ application I set 3 cameras to trigger mode. I press the trigger and the frames are displayed on screen. I want to save the captured frames on disk. Can I do that?
    In order to do that you should follow the procedure described bellow: i) set the cameras you want to capture triggered frames from, in trigger mode by checking the trigger check box for each of them. ii) start each camera and open a viewer for each of them. iii) press the trigger so that frames will be transmitted and captured. iv) highlight each window and press the shortcut key you assigned for saving frames.