v4l2

package module
v0.0.0-...-4809048 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 31, 2024 License: MIT Imports: 8 Imported by: 0

README

go-v4l2

Package v4l2 exposes the V4L2 (Video4Linux version 2) API to Golang.

Documention

Online documentation, which includes examples, can be found at: http://godoc.org/github.com/reiver/go-v4l2

GoDoc

Example

	device, err := v4l2.Open(v4l2.Video0)
	if nil != err {
		//@TODO
		return err
	}
	defer device.Close()

	fmt.Printf("Driver:  %q\n", device.MustDriver())
	fmt.Printf("Card:    %q\n", device.MustCard())
	fmt.Printf("BusInfo: %q\n", device.MustBusInfo())
	fmt.Printf("Version: %q\n", device.MustVersion())
	fmt.Println()
	fmt.Printf("Has Video Capture: %v\n", device.MustHasCapability(v4l2.CapabilityVideoCapture))
	fmt.Printf("Has Streaming I/O: %v\n", device.MustHasCapability(v4l2.CapabilityStreaming))

Documentation

Overview

Package v4l2 exposes the V4L2 (Video4Linux version 2) API to Golang.

Example: 

device, err := v4l2.Open(v4l2.Video0)
if nil != err {
	//@TODO
	return err
}
defer device.Close()

fmt.Printf("Driver:  %q\n", device.MustDriver())
fmt.Printf("Card:    %q\n", device.MustCard())
fmt.Printf("BusInfo: %q\n", device.MustBusInfo())
fmt.Printf("Version: %q\n", device.MustVersion())
fmt.Println()
fmt.Printf("Has Video Capture: %v\n", device.MustHasCapability(v4l2.CapabilityVideoCapture))
fmt.Printf("Has Streaming I/O: %v\n", device.MustHasCapability(v4l2.CapabilityStreaming))

That example opens up the V4L2 device at "/dev/video0" on the file system, and displays some basic information about the device.

(Of course, we could have opened one of the other V4L2 devices. Such as: v4l2.Video1, v4l2.Video2, ..., or v4l2.Video63.)

Continuing this same example: 

formatFamilies, err := device.FormatFamilies()
if nil != err {
	return err
}
defer formatFamilies.Close()

var formatFamily v4l2.FormatFamily
for formatFamilies.Next() {

	if err := formatFamilies.Decode(&formatFamily); nil != err {
		return err
	}

	fmt.Printf("[format] %q (%q) {compressed=%t} {emulated=%t} \n",
		formatFamily.Description(),
		formatFamily.PixelFormat(),
		formatFamily.HasFlags(v4l2.FormatFamilyFlagCompressed),
		formatFamily.HasFlags(v4l2.FormatFamilyFlagEmulated),
	)

	//@TODO
}
if err := formatFamilies.Err(); nil != err {
	return err
}

Here we have iterating through the formats that are supported for this device.

Extending that last code block, to fill in that "//@TODO", we can iterate through the frame sizes, for each format, we the following: 

frameSizes, err := formatFamily.FrameSizes()
if nil != err {
	return return
}
defer frameSizes.Close()

var frameSize v4l2.FrameSize
for frameSizes.Next() {

	if err := frameSizes.Decode(&frameSize); nil != err {
		return err
	}

	casted, err := frameSize.Cast()
	if nil != err {
		return err
	}

	switch t := casted.(type) {
	case v4l2.FrameSizeDiscrete:
		fmt.Printf("\t [frame size discrete] pixel_format=%q, width=%d, height=%d \n",
			t.PixelFormat,
			t.Width,
			t.Height,
		)
	case v4l2.FrameSizeContinuous:
		fmt.Printf("\t [frame size continuous] pixel_format=%q, min_width=%d, max_width=%d, min_height=%d, max_height=% \n",
			t.PixelFormat,
			t.MinWidth,
			t.MaxWidth,
			t.MinHeight,
			t.MaxHeight,
		)
	case v4l2.FrameSizeStepwise:
		fmt.Printf("\t [frame size stepwise] pixel_format=%q, min_width=%d, max_width=%d, min_height=%d, max_height=% \n",
			t.PixelFormat,
			t.MinWidth,
			t.MaxWidth,
			t.MinHeight,
			t.MaxHeight,
		)
	default:
		return err
	}

}
if err := frameSizes.Err(); nil != err {
	return err
}

