Skip to content

NVIDIA GPUDirect for Video#

Basler supports NVIDIA GPUDirect for Video technology. You can access and control the use of NVIDIA GPUDirect for Video technology via the Basler Framegrabber API. NVIDIA GPUDirect for Video is tailored for systems that use an NVIDIA graphics processing unit (GPU).

The technology allows to efficiently transfer video frames into NVIDIA GPU memory at low latencies. It gives you full control to stream video into the GPU at sub-frame transfer times.

GPUDirect for Video technology is available through the Basler Framegrabber API on host PCs using a Windows OS in

  • OpenGL (Open Graphics Library), or
  • CUDA (Compute Unified Device Architecture), a parallel programming framework by NVIDIA.

NVIDIA GPUDirect for Video is tailored for systems that use an NVIDIA graphics processing unit (GPU). The technology allows to efficiently transfer video frames into NVIDIA GPU memory at low latencies. It gives you full control to stream video into the GPU at sub-frame transfer times.

For details, refer to the manufacturers site, sections NVIDIA GPUDirect for Video technology and GPUDirect Technology Overview.

Requirements#

To use GPUDirect for Video technology in combination with Basler frame grabbers, your system has to meet the following requirements:

Hardware#

For the latest list of supported NVIDIA GPUs, see here.

Basler frame grabber of your choice.

Software#

  • Basler Framegrabber SDK: Version 5.10.0 or higher
  • Operating System on Host PC: Windows 10 (64bit)
  • Parallel Computing Platform/API (see Installation):
    • CUDA (Compute Unified Device Architecture), version 11.6, or
    • OpenGL (Open Graphics Library)
  • Recommended IDE: Visual Studio 15.x or higher

Info

You may need additional DLL and header files to get GPUDirect for Video running. For more information, contact Basler Technical Support.

The support of GPUDirect for Video technology has been tested under Windows 10 and can be guaranteed for this Windows version.

Installation#

Prerequisites#

  • GPU Hardware: An NVIDIA GPU that supports GPUDirect for Video technology has been plugged into your host PC.
  • Parallel Computing Platform/API: One of the following packages has been installed on your host PC:
    • CUDA (Compute Unified Device Architecture), a parallel programming framework by Nvidia
    • OpenGL (Open Graphics Library)
  • Frame Grabber Hardware: The Basler frame grabber of your choice has been connected to your host PC. For information how to connect the frame grabber, see Connecting the Frame Grabber.
  • Framegrabber SDK: The Basler Framegrabber SDK 5.10.0 or higher has been installed. For information how to install the runtime software, see Installing the Framegrabber SDK.
  • Applet: The applet of your choice has been flashed onto your frame grabber (only for marathon frame grabbers) and is selected as active applet. For information how to flash the marathon frame grabber, see Flashing. For information how to select an applet as active applet, see Changing the Active Applet.
  • GPUDirect for Video Support Files: Basler provides you with the following files:
    • siso_gpudirect.dll: library file
    • siso_gpudirect.h: header file covering the general functions always required
    • siso_gpudirect_cuda.h: header file required for working with CUDA
    • siso_gpudirect_gl.h: header file required for working in OpenGL.

Installing GPUDirect for Video Support#

To install GPUDirect for Video support on your host PC:

  1. Copy the library file siso_gpudirect.dll into your Basler Framegrabber SDK installation directory into subfolder bin, e.g., C:\Program Files\Basler\FramegrabberSDK_5.XX.X\bin.
  2. Copy the header files into the into the subfolder include of your Basler Framegrabber SDK installation directory into , e.g., C:\Program Files\Basler\FramegrabberSDK_5.XX.X\include.

After copying the files into the mentioned subfolders of your installation, you can use the functions of GPUDirect for Video via the Basler Framegrabber API.

Function Reference#

You use either CUDA or OpenGL for controlling GPUDirect for Video via the Basler Framegrabber API.

Prerequisites for Using CUDA#

  • The library file siso_gpudirect.dll has been copied into the subfolder bin of your Framegrabber SDK installation.
  • The header files siso_gpudirect.h and siso_gpudirect_cuda.h have been copied into the subfolder include of your Framegrabber SDK installation.

Prerequisites for Using OpenGL#

  • The library file siso_gpudirect.dll has been copied into the subfolder bin of your Framegrabber SDK installation.
  • The header files siso_gpudirect.h and siso_gpudirect_gl.h have been copied into the subfolder include of your Framegrabber SDK installation.

Available Functions#

The functions for controlling the GPUDirect for Video technology via the Basler Framegrabber API are the same for CUDA and OpenGL. The Basler Framegrabber API offers the following functions:

