Reading/writing images

---

Detailed Description

Read functions:

What is read from file is controlled by the "read_mode":

read_mode = component_mode | mem_data_fmt

component_mode

component_mode controls the components that are read

    color_format    | component_mode | read from file
    -------------------------------------------------
    P_NO_COLOR      | P_READ_Y       | Y             *)
                    | other          | error
    -------------------------------------------------
    P_COLOR_422,    | P_READ_ALL     | Y, U/V
    P_COLOR_420     | P_READ_Y       | Y             *)
                    | P_READ_UV      | U/V           *)
                    | other          | error
    -------------------------------------------------
    P_COLOR_444_PL, | P_READ_ALL     | Y, U, V
    P_COLOR_422_PL, | P_READ_Y       | Y             *)
    P_COLOR_420_PL  | P_READ_UV      | U, V          *)
                    | P_READ_U       | U             *)
                    | P_READ_V       | V             *)
                    | other          | error
    -------------------------------------------------
    P_COLOR_RGB     | P_READ_ALL     | R, G, B
                    | P_READ_R       | R             *)
                    | P_READ_G       | G             *)
                    | P_READ_B       | B             *)
                    | P_READ_Y       | R, G, B (for backwards compatibility)
                    | other          | error
    -------------------------------------------------
    P_STREAM        | P_READ_ALL     | S             *)
                    | P_READ_Y       | S       (for backwards compatibility)
                    | other          | error
    -------------------------------------------------

    *) Only these buffers are written to the memory; pointers to
       other buffers (e.g. U/V) can be NULL pointers.

mem_data_fmt

mem_data_fmt (memory data format) controls the data format that is read:

• For unsigned char read functions:

NOte that these are all supported conversions by these functions.

    file_data_fmt   | mem_data_fmt     | conversion
    ---------------------------------------------------------------------
    P_8_BIT_FILE    | P_8_BIT_MEM      | direct memcpy, no conversion
                    | P_16_BIT_MEM_LSB | result is always 0 (zero)
                    | P_AF_BIT_MEM     | error
    ---------------------------------------------------------------------
    P_10_BIT_FILE   | P_8_BIT_MEM      |  (sample & 0x03ff) >> 2
                    | P_16_BIT_MEM_LSB | ((sample & 0x03ff) << 6) && 0xff
                    | P_AF_BIT_MEM     | error
    ---------------------------------------------------------------------
    P_12_BIT_FILE   | P_8_BIT_MEM      |  (sample & 0x0fff) >> 4
                    | P_16_BIT_MEM_LSB | ((sample & 0x0fff) << 4) && 0xff
                    | P_AF_BIT_MEM     | error
    ---------------------------------------------------------------------
    P_14_BIT_FILE   | P_8_BIT_MEM      |  (sample & 0x3fff) >> 6
                    | P_16_BIT_MEM_LSB | ((sample & 0x3fff) << 2) && 0xff
                    | P_AF_BIT_MEM     | error
    ---------------------------------------------------------------------
    P_16_BIT_FILE   | P_8_BIT_MEM      |  (sample & 0xffff) >> 8
                    | P_16_BIT_MEM_LSB |  (sample & 0xffff)       && 0xff
                    | P_AF_BIT_MEM     | error
    ---------------------------------------------------------------------

• For unsigned short read functions:

Note that these are not all supported formats, just the most common ones; all possible combinations of file_data_fmt & mem_data_fmt are supported.

