1 // Copyright 2020 The Chromium OS Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 //! This module implements the interface that actual decoder devices need to 6 //! implement in order to provide video decoding capability to the guest. 7 8 use std::fs::File; 9 10 use crate::virtio::video::{ 11 error::{VideoError, VideoResult}, 12 format::{Format, Rect}, 13 }; 14 use base::RawDescriptor; 15 16 pub mod vda; 17 18 pub struct FramePlane { 19 pub offset: i32, 20 pub stride: i32, 21 } 22 23 /// Contains the device's state for one playback session, i.e. one stream. 24 pub trait DecoderSession { 25 /// Tell how many output buffers will be used for this session. This method 26 /// Must be called after a `ProvidePictureBuffers` event is emitted, and 27 /// before the first call to `use_output_buffers()`. set_output_buffer_count(&self, count: usize) -> VideoResult<()>28 fn set_output_buffer_count(&self, count: usize) -> VideoResult<()>; 29 30 /// Decode the compressed stream contained in [`offset`..`offset`+`bytes_used`] 31 /// of the shared memory in `descriptor`. `bitstream_id` is the identifier for that 32 /// part of the stream (most likely, a timestamp). 33 /// 34 /// The device takes ownership of `descriptor` and is responsible for closing it 35 /// once it is not used anymore. 36 /// 37 /// The device will emit a `NotifyEndOfBitstreamBuffer` event after the input 38 /// buffer has been entirely processed. 39 /// 40 /// The device will emit a `PictureReady` event with the `bitstream_id` field 41 /// set to the same value as the argument of the same name for each picture 42 /// produced from that input buffer. decode( &self, bitstream_id: i32, descriptor: RawDescriptor, offset: u32, bytes_used: u32, ) -> VideoResult<()>43 fn decode( 44 &self, 45 bitstream_id: i32, 46 descriptor: RawDescriptor, 47 offset: u32, 48 bytes_used: u32, 49 ) -> VideoResult<()>; 50 51 /// Flush the decoder device, i.e. finish processing of all queued decode 52 /// requests. 53 /// 54 /// The device will emit a `FlushCompleted` event once the flush is done. flush(&self) -> VideoResult<()>55 fn flush(&self) -> VideoResult<()>; 56 57 /// Reset the decoder device, i.e. cancel all pending decoding requests. 58 /// 59 /// The device will emit a `ResetCompleted` event once the reset is done. reset(&self) -> VideoResult<()>60 fn reset(&self) -> VideoResult<()>; 61 62 /// Returns the event pipe on which the availability of an event will be 63 /// signaled. event_pipe(&self) -> &File64 fn event_pipe(&self) -> &File; 65 66 /// Ask the device to use the memory buffer in `output_buffer` to store 67 /// decoded frames in pixel format `format`. `planes` describes how the 68 /// frame's planes should be laid out in the buffer, and `picture_buffer_id` 69 /// is the ID of the picture, that will be reproduced in `PictureReady` events 70 /// using this buffer. 71 /// 72 /// The device takes ownership of `output_buffer` and is responsible for 73 /// closing it once the buffer is not used anymore (either when the session 74 /// is closed, or a new set of buffers is provided for the session). 75 /// 76 /// The device will emit a `PictureReady` event with the `picture_buffer_id` 77 /// field set to the same value as the argument of the same name when a 78 /// frame has been decoded into that buffer. use_output_buffer( &self, picture_buffer_id: i32, format: Format, output_buffer: RawDescriptor, planes: &[FramePlane], modifier: u64, ) -> VideoResult<()>79 fn use_output_buffer( 80 &self, 81 picture_buffer_id: i32, 82 format: Format, 83 output_buffer: RawDescriptor, 84 planes: &[FramePlane], 85 modifier: u64, 86 ) -> VideoResult<()>; 87 88 /// Ask the device to reuse an output buffer previously passed to 89 /// `use_output_buffer` and that has previously been returned to the decoder 90 /// in a `PictureReady` event. 91 /// 92 /// The device will emit a `PictureReady` event with the `picture_buffer_id` 93 /// field set to the same value as the argument of the same name when a 94 /// frame has been decoded into that buffer. reuse_output_buffer(&self, picture_buffer_id: i32) -> VideoResult<()>95 fn reuse_output_buffer(&self, picture_buffer_id: i32) -> VideoResult<()>; 96 97 /// Blocking call to read a single event from the event pipe. read_event(&mut self) -> VideoResult<DecoderEvent>98 fn read_event(&mut self) -> VideoResult<DecoderEvent>; 99 } 100 101 pub trait DecoderBackend { 102 type Session: DecoderSession; 103 104 /// Create a new decoding session for the passed `profile`. new_session(&self, format: Format) -> VideoResult<Self::Session>105 fn new_session(&self, format: Format) -> VideoResult<Self::Session>; 106 } 107 108 #[derive(Debug)] 109 pub enum DecoderEvent { 110 /// Emitted when the device knows the buffer format it will need to decode 111 /// frames, and how many buffers it will need. The decoder is supposed to 112 /// provide buffers of the requested dimensions using `use_output_buffer`. 113 ProvidePictureBuffers { 114 min_num_buffers: u32, 115 width: i32, 116 height: i32, 117 visible_rect: Rect, 118 }, 119 /// Emitted when the decoder is done decoding a picture. `picture_buffer_id` 120 /// corresponds to the argument of the same name passed to `use_output_buffer()` 121 /// or `reuse_output_buffer()`. `bitstream_id` corresponds to the argument of 122 /// the same name passed to `decode()` and can be used to match decoded frames 123 /// to the input buffer they were produced from. 124 PictureReady { 125 picture_buffer_id: i32, 126 bitstream_id: i32, 127 visible_rect: Rect, 128 }, 129 /// Emitted when an input buffer passed to `decode()` is not used by the 130 /// device anymore and can be reused by the decoder. The parameter corresponds 131 /// to the `bitstream_id` argument passed to `decode()`. 132 NotifyEndOfBitstreamBuffer(i32), 133 /// Emitted when a decoding error has occured. 134 NotifyError(VideoError), 135 /// Emitted after `flush()` has been called to signal that the flush is completed. 136 FlushCompleted(VideoResult<()>), 137 /// Emitted after `reset()` has been called to signal that the reset is completed. 138 ResetCompleted(VideoResult<()>), 139 } 140