Function GDInitLib
Description Global Initialization. Call this function prior to any other function for initialization.
Parameters
  • [in] Fg_Struct* iFgHandle
    Handle of a valid frame grabber instance. See documentation of library fglib in the Framegrabber API Manual.
  • [in] GD_CONTEXT iFlag
    Define here which technology you are going to use. Possible Values (GD_CTX_LIST):
    • GD_CTX_CUDA: indicating use with CUDA
    • GD_CTX_OPENGL: indicating use with OpenGL
    • GD_CTX_D3D9: not supported
    • GD_CTX_D3D11: not supported
Function GDCloseLib
Description After no function of the library is needed anymore, you must call this function to clean up the resources from the GDInitLib function call. Each call to GCCloseLib has to be accompanied by a preceding call to GDInitLib.
Parameters None
Function GDGetContextInfo
Description Use this function to get information about the current context.
Parameters
  • [in] GD_CONTEXT_INFO_CMD iInfoCmd
    Use this parameter to indicate the information you want to get. Only available value: GD_CONTEXT_STRIDE_LENGTH.
    The stride length is defined as follows: When a video image is stored in memory, the memory buffer might contain extra padding bytes after each row of pixels. The padding bytes affect how the image is stored in memory, but don't affect how the image is displayed. The stride is the number of bytes from one row of pixels in memory to the next row of pixels in memory. Stride is also called pitch. If padding bytes are present, the stride is wider than the width of the image, as shown in the following illustration. Two buffers that contain video frames with equal dimensions can have two different strides. If you process a video image, you must take the stride into account.Stride Length
    Source: https://msdn.microsoft.com/en-us/library/windows/desktop/aa473780(v=vs.85).aspx
    Make sure the image dimensions you define match the padding constraints.
  • [out] void * pBufferThe information provided (i.e. input value), for example, the value of the stride length, is written into this buffer. If pBuffer = NULL, piSize provides the size that is needed by the buffer in order to be able to save the information (i.e., the output value).
  • [in/out] size_t * piSize
    When calling this function, you must define the size of pBuffer in this parameter. In case the size is to small (for the length of the buffer that is handed over), the value for size is automatically adapted to fit the size of the buffer. After being called, this parameter holds the number of bytes that have been written into pBuffer.
Function GDRevokeBuffer
Description Removes an announced buffer from the acquisition engine. This function will free all internally allocated resources associated with this buffer. A buffer can only be revoked if it isn't queued in any queue.
Parameters [in] BUFFER_HANDLE
Handle referencing to the buffer. The buffer itself has been announced via the function GDAllocateSourceBuffer, GDAnnounceCUDAArray, GDAnnounceTextureGL, or GDAnnounceBufferGL.
Function GDStartAcquisition
Description Starts the acquisition engine.
Parameters None
Function GDStopAcquisition
Description Stops the acquisition engine.
Parameters None
Function GDAllocateSourceBuffer
Description This function allocates the memory for a single source buffer, announces this buffer to the acquisition engine, and returns a buffer handle which references that single buffer.
Parameters
  • [in] uint32_t width: image width
  • [in] uint32_t height: image height
  • [in] GDBufferTypes type: Use this parameter to define the pixel format. Possible Values:
    • GD_UNSIGNED_BYTE
    • GD_BYTE
    • GD_UNSIGNED_SHORT
    • GD_SHORT
    • GD_UNSIGNED_INT
    • GD_INT
    • GD_FLOAT
    • GD_HALF_FLOAT
    • GD_UNSIGNED_BYTE_3_3_2
    • GD_UNSIGNED_BYTE_2_3_3_REV
    • GD_UNSIGNED_SHORT_5_6_5
    • GD_UNSIGNED_SHORT_5_6_5_REV
    • GD_UNSIGNED_SHORT_4_4_4_4
    • GD_UNSIGNED_SHORT_4_4_4_4_REV
    • GD_UNSIGNED_SHORT_5_5_5_1
    • GD_UNSIGNED_SHORT_1_5_5_5_REV
    • GD_UNSIGNED_INT_8_8_8_8
    • GD_UNSIGNED_INT_8_8_8_8_REV
    • GD_UNSIGNED_INT_10_10_10_2
    • GD_UNSIGNED_INT_2_10_10_10_REV
  • [out] BUFFER_HANDLE*: handle
Function GDRegisterEvent
Description Registers an event object to a certain iEventID.
Parameters
  • [in] EVENT_TYPE iEventID
    Possible values:
    • EVENT_ERROR: Notification on module errors.
    • EVENT_COPY_FINISHED: Notification on newly filled buffers. The event data are stored in an EVENT_NEW_BUFFER_DATA. Alternatively, you can use the function GDMemcpy.
  • [out] EVENT_HANDLE* phEvent
    Use this handle to get the events via the function GDEventGetData.
