Update Copyright

[rawv.git] / rawv.h

#ifndef _RAWV_H_
#define _RAWV_H_

/*
 *  RAWV coding-scheme for low-latency loosless video streaming
 *  Copyright (C) 2010  Kirill Smelkov <kirr@navytux.spb.ru>
 *
 *  You may use and redistribute this work under the Creative Commons
 *  Attribution-Share Alike (CC-BY-SA) 3.0. You are free to Share (to copy,
 *  distribute, display, and perform the work) and to Remix (to make derivative
 *  works), under the following conditions:
 *
 *  1. Attribution. You must attribute the work in the manner specified by the
 *     author or licensor (but not in any way that suggests that they endorse you
 *     or your use of the work).
 *  2. Share Alike. If you alter, transform, or build upon this work, you may
 *     distribute the resulting work only under the same, similar or a compatible
 *     license.
 *
 *
 *  Abstract
 *  --------
 *
 *  A scheme for transmitting progressive PAL/NTSC video over 1Gbps Ethernet
 *  LAN is presented. Loosless coding, low end-to-end latencies (under 100ms in
 *  non-specialized test setup) and packet loss tolerance make this scheme
 *  applicable for specialized tasks in medical, industrial and military
 *  environments.  Development effort for both software and hardware
 *  implementations is shown to be low because of design simplicity.
 *
 *
 *  Coding
 *  ------
 *
 *  - each frame is transmitted in series of independent fragments
 *  - each fragment carries header and payload
 *  - header:
 *
 *    1. special 4-byte magic identifying this coding method,
 *    2. version of coding subvariant and fragment flags,
 *    3. fragment's frame sequence number,
 *    4. fragment sequence number and number of fragments in the whole frame,
 *    5. width, height and pixel format of its frame,
 *    6. fragment startline and number of lines in this fragment,
 *    7. padding;
 *
 *
 *                       < - - - - - - w i d t h - - - - - - >
 *                       +-----------------------------------+ ^
 *                       |                                   | |
 *                       |                                   | |
 *                       |                                   | |
 *                       |                                   |
 *     frag_startline -->|-----------------------------------| h
 *                       |  '                                | e
 *                       |  ' frag_nlines                    | i
 *                       |  '                                | g
 *                       |-----------------------------------| h
 *                       |                                   | t
 *                       |                                   |
 *                       |                                   | |
 *                       |                                   | |
 *                       |                                   | |
 *                       +-----------------------------------+ v
 *
 *
 *
 *           0                   1                   2                   3
 *           0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 *          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 *        0 |    0x52 ('R') |    0x41 ('A') |    0x57 ('W') |    0x56 ('V') |
 *          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 *       32 |    Version    |     Flags     |         Frame Number          |
 *          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 *       64 |       Fragment Number         |        Fragments Total        |
 *          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 *       96 |         Frame Width           |         Frame Height          |
 *          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 *      128 |                          Pixel Format                         |
 *          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 *      160 |     Fragment Startline        |        Fragment Lines         |
 *          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 *      192 |                            Reserved                           |
 *          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 *      224 |                            Reserved                           |
 *          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 *
 *
 *    Version
 *       Version of coding used. This specification describes coding for
 *       version 0x01.
 *
 *    Flags
 *       This field is currently reserved to be 0x00.
 *
 *    Frame Number  (nframe)
 *       Sequence number of this fragment's frame.
 *
 *    Fragment Number  (nfragment)
 *       Sequence number of this fragment. Starts from 0 for each new frame.
 *
 *    Fragments Total  (fragments_total)
 *       Total number of fragments in current frame.
 *
 *    Frame Width  (width)
 *       Frame width in pixels.
 *
 *    Frame Height  (height)
 *       Frame height in pixels.
 *
 *    Pixel Format  (pixfmt)
 *       According to http://fourcc.org/yuv.php; recommended are YUYV, YUY2,
 *       UYVY, GREY, Y800 and Y8.
 *
 *    Fragment Startline  (frag_startline)
 *       Vertical position of this fragment's first line relative to frame top.
 *
 *    Fragment Lines  (frag_nlines)
 *       Number of lines in this fragment.
 *
 *
 *  - payload:
 *
 *    1. right after header go raw pixel data in specified-in-header pixel format.
 *       There should be data for at least
 *
 *          frag_nlines * width                     (1)
 *
 *       pixels, which is
 *
 *          frag_nlines * width * pixsize(pixfmt)   (2)
 *
 *       bytes.
 *
 *    2. there could be more data than specified in (2). in such a case,
 *       trailer content is out of this specification scope.
 *
 *
 * TODO talk about packet reordering
 * TODO talk about packet loss
 * TODO talk about needed bandwith for typical streams
 *       (PAL color, PAL mono, NTSC color, NTSC mono)
 *
 *
 * References:
 *
 * [1] RFC3550 -- RTP: A Transport Protocol for Real-Time Applications
 * [2] RFC3551 -- RTP Profile for Audio and Video Conferences with Minimal Control
 * [3] RFC4175 -- RTP Payload Format for Uncompressed Video
 * [4] IIDC 1394-based Digital Camera Specification Ver.1.32
 * [5] MPEG-TS (?)
 *
 */