Device Paths

One thing to be cognisant of, is that on Linux systems, V4L2 (Video4Linux version 2) will create a (special) file in the /dev/ directory for every V4L2 device.

These devices will name path names such as:

• /dev/video0

• /dev/video1

• /dev/video2

…

• /dev/video63

You would call Open using these names directly. For example: 

device, err := v4l2.Open("/dev/video3")

However, this package also provides constants that can be used. For example: 

device, err := v4l2.Open(v4l2.Video3)

Index

Constants

View Source 
const (
	CapabilityVideoCapture          = 0x00000001 // (V4L2_CAP_VIDEO_CAPTURE)        Is a video capture device
	CapabilityVideoOutput           = 0x00000002 // (V4L2_CAP_VIDEO_OUTPUT)         Is a video output device
	CapabilityVideoOverlay          = 0x00000004 // (V4L2_CAP_VIDEO_OVERLAY)        Can do video overlay
	CapabilityVBICapture            = 0x00000010 // (V4L2_CAP_VBI_CAPTURE)          Is a raw VBI capture device
	CapabilityVBIOutput             = 0x00000020 // (V4L2_CAP_VBI_OUTPUT)           Is a raw VBI output device
	CapabilitySlicedVBICapture      = 0x00000040 // (V4L2_CAP_SLICED_VBI_CAPTURE)   Is a sliced VBI capture device
	CapabilitySlicedVBIOutput       = 0x00000080 // (V4L2_CAP_SLICED_VBI_OUTPUT)    Is a sliced VBI output device
	CapabilityRDSCapture            = 0x00000100 // (V4L2_CAP_RDS_CAPTURE)          RDS data capture
	CapabilityVideoOutputOverlay    = 0x00000200 // (V4L2_CAP_VIDEO_OUTPUT_OVERLAY) Can do video output overlay
	CapabilityHardwareFrequencySeek = 0x00000400 // (V4L2_CAP_HW_FREQ_SEEK)         Can do hardware frequency seek
	CapabilityRDSOutput             = 0x00000800 // (V4L2_CAP_RDS_OUTPUT)           Is an RDS encoder

	CapabilityVideoCaptureMultiplanar = 0x00001000 // (V4L2_CAP_VIDEO_CAPTURE_MPLANE) Is a video capture device that supports multiplanar formats
	CapabilityVideoOutputMultiplanar  = 0x00002000 // (V4L2_CAP_VIDEO_OUTPUT_MPLANE)  Is a video output device that supports multiplanar formats
	CapabilityVideoM2MMultiplanar     = 0x00004000 // (V4L2_CAP_VIDEO_M2M_MPLANE)     Is a video mem-to-mem device that supports multiplanar formats
	CapabilityVideoM2M                = 0x00008000 // (V4L2_CAP_VIDEO_M2M)            Is a video mem-to-mem device

	CapabilityTuner     = 0x00010000 // (V4L2_CAP_TUNER)                has a tuner
	CapabilityAudio     = 0x00020000 // (V4L2_CAP_AUDIO)                has audio support
	CapabilityRadio     = 0x00040000 // (V4L2_CAP_RADIO)                is a radio device
	CapabilityModulator = 0x00080000 // (V4L2_CAP_MODULATOR)            has a modulator

	CapabilityReadWrite = 0x01000000 // (V4L2_CAP_READWRITE)            read/write systemcalls
	CapabilityAsyncIO   = 0x02000000 // (V4L2_CAP_ASYNCIO)              async I/O
	CapabilityStreaming = 0x04000000 // (V4L2_CAP_STREAMING)            streaming I/O ioctls

	CapabilityDeviceCaps = 0x80000000 // (V4L2_CAP_DEVICE_CAPS)         sets device capabilities field
)

V4L2 (Video4Linux version 2) capability constants.

