From 1473add188f7a11fb8f5e17d21659a3b30a7063f Mon Sep 17 00:00:00 2001 From: Kieran Bingham Date: Mon, 8 Feb 2021 14:30:31 +0000 Subject: libcamera: Move extensible to class The Extensible concept is a generic Class helper. To prepare for further class helper additions, move the specific extensible implementation and header to a more generic class header and source. Reviewed-by: Laurent Pinchart Signed-off-by: Kieran Bingham --- src/libcamera/class.cpp | 137 +++++++++++++++++++++++++++++++++++++++++++ src/libcamera/extensible.cpp | 134 ------------------------------------------ src/libcamera/meson.build | 2 +- 3 files changed, 138 insertions(+), 135 deletions(-) create mode 100644 src/libcamera/class.cpp delete mode 100644 src/libcamera/extensible.cpp (limited to 'src/libcamera') diff --git a/src/libcamera/class.cpp b/src/libcamera/class.cpp new file mode 100644 index 00000000..ce230be9 --- /dev/null +++ b/src/libcamera/class.cpp @@ -0,0 +1,137 @@ +/* SPDX-License-Identifier: LGPL-2.1-or-later */ +/* + * Copyright (C) 2020, Google Inc. + * + * class.cpp - Utilities and helpers for classes + */ + +#include + +/** + * \file class.h + * \brief Utilities to help constructing class interfaces + * + * The extensible class can be inherited to create public classes with stable + * ABIs. + */ + +namespace libcamera { + +/** + * \def LIBCAMERA_DECLARE_PRIVATE + * \brief Declare private data for a public class + * \param klass The public class name + * + * The LIBCAMERA_DECLARE_PRIVATE() macro plumbs the infrastructure necessary to + * make a class manage its private data through a d-pointer. It shall be used at + * the very top of the class definition, with the public class name passed as + * the \a klass parameter. + */ + +/** + * \def LIBCAMERA_DECLARE_PUBLIC + * \brief Declare public data for a private class + * \param klass The public class name + * + * The LIBCAMERA_DECLARE_PUBLIC() macro is the counterpart of + * LIBCAMERA_DECLARE_PRIVATE() to be used in the private data class. It shall be + * used at the very top of the private class definition, with the public class + * name passed as the \a klass parameter. + */ + +/** + * \def LIBCAMERA_D_PTR(klass) + * \brief Retrieve the private data pointer + * \param[in] klass The public class name + * + * This macro can be used in any member function of a class that inherits, + * directly or indirectly, from the Extensible class, to create a local + * variable named 'd' that points to the class' private data instance. + */ + +/** + * \def LIBCAMERA_O_PTR(klass) + * \brief Retrieve the public instance corresponding to the private data + * \param[in] klass The public class name + * + * This macro is the counterpart of LIBCAMERA_D_PTR() for private data classes. + * It can be used in any member function of the private data class to create a + * local variable named 'o' that points to the public class instance + * corresponding to the private data. + */ + +/** + * \class Extensible + * \brief Base class to manage private data through a d-pointer + * + * The Extensible class provides a base class to implement the + * d-pointer design pattern (also + * known as opaque pointer + * or pImpl idiom). + * It helps creating public classes that can be extended without breaking their + * ABI. Such classes store their private data in a separate private data object, + * referenced by a pointer in the public class (hence the name d-pointer). + * + * Classes that follow this design pattern are referred herein as extensible + * classes. To be extensible, a class PublicClass shall: + * + * - inherit from the Extensible class or from another extensible class + * - invoke the LIBCAMERA_DECLARE_PRIVATE() macro at the very top of the class + * definition + * - define a private data class named PublicClass::Private that inherits from + * the Private data class of the base class + * - invoke the LIBCAMERA_DECLARE_PUBLIC() macro at the very top of the Private + * data class definition + * - pass a pointer to a newly allocated Private data object to the constructor + * of the base class + * + * Additionally, if the PublicClass is not final, it shall expose one or more + * constructors that takes a pointer to a Private data instance, to be used by + * derived classes. + * + * The Private class is fully opaque to users of the libcamera public API. + * Internally, it can be kept private to the implementation of PublicClass, or + * be exposed to other classes. In the latter case, the members of the Private + * class need to be qualified with appropriate access specifiers. The + * PublicClass and Private classes always have full access to each other's + * protected and private members. + */ + +/** + * \brief Construct an instance of an Extensible class + * \param[in] d Pointer to the private data instance + */ +Extensible::Extensible(Extensible::Private *d) + : d_(d) +{ +} + +/** + * \var Extensible::d_ + * \brief Pointer to the private data instance + */ + +/** + * \class Extensible::Private + * \brief Base class for private data managed through a d-pointer + */ + +/** + * \brief Construct an instance of an Extensible class private data + * \param[in] o Pointer to the public class object + */ +Extensible::Private::Private(Extensible *o) + : o_(o) +{ +} + +Extensible::Private::~Private() +{ +} + +/** + * \var Extensible::Private::o_ + * \brief Pointer to the public class object + */ + +} /* namespace libcamera */ diff --git a/src/libcamera/extensible.cpp b/src/libcamera/extensible.cpp deleted file mode 100644 index 1dcb0bf1..00000000 --- a/src/libcamera/extensible.cpp +++ /dev/null @@ -1,134 +0,0 @@ -/* SPDX-License-Identifier: LGPL-2.1-or-later */ -/* - * Copyright (C) 2020, Google Inc. - * - * extensible.cpp - Utilities to create extensible public classes with stable ABIs - */ - -#include - -/** - * \file extensible.h - * \brief Utilities to create extensible public classes with stable ABIs - */ - -namespace libcamera { - -/** - * \def LIBCAMERA_DECLARE_PRIVATE - * \brief Declare private data for a public class - * \param klass The public class name - * - * The LIBCAMERA_DECLARE_PRIVATE() macro plumbs the infrastructure necessary to - * make a class manage its private data through a d-pointer. It shall be used at - * the very top of the class definition, with the public class name passed as - * the \a klass parameter. - */ - -/** - * \def LIBCAMERA_DECLARE_PUBLIC - * \brief Declare public data for a private class - * \param klass The public class name - * - * The LIBCAMERA_DECLARE_PUBLIC() macro is the counterpart of - * LIBCAMERA_DECLARE_PRIVATE() to be used in the private data class. It shall be - * used at the very top of the private class definition, with the public class - * name passed as the \a klass parameter. - */ - -/** - * \def LIBCAMERA_D_PTR(klass) - * \brief Retrieve the private data pointer - * \param[in] klass The public class name - * - * This macro can be used in any member function of a class that inherits, - * directly or indirectly, from the Extensible class, to create a local - * variable named 'd' that points to the class' private data instance. - */ - -/** - * \def LIBCAMERA_O_PTR(klass) - * \brief Retrieve the public instance corresponding to the private data - * \param[in] klass The public class name - * - * This macro is the counterpart of LIBCAMERA_D_PTR() for private data classes. - * It can be used in any member function of the private data class to create a - * local variable named 'o' that points to the public class instance - * corresponding to the private data. - */ - -/** - * \class Extensible - * \brief Base class to manage private data through a d-pointer - * - * The Extensible class provides a base class to implement the - * d-pointer design pattern (also - * known as opaque pointer - * or pImpl idiom). - * It helps creating public classes that can be extended without breaking their - * ABI. Such classes store their private data in a separate private data object, - * referenced by a pointer in the public class (hence the name d-pointer). - * - * Classes that follow this design pattern are referred herein as extensible - * classes. To be extensible, a class PublicClass shall: - * - * - inherit from the Extensible class or from another extensible class - * - invoke the LIBCAMERA_DECLARE_PRIVATE() macro at the very top of the class - * definition - * - define a private data class named PublicClass::Private that inherits from - * the Private data class of the base class - * - invoke the LIBCAMERA_DECLARE_PUBLIC() macro at the very top of the Private - * data class definition - * - pass a pointer to a newly allocated Private data object to the constructor - * of the base class - * - * Additionally, if the PublicClass is not final, it shall expose one or more - * constructors that takes a pointer to a Private data instance, to be used by - * derived classes. - * - * The Private class is fully opaque to users of the libcamera public API. - * Internally, it can be kept private to the implementation of PublicClass, or - * be exposed to other classes. In the latter case, the members of the Private - * class need to be qualified with appropriate access specifiers. The - * PublicClass and Private classes always have full access to each other's - * protected and private members. - */ - -/** - * \brief Construct an instance of an Extensible class - * \param[in] d Pointer to the private data instance - */ -Extensible::Extensible(Extensible::Private *d) - : d_(d) -{ -} - -/** - * \var Extensible::d_ - * \brief Pointer to the private data instance - */ - -/** - * \class Extensible::Private - * \brief Base class for private data managed through a d-pointer - */ - -/** - * \brief Construct an instance of an Extensible class private data - * \param[in] o Pointer to the public class object - */ -Extensible::Private::Private(Extensible *o) - : o_(o) -{ -} - -Extensible::Private::~Private() -{ -} - -/** - * \var Extensible::Private::o_ - * \brief Pointer to the public class object - */ - -} /* namespace libcamera */ diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build index ebce19d9..939f1189 100644 --- a/src/libcamera/meson.build +++ b/src/libcamera/meson.build @@ -9,6 +9,7 @@ libcamera_sources = files([ 'camera_controls.cpp', 'camera_manager.cpp', 'camera_sensor.cpp', + 'class.cpp', 'controls.cpp', 'control_serializer.cpp', 'control_validator.cpp', @@ -18,7 +19,6 @@ libcamera_sources = files([ 'event_dispatcher.cpp', 'event_dispatcher_poll.cpp', 'event_notifier.cpp', - 'extensible.cpp', 'file.cpp', 'file_descriptor.cpp', 'formats.cpp', -- cgit v1.2.1