/*
 *  RAWV library
 *  Copyright (C) 2010,2011  Kirill Smelkov <kirr@navytux.spb.ru>
 *  Copyright (C) 2011  Marine Bridge and Navigation Systems (http://mns.spb.ru/)
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */

#include <asm/types.h>
#include <sys/types.h>
#include <stdexcept>

#include <vector>
#include <arpa/inet.h>

struct SDL_Surface;
struct SDL_Overlay;

namespace rawv {

using std::vector;


/* XXX endiannes ? */
#define MKTAG32(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))


/*
 * RAWV packet header
 */
#pragma pack(push, 1)
struct rawv_header {
    __u32   magic;

    __u8    version;
    __u8    __reserved_for_flags;
    __u16   nframe;
// XXX here ?
#define NFRAME_MAX  0x10000

    __u16   nfragment;
    __u16   fragments_total;

    __u16   width;
    __u16   height;

    __u32   pixfmt;

    __u16   frag_startline;
    __u16   frag_nlines;

    /* padding, so that the whole header is 32 bytes */
    __u32   __reserved[2];
};
#pragma pack(pop)

/*
 * One video frame
 */
struct Frame {
    __u8       *start;
    size_t      length; /* ~= height * bytesperline */

    int         width, height, bytesperline;
    __u32       pixfmt_4cc;
    __u32       sequence;
    // XXX timestamp ?

    /* flags */

    /* if we know top/bottom fields are in wrong order in this frame
     *
     * +1   -- swap fields
     * -1   -- swap and shift one filed XXX write more
     */
    signed int  interlace_tb_swapped    : 2;
};

struct FrameSubscription {
    void (*func)(const Frame *, void *);
    void  *self;

    bool operator== (const FrameSubscription &rhs)
    {
        return (func == rhs.func) && (self == rhs.self);
    }
};


/*
 * Displays video frames to YUY2 overlay
 */
struct View
{
    View(int w, int h, bool upscale, const char *title);
    ~View();

    /* whether to upscale frame on display.
     *
     * NOTE: only upscale is supported, not downscale
     */
    bool upscale;

    void display_frame(const Frame *f);
    static void __display_frame(const Frame *f, void *self);


    SDL_Surface *display;
    SDL_Overlay *overlay;
};


/*
 * Captures video frames from V4L2 source
 */
struct VideoCapture
{
    VideoCapture(const char *dev_name, int width, int height, int interlace_tb_swapped=0, int queue_len=4);
    ~VideoCapture();

    void start_capture();
    void stop_capture();

    void subscribe(void (*func)(const Frame *, void *), void *self);
    void unsubscribe(void (*func)(const Frame *, void *), void *self);

    // XXX naming
    int  read_frame();



    int fd;

    vector<Frame> buffers;
    vector<FrameSubscription> subscribers;

    bool vcapture_on;

};


/*
 * Sends video frames to network
 */
struct NetTx
{
    NetTx(const char *dest, int port, int mtu);
    ~NetTx();

    void tx_frame(const Frame *f);
    static void __tx_frame(const Frame *f, void *self);

    int sk;
    struct sockaddr_in tx_addr;
    int mtu;
};


/*
 * Receives video frames from network
 */
struct NetRx
{
    NetRx(const char *listen_on, int port, int mtu);
    ~NetRx();

    void subscribe(void (*func)(const Frame *, void *), void *self);
    void unsubscribe(void (*func)(const Frame *, void *), void *self);

    int handle_recv();
    void __handle_recv(unsigned len);


    int sk;
    struct sockaddr_in rx_addr;
    int mtu;

    vector<FrameSubscription> subscribers;
    void flush_frame();

    vector<__u8> fragbuf;   // XXX align?
    vector<__u8> framebuf;  // XXX align?

    struct Frame f; /* current frame */

    /* current rx state */
    __u16 nframe, nfragment, fragments_total;
    __u16 frag_received;        /* # of fragments received in current frame */
    __u32 frag_dropped_total;   /* total # of dropped fragments */
};


/* XXX is this a good idea ? */
struct RawvError : std::runtime_error
{
    RawvError(const char *msg);
    ~RawvError() throw();
};

void die(const char *fmt, ...);
void die_errno(const char *msg);
void warn(const char *fmt, ...);
void warn_errno(const char *msg);

}   /* rawv:: */

#endif