## ucil

ucil

## Synopsis

    #define             UCIL_FOURCC                         (a,b,c,d)
    typedef             ucil_rgb24_t;
    typedef             ucil_rgb32_t;
    typedef             ucil_yuv_t;
    typedef             ucil_y8_t;
    typedef             ucil_color_t;
    void                ucil_convolution_mask               (unicap_data_buffer_t *dest,
                                                             unicap_data_buffer_t *src,
                                                             ucil_convolution_mask_t *mask);
    typedef             ucil_convolution_mask_t;
    typedef             ucil_font_object_t;
    typedef             ucil_video_file_object_t;
    unicap_status_t     ucil_check_version                  (unsigned int major,
                                                             unsigned int minor,
                                                             unsigned int micro);
    void                ucil_set_pixel                      (unicap_data_buffer_t *data_buffer,
                                                             ucil_color_t *color,
                                                             int x,
                                                             int y);
    void                ucil_set_pixel_alpha                (unicap_data_buffer_t *data_buffer,
                                                             ucil_color_t *color,
                                                             int alpha,
                                                             int x,
                                                             int y);
    void                ucil_draw_line                      (unicap_data_buffer_t *data_buffer,
                                                             ucil_color_t *color,
                                                             int x1,
                                                             int y1,
                                                             int x2,
                                                             int y2);
    void                ucil_draw_rect                      (unicap_data_buffer_t *data_buffer,
                                                             ucil_color_t *color,
                                                             int x1,
                                                             int y1,
                                                             int x2,
                                                             int y2);
    void                ucil_fill                           (unicap_data_buffer_t *data_buffer,
                                                             ucil_color_t *color);
    void                ucil_draw_box                       (unicap_data_buffer_t *data_buffer,
                                                             ucil_color_t *color,
                                                             int x1,
                                                             int y1,
                                                             int x2,
                                                             int y2);
    void                ucil_draw_circle                    (unicap_data_buffer_t *dest,
                                                             ucil_color_t *color,
                                                             int cx,
                                                             int cy,
                                                             int r);
    ucil_font_object_t* ucil_create_font_object             (int size,
                                                             const char *font);
    void                ucil_draw_text                      (unicap_data_buffer_t *dest,
                                                             ucil_color_t *color,
                                                             ucil_font_object_t *fobj,
                                                             const char *text,
                                                             int x,
                                                             int y);
    void                ucil_destroy_font_object            (ucil_font_object_t *fobj);
    void                ucil_text_get_size                  (ucil_font_object_t *fobj,
                                                             const char *text,
                                                             int *width,
                                                             int *height);
    void                ucil_get_pixel                      (unicap_data_buffer_t *data_buffer,
                                                             ucil_color_t *color,
                                                             int x,
                                                             int y);
    void                ucil_convert_color                  (ucil_color_t *src,
                                                             ucil_color_t *dest);
    unicap_status_t     ucil_convert_buffer                 (unicap_data_buffer_t *dest,
                                                             unicap_data_buffer_t *src);
    int                 ucil_conversion_supported           (unsigned int dest_fourcc,
                                                             unsigned int src_fourcc);
    ucil_colorspace_t   ucil_get_colorspace_from_fourcc     (unsigned int fourcc);
    void                ucil_blend_alpha                    (unicap_data_buffer_t *dest,
                                                             unicap_data_buffer_t *bg,
                                                             unicap_data_buffer_t *fg,
                                                             int alpha);
    ucil_convolution_mask_t* ucil_create_convolution_mask   (unsigned char *array,
                                                             int size,
                                                             ucil_colorspace_t cs,
                                                             int mode);
    ucil_video_file_object_t* ucil_create_video_file        (const char *path,
                                                             unicap_format_t *format,
                                                             const char *codec,
                                                             ...);
    unicap_status_t     ucil_encode_frame                   (ucil_video_file_object_t *vobj,
                                                             unicap_data_buffer_t *buffer);
    unicap_status_t     ucil_close_video_file               (ucil_video_file_object_t *vobj);
    unicap_status_t     ucil_open_video_file                (unicap_handle_t *unicap_handle,
                                                             char *filename);
    const char*         ucil_get_video_file_extension       (const char *codec);

## Description

## Details

### UCIL_FOURCC()

    #define UCIL_FOURCC(a,b,c,d) (unsigned int)((((unsigned int)d)<<24)+(((unsigned int)c)<<16)+(((unsigned int)b)<<8)+a)

`a` : |
`b` : |
`c` : |
`d` : |

### ucil_rgb24_t

    typedef struct ucil_rgb24_t ucil_rgb24_t;

### ucil_rgb32_t

    typedef struct ucil_rgb32_t ucil_rgb32_t;

### ucil_yuv_t

    typedef struct ucil_yuv_t ucil_yuv_t;

### ucil_y8_t

    typedef struct ucil_y8_t ucil_y8_t;

