summaryrefslogtreecommitdiff
path: root/src
AgeCommit message (Expand)Author
2022-06-01libcamera: Use "..." instead of <...> consistently for internal headersLaurent Pinchart
2022-06-01libcamera: Fix incorrect toString() to operator<<() conversionsLaurent Pinchart
2022-05-27py: Use ln --relative to create symlinksTomi Valkeinen
2022-05-27py: Generate bindings for propertiesTomi Valkeinen
2022-05-27py: Rename 'efd' to 'event_fd'Tomi Valkeinen
2022-05-27py: Re-structure the controls APITomi Valkeinen
2022-05-27py: Re-implement controls genenerationTomi Valkeinen
2022-05-27py: cam: Convert ctx and state to classesTomi Valkeinen
2022-05-27py: cam: Drop WA_ShowWithoutActivatingTomi Valkeinen
2022-05-27py: MappedFrameBuffer: Add type hints & docsTomi Valkeinen
2022-05-27py: Move MappedFrameBuffer to libcamera.utilsTomi Valkeinen
2022-05-27py: Add CameraManager.read_event()Tomi Valkeinen
2022-05-27py: Fix None value in ControlType enumTomi Valkeinen
2022-05-27py: Fix SceneFlicker enum valuesTomi Valkeinen
2022-05-27py: cam: CleanupsTomi Valkeinen
2022-05-27py: cam_qt: Use libcamera.formatsTomi Valkeinen
2022-05-27py: Generate pixel formats listTomi Valkeinen
2022-05-27libcamera: ipa: Move IPA control serialization structures to libcamera namespaceLaurent Pinchart
2022-05-27libcamera: pipeline: uvcvideo: Infer camera location from removable attributeLaurent Pinchart
2022-05-27libipa: camera_sensor_helper: Add Sony IMX477 helperNaushir Patuck
2022-05-27libcamera: camera_sensor: Add IMX477 sensor propertiesNaushir Patuck
2022-05-26ipa: camera_sensor_helper: Fix equation in exponential gain documentationLaurent Pinchart
2022-05-25libcamera: controls: Controls for driving AF (autofocus) algorithmsDavid Plowman
2022-05-23cam: sdl_sink: Add MJPG support to SDL sinkEric Curtin
2022-05-23cam: sdl_sink: Add SDL sink with initial YUYV supportEric Curtin
2022-05-23cam: event_loop: Add timer events to event loopEric Curtin
2022-05-23cam: event_loop: Rename addEvent to addFdEventEric Curtin
2022-05-23pipeline: raspberrypi: Fix possible null dereferenceNaushir Patuck
2022-05-22cam: Use script parser to set controlsJacopo Mondi
2022-05-22cam: Queue requests through CameraSession::queueRequest()Jacopo Mondi
2022-05-22cam: Add a parser for capture scriptsJacopo Mondi
2022-05-20android: Drop gcc 7 compatibilityLaurent Pinchart
2022-05-19libcamera: formats: Add missing RGBX8888 infoTomi Valkeinen
2022-05-19libcamera: formats: Fix warning printTomi Valkeinen
2022-05-18py: Clean up control enums generationTomi Valkeinen
2022-05-18py: Rename pyxyz to py_xyzTomi Valkeinen
2022-05-18py: Use geometry classesTomi Valkeinen
2022-05-18py: Add geometry classesTomi Valkeinen
2022-05-18py: Implement PixelFormat classTomi Valkeinen
2022-05-18py: cam_qt: Cosmetic cleanupsTomi Valkeinen
2022-05-18py: cam_kms: Fix multistream displayTomi Valkeinen
2022-05-18py: cam_kms: Support multiplanar formatsTomi Valkeinen
2022-05-18py: cam.py: Exit on exceptionTomi Valkeinen
2022-05-18py: pymain: Fix indentTomi Valkeinen
2022-05-18py: Add comment about the symlinksTomi Valkeinen
2022-05-18py: meson: Fix comment about stubsTomi Valkeinen
2022-05-18py: meson: Use files() for custom_target input filesTomi Valkeinen
2022-05-18ipa: ipu3: Put IPAFrameContext(s) in a ring bufferUmang Jain
2022-05-18ipa: libipa: Add frame context pointer in process()Umang Jain
2022-05-18ipa: ipu3: Rework IPAFrameContextUmang Jain
generated by cgit v1.2.1 (git 2.18.0) at 2024-07-10 17:40:44 +0000
446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 
/* SPDX-License-Identifier: LGPL-2.1-or-later */
/*
 * Copyright (C) 2019, Google Inc.
 *
 * ipa_interface.cpp - Image Processing Algorithm interface
 */

