# -*- coding: utf-8 -*-

"""Image Utilities

This module provides utilities for handling 16bpp bitmaps, such as those
generated by the espcamera module.
"""

def save_bitmap_file(bitmap, filename):
    """Saves the provided 16bpp displayio.Bitmap object to a file as a 24bpp BMP image.

    Note:
        Currently, only 16 bits-per-pixel bitmaps are supported.
        The bitmap data is saved in a bottom-up row order as required by the BMP format.

    Args:
        bitmap (displayio.Bitmap): The 16bpp bitmap object to save.
        filename (str): The full path and filename for the output BMP file.
                        The path must exist on a mounted VFS filesystem (e.g., '/sd/image.bmp').

    Raises:
        ValueError: If the input bitmap is not 16bpp.
        OSError: If the file path is not found in the VFS, the file cannot be opened,
                 or memory allocation fails.
    """
    # Implemented in C
    pass


def get_bitmap_bytes(bitmap):
    """Returns the raw pixel data of a displayio.Bitmap as a memoryview.

    This provides direct, efficient access to the bitmap's underlying byte data
    without copying. The data is typically in RGB565 format (16 bits per pixel).

    Args:
        bitmap (displayio.Bitmap): The bitmap object whose data is to be accessed.

    Returns:
        memoryview: A memoryview object referencing the bitmap's pixel data.
                    The size will be bitmap.width * bitmap.height * 2 bytes for a 16bpp bitmap.
    """
    # Implemented in C
    pass