1 // Copyright 2022 The ChromiumOS Authors
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
8 use crate::picture::Picture;
9 use crate::picture::PictureSync;
10 use crate::status::Status;
12 /// Wrapper around `VAImage` that is tied to the lifetime of a given `Picture`.
14 /// An image is used to either get the surface data to client memory, or to copy image data in
15 /// client memory to a surface.
16 pub struct Image<'a> {
17 /// The picture whose `Surface` we use as the source of pixel data.
18 picture: &'a Picture<PictureSync>,
19 /// The `VAImage` returned by libva.
20 image: bindings::VAImage,
21 /// The mapped surface data.
23 /// Whether the image was derived using the `vaDeriveImage` API or created using the
24 /// `vaCreateImage` API.
26 /// Tracks whether the underlying data has possibly been written to, i.e. an encoder will create
27 /// an image and map its buffer in order to write to it, so we must writeback later.
32 /// Creates a new `Image` either by calling `vaCreateImage` or
33 /// `vaDeriveImage`. Creating an Image depends on acquiring a ready Surface
34 /// from an underlying Picture. Note that Image has a borrowed Picture, so
35 /// it will be dropped before the underlying Surface is dropped, as mandated
40 /// * `picture` - The [`Picture`] that owns the Surface this image will be created from.
41 /// * `format` - A `VAImageFormat` returned by [`crate::Display::query_image_formats`].
42 /// * `width` - The image's desired width.
43 /// * `height` - The image's desired height.
44 /// * `derive` - Whether to try deriving the image from `picture`, which allows zero-copy access
45 /// to the surface data. Deriving may fail, in which case vaCreateImage will be used instead,
46 /// incurring an extra data copy.
48 picture: &'a Picture<PictureSync>,
49 mut format: bindings::VAImageFormat,
54 // An all-zero byte-pattern is a valid initial value for `VAImage`.
55 let mut image: bindings::VAImage = Default::default();
56 let mut addr = std::ptr::null_mut();
57 let mut derived = false;
60 derived = Image::derive_image(picture, &mut image)?;
64 Image::create_image(picture, &mut image, &mut format, width, height)?;
67 // Safe since `picture.inner.context` represents a valid `VAContext` and `image` has been
68 // successfully created at this point.
70 bindings::vaMapBuffer(picture.display().handle(), image.buf, &mut addr)
75 // Safe since `addr` points to data mapped onto our address space since we called
76 // `vaMapBuffer` above, which also guarantees that the data is valid for
79 unsafe { std::slice::from_raw_parts_mut(addr as _, image.data_size as usize) };
89 // Safe because `picture.inner.context` represents a valid `VAContext` and `image`
90 // represents a valid `VAImage`.
92 bindings::vaDestroyImage(picture.display().handle(), image.image_id);
99 /// Creates `image` from `picture` using `vaCreateImage` and `vaGetImage` in order to copy the
100 /// surface data into the image buffer.
102 picture: &'a Picture<PictureSync>,
103 image: &mut bindings::VAImage,
104 format: &mut bindings::VAImageFormat,
108 let dpy = picture.display().handle();
110 // Safe because `picture.inner.context` represents a valid
112 Status(unsafe { bindings::vaCreateImage(dpy, format, width as i32, height as i32, image) })
115 // Safe because `picture.inner.context` represents a valid VAContext,
116 // `picture.surface` represents a valid VASurface and `image` represents
117 // a valid `VAImage`.
118 if let Err(e) = Status(unsafe {
119 bindings::vaGetImage(
121 picture.surface().id(),
131 // Safe since `image` represents a valid `VAImage`.
133 bindings::vaDestroyImage(dpy, image.image_id);
141 /// Tries to derive `image` from `picture` to access the raw surface data without copy.
143 /// Returns `Ok(true)` if the image has been successfully derived, `Ok(false)` if deriving is
144 /// not possible and `create_image` should be used as a fallback, or an error if an error
147 picture: &'a Picture<PictureSync>,
148 image: &mut bindings::VAImage,
150 let status = Status(unsafe {
151 bindings::vaDeriveImage(picture.display().handle(), picture.surface().id(), image)
154 if status.0 == bindings::constants::VA_STATUS_ERROR_OPERATION_FAILED as i32 {
155 // The implementation can't derive, try the create API instead.
163 /// Get a reference to the underlying `VAImage` that describes this image.
164 pub fn image(&self) -> &bindings::VAImage {
169 impl<'a> AsRef<[u8]> for Image<'a> {
170 fn as_ref(&self) -> &[u8] {
175 impl<'a> AsMut<[u8]> for Image<'a> {
176 fn as_mut(&mut self) -> &mut [u8] {
182 impl<'a> Drop for Image<'a> {
184 if !self.derived && self.dirty {
185 // Safe because `picture.inner.context` represents a valid `VAContext`,
186 // `picture.surface` represents a valid `VASurface` and `image` represents a valid
189 bindings::vaPutImage(
190 self.picture.display().handle(),
191 self.picture.surface().id(),
195 self.image.width as u32,
196 self.image.height as u32,
199 self.image.width as u32,
200 self.image.height as u32,
205 // Safe since the buffer is mapped in `Image::new`, so `self.image.buf` points to a
206 // valid `VABufferID`.
207 bindings::vaUnmapBuffer(self.picture.display().handle(), self.image.buf);
208 // Safe since `self.image` represents a valid `VAImage`.
209 bindings::vaDestroyImage(self.picture.display().handle(), self.image.image_id);