#include <libcamera/ipa/ipa_interface.h>

/**
 * \file ipa_interface.h
 * \brief Image Processing Algorithm interface
 *
 * Every pipeline handler in libcamera may attach some or all of its cameras to
 * an Image Processing Algorithm (IPA) module. An IPA module is developed for a
 * specific pipeline handler and each pipeline handler may be compatible with
 * multiple IPA implementations, both open and closed source. To support this,
 * libcamera communicates with IPA modules through a standard plain C interface.
 *
 * IPA modules shall expose a public function named ipaCreate() with the
 * following prototype.
 *
 * \code{.c}
 * struct ipa_context *ipaCreate();
 * \endcode
 *
 * The ipaCreate() function creates an instance of an IPA context, which models
 * a context of execution for the IPA. IPA modules shall support creating one
 * context per camera, as required by their associated pipeline handler.
 *
 * The IPA module context operations are defined in the struct ipa_context_ops.
 * They model a low-level interface to configure the IPA, notify it of events,
 * and receive IPA actions through callbacks. An IPA module stores a pointer to
 * the operations corresponding to its context in the ipa_context::ops field.
 * That pointer is immutable for the lifetime of the context, and may differ
 * between different contexts created by the same IPA module.
 *
 * The IPA interface defines base data types and functions to exchange data. On
 * top of this, each pipeline handler is responsible for defining the set of
 * events and actions used to communicate with their IPA. These are collectively
 * referred to as IPA operations and define the pipeline handler-specific IPA
 * protocol. Each operation defines the data that it carries, and how that data
 * is encoded in the ipa_context_ops functions arguments.
 *
 * \todo Add reference to how pipelines shall document their protocol.
 *
 * IPAs can be isolated in a separate process. This implies that arguments to
 * the IPA interface functions may need to be transferred over IPC. All
 * arguments use Plain Old Data types and are documented either in the form of C
 * data types, or as a textual description of byte arrays for types that can't
 * be expressed using C data types (such as arrays of mixed data types). IPA
 * modules can thus use the C API without calling into libcamera to access the
 * data passed to the IPA context operations.
 *
 * Due to IPC, synchronous communication between pipeline handlers and IPAs can
 * be costly. For that reason, the interface operates asynchronously. This
 * implies that methods don't return a status, and that all methods may copy
 * their arguments.
 *
 * The IPAInterface class is a C++ representation of the ipa_context_ops, using
 * C++ data classes provided by libcamera. This is the API exposed to pipeline
 * handlers to communicate with IPA modules. IPA modules may use the
 * IPAInterface API internally if they want to benefit from the data and helper
 * classes offered by libcamera.
 *
 * When an IPA module is loaded directly into the libcamera process and uses
 * the IPAInterface API internally, short-circuiting the path to the
 * ipa_context_ops and back to IPAInterface is desirable. To support this, IPA
 * modules may implement the ipa_context_ops::get_interface function to return a
 * pointer to their internal IPAInterface.
 */

