1 /* 2 * Copyright (C) 2018 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package hardware.google.media.c2@1.0; 18 19 import android.hardware.graphics.bufferqueue@1.0::IGraphicBufferProducer; 20 import android.hardware.media.omx@1.0::IGraphicBufferSource; 21 22 import IConfigurable; 23 import IComponentInterface; 24 import IComponentListener; 25 26 /** 27 * Interface for a Codec 2.0 component corresponding to API level 1.0 or 28 * below. Components have two states: stopped and running. The running 29 * state has three sub-states: executing, tripped and error. 30 */ 31 interface IComponent extends IComponentInterface { 32 33 // METHODS AVAILABLE WHEN RUNNING 34 // ========================================================================= 35 36 /** 37 * Queues up work for the component. 38 * 39 * This method must be supported in running (including tripped) states. 40 * 41 * This method must return within 1ms 42 * 43 * It is acceptable for this method to return OK and return an error value 44 * using the onWorkDone() callback. 45 * 46 * @param workBundle WorkBundle object containing Works to queue to the 47 * component. 48 * @return status Status of the call, which may be 49 * - OK - Works in \p workBundle were successfully queued. 50 * - BAD_INDEX - Some component(s) in some Work do(es) not exist. 51 * - CANNOT_DO - The components are not tunneled. 52 * - NO_MEMORY - Not enough memory to queue \p workBundle. 53 * - CORRUPTED - Some unknown error prevented queuing the Works. 54 * (unexpected). 55 */ 56 queue(WorkBundle workBundle) generates (Status status); 57 58 /** 59 * Discards and abandons any pending work for the component. 60 * 61 * This method must be supported in running (including tripped) states. 62 * 63 * This method must return within 5ms. 64 * 65 * Work that could be immediately abandoned/discarded must be returned in 66 * \p flushedWorks; this can be done in an arbitrary order. 67 * 68 * Work that could not be abandoned or discarded immediately must be marked 69 * to be discarded at the earliest opportunity, and must be returned via 70 * the onWorkDone() callback. This must be completed within 500ms. 71 * 72 * @return status Status of the call, which may be 73 * - OK - The component has been successfully flushed. 74 * - TIMED_OUT - The flush could not be completed within the time limit. 75 * (unexpected) 76 * - CORRUPTED - Some unknown error prevented flushing from 77 * completion. (unexpected) 78 * @return flushedWorkBundle WorkBundle object containing flushed Works. 79 */ 80 flush( 81 ) generates ( 82 Status status, 83 WorkBundle flushedWorkBundle 84 ); 85 86 /** 87 * Drains the component, and optionally downstream components. This is a 88 * signalling method; as such it does not wait for any work completion. 89 * 90 * Marks last work item as "drain-till-here", so component is notified not 91 * to wait for further work before it processes work already queued. This 92 * method can also be used to set the end-of-stream flag after work has been 93 * queued. Client can continue to queue further work immediately after this 94 * method returns. 95 * 96 * This method must be supported in running (including tripped) states. 97 * 98 * This method must return within 1ms. 99 * 100 * Work that is completed must be returned via the onWorkDone() callback. 101 * 102 * @param withEos Whether to drain the component with marking end-of-stream. 103 * @return status Status of the call, which may be 104 * - OK - The drain request has been successfully recorded. 105 * - TIMED_OUT - The flush could not be completed within the time limit. 106 * (unexpected) 107 * - CORRUPTED - Some unknown error prevented flushing from completion. 108 * (unexpected) 109 */ 110 drain(bool withEos) generates (Status status); 111 112 /** 113 * Starts using a surface for output. 114 * 115 * @param blockPoolId The id of the BlockPool to be associated with the 116 * output surface. 117 * @param surface A surface to use for codec output. 118 * @return status Status of the call, which may be 119 * - OK - The operation completed successfully. 120 * - CANNOT_DO - The component does not support an output surface. 121 * - REFUSED - The output surface cannot be accessed. 122 * - TIMED_OUT - The component could not be connected within the time 123 * limit. (unexpected) 124 * - CORRUPTED - Some unknown error prevented connecting the component. 125 * (unexpected) 126 */ 127 setOutputSurface( 128 uint64_t blockPoolId, 129 IGraphicBufferProducer surface 130 ) generates ( 131 Status status 132 ); 133 134 /** 135 * Starts using a persistent OMX input surface for a component. 136 * 137 * The component must be in running state. 138 * 139 * @param producer Producer component of an OMX persistent input surface. 140 * @param source Source component of an OMX persistent input surface. 141 * @return status Status of the call, which may be 142 * - OK - The operation completed successfully. 143 * - CANNOT_DO - The component does not support an input surface. 144 * - BAD_STATE - Component is not in running state. 145 * - DUPLICATE - The component is already connected to an input surface. 146 * - REFUSED - The input surface is already in use. 147 * - NO_MEMORY - Not enough memory to start the component. 148 * - TIMED_OUT - The component could not be connected within the time 149 * limit. (unexpected) 150 * - CORRUPTED - Some unknown error prevented connecting the component. 151 * (unexpected) 152 */ 153 connectToOmxInputSurface( 154 IGraphicBufferProducer producer, 155 IGraphicBufferSource source 156 ) generates (Status status); 157 158 /** 159 * Stops using an input surface. 160 * 161 * This call is used for both Codec 2.0 and OMX input surfaces. 162 * 163 * The component must be in running state. 164 * 165 * @return status Status of the call, which may be 166 * - OK - The operation completed successfully. 167 * - CANNOT_DO - The component does not support an input surface. 168 * - BAD_STATE - Component is not in running state. 169 * - NOT_FOUND - The component is not connected to an input surface. 170 * - TIMED_OUT - The component could not be connected within the time 171 * limit. (unexpected) 172 * - CORRUPTED - Some unknown error prevented connecting the component. 173 * (unexpected) 174 */ 175 disconnectFromInputSurface() generates (Status Status); 176 177 /** 178 * Creates a local block pool backed by the given allocator and returns its 179 * identifier. 180 * 181 * This call must return within 100 msec. 182 * 183 * @param allocatorId The Codec 2.0 allocator ID 184 * @return status Status of the call, which may be 185 * - OK - The operation completed successfully. 186 * - NO_MEMORY - Not enough memory to create the pool. 187 * - BAD_VALUE - Invalid allocator. 188 * - TIMED_OUT - The pool could not be created within the time 189 * limit. (unexpected) 190 * - CORRUPTED - Some unknown error prevented creating the pool. 191 * (unexpected) 192 * @return blockPoolId The Codec 2.0 blockpool ID for the created pool. 193 * @return configurable Configuration interface for the created pool. 194 */ 195 createBlockPool(uint32_t allocatorId) generates ( 196 Status status, 197 uint64_t blockPoolId, 198 IConfigurable configurable 199 ); 200 201 /** 202 * Destroys a local block pool previously created by createBlockPool(). 203 * 204 * This call must return within 100 msec. 205 * 206 * @param blockPoolId The block pool id previously returned by 207 * createBlockPool(). 208 * @return status Status of the call, which may be 209 * - OK - The operation completed successfully. 210 * - NOT_FOUND - The supplied blockPoolId is not valid. 211 * - TIMED_OUT - The pool could not be destroyedwithin the time limit. 212 * (unexpected) 213 * - CORRUPTED - Some unknown error prevented destruction of the pool. 214 * (unexpected) 215 */ 216 destroyBlockPool(uint64_t blockPoolId) generates (Status status); 217 218 // STATE CHANGE METHODS 219 // ========================================================================= 220 221 /** 222 * Starts the component. 223 * 224 * This method must be supported in stopped state as well as tripped state. 225 * 226 * If the return value is OK, the component must be in the running state. 227 * If the return value is BAD_STATE or DUPLICATE, no state change is 228 * expected as a response to this call. 229 * Otherwise, the component must be in the stopped state. 230 * 231 * If a component is in the tripped state and start() is called while the 232 * component configuration still results in a trip, start must succeed and 233 * a new onTripped callback must be used to communicate the configuration 234 * conflict that results in the new trip. 235 * 236 * This method must return within 500ms. 237 * 238 * @return status Status of the call, which may be 239 * - OK - The component has started successfully. 240 * - BAD_STATE - Component is not in stopped or tripped state. 241 * - DUPLICATE - When called during another start call from another 242 * thread. 243 * - NO_MEMORY - Not enough memory to start the component. 244 * - TIMED_OUT - The component could not be started within the time limit. 245 * (unexpected) 246 * - CORRUPTED - Some unknown error prevented starting the component. 247 * (unexpected) 248 */ 249 start() generates (Status status); 250 251 /** 252 * Stops the component. 253 * 254 * This method must be supported in running (including tripped) state. 255 * 256 * This method must return withing 500ms. 257 * 258 * Upon this call, all pending work must be abandoned. 259 * If the return value is BAD_STATE or DUPLICATE, no state change is 260 * expected as a response to this call. 261 * For all other return values, the component must be in the stopped state. 262 * 263 * This does not alter any settings and tunings that may have resulted in a 264 * tripped state. 265 * 266 * @return status Status of the call, which may be 267 * - OK - The component has stopped successfully. 268 * - BAD_STATE - Component is not in running state. 269 * - DUPLICATE - When called during another stop call from another thread. 270 * - TIMED_OUT - The component could not be stopped within the time limit. 271 * (unexpected) 272 * - CORRUPTED - Some unknown error prevented starting the component. 273 * (unexpected) 274 */ 275 stop() generates (Status status); 276 277 /** 278 * Resets the component. 279 * 280 * This method must be supported in all (including tripped) states other 281 * than released. 282 * 283 * This method must be supported during any other blocking call. 284 * 285 * This method must return withing 500ms. 286 * 287 * After this call returns all work must have been abandoned, all references 288 * must have been released. 289 * 290 * If the return value is BAD_STATE or DUPLICATE, no state change is 291 * expected as a response to this call. 292 * For all other return values, the component shall be in the stopped state. 293 * 294 * This brings settings back to their default - "guaranteeing" no tripped 295 * state. 296 * 297 * @return status Status of the call, which may be 298 * - OK - The component has been reset. 299 * - BAD_STATE - Component is in released state. 300 * - DUPLICATE - When called during another reset call from another 301 * thread. 302 * - TIMED_OUT - The component could not be reset within the time limit. 303 * (unexpected) 304 * - CORRUPTED - Some unknown error prevented resetting the component. 305 * (unexpected) 306 */ 307 reset() generates (Status status); 308 309 /** 310 * Releases the component. 311 * 312 * This method must be supported in stopped state. 313 * 314 * This method must return withing 500ms. Upon return all references must 315 * be abandoned. 316 * 317 * @return status Status of the call, which may be 318 * - OK - The component has been released. 319 * - BAD_STATE - The component is running. 320 * - DUPLICATE - The component is already released. 321 * - TIMED_OUT - The component could not be released within the time 322 * limit. (unexpected) 323 * - CORRUPTED - Some unknown error prevented releasing the component. 324 * (unexpected) 325 */ 326 release() generates (Status status); 327 328 }; 329 330
