/* * 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_