/**
 * \struct ipa_context
 * \brief IPA module context of execution
 *
 * This structure models a context of execution for an IPA module. It is
 * instantiated by the IPA module ipaCreate() function. IPA modules allocate
 * context instances in an implementation-defined way, contexts shall thus be
 * destroyed using the ipa_operation::destroy function only.
 *
 * The ipa_context structure provides a pointer to the IPA context operations.
 * It shall otherwise be treated as a constant black-box cookie and passed
 * unmodified to the functions defined in struct ipa_context_ops.
 *
 * IPA modules are expected to extend struct ipa_context by inheriting from it,
 * either through structure embedding to model inheritance in plain C, or
 * through C++ class inheritance. A simple example of the latter is available
 * in the IPAContextWrapper class implementation.
 *
 * \var ipa_context::ops
 * \brief The IPA context operations
 */

/**
 * \struct ipa_settings
 * \brief IPA initialization settings for the IPA context operations
 * \sa IPASettings
 *
 * \var ipa_settings::configuration_file
 * \brief The name of the IPA configuration file (may be null or point to an
 * empty string)
 */

/**
 * \struct ipa_sensor_info
 * \brief Camera sensor information for the IPA context operations
 * \sa libcamera::CameraSensorInfo
 *
 * \var ipa_sensor_info::model
 * \brief The camera sensor model name
 * \todo Remove this field as soon as no IPA depends on it anymore
 *
 * \var ipa_sensor_info::bits_per_pixel
 * \brief The camera sensor image format bit depth
 * \sa libcamera::CameraSensorInfo::bitsPerPixel
 *
 * \var ipa_sensor_info::active_area.width
 * \brief The camera sensor pixel array active area width
 * \sa libcamera::CameraSensorInfo::activeAreaSize
 *
 * \var ipa_sensor_info::active_area.height
 * \brief The camera sensor pixel array active area height
 * \sa libcamera::CameraSensorInfo::activeAreaSize
 *
 * \var ipa_sensor_info::active_area
 * \brief The camera sensor pixel array active size
 * \sa libcamera::CameraSensorInfo::activeAreaSize
 *
 * \var ipa_sensor_info::analog_crop.left
 * \brief The left coordinate of the analog crop rectangle, relative to the
 * pixel array active area
 * \sa libcamera::CameraSensorInfo::analogCrop
 *
 * \var ipa_sensor_info::analog_crop.top
 * \brief The top coordinate of the analog crop rectangle, relative to the pixel
 * array active area
 * \sa libcamera::CameraSensorInfo::analogCrop
 *
 * \var ipa_sensor_info::analog_crop.width
 * \brief The horizontal size of the analog crop rectangle
 * \sa libcamera::CameraSensorInfo::analogCrop
 *
 * \var ipa_sensor_info::analog_crop.height
 * \brief The vertical size of the analog crop rectangle
 * \sa libcamera::CameraSensorInfo::analogCrop
 *
 * \var ipa_sensor_info::analog_crop
 * \brief The analog crop rectangle
 * \sa libcamera::CameraSensorInfo::analogCrop
 *
 * \var ipa_sensor_info::output_size.width
 * \brief The horizontal size of the output image
 * \sa libcamera::CameraSensorInfo::outputSize
 *
 * \var ipa_sensor_info::output_size.height
 * \brief The vertical size of the output image
 * \sa libcamera::CameraSensorInfo::outputSize
 *
 * \var ipa_sensor_info::output_size
 * \brief The size of the output image
 * \sa libcamera::CameraSensorInfo::outputSize
 *
 * \var ipa_sensor_info::pixel_rate
 * \brief The number of pixel produced in a second
 * \sa libcamera::CameraSensorInfo::pixelRate
 *
 * \var ipa_sensor_info::line_length
 * \brief The full line length, including blanking, in pixel units
 * \sa libcamera::CameraSensorInfo::lineLength
 */

