Part I - Video for Linux API

This part describes the Video for Linux API version 2 (V4L2 API) specification.

Revision 4.5

Table of Contents

• 1. Common API Elements
  • 1.1. Opening and Closing Devices
    • 1.1.1. Controlling a hardware peripheral via V4L2
    • 1.1.2. V4L2 Device Node Naming
    • 1.1.3. Related Devices
    • 1.1.4. Multiple Opens
    • 1.1.5. Shared Data Streams
    • 1.1.6. Functions
  • 1.2. Querying Capabilities
  • 1.3. Application Priority
  • 1.4. Video Inputs and Outputs
    • 1.4.1. Example: Information about the current video input
    • 1.4.2. Example: Switching to the first video input
  • 1.5. Audio Inputs and Outputs
    • 1.5.1. Example: Information about the current audio input
    • 1.5.2. Example: Switching to the first audio input
  • 1.6. Tuners and Modulators
    • 1.6.1. Tuners
    • 1.6.2. Modulators
    • 1.6.3. Radio Frequency
  • 1.7. Video Standards
    • 1.7.1. Example: Information about the current video standard
    • 1.7.2. Example: Listing the video standards supported by the current input
    • 1.7.3. Example: Selecting a new video standard
  • 1.8. Digital Video (DV) Timings
  • 1.9. User Controls
    • 1.9.1. Control IDs
    • 1.9.2. Example: Enumerating all controls
    • 1.9.3. Example: Enumerating all controls including compound controls
    • 1.9.4. Example: Enumerating all user controls (old style)
    • 1.9.5. Example: Changing controls
  • 1.10. Extended Controls API
    • 1.10.1. Introduction
    • 1.10.2. The Extended Control API
    • 1.10.3. Enumerating Extended Controls
    • 1.10.4. Creating Control Panels
  • 1.11. Camera Control Reference
    • 1.11.1. Camera Control IDs
  • 1.12. Flash Control Reference
    • 1.12.1. Supported use cases
      • 1.12.1.1. Unsynchronised LED flash (software strobe)
      • 1.12.1.2. Synchronised LED flash (hardware strobe)
      • 1.12.1.3. LED flash as torch
      • 1.12.1.4. Flash Control IDs
  • 1.13. Image Source Control Reference
    • 1.13.1. Image Source Control IDs
  • 1.14. Image Process Control Reference
    • 1.14.1. Image Process Control IDs
  • 1.15. Codec Control Reference
    • 1.15.1. Generic Codec Controls
      • 1.15.1.1. Codec Control IDs
    • 1.15.2. MFC 5.1 MPEG Controls
      • 1.15.2.1. MFC 5.1 Control IDs
    • 1.15.3. CX2341x MPEG Controls
      • 1.15.3.1. CX2341x Control IDs
    • 1.15.4. VPX Control Reference
      • 1.15.4.1. VPX Control IDs
    • 1.15.5. High Efficiency Video Coding (HEVC/H.265) Control Reference
      • 1.15.5.1. HEVC/H.265 Control IDs
  • 1.16. Stateless Codec Control Reference
    • 1.16.1. Stateless Codec Control ID
    • 1.16.2. FWHT Flags
  • 1.17. JPEG Control Reference
    • 1.17.1. JPEG Control IDs
  • 1.18. Digital Video Control Reference
    • 1.18.1. Digital Video Control IDs
  • 1.19. RF Tuner Control Reference
    • 1.19.1. RF_TUNER Control IDs
  • 1.20. FM Transmitter Control Reference
    • 1.20.1. FM_TX Control IDs
  • 1.21. FM Receiver Control Reference
    • 1.21.1. FM_RX Control IDs
  • 1.22. Detect Control Reference
    • 1.22.1. Detect Control IDs
  • 1.23. Colorimetry Control Reference
    • 1.23.1. Colorimetry Control IDs
  • 1.24. Guidelines for Video4Linux pixel format 4CCs
    • 1.24.1. Raw bayer
  • 1.25. Data Formats
    • 1.25.1. Data Format Negotiation
    • 1.25.2. Image Format Enumeration
  • 1.26. Single- and multi-planar APIs
    • 1.26.1. Multi-planar formats
    • 1.26.2. Calls that distinguish between single and multi-planar APIs
  • 1.27. Cropping, composing and scaling -- the SELECTION API
    • 1.27.1. Introduction
    • 1.27.2. Selection targets
    • 1.27.3. Configuration
      • 1.27.3.1. Configuration of video capture
      • 1.27.3.2. Configuration of video output
      • 1.27.3.3. Scaling control
    • 1.27.4. Comparison with old cropping API
    • 1.27.5. Examples
      • 1.27.5.1. Example: Resetting the cropping parameters
      • 1.27.5.2. Example: Simple downscaling
      • 1.27.5.3. Example: Querying for scaling factors
  • 1.28. Image Cropping, Insertion and Scaling -- the CROP API
    • 1.28.1. Cropping Structures
    • 1.28.2. Scaling Adjustments
    • 1.28.3. Examples
    • 1.28.4. Example: Resetting the cropping parameters
    • 1.28.5. Example: Simple downscaling
    • 1.28.6. Example: Selecting an output area
    • 1.28.7. Example: Current scaling factor and pixel aspect
  • 1.29. Streaming Parameters
