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. E-DDC
  • 12.35. EDID
  • 12.36. HDCP
  • 12.37. HDMI
  • 12.38. HDMI2
  • 12.39. DP
  • 12.40. poynton
  • 12.41. colimg
  • 12.42. VP8
  • 12.43. VP9
  • 12.44. 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.