pub struct Camera { /* private fields */ }
Expand description
The main Camera
struct. This is the struct that abstracts over all the backends, providing a simplified interface for use.
Implementations§
source§impl Camera
impl Camera
sourcepub fn new(
index: CameraIndex,
format: RequestedFormat<'_>
) -> Result<Self, NokhwaError>
pub fn new( index: CameraIndex, format: RequestedFormat<'_> ) -> Result<Self, NokhwaError>
Create a new camera from an index
and format
Errors
This will error if you either have a bad platform configuration (e.g. input-v4l
but not on linux) or the backend cannot create the camera (e.g. permission denied).
sourcepub fn with_backend(
index: CameraIndex,
format: RequestedFormat<'_>,
backend: ApiBackend
) -> Result<Self, NokhwaError>
pub fn with_backend( index: CameraIndex, format: RequestedFormat<'_>, backend: ApiBackend ) -> Result<Self, NokhwaError>
Create a new camera from an index
, format
, and backend
. format
can be None
.
Errors
This will error if you either have a bad platform configuration (e.g. input-v4l
but not on linux) or the backend cannot create the camera (e.g. permission denied).
sourcepub fn new_with(
index: CameraIndex,
width: u32,
height: u32,
fps: u32,
fourcc: FrameFormat,
backend: ApiBackend
) -> Result<Self, NokhwaError>
👎Deprecated since 0.10.0: please use new
instead.
pub fn new_with( index: CameraIndex, width: u32, height: u32, fps: u32, fourcc: FrameFormat, backend: ApiBackend ) -> Result<Self, NokhwaError>
new
instead.Create a new Camera
from raw values.
Errors
This will error if you either have a bad platform configuration (e.g. input-v4l
but not on linux) or the backend cannot create the camera (e.g. permission denied).
sourcepub fn with_custom(
idx: CameraIndex,
api: ApiBackend,
device: Box<dyn CaptureBackendTrait>
) -> Self
pub fn with_custom( idx: CameraIndex, api: ApiBackend, device: Box<dyn CaptureBackendTrait> ) -> Self
Allows creation of a Camera
with a custom backend. This is useful if you are creating e.g. a custom module.
You must have set a format beforehand.
sourcepub fn index(&self) -> &CameraIndex
pub fn index(&self) -> &CameraIndex
Gets the current Camera’s index.
sourcepub fn set_index(&mut self, new_idx: &CameraIndex) -> Result<(), NokhwaError>
pub fn set_index(&mut self, new_idx: &CameraIndex) -> Result<(), NokhwaError>
Sets the current Camera’s index. Note that this re-initializes the camera.
Errors
The Backend may fail to initialize.
sourcepub fn backend(&self) -> ApiBackend
pub fn backend(&self) -> ApiBackend
Gets the current Camera’s backend
sourcepub fn set_backend(
&mut self,
new_backend: ApiBackend
) -> Result<(), NokhwaError>
pub fn set_backend( &mut self, new_backend: ApiBackend ) -> Result<(), NokhwaError>
Sets the current Camera’s backend. Note that this re-initializes the camera.
Errors
The new backend may not exist or may fail to initialize the new camera.
sourcepub fn info(&self) -> &CameraInfo
pub fn info(&self) -> &CameraInfo
Gets the camera information such as Name and Index as a CameraInfo
.
sourcepub fn camera_format(&self) -> CameraFormat
pub fn camera_format(&self) -> CameraFormat
Gets the current CameraFormat
.
sourcepub fn refresh_camera_format(&mut self) -> Result<CameraFormat, NokhwaError>
pub fn refresh_camera_format(&mut self) -> Result<CameraFormat, NokhwaError>
Forcefully refreshes the stored camera format, bringing it into sync with “reality” (current camera state)
Errors
If the camera can not get its most recent CameraFormat
. this will error.
sourcepub fn set_camera_requset(
&mut self,
request: RequestedFormat<'_>
) -> Result<CameraFormat, NokhwaError>
pub fn set_camera_requset( &mut self, request: RequestedFormat<'_> ) -> Result<CameraFormat, NokhwaError>
Will set the current CameraFormat
, using a [RequestedFormat.
]
This will reset the current stream if used while stream is opened.
This will also update the cache.
This will return the new CameraFormat
Errors
If nothing fits the requested criteria, this will return an error.
sourcepub fn set_camera_format(
&mut self,
new_fmt: CameraFormat
) -> Result<(), NokhwaError>
👎Deprecated since 0.10.0: please use set_camera_requset
instead.
pub fn set_camera_format( &mut self, new_fmt: CameraFormat ) -> Result<(), NokhwaError>
set_camera_requset
instead.Will set the current CameraFormat
This will reset the current stream if used while stream is opened.
This will also update the cache.
Errors
If you started the stream and the camera rejects the new camera format, this will return an error.
sourcepub fn compatible_list_by_resolution(
&mut self,
fourcc: FrameFormat
) -> Result<HashMap<Resolution, Vec<u32>>, NokhwaError>
pub fn compatible_list_by_resolution( &mut self, fourcc: FrameFormat ) -> Result<HashMap<Resolution, Vec<u32>>, NokhwaError>
A hashmap of Resolution
s mapped to framerates
Errors
This will error if the camera is not queryable or a query operation has failed. Some backends will error this out as a UnsupportedOperationError
.
sourcepub fn compatible_fourcc(&mut self) -> Result<Vec<FrameFormat>, NokhwaError>
pub fn compatible_fourcc(&mut self) -> Result<Vec<FrameFormat>, NokhwaError>
A Vector of compatible FrameFormat
s.
Errors
This will error if the camera is not queryable or a query operation has failed. Some backends will error this out as a UnsupportedOperationError
.
sourcepub fn compatible_camera_formats(
&mut self
) -> Result<Vec<CameraFormat>, NokhwaError>
pub fn compatible_camera_formats( &mut self ) -> Result<Vec<CameraFormat>, NokhwaError>
A Vector of available CameraFormat
s.
Errors
This will error if the camera is not queryable or a query operation has failed. Some backends will error this out as a UnsupportedOperationError
.
sourcepub fn resolution(&self) -> Resolution
pub fn resolution(&self) -> Resolution
Gets the current camera resolution (See: Resolution
, CameraFormat
). This will force refresh to the current latest if it has changed.
sourcepub fn set_resolution(&mut self, new_res: Resolution) -> Result<(), NokhwaError>
pub fn set_resolution(&mut self, new_res: Resolution) -> Result<(), NokhwaError>
Will set the current Resolution
This will reset the current stream if used while stream is opened.
This will also update the cache.
Errors
If you started the stream and the camera rejects the new resolution, this will return an error.
sourcepub fn frame_rate(&self) -> u32
pub fn frame_rate(&self) -> u32
Gets the current camera framerate (See: CameraFormat
).
sourcepub fn set_frame_rate(&mut self, new_fps: u32) -> Result<(), NokhwaError>
pub fn set_frame_rate(&mut self, new_fps: u32) -> Result<(), NokhwaError>
Will set the current framerate This will reset the current stream if used while stream is opened.
This will also update the cache.
Errors
If you started the stream and the camera rejects the new framerate, this will return an error.
sourcepub fn frame_format(&self) -> FrameFormat
pub fn frame_format(&self) -> FrameFormat
Gets the current camera’s frame format (See: FrameFormat
, CameraFormat
). This will force refresh to the current latest if it has changed.
sourcepub fn set_frame_format(
&mut self,
fourcc: FrameFormat
) -> Result<(), NokhwaError>
pub fn set_frame_format( &mut self, fourcc: FrameFormat ) -> Result<(), NokhwaError>
Will set the current FrameFormat
This will reset the current stream if used while stream is opened.
This will also update the cache.
Errors
If you started the stream and the camera rejects the new frame format, this will return an error.
sourcepub fn supported_camera_controls(
&self
) -> Result<Vec<KnownCameraControl>, NokhwaError>
pub fn supported_camera_controls( &self ) -> Result<Vec<KnownCameraControl>, NokhwaError>
Gets the current supported list of KnownCameraControl
Errors
If the list cannot be collected, this will error. This can be treated as a “nothing supported”.
sourcepub fn camera_controls(&self) -> Result<Vec<CameraControl>, NokhwaError>
pub fn camera_controls(&self) -> Result<Vec<CameraControl>, NokhwaError>
Gets the current supported list of CameraControl
s keyed by its name as a String
.
Errors
If the list cannot be collected, this will error. This can be treated as a “nothing supported”.
sourcepub fn camera_controls_string(
&self
) -> Result<HashMap<String, CameraControl>, NokhwaError>
pub fn camera_controls_string( &self ) -> Result<HashMap<String, CameraControl>, NokhwaError>
Gets the current supported list of CameraControl
s keyed by its name as a String
.
Errors
If the list cannot be collected, this will error. This can be treated as a “nothing supported”.
sourcepub fn camera_controls_known_camera_controls(
&self
) -> Result<HashMap<KnownCameraControl, CameraControl>, NokhwaError>
pub fn camera_controls_known_camera_controls( &self ) -> Result<HashMap<KnownCameraControl, CameraControl>, NokhwaError>
Gets the current supported list of CameraControl
s keyed by its name as a String
.
Errors
If the list cannot be collected, this will error. This can be treated as a “nothing supported”.
sourcepub fn camera_control(
&self,
control: KnownCameraControl
) -> Result<CameraControl, NokhwaError>
pub fn camera_control( &self, control: KnownCameraControl ) -> Result<CameraControl, NokhwaError>
Gets the value of KnownCameraControl
.
Errors
If the control
is not supported or there is an error while getting the camera control values (e.g. unexpected value, too high, etc)
this will error.
sourcepub fn set_camera_control(
&mut self,
id: KnownCameraControl,
value: ControlValueSetter
) -> Result<(), NokhwaError>
pub fn set_camera_control( &mut self, id: KnownCameraControl, value: ControlValueSetter ) -> Result<(), NokhwaError>
Sets the control to control
in the camera.
Usually, the pipeline is calling camera_control()
, getting a camera control that way
then calling value()
to get a ControlValueSetter
and setting the value that way.
Errors
If the control
is not supported, the value is invalid (less than min, greater than max, not in step), or there was an error setting the control,
this will error.
sourcepub fn open_stream(&mut self) -> Result<(), NokhwaError>
pub fn open_stream(&mut self) -> Result<(), NokhwaError>
Will open the camera stream with set parameters. This will be called internally if you try and call frame()
before you call open_stream()
.
Errors
If the specific backend fails to open the camera (e.g. already taken, busy, doesn’t exist anymore) this will error.
sourcepub fn is_stream_open(&self) -> bool
pub fn is_stream_open(&self) -> bool
Checks if stream if open. If it is, it will return true.
sourcepub fn frame(&mut self) -> Result<Buffer, NokhwaError>
pub fn frame(&mut self) -> Result<Buffer, NokhwaError>
Will get a frame from the camera as a Raw RGB image buffer. Depending on the backend, if you have not called open_stream()
before you called this,
it will either return an error.
Errors
If the backend fails to get the frame (e.g. already taken, busy, doesn’t exist anymore), the decoding fails (e.g. MJPEG -> u8), or open_stream()
has not been called yet,
this will error.
sourcepub fn frame_raw(&mut self) -> Result<Cow<'_, [u8]>, NokhwaError>
pub fn frame_raw(&mut self) -> Result<Cow<'_, [u8]>, NokhwaError>
Will get a frame from the camera without any processing applied, meaning you will usually get a frame you need to decode yourself.
Errors
If the backend fails to get the frame (e.g. already taken, busy, doesn’t exist anymore), or open_stream()
has not been called yet, this will error.
sourcepub fn write_frame_to_buffer<F: FormatDecoder>(
&mut self,
buffer: &mut [u8]
) -> Result<(), NokhwaError>
pub fn write_frame_to_buffer<F: FormatDecoder>( &mut self, buffer: &mut [u8] ) -> Result<(), NokhwaError>
Directly writes the current frame into said buffer
.
Errors
If the backend fails to get the frame (e.g. already taken, busy, doesn’t exist anymore), or open_stream()
has not been called yet, this will error.
sourcepub fn frame_texture<'a, F: FormatDecoder>(
&mut self,
device: &WgpuDevice,
queue: &WgpuQueue,
label: Option<&'a str>
) -> Result<WgpuTexture, NokhwaError>
Available on crate feature output-wgpu
only.
pub fn frame_texture<'a, F: FormatDecoder>( &mut self, device: &WgpuDevice, queue: &WgpuQueue, label: Option<&'a str> ) -> Result<WgpuTexture, NokhwaError>
output-wgpu
only.Directly copies a frame to a Wgpu texture. This will automatically convert the frame into a RGBA frame.
Errors
If the frame cannot be captured or the resolution is 0 on any axis, this will error.