• 2. Image Formats
  • 2.1. Single-planar format structure
  • 2.2. Multi-planar format structures
  • 2.3. Standard Image Formats
  • 2.4. Indexed Format
  • 2.5. RGB Formats
    • 2.5.1. Less Than 8 Bits Per Component
    • 2.5.2. 8 Bits Per Component
    • 2.5.3. 10 Bits Per Component
    • 2.5.4. 12 Bits Per Component
    • 2.5.5. 16 Bits Per Component
    • 2.5.6. Deprecated RGB Formats
  • 2.6. Raw Bayer Formats
    • 2.6.1. Description
      • 2.6.1.1. V4L2_PIX_FMT_SRGGB8 (‘RGGB’), V4L2_PIX_FMT_SGRBG8 (‘GRBG’), V4L2_PIX_FMT_SGBRG8 (‘GBRG’), V4L2_PIX_FMT_SBGGR8 (‘BA81’),
        • 2.6.1.1.1. 8-bit Bayer formats
      • 2.6.1.2. V4L2_PIX_FMT_PISP_COMP1_RGGB (‘PC1R’), V4L2_PIX_FMT_PISP_COMP1_GRBG (‘PC1G’), V4L2_PIX_FMT_PISP_COMP1_GBRG (‘PC1g’), V4L2_PIX_FMT_PISP_COMP1_BGGR (‘PC1B), V4L2_PIX_FMT_PISP_COMP1_MONO (‘PC1M’), V4L2_PIX_FMT_PISP_COMP2_RGGB (‘PC2R’), V4L2_PIX_FMT_PISP_COMP2_GRBG (‘PC2G’), V4L2_PIX_FMT_PISP_COMP2_GBRG (‘PC2g’), V4L2_PIX_FMT_PISP_COMP2_BGGR (‘PC2B), V4L2_PIX_FMT_PISP_COMP2_MONO (‘PC2M’)
        • 2.6.1.2.1. Raspberry Pi PiSP compressed 8-bit Bayer formats
      • 2.6.1.3. V4L2_PIX_FMT_SRGGB10 (‘RG10’), V4L2_PIX_FMT_SGRBG10 (‘BA10’), V4L2_PIX_FMT_SGBRG10 (‘GB10’), V4L2_PIX_FMT_SBGGR10 (‘BG10’),
        • 2.6.1.3.1. Description
      • 2.6.1.4. V4L2_PIX_FMT_SRGGB10P (‘pRAA’), V4L2_PIX_FMT_SGRBG10P (‘pgAA’), V4L2_PIX_FMT_SGBRG10P (‘pGAA’), V4L2_PIX_FMT_SBGGR10P (‘pBAA’),
        • 2.6.1.4.1. Description
      • 2.6.1.5. V4L2_PIX_FMT_SBGGR10ALAW8 (‘aBA8’), V4L2_PIX_FMT_SGBRG10ALAW8 (‘aGA8’), V4L2_PIX_FMT_SGRBG10ALAW8 (‘agA8’), V4L2_PIX_FMT_SRGGB10ALAW8 (‘aRA8’),
        • 2.6.1.5.1. Description
      • 2.6.1.6. V4L2_PIX_FMT_SBGGR10DPCM8 (‘bBA8’), V4L2_PIX_FMT_SGBRG10DPCM8 (‘bGA8’), V4L2_PIX_FMT_SGRBG10DPCM8 (‘BD10’), V4L2_PIX_FMT_SRGGB10DPCM8 (‘bRA8’),
        • 2.6.1.6.1. Description
      • 2.6.1.7. V4L2_PIX_FMT_IPU3_SBGGR10 (‘ip3b’), V4L2_PIX_FMT_IPU3_SGBRG10 (‘ip3g’), V4L2_PIX_FMT_IPU3_SGRBG10 (‘ip3G’), V4L2_PIX_FMT_IPU3_SRGGB10 (‘ip3r’)
        • 2.6.1.7.1. 10-bit Bayer formats
      • 2.6.1.8. V4L2_PIX_FMT_SRGGB12 (‘RG12’), V4L2_PIX_FMT_SGRBG12 (‘BA12’), V4L2_PIX_FMT_SGBRG12 (‘GB12’), V4L2_PIX_FMT_SBGGR12 (‘BG12’),
        • 2.6.1.8.1. Description
      • 2.6.1.9. V4L2_PIX_FMT_SRGGB12P (‘pRCC’), V4L2_PIX_FMT_SGRBG12P (‘pgCC’), V4L2_PIX_FMT_SGBRG12P (‘pGCC’), V4L2_PIX_FMT_SBGGR12P (‘pBCC’),
        • 2.6.1.9.1. 12-bit packed Bayer formats
      • 2.6.1.10. V4L2_PIX_FMT_SRGGB14 (‘RG14’), V4L2_PIX_FMT_SGRBG14 (‘GR14’), V4L2_PIX_FMT_SGBRG14 (‘GB14’), V4L2_PIX_FMT_SBGGR14 (‘BG14’),
        • 2.6.1.10.1. 14-bit Bayer formats expanded to 16 bits
      • 2.6.1.11. V4L2_PIX_FMT_SRGGB14P (‘pREE’), V4L2_PIX_FMT_SGRBG14P (‘pgEE’), V4L2_PIX_FMT_SGBRG14P (‘pGEE’), V4L2_PIX_FMT_SBGGR14P (‘pBEE’),
        • 2.6.1.11.1. Description
      • 2.6.1.12. V4L2_PIX_FMT_SRGGB16 (‘RG16’), V4L2_PIX_FMT_SGRBG16 (‘GR16’), V4L2_PIX_FMT_SGBRG16 (‘GB16’), V4L2_PIX_FMT_SBGGR16 (‘BYR2’),
        • 2.6.1.12.1. 16-bit Bayer formats
  • 2.7. YUV Formats
    • 2.7.1. Subsampling
      • 2.7.1.1. Packed YUV formats
        • 2.7.1.1.1. 4:4:4 Subsampling
        • 2.7.1.1.2. 4:2:2 Subsampling
        • 2.7.1.1.3. 4:1:1 Subsampling
      • 2.7.1.2. Planar YUV formats
        • 2.7.1.2.1. Semi-Planar YUV Formats
        • 2.7.1.2.2. Fully Planar YUV Formats
      • 2.7.1.3. Luma-Only Formats
      • 2.7.1.4. V4L2_PIX_FMT_Y8I (‘Y8I ‘)
        • 2.7.1.4.1. Description
      • 2.7.1.5. V4L2_PIX_FMT_Y12I (‘Y12I’)
        • 2.7.1.5.1. Description
      • 2.7.1.6. V4L2_PIX_FMT_UV8 (‘UV8’)
        • 2.7.1.6.1. Description
      • 2.7.1.7. V4L2_PIX_FMT_M420 (‘M420’)
        • 2.7.1.7.1. Description
  • 2.8. HSV Formats
    • 2.8.1. Packed HSV formats
      • 2.8.1.1. Description
  • 2.9. Depth Formats
    • 2.9.1. V4L2_PIX_FMT_INZI (‘INZI’)
      • 2.9.1.1. Description
    • 2.9.2. V4L2_PIX_FMT_Z16 (‘Z16 ‘)
      • 2.9.2.1. Description
    • 2.9.3. V4L2_PIX_FMT_CNF4 (‘CNF4’)
      • 2.9.3.1. Description
  • 2.10. Compressed Formats
  • 2.11. SDR Formats
    • 2.11.1. V4L2_SDR_FMT_CU8 (‘CU08’)
      • 2.11.1.1. Description
    • 2.11.2. V4L2_SDR_FMT_CU16LE (‘CU16’)
      • 2.11.2.1. Description
    • 2.11.3. V4L2_SDR_FMT_CS8 (‘CS08’)
      • 2.11.3.1. Description
    • 2.11.4. V4L2_SDR_FMT_CS14LE (‘CS14’)
      • 2.11.4.1. Description
    • 2.11.5. V4L2_SDR_FMT_RU12LE (‘RU12’)
      • 2.11.5.1. Description
    • 2.11.6. V4L2_SDR_FMT_PCU16BE (‘PC16’)
      • 2.11.6.1. Description
    • 2.11.7. V4L2_SDR_FMT_PCU18BE (‘PC18’)
      • 2.11.7.1. Description
    • 2.11.8. V4L2_SDR_FMT_PCU20BE (‘PC20’)
      • 2.11.8.1. Description
  • 2.12. Touch Formats
    • 2.12.1. V4L2_TCH_FMT_DELTA_TD16 (‘TD16’)
      • 2.12.1.1. Description
    • 2.12.2. V4L2_TCH_FMT_DELTA_TD08 (‘TD08’)
      • 2.12.2.1. Description
    • 2.12.3. V4L2_TCH_FMT_TU16 (‘TU16’)
      • 2.12.3.1. Description
    • 2.12.4. V4L2_TCH_FMT_TU08 (‘TU08’)
      • 2.12.4.1. Description
  • 2.13. Metadata Formats
    • 2.13.1. V4L2_META_FMT_D4XX (‘D4XX’)
      • 2.13.1.1. Description
    • 2.13.2. V4L2_META_FMT_GENERIC_8 (‘MET8’), V4L2_META_FMT_GENERIC_CSI2_10 (‘MC1A’), V4L2_META_FMT_GENERIC_CSI2_12 (‘MC1C’), V4L2_META_FMT_GENERIC_CSI2_14 (‘MC1E’), V4L2_META_FMT_GENERIC_CSI2_16 (‘MC1G’), V4L2_META_FMT_GENERIC_CSI2_20 (‘MC1K’), V4L2_META_FMT_GENERIC_CSI2_24 (‘MC1O’)
      • 2.13.2.1. Description
        • 2.13.2.1.1. V4L2_META_FMT_GENERIC_8
        • 2.13.2.1.2. V4L2_META_FMT_GENERIC_CSI2_10
        • 2.13.2.1.3. V4L2_META_FMT_GENERIC_CSI2_12
        • 2.13.2.1.4. V4L2_META_FMT_GENERIC_CSI2_14
        • 2.13.2.1.5. V4L2_META_FMT_GENERIC_CSI2_16
        • 2.13.2.1.6. V4L2_META_FMT_GENERIC_CSI2_20
        • 2.13.2.1.7. V4L2_META_FMT_GENERIC_CSI2_24
    • 2.13.3. V4L2_META_FMT_IPU3_PARAMS (‘ip3p’), V4L2_META_FMT_IPU3_3A (‘ip3s’)
      • 2.13.3.1. 3A statistics
      • 2.13.3.2. Pipeline parameters
      • 2.13.3.3. Intel IPU3 ImgU uAPI data types
    • 2.13.4. V4L2_META_FMT_RPI_BE_CFG
      • 2.13.4.1. Raspberry Pi PiSP Back End configuration format
        • 2.13.4.1.1. Global configuration data
        • 2.13.4.1.2. Tile parameters
      • 2.13.4.2. Raspberry Pi PiSP Back End uAPI data types
    • 2.13.5. V4L2_META_FMT_RK_ISP1_PARAMS (‘rk1p’), V4L2_META_FMT_RK_ISP1_STAT_3A (‘rk1s’), V4L2_META_FMT_RK_ISP1_EXT_PARAMS (‘rk1e’)
      • 2.13.5.1. Configuration parameters
        • 2.13.5.1.1. Fixed parameters configuration format
        • 2.13.5.1.2. Extensible parameters configuration format
      • 2.13.5.2. 3A and histogram statistics
        • 2.13.5.2.1. rkisp1 uAPI data types
    • 2.13.6. V4L2_META_FMT_UVC (‘UVCH’)
      • 2.13.6.1. Description
    • 2.13.7. V4L2_META_FMT_VIVID (‘VIVD’)
      • 2.13.7.1. Description
    • 2.13.8. V4L2_META_FMT_VSP1_HGO (‘VSPH’)
      • 2.13.8.1. Description
    • 2.13.9. V4L2_META_FMT_VSP1_HGT (‘VSPT’)
      • 2.13.9.1. Description
  • 2.14. Reserved Format Identifiers
  • 2.15. Colorspaces
  • 2.16. Defining Colorspaces in V4L2
  • 2.17. Detailed Colorspace Descriptions
    • 2.17.1. Colorspace SMPTE 170M (V4L2_COLORSPACE_SMPTE170M)
    • 2.17.2. Colorspace Rec. 709 (V4L2_COLORSPACE_REC709)
    • 2.17.3. Colorspace sRGB (V4L2_COLORSPACE_SRGB)
    • 2.17.4. Colorspace opRGB (V4L2_COLORSPACE_OPRGB)
    • 2.17.5. Colorspace BT.2020 (V4L2_COLORSPACE_BT2020)
    • 2.17.6. Colorspace DCI-P3 (V4L2_COLORSPACE_DCI_P3)
    • 2.17.7. Colorspace SMPTE 240M (V4L2_COLORSPACE_SMPTE240M)
    • 2.17.8. Colorspace NTSC 1953 (V4L2_COLORSPACE_470_SYSTEM_M)
    • 2.17.9. Colorspace EBU Tech. 3213 (V4L2_COLORSPACE_470_SYSTEM_BG)
    • 2.17.10. Colorspace JPEG (V4L2_COLORSPACE_JPEG)
  • 2.18. Detailed Transfer Function Descriptions
    • 2.18.1. Transfer Function SMPTE 2084 (V4L2_XFER_FUNC_SMPTE2084)
