|
Packit Service |
e3b512 |
/* Copyright (C) 2010 The cairomm Development Team
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* This library is free software; you can redistribute it and/or
|
|
Packit Service |
e3b512 |
* modify it under the terms of the GNU Library General Public
|
|
Packit Service |
e3b512 |
* License as published by the Free Software Foundation; either
|
|
Packit Service |
e3b512 |
* version 2 of the License, or (at your option) any later version.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* This library is distributed in the hope that it will be useful,
|
|
Packit Service |
e3b512 |
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
Packit Service |
e3b512 |
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Packit Service |
e3b512 |
* Library General Public License for more details.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* You should have received a copy of the GNU Library General Public
|
|
Packit Service |
e3b512 |
* License along with this library; if not, write to the Free Software
|
|
Packit Service |
e3b512 |
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
|
|
Packit Service |
e3b512 |
* 02110-1301, USA.
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
#ifndef __CAIROMM_DEVICE_H
|
|
Packit Service |
e3b512 |
#define __CAIROMM_DEVICE_H
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
#include <cairomm/types.h>
|
|
Packit Service |
e3b512 |
#include <cairomm/enums.h>
|
|
Packit Service |
e3b512 |
#include <cairomm/refptr.h>
|
|
Packit Service |
e3b512 |
#include <cairo.h>
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
namespace Cairo
|
|
Packit Service |
e3b512 |
{
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/**
|
|
Packit Service |
e3b512 |
* Devices are the abstraction Cairo employs for the rendering system used by a
|
|
Packit Service |
e3b512 |
* cairo_surface_t. You can get the device of a surface using
|
|
Packit Service |
e3b512 |
* Surface::get_device().
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* Devices are created using custom functions specific to the rendering system
|
|
Packit Service |
e3b512 |
* you want to use. See the documentation for the surface types for those
|
|
Packit Service |
e3b512 |
* functions.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* An important function that devices fulfill is sharing access to the rendering
|
|
Packit Service |
e3b512 |
* system between Cairo and your application. If you want to access a device
|
|
Packit Service |
e3b512 |
* directly that you used to draw to with Cairo, you must first call
|
|
Packit Service |
e3b512 |
* flush() to ensure that Cairo finishes all operations on the
|
|
Packit Service |
e3b512 |
* device and resets it to a clean state.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* Cairo also provides the functions acquire() and release() to synchronize
|
|
Packit Service |
e3b512 |
* access to the rendering system in a multithreaded environment. This is done
|
|
Packit Service |
e3b512 |
* internally, but can also be used by applications. There is also a
|
|
Packit Service |
e3b512 |
* Device::Lock convenience class that allows the device to be acquired and
|
|
Packit Service |
e3b512 |
* released in an exception-safe manner.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* This is a reference-counted object that should be used via Cairo::RefPtr.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @since 1.10
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
class Device
|
|
Packit Service |
e3b512 |
{
|
|
Packit Service |
e3b512 |
public:
|
|
Packit Service |
e3b512 |
/** A convenience class for acquiring a Device object in an exception-safe
|
|
Packit Service |
e3b512 |
* manner. The device is automatically acquired when a Lock object is created
|
|
Packit Service |
e3b512 |
* and released when the Lock object is destroyed. For example:
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @code
|
|
Packit Service |
e3b512 |
* void
|
|
Packit Service |
e3b512 |
* my_device_modifying_function (const RefPtr<Device>& device)
|
|
Packit Service |
e3b512 |
* {
|
|
Packit Service |
e3b512 |
* // Ensure the device is properly reset
|
|
Packit Service |
e3b512 |
* device->flush();
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* Device::Lock lock(device);
|
|
Packit Service |
e3b512 |
* // Do the custom operations on the device here.
|
|
Packit Service |
e3b512 |
* // But do not call any Cairo functions that might acquire devices.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* } // device is automatically released at the end of the function scope
|
|
Packit Service |
e3b512 |
* @endcode
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
class Lock
|
|
Packit Service |
e3b512 |
{
|
|
Packit Service |
e3b512 |
public:
|
|
Packit Service |
e3b512 |
/** Create a new Device lock for @a device */
|
|
Packit Service |
e3b512 |
Lock (const RefPtr<Device>& device);
|
|
Packit Service |
e3b512 |
Lock (const Lock& other);
|
|
Packit Service |
e3b512 |
~Lock();
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
private:
|
|
Packit Service |
e3b512 |
RefPtr<Device> m_device;
|
|
Packit Service |
e3b512 |
};
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** Create a C++ wrapper for the C instance. This C++ instance should then be given to a RefPtr.
|
|
Packit Service |
e3b512 |
* @param cobject The C instance.
|
|
Packit Service |
e3b512 |
* @param has_reference Whether we already have a reference. Otherwise, the constructor will take an extra reference.
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
explicit Device(cairo_device_t* cobject, bool has_reference = false);
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
virtual ~Device();
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** This function returns the type of the device */
|
|
Packit Service |
e3b512 |
DeviceType get_type() const;
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** Finish any pending operations for the device and also restore any
|
|
Packit Service |
e3b512 |
* temporary modifications cairo has made to the device's state. This function
|
|
Packit Service |
e3b512 |
* must be called before switching from using the device with Cairo to
|
|
Packit Service |
e3b512 |
* operating on it directly with native APIs. If the device doesn't support
|
|
Packit Service |
e3b512 |
* direct access, then this function does nothing.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* This function may acquire devices.
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
void flush();
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** This function finishes the device and drops all references to external
|
|
Packit Service |
e3b512 |
* resources. All surfaces, fonts and other objects created for this device
|
|
Packit Service |
e3b512 |
* will be finished, too. Further operations on the device will not affect the
|
|
Packit Service |
e3b512 |
* device but will instead trigger a DEVICE_FINISHED error.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* When the last reference to the device is dropped, cairo will call
|
|
Packit Service |
e3b512 |
* finish() if it hasn't been called already, before freeing the resources
|
|
Packit Service |
e3b512 |
* associated with the device.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* This function may acquire devices.
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
void finish();
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** Acquires the device for the current thread. This function will block until
|
|
Packit Service |
e3b512 |
* no other thread has acquired the device.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* If no exception is thrown, you successfully acquired the device. From now
|
|
Packit Service |
e3b512 |
* on your thread owns the device and no other thread will be able to acquire
|
|
Packit Service |
e3b512 |
* it until a matching call to release(). It is allowed to recursively acquire
|
|
Packit Service |
e3b512 |
* the device multiple times from the same thread.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @note It is recommended to use Device::Lock to acquire devices in an
|
|
Packit Service |
e3b512 |
* exception-safe manner, rather than acquiring and releasing the device
|
|
Packit Service |
e3b512 |
* manually.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @warning You must never acquire two different devices at the same time
|
|
Packit Service |
e3b512 |
* unless this is explicitly allowed. Otherwise the possibility of deadlocks
|
|
Packit Service |
e3b512 |
* exist.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @warning As various Cairo functions can acquire devices when called, these
|
|
Packit Service |
e3b512 |
* functions may also cause deadlocks when you call them with an acquired
|
|
Packit Service |
e3b512 |
* device. So you must not have a device acquired when calling them. These
|
|
Packit Service |
e3b512 |
* functions are marked in the documentation.
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
void acquire();
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** Releases a device previously acquired using acquire().
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
void release();
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
typedef cairo_device_t cobject;
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
inline cobject* cobj() { return m_cobject; }
|
|
Packit Service |
e3b512 |
inline const cobject* cobj() const { return m_cobject; }
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
#ifndef DOXYGEN_IGNORE_THIS
|
|
Packit Service |
e3b512 |
///For use only by the cairomm implementation.
|
|
Packit Service |
e3b512 |
inline ErrorStatus get_status() const
|
|
Packit Service |
e3b512 |
{ return cairo_device_status(const_cast<cairo_device_t*>(cobj())); }
|
|
Packit Service |
e3b512 |
#endif //DOXYGEN_IGNORE_THIS
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
void reference() const;
|
|
Packit Service |
e3b512 |
void unreference() const;
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
protected:
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
cobject* m_cobject;
|
|
Packit Service |
e3b512 |
};
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
} // namespace Cairo
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
#endif //__CAIROMM_DEVICE_H
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
// vim: ts=2 sw=2 et
|