def add_overlay(self, source, size=None, format=None, **options):
    '\n        Adds a static overlay to the preview output.\n\n        This method creates a new static overlay using the same rendering\n        mechanism as the preview. Overlays will appear on the Pi\'s video\n        output, but will not appear in captures or video recordings. Multiple\n        overlays can exist; each call to :meth:`add_overlay` returns a new\n        :class:`PiOverlayRenderer` instance representing the overlay.\n\n        The *source* must be an object that supports the :ref:`buffer protocol\n        <bufferobjects>` in one of the supported unencoded formats: ``\'yuv\'``,\n        ``\'rgb\'``, ``\'rgba\'``, ``\'bgr\'``, or ``\'bgra\'``. The format can\n        specified explicitly with the optional *format* parameter. If not\n        specified, the method will attempt to guess the format based on the\n        length of *source* and the *size* (assuming 3 bytes per pixel for RGB,\n        and 4 bytes for RGBA).\n\n        The optional *size* parameter specifies the size of the source image as\n        a ``(width, height)`` tuple. If this is omitted or ``None`` then the\n        size is assumed to be the same as the camera\'s current\n        :attr:`resolution`.\n\n        The length of *source* must take into account that widths are rounded\n        up to the nearest multiple of 32, and heights to the nearest multiple\n        of 16.  For example, if *size* is ``(1280, 720)``, and *format* is\n        ``\'rgb\'``, then *source* must be a buffer with length 1280 × 720 × 3\n        bytes, or 2,764,800 bytes (because 1280 is a multiple of 32, and 720 is\n        a multiple of 16 no extra rounding is required).  However, if *size* is\n        ``(97, 57)``, and *format* is ``\'rgb\'`` then *source* must be a buffer\n        with length 128 × 64 × 3 bytes, or 24,576 bytes (pixels beyond column\n        97 and row 57 in the source will be ignored).\n\n        New overlays default to *layer* 0, whilst the preview defaults to layer\n        2. Higher numbered layers obscure lower numbered layers, hence new\n        overlays will be invisible (if the preview is running) by default. You\n        can make the new overlay visible either by making any existing preview\n        transparent (with the :attr:`~PiRenderer.alpha` property) or by moving\n        the overlay into a layer higher than the preview (with the\n        :attr:`~PiRenderer.layer` property).\n\n        All keyword arguments captured in *options* are passed onto the\n        :class:`PiRenderer` constructor. All camera properties except\n        :attr:`resolution` and :attr:`framerate` can be modified while overlays\n        exist. The reason for these exceptions is that the overlay has a static\n        resolution and changing the camera\'s mode would require resizing of the\n        source.\n\n        .. warning::\n\n            If too many overlays are added, the display output will be disabled\n            and a reboot will generally be required to restore the display.\n            Overlays are composited "on the fly". Hence, a real-time constraint\n            exists wherein for each horizontal line of HDMI output, the content\n            of all source layers must be fetched, resized, converted, and\n            blended to produce the output pixels.\n\n            If enough overlays exist (where "enough" is a number dependent on\n            overlay size, display resolution, bus frequency, and several other\n            factors making it unrealistic to calculate in advance), this\n            process breaks down and video output fails. One solution is to add\n            ``dispmanx_offline=1`` to ``/boot/config.txt`` to force the use of\n            an off-screen buffer. Be aware that this requires more GPU memory\n            and may reduce the update rate.\n\n        .. _RGB: https://en.wikipedia.org/wiki/RGB\n        .. _RGBA: https://en.wikipedia.org/wiki/RGBA_color_space\n\n        .. versionadded:: 1.8\n\n        .. versionchanged:: 1.13\n            Added *format* parameter\n        '
    self._check_camera_open()
    renderer = PiOverlayRenderer(self, source, size, format, **options)
    self._overlays.append(renderer)
    return renderer
Adds a static overlay to the preview output.

This method creates a new static overlay using the same rendering
mechanism as the preview. Overlays will appear on the Pi's video
output, but will not appear in captures or video recordings. Multiple
overlays can exist; each call to :meth:`add_overlay` returns a new
:class:`PiOverlayRenderer` instance representing the overlay.

The *source* must be an object that supports the :ref:`buffer protocol
<bufferobjects>` in one of the supported unencoded formats: ``'yuv'``,
``'rgb'``, ``'rgba'``, ``'bgr'``, or ``'bgra'``. The format can
specified explicitly with the optional *format* parameter. If not
specified, the method will attempt to guess the format based on the
length of *source* and the *size* (assuming 3 bytes per pixel for RGB,
and 4 bytes for RGBA).

The optional *size* parameter specifies the size of the source image as
a ``(width, height)`` tuple. If this is omitted or ``None`` then the
size is assumed to be the same as the camera's current
:attr:`resolution`.

The length of *source* must take into account that widths are rounded
up to the nearest multiple of 32, and heights to the nearest multiple
of 16.  For example, if *size* is ``(1280, 720)``, and *format* is
``'rgb'``, then *source* must be a buffer with length 1280 × 720 × 3
bytes, or 2,764,800 bytes (because 1280 is a multiple of 32, and 720 is
a multiple of 16 no extra rounding is required).  However, if *size* is
``(97, 57)``, and *format* is ``'rgb'`` then *source* must be a buffer
with length 128 × 64 × 3 bytes, or 24,576 bytes (pixels beyond column
97 and row 57 in the source will be ignored).