• 3. Input/Output
  • 3.1. Read/Write
  • 3.2. Streaming I/O (Memory Mapping)
    • 3.2.1. Example: Mapping buffers in the single-planar API
    • 3.2.2. Example: Mapping buffers in the multi-planar API
  • 3.3. Streaming I/O (User Pointers)
    • 3.3.1. Example: Initiating streaming I/O with user pointers
  • 3.4. Streaming I/O (DMA buffer importing)
    • 3.4.1. Example: Initiating streaming I/O with DMABUF file descriptors
    • 3.4.2. Example: Queueing DMABUF using single plane API
    • 3.4.3. Example 3.6. Queueing DMABUF using multi plane API
  • 3.5. Buffers
    • 3.5.1. Interactions between formats, controls and buffers
    • 3.5.2. struct v4l2_buffer
    • 3.5.3. struct v4l2_plane
    • 3.5.4. enum v4l2_buf_type
    • 3.5.5. Buffer Flags
    • 3.5.6. enum v4l2_memory
    • 3.5.7. Timecodes
      • 3.5.7.1. struct v4l2_timecode
      • 3.5.7.2. Timecode Types
      • 3.5.7.3. Timecode Flags
  • 3.6. Field Order
    • 3.6.1. enum v4l2_field
    • 3.6.2. Field Order, Top Field First Transmitted
    • 3.6.3. Field Order, Bottom Field First Transmitted