Use these with the v4l2.Device.HasCapability() method.

For example: 

var device v4l2.Device

// ...

if ! device.HasCapability(v4l2.CapabilityVideoCapture) {
	//@TODO
}

These are mimicked from: /usr/include/linux/videodev2.h

View Source 
const (
	Video0 = "/dev/video0"
	Video1 = "/dev/video1"
	Video2 = "/dev/video2"
	Video3 = "/dev/video3"
	Video4 = "/dev/video4"
	Video5 = "/dev/video5"
	Video6 = "/dev/video6"
	Video7 = "/dev/video7"
	Video8 = "/dev/video8"
	Video9 = "/dev/video9"

	Video10 = "/dev/video10"
	Video11 = "/dev/video11"
	Video12 = "/dev/video12"
	Video13 = "/dev/video13"
	Video14 = "/dev/video14"
	Video15 = "/dev/video15"
	Video16 = "/dev/video16"
	Video17 = "/dev/video17"
	Video18 = "/dev/video18"
	Video19 = "/dev/video19"

	Video20 = "/dev/video20"
	Video21 = "/dev/video21"
	Video22 = "/dev/video22"
	Video23 = "/dev/video23"
	Video24 = "/dev/video24"
	Video25 = "/dev/video25"
	Video26 = "/dev/video26"
	Video27 = "/dev/video27"
	Video28 = "/dev/video28"
	Video29 = "/dev/video29"

	Video30 = "/dev/video30"
	Video31 = "/dev/video31"
	Video32 = "/dev/video32"
	Video33 = "/dev/video33"
	Video34 = "/dev/video34"
	Video35 = "/dev/video35"
	Video36 = "/dev/video36"
	Video37 = "/dev/video37"
	Video38 = "/dev/video38"
	Video39 = "/dev/video39"

	Video40 = "/dev/video40"
	Video41 = "/dev/video41"
	Video42 = "/dev/video42"
	Video43 = "/dev/video43"
	Video44 = "/dev/video44"
	Video45 = "/dev/video45"
	Video46 = "/dev/video46"
	Video47 = "/dev/video47"
	Video48 = "/dev/video48"
	Video49 = "/dev/video49"

	Video50 = "/dev/video50"
	Video51 = "/dev/video51"
	Video52 = "/dev/video52"
	Video53 = "/dev/video53"
	Video54 = "/dev/video54"
	Video55 = "/dev/video55"
	Video56 = "/dev/video56"
	Video57 = "/dev/video57"
	Video58 = "/dev/video58"
	Video59 = "/dev/video59"

	Video60 = "/dev/video60"
	Video61 = "/dev/video61"
	Video62 = "/dev/video62"
	Video63 = "/dev/video63"
)

Someone claimed that the V4L2 documentation says that there can only be (a maximum of) 64 allowed devices with the prefix "/dev/video", and starting with "/dev/video0"

Thus, these constants represent the paths to these devices. Such that:

• v4l2.Video0 = "/dev/video0"

• v4l2.Video1 = "/dev/video1"

• v4l2.Video2 = "/dev/video2"

…

• v4l2.Video63 = "/dev/video63"

Use these with the v4l2.Device.Open() method or the v4l2.Open() func.

For example: 

device, err := v4l2.Open(v4l2.Video0)

Or, alternatively, for example: 

var device v4l2.Device

err := device.Open(v4l2.Video0)
View Source 
const (
	FormatFamilyFlagCompressed = 0x0001 // V4L2_FMT_FLAG_COMPRESSED
	FormatFamilyFlagEmulated   = 0x0002 // V4L2_FMT_FLAG_EMULATED
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Device 

type Device struct {
	// contains filtered or unexported fields
}

Device represents a V4L2 (Video4Linux version 2) device.

func MustOpen 

func MustOpen(name string) *Device

MustOpen is like Open, except it panic()s if there is an error.

func Open 

func Open(name string) (*Device, error)

Open opens a V4L2 device.

Example: 

device, err := v4l2.Open(v4l2.Video0)
if nil != err {
	return err
})
defer device.Close()

func (Device) BusInfo 