Note that conversion may be required even if the file_data_fmt is P_16_BIT_FILE and the mem_data_fmt is P_16_BIT_MEM due to the endian format. When writing, a file is stored in the endian mode of the platform. When reading on a platform with different endian mode, the LSB and MSB bytes are swapped.

    file_data_fmt   | mem_data_fmt    | conversion
    ----------------------------------------------------------------
    P_8_BIT_FILE    | P_8_BIT_MEM     | (sample & 0x00ff)
                    | P_16_BIT_MEM    | (sample & 0x00ff) << 8
                    | P_AF_BIT_MEM    | (sample)
    ----------------------------------------------------------------
    P_10_BIT_FILE   | P_10_BIT_MEM    | (sample & 0x03ff)
                    | P_16_BIT_MEM    | (sample & 0x03ff) << 6
                    | P_AF_BIT_MEM    | (sample)
    ----------------------------------------------------------------
    P_12_BIT_FILE   | P_12_BIT_MEM    | (sample & 0x0fff)
                    | P_16_BIT_MEM    | (sample & 0x0fff) << 4
                    | P_AF_BIT_MEM    | (sample)
    ----------------------------------------------------------------
    P_14_BIT_FILE   | P_14_BIT_MEM    | (sample & 0x3fff)
                    | P_16_BIT_MEM    | (sample & 0x3fff) << 2
                    | P_AF_BIT_MEM    | (sample)
    ----------------------------------------------------------------
    P_16_BIT_FILE   | P_16_BIT_MEM    | (sample)
                    | P_AF_BIT_MEM    | (sample)
    ----------------------------------------------------------------

Write functions

What is written to file is controlled by the "write_mode":

write_mode = mem_data_fmt

The header of the file controls the components that are written

Since the components that are written to disk only depend on the header, there is no component_mode used with the write functions.

    color_format    | written to file
    ---------------------------------
    P_NO_COLOR      | Y              *)
    ---------------------------------
    P_COLOR_422,    | Y, UV
    P_COLOR_420     |
    ---------------------------------
    P_COLOR_444_PL, | Y, U, V
    P_COLOR_422_PL, |
    P_COLOR_420_PL  |
    ---------------------------------
    P_COLOR_RGB     | R, G, B
    ---------------------------------
    P_STREAM        | S              *)
    ---------------------------------

    *) Only these buffers are read from the memory; pointers to
       other buffers (e.g. U/V) can be NULL pointers.

mem_data_fmt controls the data format that is written:

• For unsigned char write functions:

    file_data_fmt | conversion   
    --------------------------------------------
    P_8_BIT_FILE  | direct copy, no conversion
    --------------------------------------------
    P_10_BIT_FILE | (sample & 0x00ff) << 2
    --------------------------------------------
    P_12_BIT_FILE | (sample & 0x00ff) << 4
    --------------------------------------------
    P_14_BIT_FILE | (sample & 0x00ff) << 6
    --------------------------------------------
    P_16_BIT_FILE | (sample & 0x00ff) << 8
    --------------------------------------------

The mem_data_fmt is always P_8_BIT_MEM for these functions. Since mem_data_fmt is constant, these functions do not have the parameter write_mode as one of the function arguments.

• For unsigned short write functions:

Note that these are not all supported formats, just the most common ones; all possible combinations of file_data_fmt & mem_data_fmt are supported.

Note that the endian mode is not converted when writing a file since a file is always written in the endian mode of the current platform.

    file_data_fmt | mem_data_fmt    | conversion
    --------------------------------------------------------------
    P_8_BIT_FILE  | P_8_BIT_MEM     | (sample & 0x00ff)
                  | P_16_BIT_MEM    | (sample & 0xffff) >> 8
                  | P_AF_BIT_MEM    | (sample)
    --------------------------------------------------------------
    P_10_BIT_FILE | P_10_BIT_MEM    | (sample & 0x03ff)
                  | P_16_BIT_MEM    | (sample & 0xffff) >> 6
                  | P_AF_BIT_MEM    | (sample)
    --------------------------------------------------------------
    P_12_BIT_FILE | P_12_BIT_MEM    | (sample & 0x0fff)
                  | P_16_BIT_MEM    | (sample & 0xffff) >> 4
                  | P_AF_BIT_MEM    | (sample)
    --------------------------------------------------------------
    P_14_BIT_FILE | P_14_BIT_MEM    | (sample & 0x3fff)
                  | P_16_BIT_MEM    | (sample & 0xffff) >> 2
                  | P_AF_BIT_MEM    | (sample)
    --------------------------------------------------------------
    P_16_BIT_FILE | P_16_BIT_MEM    | (sample)
                  | P_AF_BIT_MEM    | (sample)
    --------------------------------------------------------------

Modules
group	Read/write functions
group	Component Mode
group	Memory data format

---