• 4. Interfaces
  • 4.1. Video Capture Interface
    • 4.1.1. Querying Capabilities
    • 4.1.2. Supplemental Functions
    • 4.1.3. Image Format Negotiation
    • 4.1.4. Reading Images
  • 4.2. Video Overlay Interface
    • 4.2.1. Querying Capabilities
    • 4.2.2. Supplemental Functions
    • 4.2.3. Setup
    • 4.2.4. Overlay Window
      • 4.2.4.1. struct v4l2_window
      • 4.2.4.2. struct v4l2_clip
      • 4.2.4.3. struct v4l2_rect
    • 4.2.5. Enabling Overlay
  • 4.3. Video Output Interface
    • 4.3.1. Querying Capabilities
    • 4.3.2. Supplemental Functions
    • 4.3.3. Image Format Negotiation
    • 4.3.4. Writing Images
  • 4.4. Video Output Overlay Interface
    • 4.4.1. Querying Capabilities
    • 4.4.2. Framebuffer
      • 4.4.2.1. Example: Finding a framebuffer device for OSD
    • 4.4.3. Overlay Window and Scaling
    • 4.4.4. Enabling Overlay
  • 4.5. Video Memory-To-Memory Interface
    • 4.5.1. Memory-to-Memory Stateful Video Decoder Interface
      • 4.5.1.1. Conventions and Notations Used in This Document
      • 4.5.1.2. Glossary
      • 4.5.1.3. State Machine
      • 4.5.1.4. Querying Capabilities
      • 4.5.1.5. Initialization
      • 4.5.1.6. Capture Setup
      • 4.5.1.7. Decoding
      • 4.5.1.8. Seek
      • 4.5.1.9. Dynamic Resolution Change
      • 4.5.1.10. Drain
      • 4.5.1.11. End of Stream
      • 4.5.1.12. Commit Points
    • 4.5.2. Memory-to-Memory Stateful Video Encoder Interface
      • 4.5.2.1. Conventions and Notations Used in This Document
      • 4.5.2.2. Glossary
      • 4.5.2.3. State Machine
      • 4.5.2.4. Querying Capabilities
      • 4.5.2.5. Initialization
      • 4.5.2.6. Encoding
      • 4.5.2.7. Encoding Parameter Changes
      • 4.5.2.8. Drain
      • 4.5.2.9. Reset
      • 4.5.2.10. Commit Points
    • 4.5.3. Memory-to-memory Stateless Video Decoder Interface
      • 4.5.3.1. Querying capabilities
      • 4.5.3.2. Initialization
      • 4.5.3.3. Decoding
      • 4.5.3.4. Buffer management while decoding
      • 4.5.3.5. Seeking
      • 4.5.3.6. Pausing
      • 4.5.3.7. Dynamic resolution change
      • 4.5.3.8. Drain
  • 4.6. Raw VBI Data Interface
    • 4.6.1. Querying Capabilities
    • 4.6.2. Supplemental Functions
    • 4.6.3. Raw VBI Format Negotiation
    • 4.6.4. Reading and writing VBI images
  • 4.7. Sliced VBI Data Interface
    • 4.7.1. Querying Capabilities
    • 4.7.2. Supplemental Functions
    • 4.7.3. Sliced VBI Format Negotiation
      • 4.7.3.1. struct v4l2_sliced_vbi_format
      • 4.7.3.2. Sliced VBI services
        • 4.7.3.2.1. V4L2_SLICED_WSS_625 payload
    • 4.7.4. Reading and writing sliced VBI data
      • 4.7.4.1. struct v4l2_sliced_vbi_data
    • 4.7.5. Sliced VBI Data in MPEG Streams
      • 4.7.5.1. MPEG Stream Embedded, Sliced VBI Data Format: NONE
      • 4.7.5.2. MPEG Stream Embedded, Sliced VBI Data Format: IVTV
      • 4.7.5.3. struct v4l2_mpeg_vbi_fmt_ivtv
      • 4.7.5.4. Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field
      • 4.7.5.5. structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0
      • 4.7.5.6. struct v4l2_mpeg_vbi_ITV0
      • 4.7.5.7. struct v4l2_mpeg_vbi_itv0_line
      • 4.7.5.8. Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field
  • 4.8. Radio Interface
    • 4.8.1. Querying Capabilities
    • 4.8.2. Supplemental Functions
    • 4.8.3. Programming
  • 4.9. RDS Interface
    • 4.9.1. Querying Capabilities
    • 4.9.2. Reading RDS data
    • 4.9.3. Writing RDS data
    • 4.9.4. RDS datastructures
  • 4.10. Software Defined Radio Interface (SDR)
    • 4.10.1. Querying Capabilities
    • 4.10.2. Supplemental Functions
    • 4.10.3. Data Format Negotiation
  • 4.11. Touch Devices
    • 4.11.1. Overview
    • 4.11.2. Querying Capabilities
    • 4.11.3. Data Format Negotiation
  • 4.12. Event Interface
  • 4.13. Sub-device Interface
    • 4.13.1. Controls
    • 4.13.2. Events
    • 4.13.3. Pad-level Formats
      • 4.13.3.1. Format Negotiation
      • 4.13.3.2. Selections: cropping, scaling and composition
      • 4.13.3.3. Types of selection targets
        • 4.13.3.3.1. Actual targets
        • 4.13.3.3.2. BOUNDS targets
      • 4.13.3.4. Order of configuration and format propagation
        • 4.13.3.4.1. Media Bus Formats
      • 4.13.3.5. Streams, multiplexed media pads and internal routing
        • 4.13.3.5.1. Understanding streams
        • 4.13.3.5.2. Interaction between routes, streams, formats and selections
        • 4.13.3.5.3. Device types and routing setup
        • 4.13.3.5.4. Configuring streams
        • 4.13.3.5.5. Multiplexed streams setup example
  • 4.14. Metadata Interface
    • 4.14.1. Querying Capabilities
    • 4.14.2. Data Format Negotiation
• 5. Libv4l Userspace Library
  • 5.1. Introduction
    • 5.1.1. libv4lconvert
    • 5.1.2. libv4l1
    • 5.1.3. libv4l2
      • 5.1.3.1. Libv4l device control functions
    • 5.1.4. v4l1compat.so wrapper library
• 6. Changes
  • 6.1. Differences between V4L and V4L2
    • 6.1.1. Opening and Closing Devices
    • 6.1.2. Querying Capabilities
    • 6.1.3. Video Sources
    • 6.1.4. Tuning
    • 6.1.5. Image Properties
    • 6.1.6. Audio
    • 6.1.7. Frame Buffer Overlay
    • 6.1.8. Cropping
    • 6.1.9. Reading Images, Memory Mapping
      • 6.1.9.1. Capturing using the read method
      • 6.1.9.2. Capturing using memory mapping
    • 6.1.10. Reading Raw VBI Data
    • 6.1.11. Miscellaneous
  • 6.2. Changes of the V4L2 API
    • 6.2.1. Early Versions
    • 6.2.2. V4L2 Version 0.16 1999-01-31
    • 6.2.3. V4L2 Version 0.18 1999-03-16
    • 6.2.4. V4L2 Version 0.19 1999-06-05
    • 6.2.5. V4L2 Version 0.20 (1999-09-10)
    • 6.2.6. V4L2 Version 0.20 incremental changes
    • 6.2.7. V4L2 Version 0.20 2000-11-23
    • 6.2.8. V4L2 Version 0.20 2002-07-25
    • 6.2.9. V4L2 in Linux 2.5.46, 2002-10
    • 6.2.10. V4L2 2003-06-19
    • 6.2.11. V4L2 2003-11-05
    • 6.2.12. V4L2 in Linux 2.6.6, 2004-05-09
    • 6.2.13. V4L2 in Linux 2.6.8
    • 6.2.14. V4L2 spec erratum 2004-08-01
    • 6.2.15. V4L2 in Linux 2.6.14
    • 6.2.16. V4L2 in Linux 2.6.15
    • 6.2.17. V4L2 spec erratum 2005-11-27
    • 6.2.18. V4L2 spec erratum 2006-01-10
    • 6.2.19. V4L2 spec erratum 2006-02-03
    • 6.2.20. V4L2 spec erratum 2006-02-04
    • 6.2.21. V4L2 in Linux 2.6.17
    • 6.2.22. V4L2 spec erratum 2006-09-23 (Draft 0.15)
    • 6.2.23. V4L2 in Linux 2.6.18
    • 6.2.24. V4L2 in Linux 2.6.19
    • 6.2.25. V4L2 spec erratum 2006-10-12 (Draft 0.17)
    • 6.2.26. V4L2 in Linux 2.6.21
    • 6.2.27. V4L2 in Linux 2.6.22
    • 6.2.28. V4L2 in Linux 2.6.24
    • 6.2.29. V4L2 in Linux 2.6.25
    • 6.2.30. V4L2 in Linux 2.6.26
    • 6.2.31. V4L2 in Linux 2.6.27
    • 6.2.32. V4L2 in Linux 2.6.28
    • 6.2.33. V4L2 in Linux 2.6.29
    • 6.2.34. V4L2 in Linux 2.6.30
    • 6.2.35. V4L2 in Linux 2.6.32
    • 6.2.36. V4L2 in Linux 2.6.33
    • 6.2.37. V4L2 in Linux 2.6.34
    • 6.2.38. V4L2 in Linux 2.6.37
    • 6.2.39. V4L2 in Linux 2.6.39
    • 6.2.40. V4L2 in Linux 3.1
    • 6.2.41. V4L2 in Linux 3.2
    • 6.2.42. V4L2 in Linux 3.3
    • 6.2.43. V4L2 in Linux 3.4
    • 6.2.44. V4L2 in Linux 3.5
    • 6.2.45. V4L2 in Linux 3.6
    • 6.2.46. V4L2 in Linux 3.9
    • 6.2.47. V4L2 in Linux 3.10
    • 6.2.48. V4L2 in Linux 3.11
    • 6.2.49. V4L2 in Linux 3.14
    • 6.2.50. V4L2 in Linux 3.15
    • 6.2.51. V4L2 in Linux 3.16
    • 6.2.52. V4L2 in Linux 3.17
    • 6.2.53. V4L2 in Linux 3.18
    • 6.2.54. V4L2 in Linux 3.19
    • 6.2.55. V4L2 in Linux 4.4
    • 6.2.56. Relation of V4L2 to other Linux multimedia APIs
      • 6.2.56.1. X Video Extension
      • 6.2.56.2. Digital Video
      • 6.2.56.3. Audio Interfaces
    • 6.2.57. Experimental API Elements
    • 6.2.58. Obsolete API Elements
