/*
* Copyright (C) 2016 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.graphics.mapper@2.0;
import android.hardware.graphics.common@1.0;
interface IMapper {
struct BufferDescriptorInfo {
/**
* The width specifies how many columns of pixels must be in the
* allocated buffer, but does not necessarily represent the offset in
* columns between the same column in adjacent rows. The rows may be
* padded.
*/
uint32_t width;
/**
* The height specifies how many rows of pixels must be in the
* allocated buffer.
*/
uint32_t height;
/**
* The number of image layers that must be in the allocated buffer.
*/
uint32_t layerCount;
/** Buffer pixel format. */
PixelFormat format;
/**
* Buffer usage mask; valid flags can be found in the definition of
* BufferUsage.
*/
bitfield<BufferUsage> usage;
};
struct Rect {
int32_t left;
int32_t top;
int32_t width;
int32_t height;
};
/**
* Creates a buffer descriptor. The descriptor can be used with IAllocator
* to allocate buffers.
*
* Since the buffer descriptor fully describes a buffer, any device
* dependent or device independent checks must be performed here whenever
* possible. Specifically, when layered buffers are not supported, this
* function must return UNSUPPORTED if layerCount is great than 1.
*
* @param descriptorInfo specifies the attributes of the descriptor.
* @return error is NONE upon success. Otherwise,
* BAD_VALUE when any of the specified attributes is
* invalid or conflicting.
* NO_RESOURCES when the creation cannot be fullfilled at
* this time.
* UNSUPPORTED when any of the specified attributes is
* not supported.
* @return descriptor is the newly created buffer descriptor.
*/
@entry
@callflow(next="*")
createDescriptor(BufferDescriptorInfo descriptorInfo)
generates (Error error,
BufferDescriptor descriptor);
/**
* Imports a raw buffer handle to create an imported buffer handle for use
* with the rest of the mapper or with other in-process libraries.
*
* A buffer handle is considered raw when it is cloned (e.g., with
* native_handle_clone) from another buffer handle locally, or when it is
* received from another HAL server/client or another process. A raw
* buffer handle must not be used to access the underlying graphics
* buffer. It must be imported to create an imported handle first.
*
* This function must at least validate the raw handle before creating the
* imported handle. It must also support importing the same raw handle
* multiple times to create multiple imported handles. The imported handle
* must be considered valid everywhere in the process, including in
* another instance of the mapper.
*
* Because of passthrough HALs, a raw buffer handle received from a HAL
* may actually have been imported in the process. importBuffer must treat
* such a handle as if it is raw and must not return BAD_BUFFER. The
* returned handle is independent from the input handle as usual, and
* freeBuffer must be called on it when it is no longer needed.
*
* @param rawHandle is the raw buffer handle to import.
* @return error is NONE upon success. Otherwise,
* BAD_BUFFER when the raw handle is invalid.
* NO_RESOURCES when the raw handle cannot be imported at
* this time.
* @return buffer is the imported buffer handle and has the type
* buffer_handle_t.
*/
@entry
@callflow(next="*")
importBuffer(handle rawHandle) generates (Error error, pointer buffer);
/**
* Frees a buffer handle. Buffer handles returned by importBuffer must be
* freed with this function when no longer needed.
*
* This function must free up all resources allocated by importBuffer for
* the imported handle. For example, if the imported handle was created
* with native_handle_create, this function must call native_handle_close
* and native_handle_delete.
*
* @return error is NONE upon success. Otherwise,
* BAD_BUFFER when the buffer is invalid.
*/
@exit
@callflow(next="*")
freeBuffer(pointer buffer) generates (Error error);
/**
* Locks the given buffer for the specified CPU usage.
*
* Locking the same buffer simultaneously from multiple threads is
* permitted, but if any of the threads attempt to lock the buffer for
* writing, the behavior is undefined, except that it must not cause
* process termination or block the client indefinitely. Leaving the
* buffer content in an indeterminate state or returning an error are both
* acceptable.
*
* The client must not modify the content of the buffer outside of
* accessRegion, and the device need not guarantee that content outside of
* accessRegion is valid for reading. The result of reading or writing
* outside of accessRegion is undefined, except that it must not cause
* process termination.
*
* data will be filled with a pointer to the locked buffer memory. This
* address will represent the top-left corner of the entire buffer, even
* if accessRegion does not begin at the top-left corner.
*
* @param buffer is the buffer to lock.
* @param cpuUsage specifies one or more CPU usage flags to request.
* @param accessRegion is the portion of the buffer that the client
* intends to access.
* @param acquireFence when non-empty, is a handle containing a file
* descriptor referring to a sync fence object, which will be
* signaled when it is safe for the mapper to lock the buffer. If
* it is already safe to lock, acquireFence is empty.
* @return error is NONE upon success. Otherwise,
* BAD_BUFFER when the buffer is invalid or is
* incompatible with this function.
* BAD_VALUE when cpuUsage is 0, contains non-CPU usage
* flags, or is incompatible with the buffer.
* NO_RESOURCES when the buffer cannot be locked at this
* time, but locking may succeed at a future
* time.
* @return data is a CPU-accessible pointer to the buffer data.
*/
@callflow(next="unlock")
lock(pointer buffer,
bitfield<BufferUsage> cpuUsage,
Rect accessRegion,
handle acquireFence)
generates (Error error,
pointer data);
/**
* This is largely the same as lock(), except that instead of returning a
* pointer directly to the buffer data, it returns an YCbCrLayout struct
* describing how to access the data planes.
*
* This function must work on buffers with PixelFormat::YCbCr_*_888 if
* supported by the device, as well as with any other formats requested by
* multimedia codecs when they are configured with a
* flexible-YUV-compatible color format.
*
* @param buffer is the buffer to lock.
* @param cpuUsage specifies one or more CPU usage flags to request.
* @param accessRegion is the portion of the buffer that the client
* intends to access.
* @param acquireFence when non-empty, is a handle containing a file
* descriptor referring to a sync fence object, which will be
* signaled when it is safe for the mapper to lock the buffer. If
* it is already safe to lock, acquireFence is empty.
* @return error is NONE upon success. Otherwise,
* BAD_BUFFER when the buffer is invalid or is
* incompatible with this function.
* BAD_VALUE when cpuUsage is 0, contains non-CPU usage
* flags, or is incompatible with the buffer.
* NO_RESOURCES when the buffer cannot be locked at this
* time, but locking may succeed at a future
* time.
* @return layout is the data layout of the buffer.
*/
@callflow(next="unlock")
lockYCbCr(pointer buffer,
bitfield<BufferUsage> cpuUsage,
Rect accessRegion,
handle acquireFence)
generates (Error error,
YCbCrLayout layout);
/**
* Unlocks a buffer to indicate all CPU accesses to the buffer have
* completed.
*
* @param buffer is the buffer to unlock.
* @return error is NONE upon success. Otherwise,
* BAD_BUFFER when the buffer is invalid or not locked.
* @return releaseFence, when non-empty, is a handle containing a file
* descriptor referring to a sync fence object. The sync fence
* object will be signaled when the mapper has completed any
* pending work.
*/
@callflow(next="*")
unlock(pointer buffer)
generates (Error error,
handle releaseFence);
};