duvc-ctl C++ API Documentation

A guide to using the duvc-ctl C++ library/API for controlling USB Video Class (UVC) cameras on Windows.

---

Refer the Doxygen docs here!: C++ API (Doxygen)

Contents

Getting Started

• 1. Overview & Getting Started

  • 1.1 Introduction

  • 1.2 Installation & Setup

  • 1.3 Quick Start Examples

Core Concepts

• 2. Core API & Public Headers

  • 2.1 Device Discovery & Management

  • 2.2 Camera Control Class

  • 2.3 Device Capabilities

  • 2.4 Core Types & Enumerations

  • 2.5 Result Type & Error Handling

  • 2.6 Main Include Header

Utility Functions & Helpers

• 3. Utility Functions & Helpers

  • 3.1 Logging System

  • 3.2 String Conversion

  • 3.3 Error Decoding

Platform Abstraction

• 4. Platform Abstraction Layer

  • 4.1 Platform Interfaces

Vendor-Specific Extensions

• 5. Vendor-Specific Extensions

  • 5.1 Logitech Extensions

  • 5.2 Kernel Streaming Properties

  • 5.3 Vendor Property Structure

Internal Implementation

• 6. Internal Implementation Details

  • 6.1 Device Connection Pool

  • 6.2 COM Helpers

  • 6.3 DirectShow Integration

  • 6.4 Windows Internals

  • 6.5 Device Monitoring

  • 6.6 Factory Implementation

Property Reference

• 7. Property Reference Details

  • 7.1 Camera Properties Complete Reference

  • 7.2 Video Properties Complete Reference

  • 7.3 Property Range Discovery

  • 7.4 Auto vs Manual Modes

Usage Patterns & Best Practices

• 8. Usage Patterns & Best Practices

  • 8.1 Basic Usage Patterns

  • 8.2 Advanced Patterns

  • 8.3 Error Handling Strategies

  • 8.4 Thread Safety Guidelines

  • 8.5 Performance Optimization

Build System Integration

• 9. Build System Integration

  • 9.1 CMake Integration

  • 9.2 Building from Source

  • 9.3 Package Managers

Platform-Specific Information

• 10. Platform-Specific Information

  • 10.1 Windows-Specific Details

  • 10.2 DirectShow Background

  • 10.3 UVC Camera Standards

Device Support & Compatibility

• 11. Device Support & Compatibility

  • 11.1 Tested Devices

  • 11.2 Device Capability Matrix

  • 11.3 Known Issues & Workarounds

Troubleshooting & Debugging

• 12. Troubleshooting & Debugging

  • 12.1 Common Issues

  • 12.2 Debugging Techniques

  • 12.3 Diagnostic Tools

Examples & Tutorials

• 13. Examples & Tutorials

  • 13.1 Complete Examples

  • 13.2 Code Snippets

Contributing & Extending

• 14. Contributing & Extending

  • 14.1 Architecture Overview

  • 14.2 Adding New Features

  • 14.3 Testing [INCOMPLETE]

FAQ

• 15. FAQ

  • 15.1 General Questions

  • 15.2 Technical Questions

Appendices

• 16. Appendices

  • 16.1 DirectShow Property Constants

  • 16.2 Error Code Reference

  • 16.3 GUID Reference

  • 16.4 Glossary

Overview

duvc-ctl is a C++ library for controlling UVC cameras on Windows through the DirectShow API. The library exposes camera properties (pan, tilt, zoom, exposure, focus) and video properties (brightness, contrast, white balance) without requiring vendor-specific drivers or SDKs.

Supported operations:

• Device enumeration and connection

• Camera properties: pan, tilt, roll, zoom, exposure, iris, focus, scan mode, privacy, digital zoom, backlight compensation, lamp

• Video properties: brightness, contrast, hue, saturation, sharpness, gamma, color enable, white balance, backlight compensation, gain

• Hot-plug detection and device change notifications

• Vendor-specific extensions (Logitech cameras supported)

Requirements:

• Windows 7 SP1 or later (Windows 10/11 recommended)

• C++17 compiler: Visual Studio 2019/2022, or MinGW-w64 with GCC 9+

• CMake 3.16 or later

• DirectShow (included with Windows)