• 7. Function Reference
  • 7.1. V4L2 close()
    • 7.1.1. Name
    • 7.1.2. Synopsis
    • 7.1.3. Arguments
    • 7.1.4. Description
    • 7.1.5. Return Value
  • 7.2. V4L2 ioctl()
    • 7.2.1. Name
    • 7.2.2. Synopsis
    • 7.2.3. Arguments
    • 7.2.4. Description
    • 7.2.5. Return Value
  • 7.3. ioctl VIDIOC_CREATE_BUFS
    • 7.3.1. Name
    • 7.3.2. Synopsis
    • 7.3.3. Arguments
    • 7.3.4. Description
    • 7.3.5. Return Value
  • 7.4. ioctl VIDIOC_CROPCAP
    • 7.4.1. Name
    • 7.4.2. Synopsis
    • 7.4.3. Arguments
    • 7.4.4. Description
    • 7.4.5. Return Value
  • 7.5. ioctl VIDIOC_DBG_G_CHIP_INFO
    • 7.5.1. Name
    • 7.5.2. Synopsis
    • 7.5.3. Arguments
    • 7.5.4. Description
    • 7.5.5. Return Value
  • 7.6. ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
    • 7.6.1. Name
    • 7.6.2. Synopsis
    • 7.6.3. Arguments
    • 7.6.4. Description
    • 7.6.5. Return Value
  • 7.7. ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD
    • 7.7.1. Name
    • 7.7.2. Synopsis
    • 7.7.3. Arguments
    • 7.7.4. Description
    • 7.7.5. Return Value
  • 7.8. ioctl VIDIOC_DQEVENT
    • 7.8.1. Name
    • 7.8.2. Synopsis
    • 7.8.3. Arguments
    • 7.8.4. Description
    • 7.8.5. Return Value
  • 7.9. ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP
    • 7.9.1. Name
    • 7.9.2. Synopsis
    • 7.9.3. Arguments
    • 7.9.4. Description
    • 7.9.5. Return Value
  • 7.10. ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
    • 7.10.1. Name
    • 7.10.2. Synopsis
    • 7.10.3. Arguments
    • 7.10.4. Description
    • 7.10.5. Return Value
  • 7.11. ioctl VIDIOC_ENUMAUDIO
    • 7.11.1. Name
    • 7.11.2. Synopsis
    • 7.11.3. Arguments
    • 7.11.4. Description
    • 7.11.5. Return Value
  • 7.12. ioctl VIDIOC_ENUMAUDOUT
    • 7.12.1. Name
    • 7.12.2. Synopsis
    • 7.12.3. Arguments
    • 7.12.4. Description
    • 7.12.5. Return Value
  • 7.13. ioctl VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS
    • 7.13.1. Name
    • 7.13.2. Synopsis
    • 7.13.3. Arguments
    • 7.13.4. Description
    • 7.13.5. Return Value
  • 7.14. ioctl VIDIOC_ENUM_FMT
    • 7.14.1. Name
    • 7.14.2. Synopsis
    • 7.14.3. Arguments
    • 7.14.4. Description
    • 7.14.5. Return Value
  • 7.15. ioctl VIDIOC_ENUM_FRAMESIZES
    • 7.15.1. Name
    • 7.15.2. Synopsis
    • 7.15.3. Arguments
    • 7.15.4. Description
    • 7.15.5. Structs
    • 7.15.6. Enums
    • 7.15.7. Return Value
  • 7.16. ioctl VIDIOC_ENUM_FRAMEINTERVALS
    • 7.16.1. Name
    • 7.16.2. Synopsis
    • 7.16.3. Arguments
    • 7.16.4. Description
    • 7.16.5. Structs
    • 7.16.6. Enums
    • 7.16.7. Return Value
  • 7.17. ioctl VIDIOC_ENUM_FREQ_BANDS
    • 7.17.1. Name
    • 7.17.2. Synopsis
    • 7.17.3. Arguments
    • 7.17.4. Description
    • 7.17.5. Return Value
  • 7.18. ioctl VIDIOC_ENUMINPUT
    • 7.18.1. Name
    • 7.18.2. Synopsis
    • 7.18.3. Arguments
    • 7.18.4. Description
    • 7.18.5. Return Value
  • 7.19. ioctl VIDIOC_ENUMOUTPUT
    • 7.19.1. Name
    • 7.19.2. Synopsis
    • 7.19.3. Arguments
    • 7.19.4. Description
    • 7.19.5. Return Value
  • 7.20. ioctl VIDIOC_ENUMSTD, VIDIOC_SUBDEV_ENUMSTD
    • 7.20.1. Name
    • 7.20.2. Synopsis
    • 7.20.3. Arguments
    • 7.20.4. Description
    • 7.20.5. Return Value
  • 7.21. ioctl VIDIOC_EXPBUF
    • 7.21.1. Name
    • 7.21.2. Synopsis
    • 7.21.3. Arguments
    • 7.21.4. Description
    • 7.21.5. Examples
    • 7.21.6. Return Value
  • 7.22. ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO
    • 7.22.1. Name
    • 7.22.2. Synopsis
    • 7.22.3. Arguments
    • 7.22.4. Description
    • 7.22.5. Return Value
  • 7.23. ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
    • 7.23.1. Name
    • 7.23.2. Synopsis
    • 7.23.3. Arguments
    • 7.23.4. Description
    • 7.23.5. Return Value
  • 7.24. ioctl VIDIOC_G_CROP, VIDIOC_S_CROP
    • 7.24.1. Name
    • 7.24.2. Synopsis
    • 7.24.3. Arguments
    • 7.24.4. Description
    • 7.24.5. Return Value
  • 7.25. ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
    • 7.25.1. Name
    • 7.25.2. Synopsis
    • 7.25.3. Arguments
    • 7.25.4. Description
    • 7.25.5. Return Value
  • 7.26. ioctl VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS
    • 7.26.1. Name
    • 7.26.2. Synopsis
    • 7.26.3. Arguments
    • 7.26.4. Description
    • 7.26.5. Return Value
  • 7.27. ioctl VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID
    • 7.27.1. Name
    • 7.27.2. Synopsis
    • 7.27.3. Arguments
    • 7.27.4. Description
    • 7.27.5. Return Value
  • 7.28. ioctl VIDIOC_G_ENC_INDEX
    • 7.28.1. Name
    • 7.28.2. Synopsis
    • 7.28.3. Arguments
    • 7.28.4. Description
    • 7.28.5. Return Value
  • 7.29. ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLS
    • 7.29.1. Name
    • 7.29.2. Synopsis
    • 7.29.3. Arguments
    • 7.29.4. Description
    • 7.29.5. Return Value
  • 7.30. ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF
    • 7.30.1. Name
    • 7.30.2. Synopsis
    • 7.30.3. Arguments
    • 7.30.4. Description
    • 7.30.5. Return Value
  • 7.31. ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT
    • 7.31.1. Name
    • 7.31.2. Synopsis
    • 7.31.3. Arguments
    • 7.31.4. Description
    • 7.31.5. Return Value
  • 7.32. ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY
    • 7.32.1. Name
    • 7.32.2. Synopsis
    • 7.32.3. Arguments
    • 7.32.4. Description
    • 7.32.5. Return Value
  • 7.33. ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT
    • 7.33.1. Name
    • 7.33.2. Synopsis
    • 7.33.3. Arguments
    • 7.33.4. Description
    • 7.33.5. Return Value
  • 7.34. ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP
    • 7.34.1. Name
    • 7.34.2. Synopsis
    • 7.34.3. Arguments
    • 7.34.4. Description
    • 7.34.5. Return Value
  • 7.35. ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR
    • 7.35.1. Name
    • 7.35.2. Synopsis
    • 7.35.3. Arguments
    • 7.35.4. Description
    • 7.35.5. Return Value
  • 7.36. ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT
    • 7.36.1. Name
    • 7.36.2. Synopsis
    • 7.36.3. Arguments
    • 7.36.4. Description
    • 7.36.5. Return Value
  • 7.37. ioctl VIDIOC_G_PARM, VIDIOC_S_PARM
    • 7.37.1. Name
    • 7.37.2. Synopsis
    • 7.37.3. Arguments
    • 7.37.4. Description
    • 7.37.5. Return Value
  • 7.38. ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
    • 7.38.1. Name
    • 7.38.2. Synopsis
    • 7.38.3. Arguments
    • 7.38.4. Description
    • 7.38.5. Return Value
  • 7.39. ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION
    • 7.39.1. Name
    • 7.39.2. Synopsis
    • 7.39.3. Arguments
    • 7.39.4. Description
    • 7.39.5. Return Value
  • 7.40. ioctl VIDIOC_G_SLICED_VBI_CAP
    • 7.40.1. Name
    • 7.40.2. Synopsis
    • 7.40.3. Arguments
    • 7.40.4. Description
      • 7.40.4.1. V4L2_SLICED_VBI_CAP WSS_625 payload
    • 7.40.5. Return Value
  • 7.41. ioctl VIDIOC_G_STD, VIDIOC_S_STD, VIDIOC_SUBDEV_G_STD, VIDIOC_SUBDEV_S_STD
    • 7.41.1. Name
    • 7.41.2. Synopsis
    • 7.41.3. Arguments
    • 7.41.4. Description
    • 7.41.5. Return Value
  • 7.42. ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER
    • 7.42.1. Name
    • 7.42.2. Synopsis
    • 7.42.3. Arguments
    • 7.42.4. Description
    • 7.42.5. Return Value
  • 7.43. ioctl VIDIOC_LOG_STATUS
    • 7.43.1. Name
    • 7.43.2. Synopsis
    • 7.43.3. Arguments
    • 7.43.4. Description
    • 7.43.5. Return Value
  • 7.44. ioctl VIDIOC_OVERLAY
    • 7.44.1. Name
    • 7.44.2. Synopsis
    • 7.44.3. Arguments
    • 7.44.4. Description
    • 7.44.5. Return Value
  • 7.45. ioctl VIDIOC_PREPARE_BUF
    • 7.45.1. Name
    • 7.45.2. Synopsis
    • 7.45.3. Arguments
    • 7.45.4. Description
    • 7.45.5. Return Value
  • 7.46. ioctl VIDIOC_QBUF, VIDIOC_DQBUF
    • 7.46.1. Name
    • 7.46.2. Synopsis
    • 7.46.3. Arguments
    • 7.46.4. Description
    • 7.46.5. Return Value
  • 7.47. ioctl VIDIOC_QUERYBUF
    • 7.47.1. Name
    • 7.47.2. Synopsis
    • 7.47.3. Arguments
    • 7.47.4. Description
    • 7.47.5. Return Value
  • 7.48. ioctl VIDIOC_QUERYCAP
    • 7.48.1. Name
    • 7.48.2. Synopsis
    • 7.48.3. Arguments
    • 7.48.4. Description
    • 7.48.5. Return Value
  • 7.49. ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU
    • 7.49.1. Name
    • 7.49.2. Synopsis
    • 7.49.3. Arguments
    • 7.49.4. Description
    • 7.49.5. Return Value
  • 7.50. ioctl VIDIOC_QUERY_DV_TIMINGS
    • 7.50.1. Name
    • 7.50.2. Synopsis
    • 7.50.3. Arguments
    • 7.50.4. Description
    • 7.50.5. Return Value
  • 7.51. ioctl VIDIOC_QUERYSTD, VIDIOC_SUBDEV_QUERYSTD
    • 7.51.1. Name
    • 7.51.2. Synopsis
    • 7.51.3. Arguments
    • 7.51.4. Description
    • 7.51.5. Return Value
  • 7.52. ioctl VIDIOC_REQBUFS
    • 7.52.1. Name
    • 7.52.2. Synopsis
    • 7.52.3. Arguments
    • 7.52.4. Description
    • 7.52.5. Return Value
  • 7.53. ioctl VIDIOC_REMOVE_BUFS
    • 7.53.1. Name
    • 7.53.2. Synopsis
    • 7.53.3. Arguments
    • 7.53.4. Description
    • 7.53.5. Return Value
  • 7.54. ioctl VIDIOC_S_HW_FREQ_SEEK
    • 7.54.1. Name
    • 7.54.2. Synopsis
    • 7.54.3. Arguments
    • 7.54.4. Description
    • 7.54.5. Return Value
  • 7.55. ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
    • 7.55.1. Name
    • 7.55.2. Synopsis
    • 7.55.3. Arguments
    • 7.55.4. Description
    • 7.55.5. Return Value
  • 7.56. ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
    • 7.56.1. Name
    • 7.56.2. Synopsis
    • 7.56.3. Arguments
    • 7.56.4. Description
    • 7.56.5. Return Value
  • 7.57. ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE
    • 7.57.1. Name
    • 7.57.2. Synopsis
    • 7.57.3. Arguments
    • 7.57.4. Description
    • 7.57.5. Return Value
  • 7.58. ioctl VIDIOC_SUBDEV_ENUM_MBUS_CODE
    • 7.58.1. Name
    • 7.58.2. Synopsis
    • 7.58.3. Arguments
    • 7.58.4. Description
    • 7.58.5. Return Value
  • 7.59. ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP
    • 7.59.1. Name
    • 7.59.2. Synopsis
    • 7.59.3. Arguments
    • 7.59.4. Description
    • 7.59.5. Return Value
  • 7.60. ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT
    • 7.60.1. Name
    • 7.60.2. Synopsis
    • 7.60.3. Arguments
    • 7.60.4. Description
    • 7.60.5. Return Value
  • 7.61. ioctl VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL
    • 7.61.1. Name
    • 7.61.2. Synopsis
    • 7.61.3. Arguments
    • 7.61.4. Description
    • 7.61.5. Return Value
  • 7.62. ioctl VIDIOC_SUBDEV_G_ROUTING, VIDIOC_SUBDEV_S_ROUTING
    • 7.62.1. Name
    • 7.62.2. Synopsis
    • 7.62.3. Arguments
    • 7.62.4. Description
    • 7.62.5. Return Value
  • 7.63. ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
    • 7.63.1. Name
    • 7.63.2. Synopsis
    • 7.63.3. Arguments
    • 7.63.4. Description
      • 7.63.4.1. Types of selection targets
      • 7.63.4.2. Discovering supported features
    • 7.63.5. Return Value
  • 7.64. ioctl VIDIOC_SUBDEV_G_CLIENT_CAP, VIDIOC_SUBDEV_S_CLIENT_CAP
    • 7.64.1. Name
    • 7.64.2. Synopsis
    • 7.64.3. Arguments
    • 7.64.4. Description
    • 7.64.5. Return Value
  • 7.65. ioctl VIDIOC_SUBDEV_QUERYCAP
    • 7.65.1. Name
    • 7.65.2. Synopsis
    • 7.65.3. Arguments
    • 7.65.4. Description
    • 7.65.5. Return Value
  • 7.66. ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
    • 7.66.1. Name
    • 7.66.2. Synopsis
    • 7.66.3. Arguments
    • 7.66.4. Description
    • 7.66.5. Return Value
  • 7.67. V4L2 mmap()
    • 7.67.1. Name
    • 7.67.2. Synopsis
    • 7.67.3. Arguments
    • 7.67.4. Description
    • 7.67.5. Return Value
  • 7.68. V4L2 munmap()
    • 7.68.1. Name
    • 7.68.2. Synopsis
    • 7.68.3. Arguments
    • 7.68.4. Description
    • 7.68.5. Return Value
  • 7.69. V4L2 open()
    • 7.69.1. Name
    • 7.69.2. Synopsis
    • 7.69.3. Arguments
    • 7.69.4. Description
    • 7.69.5. Return Value
  • 7.70. V4L2 poll()
    • 7.70.1. Name
    • 7.70.2. Synopsis
    • 7.70.3. Arguments
    • 7.70.4. Description
    • 7.70.5. Return Value
  • 7.71. V4L2 read()
    • 7.71.1. Name
    • 7.71.2. Synopsis
    • 7.71.3. Arguments
    • 7.71.4. Description
    • 7.71.5. Return Value
  • 7.72. V4L2 select()
    • 7.72.1. Name
    • 7.72.2. Synopsis
    • 7.72.3. Arguments
    • 7.72.4. Description
    • 7.72.5. Return Value
  • 7.73. V4L2 write()
    • 7.73.1. Name
    • 7.73.2. Synopsis
    • 7.73.3. Arguments
    • 7.73.4. Description
    • 7.73.5. Return Value
