[−][src]Crate dcv_color_primitives

DCV color primitives is a library to perform image color model conversion.

It is able to convert the following pixel formats:

BGRA8
RGBA8
BGR8

To the following destination pixel formats:

NV12 (single plane or biplanar 4:2:0)

Additionally, it is possible to convert the following pixel formats:

NV12 (single plane or biplanar 4:2:0)

To the following destination pixel formats:

BGRA8 (alpha is set to 255)

The supported color models are:

YCbCr, ITU-R Recommendation BT.601 (standard video system)
YCbCr, ITU-R Recommendation BT.709 (CSC systems)

Examples

Initialize the library:

use dcv_color_primitives as dcp;
fn main() {
    dcp::initialize();
}

Convert an image from bgra to nv12 (single plane) format, with Bt601 color space:

use dcv_color_primitives as dcp;
use dcp::{convert_image, ColorSpace, ImageFormat, PixelFormat};

fn convert() {
    dcp::initialize();

    const WIDTH: u32 = 640;
    const HEIGHT: u32 = 480;

    let src_buffers: &[&[u8]] = &[&[0u8; 4 * (WIDTH as usize) * (HEIGHT as usize)]];
    let dst_buffers: &mut [&mut [u8]] =
        &mut [&mut [0u8; 3 * (WIDTH as usize) * (HEIGHT as usize) / 2]];

    let src_format = ImageFormat {
        pixel_format: PixelFormat::Bgra,
        color_space: ColorSpace::Lrgb,
        num_planes: 1,
    };

    let dst_format = ImageFormat {
        pixel_format: PixelFormat::Nv12,
        color_space: ColorSpace::Bt601,
        num_planes: 1,
    };

    convert_image(
        WIDTH,
        HEIGHT,
        &src_format,
        None,
        src_buffers,
        &dst_format,
        None,
        dst_buffers,
    );
}

Handle conversion errors:

use dcv_color_primitives as dcp;
use dcp::{convert_image, ColorSpace, ImageFormat, PixelFormat};
use std::error;

fn convert() -> Result<(), Box<dyn error::Error>> {
    dcp::initialize();

    const WIDTH: u32 = 640;
    const HEIGHT: u32 = 480;

    let src_buffers: &[&[u8]] = &[&[0u8; 4 * (WIDTH as usize) * (HEIGHT as usize)]];
    let dst_buffers: &mut [&mut [u8]] =
        &mut [&mut [0u8; 3 * (WIDTH as usize) * (HEIGHT as usize) / 2]];

    let src_format = ImageFormat {
        pixel_format: PixelFormat::Bgra,
        color_space: ColorSpace::Bt709,
        num_planes: 1,
    };

    let dst_format = ImageFormat {
        pixel_format: PixelFormat::Nv12,
        color_space: ColorSpace::Bt601,
        num_planes: 1,
    };

    convert_image(
        WIDTH,
        HEIGHT,
        &src_format,
        None,
        src_buffers,
        &dst_format,
        None,
        dst_buffers,
    )?;

    Ok(())
}

Compute how many bytes are needed to store and image of a given format and size:

use dcv_color_primitives as dcp;
use dcp::{get_buffers_size, ColorSpace, ImageFormat, PixelFormat};
use std::error;

fn compute_size() -> Result<(), Box<dyn error::Error>> {
    dcp::initialize();

    const WIDTH: u32 = 640;
    const HEIGHT: u32 = 480;
    const NUM_PLANES: u32 = 1;

    let format = ImageFormat {
        pixel_format: PixelFormat::Bgra,
        color_space: ColorSpace::Lrgb,
        num_planes: NUM_PLANES,
    };

    let sizes: &mut [usize] = &mut [0usize; NUM_PLANES as usize];
    get_buffers_size(WIDTH, HEIGHT, &format, None, sizes)?;

    let buffer: Vec<_> = vec![0u8; sizes[0]];

    // Do something with buffer
    // --snip--

    Ok(())
}

Provide image planes to hangle data scattered in multiple buffers that are not necessarily contiguous:

use dcv_color_primitives as dcp;
use dcp::{convert_image, get_buffers_size, ColorSpace, ImageFormat, PixelFormat};
use std::error;