func (receiver Device) BusInfo() (string, error)

BusInfo returns the location of the V4L2 device in the system.

Example values that BusInfo might return are:

• "usb-0000:00:1a.0-1.5"

• "PCI:0000:05:06.0"

The information returned by BusInfo is intended for users to be able to distinguish between multiple identical devices.

For example, if you have 2 of the exact same (hardware) devices that plug into the USB ports of your computer, and capture HDMI video, then the driver, the card, all the capabilities, etc will be the same for these 2 devices. However, what BusInfo returns will be different.

In the cases wwere no such information is available for the BusInfo (at the Linux or driver level) then BusInfo will be the count of the devices controlled by the driver ("platform:vivi-000").

What is returned from BusInfo will start with:

• "PCI:" for PCI boards, • "PCIe:" for PCI Express boards, • "usb-" for USB devices, • "I2C:" for i2c devices, • "ISA:" for ISA devices, • "parport" for parallel port devices, and • "platform:" for platform devices.

What BusInfo returns is called "bus_info" in the Linux V4L2 documention, which is found in the Linux "v4l2_capability" data structure.

func (Device) Card 

func (receiver Device) Card() (string, error)

Card returns the name of the device.

Example values that Card might return are:

• "Laptop_Integrated_Webcam_HD"

• "Yoyodyne TV/FM"

The information that Card returns is intended for users. I.e., intended to be human readable) And can be used for things such as being use in a menu of available devices.

Note that it is possible for a system to have multiple cards from the same brand.

And thus it is possible for multiple devices to return the exact same value from Card.

To make the name, shown to the user, unique, it can be combined with either the file name path, or what BusInfo returns.

func (*Device) Close 

func (receiver *Device) Close() error

Close closes the device.

You should always close a device after you finished with it, so that you do not create a resource leak.

func (Device) Driver 

func (receiver Device) Driver() (string, error)

Driver returns the name of the driver.

Example values that Driver might return are:

• "uvcvideo"

• "bttv"

If an application can only work with specific drivers, then the information returned from Driver can be used to detect which driver is behind this device.

Also, if certain drivers have bugs, then this can (in part) be used to create driver specific work-arounds.

func (*Device) FormatFamilies 

func (receiver *Device) FormatFamilies() (FormatFamilies, error)

FormatFamilies returns an iterator that enables you to list out all the supported formats by the device.

Example: 

var device v4l2.Device

// ...

formats, err := device.FormatFamilies() // <---- NOTE THAT THIS IS WHERE THE v4l2.Device.FormatFamilies() METHOD IS CALLED.
if nil != err {
        return err
}
defer formats.Close()

var formatFamily v4l2.FormatFamily
forformats.Next() {

        err := formats.Decode(&formatFamily)
        if nil != err {
                fmt.Fprintf(os.Stderr, "ERROR: Problem decoding format: (%T) %v \n", err, err)
                return err
        }

        fmt.Printf("[format] %q (%q) {compressed=%t} {emulated=%t} \n",
                formatFamily.Description(),
                formatFamily.PixelFormat(),
                formatFamily.HasFlags(v4l2.FormatFamilyFlagCompressed),
                formatFamily.HasFlags(v4l2.FormatFamilyFlagEmulated),
        )
}
if err := formats.Err(); nil != err {
        return err
}

func (*Device) GetFormat 

func (receiver *Device) GetFormat(formatcaster v4l2_format.Caster) error

func (Device) HasCapability 

func (receiver Device) HasCapability(cap uint32) (bool, error)

HasCapability return whether the device has a capability a particular capability.

Example: 

device, err := v4l2.Open(v4l2.Video17)

// ...

hasVideoCaptureCapability, err := device.HasCapability(CapabilityVideoCapture)

func (Device) MustBusInfo 

func (receiver Device) MustBusInfo() string

MustBusInfo is like BusInfo, except it panic()s if there is an error. 

device := v4l2.MustOpen(v4l2.Video0)
defer device.MustClose()

fmt.Printf("Bus Info: %q \n", device.MustBusInfo())

func (Device) MustCard 

