.TH fame_start_frame 3 "February 19th, 2002" "libfame" "fame_start_frame"
.SH NAME
fame_start_frame \- starts encoding of a frame
.SH SYNOPSIS
.nf
.B #include <fame.h>
.sp
.BI "void fame_start_frame(fame_context_t *" context ", fame_yuv_t *" yuv ", unsigned char *" shape );
.fi
.SH DESCRIPTION
.B fame_start_frame()
starts the encoding of an uncompressed frame from 
.I yuv
to a binary stream in  buffer, according to initialization parameters and optionnaly previously encoded frames. It should be called before starting processing slices with 
.I fame_encode_slice

Note that in the case of video sequences containing B frames, it is up to the caller to present frames in the encoder order. Since B frames require both previous and next reference frames, they must be presented after both previous and next reference frames have been coded. For example, a "IBBPBBP" coding sequence must be presented in "IPBBPBB" order. This presentation order is also the order in which the frames should be stored in a file or sent to a network.

.PP
.I context
is the context handle previously returned by 
.I fame_open
.PP
.I yuv
is a pointer to the input frame. Currently, only YV12 planar format, also called YUV 4:2:0, is supported. The YV12 planar format consists in three plane, one for the Y (luminance) and two for the Cr and Cb (chrominance) components, the chrominance planes being subsampled by 2x2. These three planes are mapped linearly in memory:
.sp
.nf
           width
yuv ->  +=========+
        |         |
        |    Y    | height
        |         |
        +====+====+
        | Cr | height / 2
        +====+
        | Cb | height / 2
        +====+
       width / 2
.fi
.sp
The process of converting RGB pictures to YUV12 will not be detailled here.
.PP
.I shape
represents the shape in case of video with arbitrary shape. 
It consists in a bitmap of 
.I width
x
.I height
bytes, with 255 representing an opaque pixel and 0 representing a transparent pixel. Values between 0 and 255 are not supported yet.
For rectangular video, this parameter must be set to NULL.

.SH "SEE ALSO"
.BR fame_open (3),
.BR fame_init (3),
.BR fame_close (3),
.BR fame_encode_slice (3),
.BR fame_end_frame (3)