New overlays default to *layer* 0, whilst the preview defaults to layer
2. Higher numbered layers obscure lower numbered layers, hence new
overlays will be invisible (if the preview is running) by default. You
can make the new overlay visible either by making any existing preview
transparent (with the :attr:`~PiRenderer.alpha` property) or by moving
the overlay into a layer higher than the preview (with the
:attr:`~PiRenderer.layer` property).

All keyword arguments captured in *options* are passed onto the
:class:`PiRenderer` constructor. All camera properties except
:attr:`resolution` and :attr:`framerate` can be modified while overlays
exist. The reason for these exceptions is that the overlay has a static
resolution and changing the camera's mode would require resizing of the
source.

.. warning::

    If too many overlays are added, the display output will be disabled
    and a reboot will generally be required to restore the display.
    Overlays are composited "on the fly". Hence, a real-time constraint
    exists wherein for each horizontal line of HDMI output, the content
    of all source layers must be fetched, resized, converted, and
    blended to produce the output pixels.

    If enough overlays exist (where "enough" is a number dependent on
    overlay size, display resolution, bus frequency, and several other
    factors making it unrealistic to calculate in advance), this
    process breaks down and video output fails. One solution is to add
    ``dispmanx_offline=1`` to ``/boot/config.txt`` to force the use of
    an off-screen buffer. Be aware that this requires more GPU memory
    and may reduce the update rate.

.. _RGB: https://en.wikipedia.org/wiki/RGB
.. _RGBA: https://en.wikipedia.org/wiki/RGBA_color_space

.. versionadded:: 1.8

.. versionchanged:: 1.13
    Added *format* parameter
def add_overlay(self, source, size=None, format=None, **options):
    '\n        Adds a static overlay to the preview output.\n\n        This method creates a new static overlay using the same rendering\n        mechanism as the preview. Overlays will appear on the Pi\'s video\n        output, but will not appear in captures or video recordings. Multiple\n        overlays can exist; each call to :meth:`add_overlay` returns a new\n        :class:`PiOverlayRenderer` instance representing the overlay.\n\n        The *source* must be an object that supports the :ref:`buffer protocol\n        <bufferobjects>` in one of the supported unencoded formats: ``\'yuv\'``,\n        ``\'rgb\'``, ``\'rgba\'``, ``\'bgr\'``, or ``\'bgra\'``. The format can\n        specified explicitly with the optional *format* parameter. If not\n        specified, the method will attempt to guess the format based on the\n        length of *source* and the *size* (assuming 3 bytes per pixel for RGB,\n        and 4 bytes for RGBA).\n\n        The optional *size* parameter specifies the size of the source image as\n        a ``(width, height)`` tuple. If this is omitted or ``None`` then the\n        size is assumed to be the same as the camera\'s current\n        :attr:`resolution`.\n\n        The length of *source* must take into account that widths are rounded\n        up to the nearest multiple of 32, and heights to the nearest multiple\n        of 16.  For example, if *size* is ``(1280, 720)``, and *format* is\n        ``\'rgb\'``, then *source* must be a buffer with length 1280 × 720 × 3\n        bytes, or 2,764,800 bytes (because 1280 is a multiple of 32, and 720 is\n        a multiple of 16 no extra rounding is required).  However, if *size* is\n        ``(97, 57)``, and *format* is ``\'rgb\'`` then *source* must be a buffer\n        with length 128 × 64 × 3 bytes, or 24,576 bytes (pixels beyond column\n        97 and row 57 in the source will be ignored).\n\n        New overlays default to *layer* 0, whilst the preview defaults to layer\n        2. Higher numbered layers obscure lower numbered layers, hence new\n        overlays will be invisible (if the preview is running) by default. You\n        can make the new overlay visible either by making any existing preview\n        transparent (with the :attr:`~PiRenderer.alpha` property) or by moving\n        the overlay into a layer higher than the preview (with the\n        :attr:`~PiRenderer.layer` property).\n\n        All keyword arguments captured in *options* are passed onto the\n        :class:`PiRenderer` constructor. All camera properties except\n        :attr:`resolution` and :attr:`framerate` can be modified while overlays\n        exist. The reason for these exceptions is that the overlay has a static\n        resolution and changing the camera\'s mode would require resizing of the\n        source.\n\n        .. warning::\n\n            If too many overlays are added, the display output will be disabled\n            and a reboot will generally be required to restore the display.\n            Overlays are composited "on the fly". Hence, a real-time constraint\n            exists wherein for each horizontal line of HDMI output, the content\n            of all source layers must be fetched, resized, converted, and\n            blended to produce the output pixels.\n\n            If enough overlays exist (where "enough" is a number dependent on\n            overlay size, display resolution, bus frequency, and several other\n            factors making it unrealistic to calculate in advance), this\n            process breaks down and video output fails. One solution is to add\n            ``dispmanx_offline=1`` to ``/boot/config.txt`` to force the use of\n            an off-screen buffer. Be aware that this requires more GPU memory\n            and may reduce the update rate.\n\n        .. _RGB: https://en.wikipedia.org/wiki/RGB\n        .. _RGBA: https://en.wikipedia.org/wiki/RGBA_color_space\n\n        .. versionadded:: 1.8\n\n        .. versionchanged:: 1.13\n            Added *format* parameter\n        '
    self._check_camera_open()
    renderer = PiOverlayRenderer(self, source, size, format, **options)
    self._overlays.append(renderer)
    return renderer