func (receiver Device) MustCard() string

MustCard is like BusCard, except it panic()s if there is an error. 

device := v4l2.MustOpen(v4l2.Video0)
defer device.MustClose()

fmt.Printf("Card: %q \n", device.MustCard())

func (*Device) MustClose 

func (receiver *Device) MustClose()

MustClose is like Close, except it panic()s if there is an error.

Example: 

device := v4l2.MustOpen(v4l2.Video0)
defer device.MustClose()

func (Device) MustDriver 

func (receiver Device) MustDriver() string

MustDriver is like Driver, except it panic()s if there is an error.

Example: 

device := v4l2.MustOpen(v4l2.Video0)
defer device.MustClose()

fmt.Printf("Driver: %q \n", device.MustDriver())

func (Device) MustHasCapability 

func (receiver Device) MustHasCapability(cap uint32) bool

MustHasCapability is like HasCapability, except it panic()s if there is an error. 

device := v4l2.MustOpen(v4l2.Video0)
defer device.MustClose()

fmt.Printf("Has Streaming Capability: %t \n", device.MustHasCapability(v4l2.CapabilityStreaming))

func (*Device) MustOpen 

func (receiver *Device) MustOpen(name string)

MustOpen is like Open, except it panic()s if there is an error.

func (Device) MustVersion 

func (receiver Device) MustVersion() string

MustVersion is like Version, except it panic()s if there is an error.

Example: 

device := v4l2.MustOpen(v4l2.Video0)
defer device.MustClose()

fmt.Printf("Version: %q \n", device.MustVersion())

func (*Device) Open 

func (receiver *Device) Open(name string) error

Open opens a V4L2 device.

(This method exist so as not to create GC pressure.)

Example: 

var device Device

err := device.Open(v4l2.Video0)
if nil != err {
	return err
})
defer device.Close()

func (*Device) SetFormat 

func (receiver *Device) SetFormat(formatcaster v4l2_format.Caster) error

func (Device) Version 

func (receiver Device) Version() (string, error)

Version returns the version number of the driver.

Example values that Version might return are:

• "4.4.98"

• "4.14.0"

type FormatFamilies 

type FormatFamilies struct {
	// contains filtered or unexported fields
}

FormatFamilies is an interator that enables you to list out all the supported formats by the device.

func (*FormatFamilies) Close 

func (receiver *FormatFamilies) Close() error

Close closes the FormatFamilies iterator.

func (FormatFamilies) Decode 

func (receiver FormatFamilies) Decode(x interface{}) error

Decode loads the next format (previously obtained by calling Next).

func (*FormatFamilies) Err 

func (receiver *FormatFamilies) Err() error

Err returns any errors that occurred when Next was called.

func (*FormatFamilies) Next 

func (receiver *FormatFamilies) Next() bool

Next fetches the next format.

If there is a next format, it returns true. And the next format get be obtained by calling Decode.

If there is not next format, then it returns false.

type FormatFamily 

type FormatFamily struct {
	// contains filtered or unexported fields
}

FormatFamily is a format family.

A format family contains:

• a human-readable description,

• a pixel format (as a FOURCC code), and

• flags.

As well as logicall "containing" a list of frame sizes.

The possible flags are given by the constants:

• v4l2.FormatFamilyFlagCompressed, and

• v4l2.FormatFamilyFlagEmulated.

Samples:

An example format migh have have values such as:

• description: "YUYV 4:2:2"

• pixel format: "YUYV"

• (flag) compressed: false

• (flag) emulated: false

Or an example format migh have have values such as:

• description: "Motion-JPEG"

• pixel format: "MJPG"

• (flag) compressed: true

• (flag) emulated: false

Etc.

Usually, one would get a series of formats by iterating through all the supported formats that are supported by a device.

Example: 

var device v4l2.Device

// ...

formats, err := device.Formats()
if nil != err {
	return err
}
defer formats.Close()