fn convert() -> Result<(), Box<dyn error::Error>> {
    dcp::initialize();

    const WIDTH: u32 = 640;
    const HEIGHT: u32 = 480;
    const NUM_SRC_PLANES: u32 = 2;
    const NUM_DST_PLANES: u32 = 1;

    let src_format = ImageFormat {
        pixel_format: PixelFormat::Nv12,
        color_space: ColorSpace::Bt709,
        num_planes: NUM_SRC_PLANES,
    };

    let src_sizes: &mut [usize] = &mut [0usize; NUM_SRC_PLANES as usize];
    get_buffers_size(WIDTH, HEIGHT, &src_format, None, src_sizes)?;

    let src_y: Vec<_> = vec![0u8; src_sizes[0]];
    let src_uv: Vec<_> = vec![0u8; src_sizes[1]];
    let src_buffers: &[&[u8]] = &[&src_y[..], &src_uv[..]];

    let dst_format = ImageFormat {
        pixel_format: PixelFormat::Bgra,
        color_space: ColorSpace::Lrgb,
        num_planes: NUM_DST_PLANES,
    };

    let dst_sizes: &mut [usize] = &mut [0usize; NUM_DST_PLANES as usize];
    get_buffers_size(WIDTH, HEIGHT, &dst_format, None, dst_sizes)?;

    let mut dst_rgba: Vec<_> = vec![0u8; dst_sizes[0]];
    let dst_buffers: &mut [&mut [u8]] = &mut [&mut dst_rgba[..]];

    convert_image(
        WIDTH,
        HEIGHT,
        &src_format,
        None,
        src_buffers,
        &dst_format,
        None,
        dst_buffers,
    )?;

    Ok(())
}

Provide image strides to convert data which is not tightly packed:

use dcv_color_primitives as dcp;
use dcp::{convert_image, get_buffers_size, ColorSpace, ImageFormat, PixelFormat};
use std::error;

fn convert() -> Result<(), Box<dyn error::Error>> {
    dcp::initialize();

    const WIDTH: u32 = 640;
    const HEIGHT: u32 = 480;
    const NUM_SRC_PLANES: u32 = 1;
    const NUM_DST_PLANES: u32 = 2;
    const RGB_STRIDE: usize = 4 * (((3 * (WIDTH as usize)) + 3) / 4);

    let src_format = ImageFormat {
        pixel_format: PixelFormat::Bgr,
        color_space: ColorSpace::Lrgb,
        num_planes: NUM_SRC_PLANES,
    };

    let src_strides: &[usize] = &[RGB_STRIDE];

    let src_sizes: &mut [usize] = &mut [0usize; NUM_SRC_PLANES as usize];
    get_buffers_size(WIDTH, HEIGHT, &src_format, Some(src_strides), src_sizes)?;

    let src_rgba: Vec<_> = vec![0u8; src_sizes[0]];
    let src_buffers: &[&[u8]] = &[&src_rgba[..]];

    let dst_format = ImageFormat {
        pixel_format: PixelFormat::Nv12,
        color_space: ColorSpace::Bt709,
        num_planes: NUM_DST_PLANES,
    };

    let dst_sizes: &mut [usize] = &mut [0usize; NUM_DST_PLANES as usize];
    get_buffers_size(WIDTH, HEIGHT, &dst_format, None, dst_sizes)?;

    let mut dst_y: Vec<_> = vec![0u8; dst_sizes[0]];
    let mut dst_uv: Vec<_> = vec![0u8; dst_sizes[1]];
    let dst_buffers: &mut [&mut [u8]] = &mut [&mut dst_y[..], &mut dst_uv[..]];

    convert_image(
        WIDTH,
        HEIGHT,
        &src_format,
        Some(src_strides),
        src_buffers,
        &dst_format,
        None,
        dst_buffers,
    )?;

    Ok(())
}

Structs

ImageFormat

Describes how the image data is laid out in memory and its color space.

Enums

ColorSpace	An enumeration of supported color models.
ErrorKind	An enumeration of errors.
PixelFormat	An enumeration of supported pixel formats.

Constants

STRIDE_AUTO

If a plane stride is assigned to this constant, the plane will be assumed to contain packed data

Functions

convert_image	Converts from a color space to another one, applying downsampling/upsampling to match destination image format.
describe_acceleration	Returns a description of the algorithms that are best for the running cpu and available instruction sets
get_buffers_size	Compute number of bytes required to store an image given its format, dimensions and optionally its strides
initialize	Automatically initializes the library functions that are most appropriate for the current processor type.