Function GDEventGetData
Description Retrieves the next event data entry from the event data queue associated with the event handle.
Parameters
  • [in] EVENT_HANDLE phEvent
    You have already created this handle via function GDRegisterEvent.
  • [out] void * pBuffer
    The information provided (i.e. the output value) is written into this buffer. If pBuffer = NULL, piSize provides the size that is needed by the buffer in order to be able to save the information (i.e., the output value).
  • [in/out] size_t * piSize
    When calling this function, you must define the size of pBuffer in this parameter. In case the size is to small (for the length of the buffer that is handed over), the value for size is automatically adapted to fit the size of the buffer. After being called, this parameter holds the number of bytes that have been written into pBuffer.
  • [in] uint64_t iTimeout The function doesn't deliver any output until the timeout is over (in this case, the function returns state GD_ERR_TIMEOUT ), or until the specified event occurs.
Function GDMemcpy
Description Copies the next frame that has been delivered by the frame grabber into the GPU. Use this function if you want to trigger the copy process. The result is delivered as EVENT_NEW_BUFFER_DATA type.
Parameters
  • [out] void * pBuffer
    The value is written into this buffer. If pBuffer = NULL, piSize provides the size that is needed by the buffer in order to be able to save the EVENT_NEW_BUFFER_DATA type.
  • [in/out] size_t * piSize
    When calling this function, you must define the size of pBuffer in this parameter. In case the size is to small (for the length of the buffer that is handed over), the value for size is automatically adapted to fit the size of the buffer. After being called, this parameter holds the number of bytes that have been written into pBuffer.
Function GDBufferUnblock
Description This function unblocks buffer for the copying process. Each buffer that you have received as member of EVENT_NEW_BUFFER_DATA needs to be unblocked via this function (e.g., in order to have buffer for new copy processes). Make sure your operations on the buffer content have been completed before you unblock a buffer.
Parameters [in] BUFFER_HANDLE phBuffer
Function GDBufferGetDataPtr
Description This function returns the pointer to the starting point of the memory location of the buffer. The buffer must have been created with the GDAllocateSourceBuffer function.
Parameters
  • [in] BUFFER_HANDLE phBuffer
  • [out] void** mDataPtr
    Contains the pointer that points to the raw data that are managed by this buffer.
Function GGDGetBufferInfo
Description Use this function to inquire information about the buffer module associated with this buffer handle.
Parameters
  • [in] BUFFER_HANDLE hBuffer
  • [in] GD_BUFFER_INFO_CMD iInfoCmd
    Possible values:
    • GD_BUFFER_TIMESTAMP: Time stamp last change in buffer.
    • GD_BUFFER_TIMESTAMP_FREQUENCY: Frequency for time stamp.
    • GD_BUFFER_PICNUMBER: Index for buffer content.
    • GD_BUFFER_DATA_PTR: Pointer to the raw data that are managed by the buffer.
  • [out] void * pBuffer
    The value is written into this buffer. If pBuffer = NULL, piSize provides the size that is needed by the buffer in order to be able to save the data.
  • [in/out] size_t * piSize
    When calling this function, you must define the size of pBuffer in this parameter. In case the size is to small (for the length of the buffer that is handed over) the value for size is automatically adapted to fit the size of the buffer. After being called, this parameter holds the number of bytes that have been written into pBuffer.
Function GDGetLastError
Description Use this function to inquire the message associated with the last error that occurred.
Parameters
  • [out] char * pMsgBuffer
    The value is written into this buffer. If pMsgBuffer = NULL, piSize provides the size that is needed by the buffer in order to be able to save the error message.
  • [in/out] size_t * piSize
    When calling this function, you must define the size of pMsgBuffer in this parameter. In case the size is to small (for the message that is handed over) the value for size is automatically adapted to fit the size of the message. After being called, this parameter holds the number of bytes that have been written into pBuffer.
Function GDAnnounceTextureGL
Description This function announces a target object as a destination for copy operations and returns a buffer handle which references that single buffer.
Parameters
  • [in]GLuint texture
    ID of the texture you have created with openGL.
  • [out]BUFFER_HANDLE* handle
    The handle that points to this buffer.
Function GDAnnounceBufferGL
Description This function announces a target object as a destination for copy operations and returns a buffer handle which references that single buffer.
Parameters
  • [in]GLuint buffer
    ID of the texture you have created with openGL.
  • [out]BUFFER_HANDLE* handle
    The handle that points to this buffer.
Function GDAnnounceCUDAArray
Description This function announces a target object as a destination for copy operations and returns a buffer handle which references that single buffer.
Parameters
  • CUarray array
    The handle that references the buffer you have created with CUDA.
  • BUFFER_HANDLE* handle
    The handle that points to this buffer.