• 8. Common definitions for V4L2 and V4L2 subdev interfaces
  • 8.1. Common selection definitions
    • 8.1.1. Selection targets
    • 8.1.2. Selection flags
• 9. Video For Linux Two Header File
  • 9.1. videodev2.h
• 10. Video Capture Example
  • 10.1. file: media/v4l/capture.c
• 11. Video Grabber example using libv4l
  • 11.1. file: media/v4l/v4l2grab.c
• 12. References
  • 12.1. CEA 608-E
  • 12.2. EN 300 294
  • 12.3. ETS 300 231
  • 12.4. ETS 300 706
  • 12.5. ISO 13818-1
  • 12.6. ISO 13818-2
  • 12.7. ITU BT.470
  • 12.8. ITU BT.601
  • 12.9. ITU BT.653
  • 12.10. ITU BT.709
  • 12.11. ITU BT.1119
  • 12.12. ITU-T Rec. H.264 Specification (04/2017 Edition)
  • 12.13. ITU H.265/HEVC
  • 12.14. JFIF
  • 12.15. ITU-T.81
  • 12.16. W3C JPEG JFIF
  • 12.17. SMPTE 12M
  • 12.18. SMPTE 170M
  • 12.19. SMPTE 240M
  • 12.20. SMPTE RP 431-2
  • 12.21. SMPTE ST 2084
  • 12.22. sRGB
  • 12.23. sYCC
  • 12.24. xvYCC
  • 12.25. opRGB
  • 12.26. ITU BT.2020
  • 12.27. EBU Tech 3213
  • 12.28. EBU Tech 3321
  • 12.29. IEC 62106
  • 12.30. NRSC-4-B
  • 12.31. ISO 12232:2006
  • 12.32. CEA-861-E
  • 12.33. VESA DMT
  • 12.34. EDID
  • 12.35. HDCP
  • 12.36. HDMI
  • 12.37. HDMI2
  • 12.38. DP
  • 12.39. poynton
  • 12.40. colimg
  • 12.41. VP8
  • 12.42. VP9
  • 12.43. AV1