var formatFamily v4l2.FormatFamily // <---- NOTE THAT THIS IS THE v4l2.FormatFamily TYPE.
forformats.Next() {

	err := formats.Decode(&formatFamily) // <---- NOTE THAT WE ARE PUTTING A NEW VALUE INTO THE v4l2.FormatFamily HERE.
	if nil != err {
		fmt.Fprintf(os.Stderr, "ERROR: Problem decoding format family: (%T) %v \n", err, err)
		return err
	}

	fmt.Printf("[format family] %q (%q) {compressed=%t} {emulated=%t} \n",
		formatFamily.Description(),
		formatFamily.PixelFormat(),
		formatFamily.HasFlags(v4l2.FormatFamilyFlagCompressed),
		formatFamily.HasFlags(v4l2.FormatFamilyFlagEmulated),
	)
}
if err := formats.Err(); nil != err {
	return err
}

v4l2.FormatFamily is the same as the V4L2 (Video4Linux version 2) type v4l2_fmtdesc.

func (FormatFamily) Description 

func (receiver FormatFamily) Description() string

Description returns a human-readable description for the format family.

Some examples of what might be returned by Description are;

• "YUYV 4:2:2",

• "Motion-JPEG",

• etc.

func (*FormatFamily) FrameSizes 

func (receiver *FormatFamily) FrameSizes() (FrameSizes, error)

FrameSizes returns an iterator that enables you to list out all the supported frame sizes by the format family.

func (FormatFamily) HasFlags 

func (receiver FormatFamily) HasFlags(flags uint32) bool

HasFlags returns true if the format family has all the flags inquired about, and returns false otherwise.

Example: 

var formatFamily v4l2.FormatFamily

// ...

if formatFamily.HasFlags(v4l2.FormatFamilyFlagCompressed) {
	//@TODO
}

Example: 

var formatFamily v4l2.FormatFamily

// ...

if formatFamily.HasFlags(v4l2.FormatFamilyFlagEmulated) {
	//@TODO
}

Example: 

var formatFamily v4l2.FormatFamily

// ...

if formatFamily.HasFlags(v4l2.FormatFamilyFlagCompressed | v4l2.FormatFamilyFlagEmulated) {
	//@TODO
}

func (FormatFamily) PixelFormat 

func (receiver FormatFamily) PixelFormat() v4l2_pixelformat.Type

PixelFormat returns the formal family's pixel format.

Some examples of what might be returned by PixelFormat are;

• v4l2_pixelformat.FourCC("YUYV"),

• v4l2_pixelformat.FourCC("MJPG"),

• etc,

type FrameSizes 

type FrameSizes struct {
	// contains filtered or unexported fields
}

FrameSizes is an interator that enables you to list out all the supported formats by the format family.

func (*FrameSizes) Close 

func (receiver *FrameSizes) Close() error

Close closes the FrameSizes iterator.

func (FrameSizes) Decode 

func (receiver FrameSizes) Decode(x interface{}) error

Decode loads the next frame size (previously obtained by calling Next).

func (*FrameSizes) Err 

func (receiver *FrameSizes) Err() error

Err returns any errors that occurred when Next was called.

func (*FrameSizes) Next 

func (receiver *FrameSizes) Next() bool

Next fetches the next frame size.

If there is a next frame size, it returns true. And the next frame size get be obtained by calling Decode.

If there is not next frame size, then it returns false.

Source Files

View all Source files

Directories

Path Synopsis
Package v4l2_buftype provides a type used to represents a V4L2 (Video4Linux version 2) buffer type.
 Package v4l2_buftype provides a type used to represents a V4L2 (Video4Linux version 2) buffer type.
Package v4l2_format provides a type used to represents a V4L2 (Video4Linux version 2) format.
 Package v4l2_format provides a type used to represents a V4L2 (Video4Linux version 2) format.
Package v4l2_framesize provides a type used to represents a V4L2 (Video4Linux version 2) frame size.
 Package v4l2_framesize provides a type used to represents a V4L2 (Video4Linux version 2) frame size.
Package v4l2_pixelformat provides a type used to represents a V4L2 (Video4Linux version 2) pixel format.
 Package v4l2_pixelformat provides a type used to represents a V4L2 (Video4Linux version 2) pixel format.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.