Data Types#

Name of STRUCT EVENT_NEW_BUFFER_DATA
Description The event has copied the content of the source buffer into the target buffer.
Parameters
  • BUFFER_HANDLE SourceBufferHandle
    You have created this buffer via function GDAllocateSourceBuffer.
  • BUFFER_HANDLE TargetBufferHandle
    You have created this buffer via function GDAnnounceCUDAArray (CUDA), or via function GDAnnounceTextureGL or PGDAnnounceBufferGL (OpenGL).

Enumerations#

GD_CTX_LIST
GD_CTX_CUDA Name of CUDA context
GD_CTX_OPENGL Name of OpenGL context
GD_CTX_D3D9 Not supported
GD_CTX_D3D11 Not supported
GD_CONTEXT_INFO_LIST
GD_CONTEXT_STRIDE_LENGTH Stride Length
Source: https://msdn.microsoft.com/en-us/library/windows/desktop/aa473780(v=vs.85).aspx
GDBufferTypes
GD_UNSIGNED_BYTE
GD_BYTE
GD_UNSIGNED_SHORT
GD_SHORT
GD_UNSIGNED_INT
GD_INT
GD_FLOAT
GD_HALF_FLOAT
GD_UNSIGNED_BYTE_3_3_2
GD_UNSIGNED_BYTE_2_3_3_REV
GD_UNSIGNED_SHORT_5_6_5
GD_UNSIGNED_SHORT_5_6_5_REV
GD_UNSIGNED_SHORT_4_4_4_4
GD_UNSIGNED_SHORT_4_4_4_4_REV
GD_UNSIGNED_SHORT_5_5_5_1
GD_UNSIGNED_SHORT_1_5_5_5_REV
GD_UNSIGNED_INT_8_8_8_8
GD_UNSIGNED_INT_8_8_8_8_REV
GD_UNSIGNED_INT_10_10_10_2
GD_UNSIGNED_INT_2_10_10_10_REV
EVENT_TYPE_LIST
EVENT_ERROR Notification on module errors.
EVENT_COPY_FINISHED Notification on newly filled buffers. The event data are stored in an EVENT_NEW_BUFFER_DATA.
GD_BUFFER_INFO_LIST
GD_BUFFER_TIMESTAMP Time stamp last change in buffer
GD_BUFFER_TIMESTAMP_FREQUENCY Frequency for time stamp
GD_BUFFER_PICNUMBER Index for buffer content
GD_BUFFER_DATA_PTR Pointer to the raw data that are managed by the buffer

Examples#

Prerequisites#

  • You have the examples folder you received from Basler available.
  • Visual Studio 15.x or higher is installed on your PC.
  • CMake is installed on your PC.
  • The according libraries are installed on your PC.

Using the Examples#

To use the examples provided by Basler:

  1. Copy the examples folder you received from Basler to the hard drive of your host PC.

    CUDA Example

    For the CUDA example you only need cuda.lib and cudart.lib in addition to the libraries already installed on your PC.

    OpenGL Example: Glew must be found by CMake

    Make sure CMake can find the glew - otherwise, the project will not be built correctly.

    CMake should be able to find the glew without your interaction. However, in case it doesn't find the glew:

    1. Set the according enviromnent variables:

      GLUT_ROOT_PATH for example to D:\libs\freeglut-2.8.1\win32

      GLEW_ROOT_PATH for example to D:\libs\glew-1.13.0\glew-1.13.0\Win32

    2. If CMake has still trouble to find the glew, set the CMake project variables manually:

      GLEW_INCLUDE_DIR for example to D:/libs/glew-1.13.0/glew-1.13.0/x64/include

      GLEW_LIBRARY for example to D:/libs/glew-1.13.0/glew-1.13.0/x64/lib/glew32.lib

      OPENGL_gl_LIBRARY for example to opengl32

      OPENGL_glu_LIBRARY for example to glu32

  2. Create a project using CMake with examples\gpudirect\cuda or examples\gpudirect\opengl as source directory.

  3. Run the example.

While executing the examples, you will be asked to select an applet. Select a grayscale applet, for example, Acq_SingleCXP6X4AreaGray.dll for a marathon frame grabber. The name is somewhat cut off, you'll only see the end.

For marathon Frame Grabbers: Use Grayscale Applet for Examples

The Basler NVIDIA GPUDirect for Video support works with color formats as well as with grayscale formats.

However, as both examples are designed for use with grayscale applets, make sure you select a grayscale applet for using the examples, e.g., Acq_SingleCXP6X4AreaGray.dll (only for marathon frame grabbers).