Revision and Copyright

Authors, in alphabetical order:

• Ailus, Sakari <sakari.ailus@iki.fi>

  • Subdev selections API.

• Carvalho Chehab, Mauro <mchehab+samsung@kernel.org>

  • Documented libv4l, designed and added v4l2grab example, Remote Controller chapter.

• Dirks, Bill

  • Original author of the V4L2 API and documentation.

• Figa, Tomasz <tfiga@chromium.org>

  • Documented the memory-to-memory decoder interface.

  • Documented the memory-to-memory encoder interface.

• H Schimek, Michael <mschimek@gmx.at>

  • Original author of the V4L2 API and documentation.

• Karicheri, Muralidharan <m-karicheri2@ti.com>

  • Documented the Digital Video timings API.

• Osciak, Pawel <posciak@chromium.org>

  • Documented the memory-to-memory decoder interface.

  • Documented the memory-to-memory encoder interface.

• Osciak, Pawel <pawel@osciak.com>

  • Designed and documented the multi-planar API.

• Palosaari, Antti <crope@iki.fi>

  • SDR API.

• Ribalda, Ricardo

  • Introduce HSV formats and other minor changes.

• Rubli, Martin

  • Designed and documented the VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS ioctls.

• Walls, Andy <awalls@md.metrocast.net>

  • Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV MPEG stream embedded, sliced VBI data format in this specification.

• Verkuil, Hans <hverkuil@xs4all.nl>

  • Designed and documented the VIDIOC_LOG_STATUS ioctl, the extended control ioctls, major parts of the sliced VBI API, the MPEG encoder and decoder APIs and the DV Timings API.

Copyright © 1999-2018: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari, Tomasz Figa

Except when explicitly stated as GPL, programming examples within this part can be used and distributed without restrictions.

Revision History

revision

4.10 / 2016-07-15 (rr)

Introduce HSV formats.

revision

4.5 / 2015-10-29 (rr)

Extend VIDIOC_G_EXT_CTRLS;. Replace ctrl_class with a new union with ctrl_class and which. Which is used to select the current value of the control or the default value.

revision

