Device Enumeration

This section describes device enumeration, querying information about attached devices and their connection topology.

Simple Device Enumeration

The simplest way to gather information about the available video capture devices is calling ic4::DeviceEnum::enumDevices(). The function returns a flat list of ic4::DeviceInfo objects.

The following code snippet shows how to get the list of devices and print device information to the console:

void print_device_list()
{
    std::cout << "Enumerating all attached video capture devices in a single list..." << std::endl;
 
    auto device_list = ic4::DeviceEnum::enumDevices();
 
    if (device_list.empty())
    {
        std::cout << "No devices found" << std::endl;
        return;
    }
 
    std::cout << "Found " << device_list.size() << " devices:" << std::endl;
 
    for (auto&& dev_info : device_list)
    {
        std::cout << "\t" <<  format_device_info(dev_info) << std::endl;
    }
    
    std::cout << std::endl;  
static std::vector< DeviceInfo > enumDevices(Error &err=Error::Default())
Get a list of the devices currently attached to the system.
Definition DeviceEnum.h:446
Contains information about a video capture device.
Definition DeviceEnum.h:46

The device information is printed using a simple helper function:

std::string format_device_info(const ic4::DeviceInfo& device_info)
{
    return "Model: " + device_info.modelName() + " Serial: " + device_info.serial() + " Version: " + device_info.version();
}
std::string version(Error &err=Error::Default()) const
Gets the version of this device.
Definition DeviceEnum.h:156
std::string serial(Error &err=Error::Default()) const
Gets the serial of this device.
Definition DeviceEnum.h:143
std::string modelName(Error &err=Error::Default()) const
Gets the model name for this device.
Definition DeviceEnum.h:116

Query Interface/Device Topology

Device enumeration can also be performed on a per-interface basis. Interfaces are the physical pieces of hardware that cameras are attached to, e.g. USB controllers or network adapters.

To get a list of the available interfaces in the system, call ic4::DeviceEnum::enumInterfaces(). Each interface can in turn be queried for the currently attached video capture devices by calling ic4::Interface::enumDevices().

The following code snippet shows how to get the list of interfaces. It then prints interface information and device information to the console:

void print_interface_device_tree()
{
    std::cout << "Enumerating video capture devices by interface..." << std::endl;
 
    auto interface_list = ic4::DeviceEnum::enumInterfaces();
 
    for (auto&& itf : interface_list)
    {
        std::cout << "Interface: " << itf.interfaceDisplayName() << std::endl;
        std::cout << "\tProvided by " << itf.transportLayerName() << " [TLType: " << toString(itf.transportLayerType()) << "]" << std::endl;
 
        auto device_list = itf.enumDevices();
 
        if (device_list.empty())
        {
            std::cout << "\tNo devices found" << std::endl;
            continue;
        }
 
        std::cout << "\tFound " << device_list.size() << " devices:" << std::endl;
 
        for (auto&& dev_info : device_list)
        {
            std::cout << "\t\t" << format_device_info(dev_info) << std::endl;
        }
    }
 
    std::cout << std::endl;
}
static std::vector< Interface > enumInterfaces(Error &err=Error::Default())
Get a list of the interfaces present in the system.
Definition DeviceEnum.h:466

Receiving Device Arrival and Removal Notifications

ic4::DeviceEnum objects allow registering a callback function that notifies the program of changes in the list of available devices. To register a callback function, call ic4::DeviceEnum::eventAddDeviceListChanged().

The following code snippet shows how to register and finally unregister a device-list-changed event handler:

int main()
{
    ic4::initLibrary
    std::atexit(ic4::exitLibrary);
 
    ic4::DeviceEnum enumerator;
    auto token = enumerator.eventAddDeviceListChanged(device_list_changed_handler);
 
    auto initial_device_count = ic4::DeviceEnum::enumDevices().size();
 
    std::cout << "Press ENTER to exit program" << std::endl;
    std::cout << initial_device_count << " devices connected initially." << std::endl;
    std::cout << std::endl;
 
    (void)std::getchar();
 
    // This is technically not necessary, since the DeviceEnum object is destroyed at the end of this function.
    enumerator.eventRemoveDeviceListChanged(token);
 
    return 0;
}
Device enumerator.
Definition DeviceEnum.h:390
bool eventRemoveDeviceListChanged(NotificationToken token, Error &err=Error::Default())
Unregisters a device-list-changed event handler.
Definition DeviceEnum.h:546
NotificationToken eventAddDeviceListChanged(DeviceListChangedHandler cb, Error &err=Error::Default())
Registers a new device-list-changed event handler.
Definition DeviceEnum.h:524
bool initLibrary(const InitLibraryConfig &config={})
This function must be used to initialize the library.
Definition InitLibrary.h:89
void exitLibrary()
This method should be called by the application, when the library should shut down.
Definition InitLibrary.h:112

An example device-list-changed handler can look like this:

void device_list_changed_handler(ic4::DeviceEnum& enumerator)
{
    auto device_list = ic4::DeviceEnum::enumDevices();
 
    auto new_device_count = device_list.size();
 
    std::cout << "Device list has changed!" << std::endl;
    std::cout << "Found " << new_device_count << " devices" << std::endl;
    std::cout << std::endl;
}

Since ic4::DeviceEnum::eventAddDeviceListChanged() accepts a std::function, every callable C++ object can be registered as a callback.