/**
 * \struct ipa_stream
 * \brief Stream information for the IPA context operations
 *
 * \var ipa_stream::id
 * \brief Identifier for the stream, defined by the IPA protocol
 *
 * \var ipa_stream::pixel_format
 * \brief The stream pixel format, as defined by the PixelFormat class
 *
 * \var ipa_stream::width
 * \brief The stream width in pixels
 *
 * \var ipa_stream::height
 * \brief The stream height in pixels
 */

/**
 * \struct ipa_control_info_map
 * \brief ControlInfoMap description for the IPA context operations
 *
 * \var ipa_control_info_map::id
 * \brief Identifier for the ControlInfoMap, defined by the IPA protocol
 *
 * \var ipa_control_info_map::data
 * \brief Pointer to a control packet for the ControlInfoMap
 * \sa ipa_controls.h
 *
 * \var ipa_control_info_map::size
 * \brief The size of the control packet in bytes
 */

/**
 * \struct ipa_buffer_plane
 * \brief A plane for an ipa_buffer
 *
 * \var ipa_buffer_plane::dmabuf
 * \brief The dmabuf file descriptor for the plane (-1 for unused planes)
 *
 * \var ipa_buffer_plane::length
 * \brief The plane length in bytes (0 for unused planes)
 */

/**
 * \struct ipa_buffer
 * \brief Buffer information for the IPA context operations
 *
 * \var ipa_buffer::id
 * \brief The buffer unique ID (see \ref libcamera::IPABuffer::id)
 *
 * \var ipa_buffer::num_planes
 * \brief The number of used planes in the ipa_buffer::planes array
 *
 * \var ipa_buffer::planes
 * \brief The buffer planes (up to 3)
 */

/**
 * \struct ipa_control_list
 * \brief ControlList description for the IPA context operations
 *
 * \var ipa_control_list::data
 * \brief Pointer to a control packet for the ControlList
 * \sa ipa_controls.h
 *
 * \var ipa_control_list::size
 * \brief The size of the control packet in bytes
 */

/**
 * \struct ipa_operation_data
 * \brief IPA operation data for the IPA context operations
 * \sa libcamera::IPAOperationData
 *
 * \var ipa_operation_data::operation
 * \brief IPA protocol operation
 *
 * \var ipa_operation_data::data
 * \brief Pointer to the operation data array
 *
 * \var ipa_operation_data::num_data
 * \brief Number of entries in the ipa_operation_data::data array
 *
 * \var ipa_operation_data::lists
 * \brief Pointer to an array of ipa_control_list
 *
 * \var ipa_operation_data::num_lists
 * \brief Number of entries in the ipa_control_list array
 */

/**
 * \struct ipa_callback_ops
 * \brief IPA context operations as a set of function pointers
 */

/**
 * \var ipa_callback_ops::queue_frame_action
 * \brief Queue an action associated with a frame to the pipeline handler
 * \param[in] cb_ctx The callback context registered with
 * ipa_context_ops::register_callbacks
 * \param[in] frame The frame number
 *
 * \sa libcamera::IPAInterface::queueFrameAction
 */

/**
 * \struct ipa_context_ops
 * \brief IPA context operations as a set of function pointers
 *
 * To allow for isolation of IPA modules in separate processes, the functions
 * defined in the ipa_context_ops structure return only data related to the
 * libcamera side of the operations. In particular, error related to the
 * libcamera side of the IPC may be returned. Data returned by the IPA,
 * including status information, shall be provided through callbacks from the
 * IPA to libcamera.
 */

/**
 * \var ipa_context_ops::destroy
 * \brief Destroy the IPA context created by the module's ipaCreate() function
 * \param[in] ctx The IPA context
 */

/**
 * \var ipa_context_ops::get_interface
 * \brief Retrieve the IPAInterface implemented by the ipa_context (optional)
 * \param[in] ctx The IPA context
 *
 * IPA modules may implement this function to expose their internal
 * IPAInterface, if any. When implemented, libcamera may at its sole discretion
 * call it and then bypass the ipa_context_ops API by calling the IPAInterface