4.4 / 2015-05-26 (ap)

Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. Added V4L2_CID_RF_TUNER_RF_GAIN control. Added transmitter support for Software Defined Radio (SDR) Interface.

revision

4.1 / 2015-02-13 (mcc)

Fix documentation for media controller device nodes and add support for DVB device nodes. Add support for Tuner sub-device.

revision

3.19 / 2014-12-05 (hv)

Rewrote Colorspace chapter, added new enum v4l2_ycbcr_encoding and enum v4l2_quantization fields to struct v4l2_pix_format, struct v4l2_pix_format_mplane and struct v4l2_mbus_framefmt.

revision

3.17 / 2014-08-04 (lp, hv)

Extended struct v4l2_pix_format. Added format flags. Added compound control types and VIDIOC_QUERY_EXT_CTRL.

revision

3.15 / 2014-02-03 (hv, ap)

Update several sections of “Common API Elements”: “Opening and Closing Devices” “Querying Capabilities”, “Application Priority”, “Video Inputs and Outputs”, “Audio Inputs and Outputs” “Tuners and Modulators”, “Video Standards” and “Digital Video (DV) Timings”. Added SDR API.

revision

3.14 / 2013-11-25 (rr)

Set width and height as unsigned on v4l2_rect.

revision

3.11 / 2013-05-26 (hv)

Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl.

revision

3.10 / 2013-03-25 (hv)

Remove obsolete and unused DV_PRESET ioctls: VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS. Added VIDIOC_DBG_G_CHIP_INFO.

revision

3.9 / 2012-12-03 (sa, sn)

Added timestamp types to v4l2_buffer. Added V4L2_EVENT_CTRL_CH_RANGE control event changes flag.

revision

3.6 / 2012-07-02 (hv)

Added VIDIOC_ENUM_FREQ_BANDS.

revision

3.5 / 2012-05-07 (sa, sn, hv)

Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API. Improved the description of V4L2_CID_COLORFX control, added V4L2_CID_COLORFX_CBCR control. Added camera controls V4L2_CID_AUTO_EXPOSURE_BIAS, V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE, V4L2_CID_IMAGE_STABILIZATION, V4L2_CID_ISO_SENSITIVITY, V4L2_CID_ISO_SENSITIVITY_AUTO, V4L2_CID_EXPOSURE_METERING, V4L2_CID_SCENE_MODE, V4L2_CID_3A_LOCK, V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP, V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. Added VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and VIDIOC_DV_TIMINGS_CAP.

revision

3.4 / 2012-01-25 (sn)

Added JPEG compression control class.

revision

3.3 / 2012-01-11 (hv)

Added device_caps field to struct v4l2_capabilities.

revision

3.2 / 2011-08-26 (hv)

Added V4L2_CTRL_FLAG_VOLATILE.

revision

3.1 / 2011-06-27 (mcc, po, hv)

Documented that VIDIOC_QUERYCAP now returns a per-subsystem version instead of a per-driver one. Standardize an error code for invalid ioctl. Added V4L2_CTRL_TYPE_BITMASK.

revision

2.6.39 / 2011-03-01 (mcc, po)

Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect latest changes. Added the multi-planar API.

revision

2.6.37 / 2010-08-06 (hv)

Removed obsolete vtx (videotext) API.

revision

2.6.33 / 2009-12-03 (mk)

Added documentation for the Digital Video timings API.

revision

2.6.32 / 2009-08-31 (mcc)

Now, revisions will match the kernel version where the V4L2 API changes will be used by the Linux Kernel. Also added Remote Controller chapter.

revision

0.29 / 2009-08-26 (ev)

Added documentation for string controls and for FM Transmitter controls.

revision

0.28 / 2009-08-26 (gl)

Added V4L2_CID_BAND_STOP_FILTER documentation.

revision

0.27 / 2009-08-15 (mcc)

Added libv4l and Remote Controller documentation; added v4l2grab and keytable application examples.

revision

0.26 / 2009-07-23 (hv)

Finalized the RDS capture API. Added modulator and RDS encoder capabilities. Added support for string controls.

revision

0.25 / 2009-01-18 (hv)

Added pixel formats VYUY, NV16 and NV61, and changed the debug ioctls VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. Added camera controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE, V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.

revision

0.24 / 2008-03-04 (mhs)

Added pixel formats Y16 and SBGGR16, new controls and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.

revision

0.23 / 2007-08-30 (mhs)

Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of packed pixel formats.

revision

0.22 / 2007-08-29 (mhs)

Added the Video Output Overlay interface, new MPEG controls, V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT, VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD, VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats. Clarifications in the cropping chapter, about RGB pixel formats, the mmap(), poll(), select(), read() and write() functions. Typographical fixes.

revision

0.21 / 2006-12-19 (mhs)

Fixed a link in the VIDIOC_G_EXT_CTRLS section.

revision

0.20 / 2006-11-24 (mhs)

Clarified the purpose of the audioset field in struct v4l2_input and v4l2_output.

revision

0.19 / 2006-10-19 (mhs)

Documented V4L2_PIX_FMT_RGB444.

revision

0.18 / 2006-10-18 (mhs)

Added the description of extended controls by Hans Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.

revision

0.17 / 2006-10-12 (mhs)

Corrected V4L2_PIX_FMT_HM12 description.

revision

0.16 / 2006-10-08 (mhs)

VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.

revision

0.15 / 2006-09-23 (mhs)

Cleaned up the bibliography, added BT.653 and BT.1119. capture.c/start_capturing() for user pointer I/O did not initialize the buffer index. Documented the V4L MPEG and MJPEG VID_TYPEs and V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel formats. See the history chapter for API changes.

revision

0.14 / 2006-09-14 (mr)

Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of digital devices.

revision

0.13 / 2006-04-07 (mhs)

Corrected the description of struct v4l2_window clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2 defines.

revision

0.12 / 2006-02-03 (mhs)

Corrected the description of struct v4l2_captureparm and v4l2_outputparm.

revision

0.11 / 2006-01-27 (mhs)

Improved the description of struct v4l2_tuner.

revision

0.10 / 2006-01-10 (mhs)

VIDIOC_G_INPUT and VIDIOC_S_PARM clarifications.

revision

0.9 / 2005-11-27 (mhs)

Improved the 525 line numbering diagram. Hans Verkuil and I rewrote the sliced VBI section. He also contributed a VIDIOC_LOG_STATUS page. Fixed VIDIOC_S_STD call in the video standard selection example. Various updates.

revision

0.8 / 2004-10-04 (mhs)

Somehow a piece of junk slipped into the capture example, removed.

revision

0.7 / 2004-09-19 (mhs)

Fixed video standard selection, control enumeration, downscaling and aspect example. Added read and user pointer i/o to video capture example.

revision

0.6 / 2004-08-01 (mhs)

v4l2_buffer changes, added video capture example, various corrections.

revision

0.5 / 2003-11-05 (mhs)

Pixel format erratum.

revision

0.4 / 2003-09-17 (mhs)

Corrected source and Makefile to generate a PDF. SGML fixes. Added latest API changes. Closed gaps in the history chapter.

revision

0.3 / 2003-02-05 (mhs)

Another draft, more corrections.

revision

0.2 / 2003-01-15 (mhs)

Second draft, with corrections pointed out by Gerd Knorr.

revision

0.1 / 2002-12-01 (mhs)

First draft, based on documentation by Bill Dirks and discussions on the V4L mailing list.