### ucil_color_t

    typedef struct ucil_color_t ucil_color_t;

### ucil_convolution_mask ()

    void                ucil_convolution_mask               (unicap_data_buffer_t *dest,
                                                             unicap_data_buffer_t *src,
                                                             ucil_convolution_mask_t *mask);

Apply a convolution mask

`dest` : | target buffer
`src` : | source buffer
`mask` : | an ucil_convolution_mask

### ucil_convolution_mask_t

    typedef struct ucil_convolution_mask_t ucil_convolution_mask_t;

### ucil_font_object_t

    typedef struct ucil_font_object_t ucil_font_object_t;

### ucil_video_file_object_t

    typedef struct ucil_video_file_object_t ucil_video_file_object_t;

### ucil_check_version ()

    unicap_status_t     ucil_check_version                  (unsigned int major,
                                                             unsigned int minor,
                                                             unsigned int micro);

`major` : |
`minor` : |
`micro` : |
Returns : |

### ucil_set_pixel ()

    void                ucil_set_pixel                      (unicap_data_buffer_t *data_buffer,
                                                             ucil_color_t *color,
                                                             int x,
                                                             int y);

Draws a pixel on the data buffer.

`data_buffer` : |
`color` : |
`x` : |
`y` : |

### ucil_set_pixel_alpha ()

    void                ucil_set_pixel_alpha                (unicap_data_buffer_t *data_buffer,
                                                             ucil_color_t *color,
                                                             int alpha,
                                                             int x,
                                                             int y);

Draws a pixel on the data buffer, applying an alpha ( transparency ) value to the pixel.

`data_buffer` : | target buffer
`color` : | an ucil_color_t. The colorspace of the color has to match the colorspace of the data_buffer.
`alpha` : | the alpha value that should be applied to this pixel
`x` : | x position
`y` : | y position

### ucil_draw_line ()

    void                ucil_draw_line                      (unicap_data_buffer_t *data_buffer,
                                                             ucil_color_t *color,
                                                             int x1,
                                                             int y1,
                                                             int x2,
                                                             int y2);

Draws a line on the data buffer. The endpoints are clipped to the buffer dimensions

`data_buffer` : |
`color` : |
`x1` : |
`y1` : |
`x2` : |
`y2` : |

### ucil_draw_rect ()

    void                ucil_draw_rect                      (unicap_data_buffer_t *data_buffer,
                                                             ucil_color_t *color,
                                                             int x1,
                                                             int y1,
                                                             int x2,
                                                             int y2);

Draws a rectangle filled with color.

`data_buffer` : |
`color` : |
`x1` : |
`y1` : |
`x2` : |
`y2` : |

### ucil_fill ()

    void                ucil_fill                           (unicap_data_buffer_t *data_buffer,
                                                             ucil_color_t *color);

Fill the buffer with a color.

`data_buffer` : |
`color` : |

### ucil_draw_box ()

    void                ucil_draw_box                       (unicap_data_buffer_t *data_buffer,
                                                             ucil_color_t *color,
                                                             int x1,
                                                             int y1,
                                                             int x2,
                                                             int y2);

Draws a box

`data_buffer` : |
`color` : |
`x1` : |
`y1` : |
`x2` : |
`y2` : |

### ucil_draw_circle ()

    void                ucil_draw_circle                    (unicap_data_buffer_t *dest,
                                                             ucil_color_t *color,
                                                             int cx,
                                                             int cy,
                                                             int r);

Draws a circle.

`dest` : |
`color` : | an ucil_color_t. The colorspace of the color has to match the colorspace of the data_buffer.
`cx` : | center of the circle ( x position )
`cy` : | center of the circle ( y position )
`r` : | radius

### ucil_create_font_object ()

    ucil_font_object_t* ucil_create_font_object             (int size,
                                                             const char *font);

Creates a font object required for text operations. The application must free the font object with ucil_destroy_font_object.

`size` : | size of font in points
`font` : | name of font or NULL to use default font
Returns : | a new ucil_font_object_t

### ucil_draw_text ()

    void                ucil_draw_text                      (unicap_data_buffer_t *dest,
                                                             ucil_color_t *color,
                                                             ucil_font_object_t *fobj,
                                                             const char *text,
                                                             int x,
                                                             int y);

Draws a text string onto the target buffer.

`dest` : | target buffer
`color` : | an ucil_color_t. The colorspace of the color has to match the colorspace of the data_buffer.
`fobj` : | an ucil_font_object_t
`text` : | text string to draw
`x` : | x position
`y` : | y position

### ucil_destroy_font_object ()

    void                ucil_destroy_font_object            (ucil_font_object_t *fobj);

Frees all resources allocated by the font object

`fobj` : |

### ucil_text_get_size ()

    void                ucil_text_get_size                  (ucil_font_object_t *fobj,
                                                             const char *text,
                                                             int *width,
                                                             int *height);

