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;
}

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();
}

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;
}

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;
}

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.