/*
* Copyright © 2016 Canonical Ltd.
*
* This program is free software: you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License version 3,
* as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program. If not, see .
*
*/
#ifndef MIR_TOOLKIT_MIR_BUFFER_H_
#define MIR_TOOLKIT_MIR_BUFFER_H_
#include
#include
#include
#ifdef __cplusplus
/**
* \addtogroup mir_toolkit
* @{
*/
extern "C" {
#endif
/** Allocate a MirBuffer and do not wait for the server to return it.
* The buffer will be suitable for writing to via the CPU. Buffers that
* will be used on a GPU should be allocated via the platform appropriate
* extensions. (eg, mir_extension_gbm_buffer or mir_extension_android_buffer)
*
* The callback will be called when the buffer is created.
*
* \param [in] connection The connection
* \param [in] width Requested buffer width
* \param [in] height Requested buffer height
* \param [in] buffer_usage Requested buffer usage
* \param [in] available_callback The callback called when the buffer
* is available
* \param [in] available_context The context for the available_callback
**/
void mir_connection_allocate_buffer(
MirConnection* connection,
int width, int height,
MirPixelFormat format,
MirBufferCallback available_callback, void* available_context);
/** Allocate a MirBuffer and wait for the server to return it.
*
* \param [in] connection The connection
* \param [in] width Requested buffer width
* \param [in] height Requested buffer height
* \param [in] buffer_usage Requested buffer usage
* \return The buffer
**/
MirBuffer* mir_connection_allocate_buffer_sync(
MirConnection* connection,
int width, int height,
MirPixelFormat format);
/** Test for a valid buffer
* \param [in] buffer The buffer
* \return True if the buffer is valid, or false otherwise.
**/
bool mir_buffer_is_valid(MirBuffer* buffer);
/** Retrieve a text description an error associated with a MirBuffer.
* The returned string is owned by the library and remains valid until the
* buffer or the associated connection has been released.
* \param [in] buffer The buffer
* \return A text description of any error resulting in an
* invalid buffer, or the empty string "" if the
* connection is valid.
**/
char const *mir_buffer_get_error_message(MirBuffer* buffer);
/**
* Access the MirBufferPackage
*
* \param [in] buffer The buffer
* \return The MirBufferPackage representing buffer
*/
MirBufferPackage* mir_buffer_get_buffer_package(MirBuffer* buffer);
/** Access a CPU-mapped region associated with a given buffer.
*
* \param [in] buffer The buffer
* \param [out] region The mapped region
* \param [out] layout The memory layout of the region
* \return true if success, false if failure
* \warning The buffer should be flushed via mir_buffer_munmap() before
* submitting the buffer to the server.
**/
bool mir_buffer_map(MirBuffer* buffer, MirGraphicsRegion* region, MirBufferLayout* layout);
/** Flush the CPU caches for the buffer.
*
* \post MirGraphicsRegions that are associated with the buffer will be invalid.
* \param [in] buffer The buffer
**/
void mir_buffer_unmap(MirBuffer* buffer);
/** Retrieve the width of the buffer in pixels.
*
* \param [in] buffer The buffer
* \return The width of the buffer in pixels
**/
unsigned int mir_buffer_get_width(MirBuffer* buffer);
/** Retrieve the height of the buffer in pixels.
*
* \param [in] buffer The buffer
* \return The height of the buffer in pixels
**/
unsigned int mir_buffer_get_height(MirBuffer* buffer);
/** Retrieve the pixel format of the buffer.
*
* \param [in] buffer The buffer
* \return The pixel format of the buffer
**/
MirPixelFormat mir_buffer_get_pixel_format(MirBuffer* buffer);
/** @} */
/** release a MirBuffer
* \param [in] buffer The buffer to be released
**/
void mir_buffer_release(MirBuffer* buffer);
#ifdef __cplusplus
}
/**@}*/
#endif
#endif // MIR_TOOLKIT_MIR_BUFFER_H_