| // Copyright 2021 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| library fuchsia.media2; |
| |
| using fuchsia.mediastreams; |
| using fuchsia.sysmem; |
| using zx; |
| |
| alias BufferId = uint32; |
| |
| const MAX_BUFFERS uint32 = 64; |
| const MAX_VMO_NAME_LENGTH uint32 = 64; |
| const MAX_PARTICIPANT_NAME_LENGTH uint32 = 64; |
| |
| /// Provides buffers (VMOs) to groups of participants. |
| @discoverable |
| protocol BufferProvider { |
| /// Creates a new logical buffer collection identified by `provider_token`. The reply is sent |
| /// when all participant tokens have been submitted or the operation fails for some reason. |
| /// |
| /// + request `provider_token` the token used to identify the collection. Peers of this eventpair |
| /// are used by participants to identify the logical collection in `GetBuffers`. |
| /// + request `vmo_name` the name to be applied to VMOs. |
| /// - response `collection_info` a description of the resulting buffer collection. |
| /// * error reason for failure to create the collection. This method will never return |
| /// `BufferProviderError.TIMED_OUT_WAITING_FOR_CREATION`. |
| CreateBufferCollection(resource struct { |
| provider_token zx.handle:EVENTPAIR; |
| vmo_name string:MAX_VMO_NAME_LENGTH; |
| }) -> (struct { |
| collection_info BufferCollectionInfo; |
| }) error BufferProviderError; |
| |
| /// Gets buffers for the logical buffer collection identified by `participant_token`, which must |
| /// be a peer of the provider token used in a `CreateBufferCollection` call. This operation |
| /// completes when all copies of the participant token have been destroyed or passed in a |
| /// `GetBuffers` call. |
| /// |
| /// + request `participant_token` one of the peers of a provider token submitted via |
| /// `CreateBufferCollection`. |
| /// + request `constraints` constraints that must be satisfied in order for the collection |
| /// to be fit for the participant's purpose. |
| /// + request `rights` rights that are required with respect to buffers. |
| /// + request `name` the name of the participant for debugging purposes. The process name is |
| /// typically used here. |
| /// + request `id` the id of the participant for debugging purposes. The process id is typically |
| /// used here. |
| /// - response `buffers `the VMOs that make up the collection, meeting all constraints from all |
| /// participants. |
| /// * error reason for failiure to create the collection. |
| GetBuffers(resource struct { |
| participant_token zx.handle:EVENTPAIR; |
| constraints BufferConstraints; |
| rights BufferRights; |
| name string:MAX_PARTICIPANT_NAME_LENGTH; |
| id uint64; |
| }) -> (resource struct { |
| buffers vector<zx.handle:VMO>:MAX_BUFFERS; |
| }) error BufferProviderError; |
| |
| /// Binds a participant token to a sysmem `BufferCollectionToken` for the same buffer |
| /// collection. |
| /// |
| /// + request `participant_token` one of the peers of a provider token submitted via |
| /// `CreateBufferCollection`. |
| /// - response `sysmem_token_client_end` client end of a sysmem `BufferCollectionToken` channel. |
| /// |
| /// This method is useful for participants that need to constrain the buffer collection in |
| /// ways that are not expressible using `BufferConstraints`. When a participant uses this method |
| /// (as opposed to `GetBuffers`), the provider delegates the creation of the buffer collection |
| /// to sysmem. `GetBuffers` continues to work normally for participants that use it. |
| // TODO: Make this feed-forward when sysmem is fixed. |
| BindSysmemToken(resource struct { |
| participant_token zx.handle:EVENTPAIR; |
| }) -> (resource struct { |
| sysmem_token_client_end client_end:fuchsia.sysmem.BufferCollectionToken; |
| }); |
| }; |
| |
| type BufferCollectionInfo = table { |
| /// The size of the buffers in the collection. |
| 1: buffer_size uint32; |
| |
| /// The size of the collection. |
| 2: buffer_count uint32; |
| }; |
| |
| /// Describes constraints applied to a buffer collection by a participant via |
| /// `BufferProvider.GetBuffers`. |
| // TODO: More specific name? BufferConstraints? |
| type BufferConstraints = table { |
| /// Minimum buffer size. The participant requires that each buffer in the collection be at |
| /// least this size (in bytes). The size of the buffers in the buffer collection will be at |
| /// least the maximum of these values across all participants. If this value is not provided, |
| /// a default value of 0 is presumed. |
| 1: min_buffer_size uint32; |
| |
| /// Buffer count. The participant may, at any given time, maintain possession of this many |
| /// buffers. The number of buffers in the buffer collection will be at least the sum of these |
| /// values across all participants. If this value is not provided, a default value of 0 is |
| /// presumed. |
| 2: buffer_count uint32; |
| |
| /// Minimum aggregate buffer size. The participant requires that the sum (in bytes) of the sizes |
| /// of all the buffers in the collection be at least this large. The sum of the sizes of all the |
| /// buffers in the buffer collection will be at least the sum of these values across all |
| /// participants. If this value is not provided, a default value of 0 is presumed. |
| 3: min_aggregate_buffer_size uint64; |
| |
| /// Video format of payloads. This value should be provided by producers of video streams in |
| /// the likely event that the consumer will want to use sysmem to allocate buffers. Consumers |
| /// that can accept a range of formats must use `BufferProvider.BindSysmemToken` rather than |
| /// `BufferProvider.GetBuffers`. |
| 4: video_format fuchsia.mediastreams.VideoFormat; |
| }; |
| |
| /// Indicates what rights are required with respect to buffers. |
| type BufferRights = strict bits { |
| /// Read right is required (for reading or mapping for read). |
| READ = 0x01; |
| |
| /// Write right is required (for writing or mapping for write). |
| WRITE = 0x02; |
| }; |
| |
| /// Errors that may be returned by `BufferProvider.CreateBufferCollection` or |
| /// `BufferProvider.GetBuffers`. |
| type BufferProviderError = strict enum { |
| /// Participants have submitted constraints that cannot be collectively satisfied. |
| OVERCONSTRAINED = 1; |
| |
| /// Participants have submitted constraints that don't collectively provide enough information |
| /// to create a buffer collection. |
| UNDERCONSTRAINED = 2; |
| |
| /// Insufficient free memory of the required type was available. |
| INSUFFICIENT_MEMORY = 3; |
| |
| /// All provider tokens were destroyed without `GetBuffers` being called. |
| NO_PARTICIPANTS = 4; |
| |
| /// Timed out waiting for a `CreateBufferCollection` call with a matching provider token. |
| TIMED_OUT_WAITING_FOR_CREATION = 5; |
| |
| /// Timed out waiting for one or more participants in the logical connection to call |
| /// `GetBuffers` with a matching participant token. |
| TIMED_OUT_WAITING_FOR_PARTICPANT = 6; |
| |
| /// Attempt to allocate from sysmem yielded `ZX_ERR_ACCESS_DENIED`, indicating the client is |
| /// not permitted to obtain the buffers it requested. |
| ACCESS_DENIED = 7; |
| |
| /// Attempt to allocate from sysmem yielded `ZX_ERR_INVALID_ARGS`, indicating the request was |
| /// malformed. |
| MALFORMED_REQUEST = 8; |
| |
| /// Attempt to allocate from sysmem yielded `ZX_ERR_NOT_SUPPORTED`, indicating the request was |
| /// valid but could not be satisfied. |
| NOT_SUPPORTED = 9; |
| }; |