Determines the size in pixels a text string will take up when drawn onto a buffer.

`fobj` : | an ucil_font_object_t
`text` : | text string
`width` : | pointer to int which will receive the width of the text
`height` : | pointer to int which will receive the height of the text

### ucil_get_pixel ()

    void                ucil_get_pixel                      (unicap_data_buffer_t *data_buffer,
                                                             ucil_color_t *color,
                                                             int x,
                                                             int y);

Reads the pixel at position (x,y) and stores the result in `color`.

`data_buffer` : | buffer
`color` : | pointer to an ucil_color_t to store the result
`x` : | x position
`y` : | y position

### ucil_convert_color ()

    void                ucil_convert_color                  (ucil_color_t *src,
                                                             ucil_color_t *dest);

Convert colors between colorspaces. The `colorspace` field of dest needs to be set to the target colorspace, like in this example:

    src.colorspace = UCIL_COLORSPACE_RGB24;
    src.rgb24.r = 0xff;
    src.rgb24.g = 0xff;
    src.rgb24.b = 0xff;
    dest.colorspace = UCIL_COLORSPACE_YUV;
    ucil_convert_color( &dest, &src );

`src` : |
`dest` : |

### ucil_convert_buffer ()

    unicap_status_t     ucil_convert_buffer                 (unicap_data_buffer_t *dest,
                                                             unicap_data_buffer_t *src);

Convert the colorspace of a data buffer. The colorspaces are denoted by the `buffer.format.fourcc` field. The dest->format.fourcc gets set to the correct value.

`dest` : | target buffer
`src` : | source buffer
Returns : | STATUS_SUCCESS if the buffer could be converted successfully. STATUS_FAILURE if no conversion exists.

### ucil_conversion_supported ()

    int                 ucil_conversion_supported           (unsigned int dest_fourcc,
                                                             unsigned int src_fourcc);

Tests whether a specific conversion is supported.

`dest_fourcc` : | target fourcc
`src_fourcc` : | source fourcc
Returns : | 1 when the conversion is supported

### ucil_get_colorspace_from_fourcc ()

    ucil_colorspace_t   ucil_get_colorspace_from_fourcc     (unsigned int fourcc);

Gets the ucil_colorspace_t that matches the fourcc.

`fourcc` : | fourcc
Returns : | an ucil_colorspace_t. This is UCIL_COLORSPACE_UNKNOWN when no conversion exists.

### ucil_blend_alpha ()

    void                ucil_blend_alpha                    (unicap_data_buffer_t *dest,
                                                             unicap_data_buffer_t *bg,
                                                             unicap_data_buffer_t *fg,
                                                             int alpha);

Blends two buffers into a target buffer. Colorspaces of buffers should match.

`dest` : | target buffer
`bg` : | background buffer
`fg` : | foreground buffer
`alpha` : | transparency value

### ucil_create_convolution_mask ()

    ucil_convolution_mask_t* ucil_create_convolution_mask   (unsigned char *array,
                                                             int size,
                                                             ucil_colorspace_t cs,
                                                             int mode);

`array` : |
`size` : |
`cs` : |
`mode` : |
Returns : |

### ucil_create_video_file ()

    ucil_video_file_object_t* ucil_create_video_file        (const char *path,
                                                             unicap_format_t *format,
                                                             const char *codec,
                                                             ...);

Creates a video file to be used for video recording. After creation, add frames to the video file with ucil_encode_frame.

`path` : | filename with full path
`format` : | image format of individual frames
`codec` : | codec name or NULL to use default codec
`...` : |
Returns : | A new ucil_video_file_object_t or NULL on error.

### ucil_encode_frame ()

    unicap_status_t     ucil_encode_frame                   (ucil_video_file_object_t *vobj,
                                                             unicap_data_buffer_t *buffer);

Adds a frame to a video file.

`vobj` : | a video file object
`buffer` : | data buffer
Returns : | STATUS_SUCCESS if the frame got added successfully.

### ucil_close_video_file ()

    unicap_status_t     ucil_close_video_file               (ucil_video_file_object_t *vobj);

Close a video file created with ucil_create_video_file

`vobj` : | an ucil_video_file_object
Returns : |

### ucil_open_video_file ()

    unicap_status_t     ucil_open_video_file                (unicap_handle_t *unicap_handle,
                                                             char *filename);

Opens a video file for playback. The resulting handle can be used like a video capture device.

`unicap_handle` : | pointer to an unicap_handle_t where the new handle gets stored.
`filename` : | full path of the video file
Returns : |

### ucil_get_video_file_extension ()

    const char*         ucil_get_video_file_extension       (const char *codec);

Get the file extension of a codec. Eg. for the "ogg/theora" codec, this will return "ogg". The returned string is owned by ucil and should not be freed.

`codec` : | codec name
Returns : | string