V4LCapture.cpp

Go to the documentation of this file.

/* ---------------------------------------------------------------------------
    Phission : 
        Realtime Vision Processing System
    
    Copyright (C) 2003-2006 Philip D.S. Thoren (pthoren@cs.uml.edu)
    University of Massachusetts at Lowell,
    Laboratory for Artificial Intelligence and Robotics
    
    This file is part of Phission.

    Phission 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 of the License, or
    (at your option) any later version.

    Phission 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 Phission; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 ---------------------------------------------------------------------------*/
/* ---------------------------------------------------------------------- */
/* plugins/camera/v4l/V4LCapture.cpp
 *      Improved upon previous V4LCapture class that was in camera/v4l/V4LCapture.cpp
 * 
 *      V4LCapture object now allows more control by the user in terms of
 *      when to start capturing and what to do with the data.
 *
 *      The data can be passed or taken by any object that knows
 *      how to work with the phImage class. (It doesn't take 
 *      a rocket scientist to figure it out.)
 *
 *      When a capture is started, a thread is spawned to handle transfers
 *      of the image from the mmapped hw_buffer to the phImage
 *      buffer. There is always a full fresh image waiting to be accessed
 *      while capturing is being done.
 *
 *      When the capture is stopped, the phImage buffer retains it's 
 *      last frame until the V4LCapture object is destroyed or a new capture 
 *      session is started.
 * 
 * ---------------------------------------------------------------------- *
 * TODO:
 *  - use capabilities structure to limit image settings.
 *  - allow picture format setting while capture is in progress ?
 *  
 *
 *
 * ---------------------------------------------------------------------- */
/* ---------------------------------------------------------------------- *
 * possible events which each class method/function must check if the 
 * event is relevant to the function's proper execution.
 * 
 *      (1)device open/(2)closed. 
 *      (3)capture running/(4)stopped
 *      (5)hw buffers mapped/(6)unmapped 
 *       
 *------------------------------------------------------------------------*/
#ifdef HAVE_CONFIG_H
    #include <phissionconfig.h>
#endif

/* ---------------------------------------------------------------------- */
#if defined(HAVE_STDIO_H)
    #include <stdio.h>
#endif
#if defined(HAVE_STDLIB_H)
    #include <stdlib.h>
#endif
#if defined(HAVE_STRING_H)
    #include <string.h>
#endif
#if defined(HAVE_UNISTD_H)
    #include <unistd.h>
#endif
#if defined(HAVE_SYS_FCNTL_H)
    #include <sys/fcntl.h>
#endif
#if defined(HAVE_SYS_MMAN_H)
    #include <sys/mman.h>
#endif
#if defined(HAVE_SYS_IOCTL_H)
    #include <sys/ioctl.h>
#endif
#if defined(HAVE_ERRNO_H)
    #include <errno.h>
#endif
#if defined(HAVE_LINUX_VIDEODEV_H)
    #include <linux/videodev.h>
#endif

#define V4L_MAX_HWBUFFERS 32

/* ---------------------------------------------------------------------- */
#include <phStandard.h>
#include <ImageConversions.h>
#include <V4LCapture.h>

#define TIMESTUFF() 0
#if TIMESTUFF()
    #include <phTime.h>
#endif

#include <phError.h>
#include <phMemory.h>
#include <phPrint.h>

#ifdef __cplusplus
extern "C" {
#endif
           
/* ---------------------------------------------------------------------- */
void v4l_print_video_capability( struct video_capability caps )
{   
    phPRINT("struct video_capability\n[\n");
    phPRINT("\tname         : %s\n",    caps.name );
    phPRINT("\ttype         : 0x%08x\n",    caps.type );
    phPRINT("\t(type) ");
    if (caps.type & VID_TYPE_CAPTURE)       phPRINT("CAPTURE ");
    if (caps.type & VID_TYPE_TUNER)         phPRINT("TUNER ");
    if (caps.type & VID_TYPE_TELETEXT)      phPRINT("TELETEXT ");
    if (caps.type & VID_TYPE_OVERLAY)       phPRINT("OVERLAY ");
    if (caps.type & VID_TYPE_CHROMAKEY)     phPRINT("CHROMAKEY ");
    if (caps.type & VID_TYPE_CLIPPING)      phPRINT("CLIPPING ");
    if (caps.type & VID_TYPE_FRAMERAM)      phPRINT("FRAMERAM ");
    if (caps.type & VID_TYPE_SCALES )       phPRINT("SCALES  ");
    if (caps.type & VID_TYPE_MONOCHROME)    phPRINT("MONOCHROME ");
    if (caps.type & VID_TYPE_SUBCAPTURE )   phPRINT("SUBCAPTURE  ");
    if (caps.type & VID_TYPE_MPEG_DECODER)  phPRINT("MPEG_DECODER ");
    if (caps.type & VID_TYPE_MPEG_ENCODER)  phPRINT("MPEG_ENCODER ");
    if (caps.type & VID_TYPE_MJPEG_DECODER) phPRINT("MJPEG_DECODER ");
    if (caps.type & VID_TYPE_MJPEG_ENCODER) phPRINT("MJPEG_ENCODER ");
    phPRINT("\n");
    phPRINT("\tchannels     : %d\n",    caps.channels );
    phPRINT("\taudios       : %d\n",    caps.audios );
    phPRINT("\tmax width    : %d\n",    caps.maxwidth );
    phPRINT("\tmax height   : %d\n",    caps.maxheight );
    phPRINT("\tmin width    : %d\n",    caps.minwidth );
    phPRINT("\tmin height   : %d\n",    caps.minheight );
    phPRINT("]\n");
}

/* ---------------------------------------------------------------------- */
void v4l_print_video_channel( struct video_channel chan )
{   
    phPRINT("struct video_channel\n[\n");
    phPRINT("\tchannel  : %d\n",chan.channel);
    phPRINT("\tname     : %s\n",chan.name);
    phPRINT("\ttuners   : %d\n",chan.tuners);
    phPRINT("\tflags    : 0x%08x\n",chan.flags);
    phPRINT("\t  tuner  : %d\n",chan.flags & VIDEO_VC_TUNER ? 1 : 0);
    phPRINT("\t  audio  : %d\n",chan.flags & VIDEO_VC_AUDIO ? 1 : 0);
    phPRINT("\ttype     : %hu\n",chan.type);
    phPRINT("\t  tv     : %d\n",chan.type & VIDEO_TYPE_TV ? 1 : 0);
    phPRINT("\t  camera : %d\n",chan.type & VIDEO_TYPE_CAMERA ? 1 : 0);
    phPRINT("\tnorm     : %hu\n",chan.norm);
    phPRINT("\t(norm) ");
    if (chan.norm == VIDEO_MODE_PAL) phPRINT("PAL ");
    if (chan.norm == VIDEO_MODE_NTSC) phPRINT("NTSC ");
    if (chan.norm == VIDEO_MODE_SECAM) phPRINT("SECAM ");
    if (chan.norm == VIDEO_MODE_AUTO) phPRINT("AUTO ");
    phPRINT("\n]\n");
}
    
/* ---------------------------------------------------------------------- */
void v4l_print_video_picture( struct video_picture pict )
{   
    char *palette_name = NULL;
    char *palette_type = NULL;
    const char *palette_names[] = {
                "unknown",
                "VIDEO_PALETTE_GREY",
                "VIDEO_PALETTE_HI240",
                "VIDEO_PALETTE_RGB565",
                "VIDEO_PALETTE_RGB24",
                "VIDEO_PALETTE_RGB32",
                "VIDEO_PALETTE_RGB555",
                "VIDEO_PALETTE_YUV422",
                "VIDEO_PALETTE_YUYV",
                "VIDEO_PALETTE_UYVY",
                "VIDEO_PALETTE_YUV420",
                "VIDEO_PALETTE_YUV411",
                "VIDEO_PALETTE_RAW",
                "VIDEO_PALETTE_YUV422P",
                "VIDEO_PALETTE_YUV411P",
                "VIDEO_PALETTE_YUV420P",
                "VIDEO_PALETTE_YUV410P" };


    phPRINT("struct video_picture\n[\n");
    phPRINT("\tbrightness   : %hu %f%%\n",
            pict.brightness,
            (pict.brightness / 65535.0) * 100
            );
    phPRINT("\thue          : %hu %f%%\n",
            pict.hue,
            (pict.hue / 65535.0) * 100
            );
    phPRINT("\tcolor        : %hu %f%%\n",
            pict.colour,
            (pict.colour / 65535.0) * 100
            );
    phPRINT("\tcontrast     : %hu %f%%\n",
            pict.contrast,
            (pict.contrast / 65535.0) * 100
            );
    phPRINT("\twhiteness    : %hu %f%%\n",
            pict.whiteness,
            (pict.whiteness / 65535.0) * 100
            );
    phPRINT("\tdepth        : %hu bits\n",
            pict.depth
            );
    if (pict.palette >= VIDEO_PALETTE_PLANAR)
        palette_type = "PLANAR";
    else if (pict.palette >= VIDEO_PALETTE_COMPONENT)
        palette_type = "COMPONENT";
    else
        palette_type = "PACKED";
    if (pict.palette <= VIDEO_PALETTE_YUV410P)
        palette_name = (char *)palette_names[pict.palette];
    else
        palette_name = "unknown";
    phPRINT("\tpalette      : %hu %s %s\n",
            pict.palette,
            palette_name, palette_type
            );
    phPRINT("]\n");
}
    
/* ---------------------------------------------------------------------- */
void v4l_print_video_mmap( struct video_mmap mmap )
{   
    phPRINT("struct video_mmap\n[\n");
    phPRINT("\tframe    : %d\n",   mmap.frame   );
    phPRINT("\theight   : %d\n",   mmap.height  );
    phPRINT("\twidth    : %d\n",   mmap.width   );
    phPRINT("\tformat   : %u\n",   mmap.format  );
    phPRINT("]\n");
}

/* ---------------------------------------------------------------------- */
void v4l_print_video_mbuf( struct video_mbuf mbuf )
{   
    int i = 0;
    phPRINT("struct video_mbuf\n[\n");
    phPRINT("\tsize     : %d\n", mbuf.size );
    phPRINT("\tframes   : %d\n", mbuf.frames );
    for (i = 0; i < VIDEO_MAX_FRAME; i++ )
    {
        phPRINT("\t%d:{ %12d }",i,mbuf.offsets[i]);
        if (((i + 1) % 3) == 0) phPRINT("\n");
    }
    phPRINT("\n]\n");
}

/* ---------------------------------------------------------------------- */
void v4l_print_video_window( struct video_window win )
{   
    int i = 0;
    struct video_clip       *clip = NULL;
    
    phPRINT("struct video_window\n[\n");
    phPRINT("\tx        : %u\n",win.x);
    phPRINT("\ty        : %u\n",win.y);
    phPRINT("\twidth    : %u\n",win.width);
    phPRINT("\theight   : %u\n",win.height);
    phPRINT("\tchromakey: %u\n",win.chromakey);
    phPRINT("\tflags    : %u\n",win.flags);
    phPRINT("\tclipcount: %d\n",win.clipcount);
    phPRINT("\tclips    : %p\n",win.clips);
    
    clip = win.clips;
    for (i = 0; (i < win.clipcount) && (clip != NULL); i++ )
    {
        phPRINT("\t------------------------------\n");
        phPRINT("\t  i        : %d\n",i);
        phPRINT("\t  x        : %d\n",clip->x);
        phPRINT("\t  y        : %d\n",clip->y);
        phPRINT("\t  width    : %d\n",clip->width);
        phPRINT("\t  height   : %d\n",clip->height);
        clip = clip->next;
    }

    phPRINT("\n]\n");
}
    
/* ---------------------------------------------------------------------- */
void v4l_print_video_tuner( struct video_tuner tuner )
{   
    phPRINT("struct video_tuner\n[\n");
    phPRINT("\ttuner    :%d\n",tuner.tuner);
    phPRINT("\tname     :%s\n",tuner.name);
    phPRINT("\trangelow :%lu\n",tuner.rangelow);
    phPRINT("\trangehigh:%lu\n",tuner.rangehigh);
    phPRINT("\tflags    :%u\n",tuner.flags);
    phPRINT("\t(flags) ");
    if (tuner.flags & VIDEO_TUNER_PAL) phPRINT("PAL ");
    if (tuner.flags & VIDEO_TUNER_NTSC) phPRINT("NTSC ");
    if (tuner.flags & VIDEO_TUNER_SECAM) phPRINT("SECAM ");
    if (tuner.flags & VIDEO_TUNER_LOW) phPRINT("LOW ");
    if (tuner.flags & VIDEO_TUNER_NORM) phPRINT("NORM ");
    if (tuner.flags & VIDEO_TUNER_STEREO_ON) phPRINT("STEREO_ON ");
    if (tuner.flags & VIDEO_TUNER_RDS_ON) phPRINT("RDS_ON ");
    if (tuner.flags & VIDEO_TUNER_MBS_ON) phPRINT("MBS_ON ");
    phPRINT("\n");
    phPRINT("\tmode     : %hu\n",tuner.mode); 
    phPRINT("\t(mode) ");
    if (tuner.flags & VIDEO_MODE_PAL) phPRINT("PAL ");
    if (tuner.flags & VIDEO_MODE_NTSC) phPRINT("NTSC ");
    if (tuner.flags & VIDEO_MODE_SECAM) phPRINT("SECAM ");
    if (tuner.flags & VIDEO_MODE_AUTO) phPRINT("AUTO ");
    phPRINT("\n");
    phPRINT("\tsignal   : %hu\n",tuner.signal);

    phPRINT("\n]\n");
}

/* ---------------------------------------------------------------------- */
/* TODO: check object's m_info for != NULL everywhere */
struct phV4LCaptureInfo_t
{
    /* this structure will hold the capabilities of the 
     * capture device when the device is open */
    struct video_capability m_device_caps;
    
    /* This is used when capturing from the source 
     * and specifies: frame, width, height, depth */
    struct video_mmap       m_device_mmap;

    /* This holds the features of the channel including,
     * the type of signal(NTSC,PAL,etc.) and channel num */
    struct video_channel    m_device_chan;

    struct video_picture    m_device_picture;
    
    struct video_mbuf       m_device_mbuf;

    struct video_window     m_device_win;

    struct video_tuner      m_device_tuner;
};

#ifdef __cplusplus
}
#endif

/* ---------------------------------------------------------------------- *
 * V4LCapture Constructor - This is called when a new instance of the V4LCapture object
 * is created.
 * 
 * PRE: Who knows
 * POST: All variables have been initialized to 0, or NULL.
 *       channelSpec.channel = 1, m_device_mmap.width = 160,
 *       m_device_mmap.height = 120, device = "/dev/video0", h
 *       hw_bufferCount = 2
 *
 * ---------------------------------------------------------------------- */
V4LCapture::V4LCapture(char *path)
{
    phFUNCTION("V4LCapture::V4LCapture")
    
    rc = this->lock();
    phPRINT_RC(rc,NULL,"this->lock()");
   
    this->setName("V4LCapture");
    
    this->m_changed_settings = 0;
    this->m_changed_channel = 0;

    this->m_info = (struct phV4LCaptureInfo_t *)phCalloc(1,
                        sizeof(struct phV4LCaptureInfo_t));
    phPRINT_PTR(this->m_info,"phCalloc",
              "phCalloc failed to alloc phV4LCaptureInfo");
    
    phMemset(&this->m_info->m_device_caps,   0,sizeof(struct video_capability));
    phMemset(&this->m_info->m_device_mmap,   0,sizeof(struct video_mmap));
    phMemset(&this->m_info->m_device_chan,   0,sizeof(struct video_channel));
    phMemset(&this->m_info->m_device_picture,0,sizeof(struct video_picture));
    phMemset(&this->m_info->m_device_mbuf,   0,sizeof(struct video_mbuf));
    phMemset(&this->m_info->m_device_win,    0,sizeof(struct video_window));
    phMemset(&this->m_info->m_device_tuner,  0,sizeof(struct video_tuner));

    this->m_deviceOpen = 0;
    this->m_device_fd = 0;
    
    this->m_hw_mmapped = 0;
    this->m_hw_buffer = NULL;
    this->m_hw_bufferSize = 0;
    /* Init the buffer count to 2, not the maximum, because the lag involved
     * with > 2 buffers can be annoying */
    this->m_hw_bufferCount = 3;
    
    this->m_image_size = 0;

    if (path != NULL)
    {
        this->setPath(path);
    }
    else
    {
        this->setPath("/dev/video0");
    }

    /*
    this->m_info->m_device_picture.brightness   = 65536 / 2;
    this->m_info->m_device_picture.hue          = 65536 / 2;
    this->m_info->m_device_picture.colour       = 65536 / 2;
    this->m_info->m_device_picture.contrast     = 65536 / 2;
    this->m_info->m_device_picture.whiteness    = 65536 / 2;
    this->m_info->m_device_picture.palette      = VIDEO_PALETTE_RGB24;
    this->m_info->m_device_picture.depth        = 24;
    */    
    
    /*
    this->m_info->m_device_mmap.width = 160;
    this->m_info->m_device_mmap.height = 120;
    this->m_info->m_device_chan.channel = 1;
    */
    
    /* this->setFormat(phImageRGB24); */
    this->m_current_format = this->m_format;

    /* This applies the default (1) picture/image settings[w,h,format,etc.]
     * (2) channel settings  */
    this->applySettings();
    
    /* opening the device must be explicitly done */
    /* capturing must be explicitly done. */
/*error:*/
    rc = this->unlock();
    phPRINT_RC(rc,NULL,"this->unlock()");
    
    return;
}

/* ---------------------------------------------------------------------- *
 * V4LCapture Destructor - Called when the V4LCapture object is freed/destroyed. Yup.
 * 
 * PRE: Stuff. Like allocations and Stuff.
 * 
 * POST: All allocations will be freed, the capture stopped, the 
 * device closed and mappings unmapped.
 * ---------------------------------------------------------------------- */
V4LCapture::~V4LCapture ()
{
    phFUNCTION("V4LCapture::~V4LCapture")
  
    rc = this->lock();
    phPRINT_RC(rc,NULL,"this->lock()");

    if (this->isRunning())
    {
        /* this unmaps the hw_buffer and closes the device */
        rc = this->stop();
        phPRINT_RC(rc,NULL,"this->stop()");
    }
   
    if (this->isOpen())
    {
        rc = this->close();
        phPRINT_RC(rc,NULL,"this->close()");
    }
 
    phFree(this->m_info);
    
    rc = this->unlock();
    phPRINT_RC(rc,NULL,"this->unlock()");
}
    
/* ---------------------------------------------------------------------- */
/* open - This opens the device named in this->m_path as a V4LCapture
 *  file descriptor.
 *
 * This is called from phImageCapture::startCapturing()
 * 
 * PRE: V4LCapture Object has been created. 
 *      m_device_fd = 0 (closed), 
 *      m_path is some valid device name (default: /dev/video0)
 *      hardware buffer isn't mmapped.
 * 
 * POST: m_device_fd > 0 (opened)
 *      hardware buffers are still not mmapped
 *      Object is ready to start capturing with a call to start.
 */
/* ---------------------------------------------------------------------- */
/* start - This starts the capture session.
 * 
 *  [OLD comment that I'll put here for now]
 *
 * PRE: The device is open. The capture hasn't been started yet.
 *  HW Buffers aren't mapped.
 *
 * POST: The HW Buffers are mapped.
 *  A new thread has been spawned to manage the capturing of the data.
 *  The sw_buffer is being updated and is ready to have data copied from 
 *  it.
 */
/* ---------------------------------------------------------------------- */
int V4LCapture::open(char *path)
{
    phFUNCTION("V4LCapture::open")

    rc = this->lock();
    phPRINT_RC(rc,NULL,"this->lock()");
   
    /* device is already open, close it */
    if (this->isOpen())
    {
        rc = this->close();
        phPRINT_RC(rc,NULL,"this->close()");
    }
  
    if (path != NULL)
    {
        rc = this->setPath( path );
        phPRINT_RC(rc,NULL,"this->setPath( path:%s )",path);
    }
   
    if ((this->m_device_fd <= 0) && (this->getPath() != NULL))
    {
        /* open the video device */
        rc = (this->m_device_fd = ::open((char*)this->getPath(), O_RDWR));
        phCHECK_RC(rc,"::open",
                "Error: opening video device (%s)",
                (char*)this->getPath()
                );

        this->ioctl_get_capability();
        this->m_info->m_device_chan.norm = VIDEO_MODE_NTSC;
        this->ioctl_set_channel();
        this->ioctl_set_tuner();
        this->ioctl_get_capability();
        this->ioctl_set_picture();
        this->ioctl_set_window();
        
        /* Try to apply all the settings to the V4L device */
        ph_int32_array_append(this->m_changed_array,phCHANGE_INIT);
        this->applySettings();
        
        this->m_deviceOpen = 1;
    }

    rc = this->unlock();
    phPRINT_RC(rc,NULL,"this->unlock()");
    
    return phSUCCESS;
error:
    rc = this->unlock();
    phPRINT_RC(rc,NULL,"this->unlock()");
    
    return phFAIL;
}

/* ---------------------------------------------------------------------- */
int V4LCapture::isOpen() 
{ 
    return ((this->m_deviceOpen > 0) ? 1 : 0); 
}    

/* ---------------------------------------------------------------------- */
/* close - closes the video device file descriptor. Also cleans
 *  up any other class items like mappings and running threads.
 *
 * This is called from phImageCapture::stopCapturing()
 * 
 * PRE: m_device_fd > 0 (device open)
 *      m_deviceOpen > 0
 * POST: All mappings unmapped. All threads cleaned up. All necessary 
 *  variables reinitialized as in Constructor.
 */
/* ---------------------------------------------------------------------- */
int V4LCapture::close()
{
    phFUNCTION("V4LCapture::close")
   
    rc = this->lock();
    phPRINT_RC(rc,NULL,"this->lock()");
    
    if (this->m_hw_mmapped == 1)
    {
        phERR_PRINT("What the hell? hw_mapped == 1\n");
    }
    
    if (this->m_device_fd > 0)
    {
        /* close the video device */
        rc = ::close(this->m_device_fd);
        phCHECK_RC(rc, "::close",
                "Error: closing video device (%s)",
                this->getPath()
                );
        
        memset(&this->m_info->m_device_caps,
               0,sizeof(struct video_capability));
        
        /* These are reset last */
        this->m_device_fd = 0;
        this->m_deviceOpen = 0;
    }
    else if (this->m_device_fd < 0)
    {
        /* These are reset last */
        this->m_device_fd = 0;
        this->m_deviceOpen = 0;
    }
   
    rc = this->unlock();
    phPRINT_RC(rc,NULL,"this->unlock()");
    
    return phSUCCESS;
    
error:
    rc = this->unlock();
    phPRINT_RC(rc,NULL,"this->unlock()");
    
    return phFAIL;
}

/* ---------------------------------------------------------------------- */
/* setBufferCount - sets the number of frame buffers to set at the 
 *  hardware/kernel level of aquisition; potentially speeds things up if
 *  multiple buffers are supported.
 * 
 * PRE: device isn't open (m_device_fd = 0)
 *      hw buffer isn't mmapped
 *      capture is stopped/no captures in progress
 *      buffer_count > 0 and <= 32
 * POST:
 *      buffer_count is stored in hw_bufferCount
 */
/* ---------------------------------------------------------------------- */
int V4LCapture::setBufferCount( uint32_t buffer_count )
{
    phFUNCTION("V4LCapture::setBufferCount")

    rc = this->lock();
    phPRINT_RC(rc,NULL,"this->lock()");
   
    /* The hw_bufferCount won't be applied until the next time the
     * capturing thread is started */
    if (buffer_count > V4L_MAX_HWBUFFERS)
        buffer_count = V4L_MAX_HWBUFFERS;
    
    this->m_hw_bufferCount = buffer_count;
    
    rc = this->unlock();
    phPRINT_RC(rc,NULL,"this->unlock()");
    
    return phSUCCESS;
    /*
error:
    rc = this->unlock();
    phPRINT_RC(rc,NULL,"this->unlock()");
    
    return phFAIL;
    */
}

/* ---------------------------------------------------------------------- */
uint32_t V4LCapture::getBufferCount() 
{ 
    return this->m_hw_bufferCount; 
}

/* ---------------------------------------------------------------------- */
/* getWidth, getHeight, getFormat, getImageSize:
 * 
 *  if the device is open, then return the value in V4LCapture...
 * otherwise we won't have a consistent value with what the h/w/sz/f
 * is supposed to be since some of the V4LCapture fields don't get set
 * until the device is open but m_height is always set. Then, when
 * the device is open, captureSpec reflects the current setting
 * since the height can't be changed without closing the device...
 * at least not yet */
/* ---------------------------------------------------------------------- */
int V4LCapture::getWidth() 
{
    if (this->m_device_fd > 0)
    {
        return this->m_info->m_device_mmap.width; 
    }
    else
    {
        return this->phImageCapture::getWidth();
    }
}
/* ---------------------------------------------------------------------- */
int V4LCapture::getHeight() 
{
    if (this->m_device_fd > 0)
    {
        return this->m_info->m_device_mmap.height; 
    }
    else
    {
        return this->phImageCapture::getHeight();
    }
}
/* ---------------------------------------------------------------------- */
int32_t V4LCapture::getFormat() 
{ 
    if (this->m_device_fd > 0)
    {
        return this->m_current_format; 
    }
    else
    {
        return this->phImageCapture::getFormat(); 
    }
}
/* ---------------------------------------------------------------------- */
uint32_t V4LCapture::getImageSize() 
{ 
    if (this->m_device_fd > 0)
    {
        return this->m_image_size; 
    }
    else
    {
        return this->phImageCapture::getImageSize();
    }
}

/* ---------------------------------------------------------------------- */
/*  - 
 * 
 */
/* ---------------------------------------------------------------------- */
int V4LCapture::unmapHWBuffer()
{
    phFUNCTION("V4LCapture::unmapHWBuffer")
    uint32_t i = 0;

    rc = this->lock();
    phPRINT_RC(rc,NULL,"this->lock()");
    
    /* This is a must. Check all input parameters; raise an error is needed */
    if (this->isCapturing())
    {
        phCHECK_RC(-1,NULL,"Capture still in progress. Stop capturing first.");
    }
    
    if (this->m_hw_mmapped == 0)
    {
        goto success;
    }
    
    /* TODO: SYNC with all hw buffers */
    for (i = 0; i < this->m_hw_bufferCount; i++)
    {
        m_info->m_device_mmap.frame = i;
        /*phPRINT("ioctl:VIDIOCSYNC\n");*/
        rc = ioctl(this->m_device_fd, VIDIOCSYNC, 
                   &(this->m_info->m_device_mmap));
    }    
    
    /* Reset the frame index because the old frame index is
     * likely to be obsolete */
    this->m_info->m_device_mmap.frame  = 0;
    
    if (this->m_hw_mmapped == 1)
    {
        if ((this->m_hw_buffer != NULL) && (this->m_hw_bufferSize > 0))
        {
            rc = munmap((void *)this->m_hw_buffer, this->m_hw_bufferSize);
            phPRINT_RC(rc,"munmap failed",
                     "munmap(%p,%u);",
                     this->m_hw_buffer,
                     this->m_hw_bufferSize );
        }
       
        this->m_hw_buffer = NULL;
        this->m_hw_bufferSize = 0;
        this->m_hw_mmapped = 0;
    }

success:
    rc = this->unlock();
    phPRINT_RC(rc,NULL,"this->unlock()");
    
    return phSUCCESS;
error:
    rc = this->unlock();
    phPRINT_RC(rc,NULL,"this->unlock()");
    
    return phFAIL;
}

/* ---------------------------------------------------------------------- */
/*  - 
 * 
 */
/* ---------------------------------------------------------------------- */
int V4LCapture::mapHWBuffer()
{
    phFUNCTION("V4LCapture::mapHWBuffer")
    intmax_t    map_rc = 0;
    void        *vrc = NULL;

    rc = this->lock();
    phPRINT_RC(rc,NULL,"this->lock()");
    
    if (this->m_device_fd <= 0)
    {
        phERR_PRINT("this->m_device_fd <= 0\n");
    }
    
    if (this->m_image_size <= 0)
    {
        phERR_PRINT("this->m_image_size <= 0\n");
    }

    /* Automatically unmap it */
    if (this->m_hw_mmapped == 1)
    {
        rc = unmapHWBuffer();
        phPRINT_RC(rc,NULL,"unmapHWBuffer");
    }
 
    memset( &this->m_info->m_device_win, 0, sizeof( struct video_window ) );
    this->m_info->m_device_win.width = this->m_info->m_device_mmap.width;
    this->m_info->m_device_win.height = this->m_info->m_device_mmap.height;

    if (this->m_device_fd > 0)
    {
        rc = this->ioctl_set_window();
        phPRINT_RC(rc,NULL,"ioctl_set_window");
    }
    
    /* Set the video buffer data */
    rc = this->ioctl_get_mbuf();
    phCHECK_RC(rc,NULL,"ioctl_get_mbuf");

    /* Make sure the hardware buffer count isn't greater than 
     * what is allowed by the just queried device */
    if (this->m_hw_bufferCount > 
        (uint32_t)this->m_info->m_device_mbuf.frames)
    {
        if (!(((uint32_t)this->m_info->m_device_mbuf.frames) > 
                                            V4L_MAX_HWBUFFERS))
            this->m_hw_bufferCount = this->m_info->m_device_mbuf.frames;
    }

    /* map the memory being used to grab the images */
    this->m_hw_bufferSize = this->m_info->m_device_mbuf.size;
    this->m_hw_buffer = (uint8_t *)(vrc = mmap(NULL,
                                            this->m_hw_bufferSize, 
                                            PROT_READ | PROT_WRITE, 
                                            MAP_SHARED, 
                                            this->m_device_fd, 
                                            0)); 
    /* must cast to intmax_t because of 64bit vs. 32bit processor addrs */
    map_rc = (intmax_t)vrc;
    if (map_rc == -1)
    {
        phERROR_PRINT("mmap",
                    "*** ERROR (rc:%p)*** Error: mmap\n",
                    this->m_hw_buffer);
        DEBUG_PRINT("%p\n",this->m_hw_buffer);
        
        this->m_hw_buffer = NULL;
        
        goto error;
    }
    
    /* let the destructor know to free using munmap */
    this->m_hw_mmapped = 1;

    rc = this->unlock();
    phPRINT_RC(rc,NULL,"this->unlock()");
    
    return phSUCCESS;
error:
    rc = this->unlock();
    phPRINT_RC(rc,NULL,"this->unlock()");
    
    return phFAIL;
}

/* ---------------------------------------------------------------------- */
int V4LCapture::remapHWBuffer()
{
    phFUNCTION("V4LCapture::remapHWBuffer")

    rc = this->lock();
    phPRINT_RC(rc,NULL,"this->lock()");
    
    rc = this->unmapHWBuffer();
  
    rc = this->mapHWBuffer();
    phPRINT_RC(rc,NULL,"mapHWBuffer() failed");
    
    rc = this->unlock();
    phPRINT_RC(rc,NULL,"this->unlock()");
    
    return phSUCCESS;
    /*
error:
    rc = this->unlock();
    phPRINT_RC(rc,NULL,"this->unlock()");
    
    return phFAIL;
    */
}


/* ---------------------------------------------------------------------- */
/* m_info->m_device_picture and this are locked upon entry */
/* ---------------------------------------------------------------------- */
int V4LCapture::onApplySettings()
{
    phFUNCTION("V4LCapture::onApplySettings")
    int retrc = phSUCCESS;

    int ch_init     = 0;
    int ch_b        = 0;
    int ch_hue      = 0;
    int ch_color    = 0;
    int ch_con      = 0;
    int ch_white    = 0;
    int ch_channel  = 0;
    int ch_tuner    = 0;
    int ch_h        = 0;
    int ch_w        = 0;
    int ch_f        = 0;
    int ch_p        = 0;
   
    ch_init = ph_int32_array_find(this->m_changed_array, phCHANGE_INIT,NULL);
    /* 
     * this->m_changed_array contains the list of changes that are to 
     *  be applied.
     *
     * This method will call phImageCapture::onApplySettings which will empty
     * the array so that settings are applied only once.
     */
    
    /* Copy the image settings into the V4L structure */
    ch_b = ph_int32_array_find(this->m_changed_array,       phCHANGE_BRIGHTNESS,
                            NULL);
    ch_hue = ph_int32_array_find(this->m_changed_array,     phCHANGE_HUE,
                            NULL);
    ch_color = ph_int32_array_find(this->m_changed_array,   phCHANGE_COLOR,
                            NULL);
    ch_con = ph_int32_array_find(this->m_changed_array,     phCHANGE_CONTRAST,
                            NULL);
    ch_white = ph_int32_array_find(this->m_changed_array,   phCHANGE_WHITENESS,
                            NULL);
    if (ch_init > 0) ch_b = ch_hue = ch_color = ch_con = ch_white = 1;
    if ((ch_b > 0) || (ch_hue > 0) || (ch_color > 0) || 
        (ch_con > 0) || (ch_white > 0))
    {
        this->m_changed_settings = 1;
        if (ch_b > 0)
            this->m_info->m_device_picture.brightness   = this->m_brightness;
        if (ch_hue > 0)
            this->m_info->m_device_picture.hue          = this->m_hue;
        if (ch_color > 0)
            this->m_info->m_device_picture.colour       = this->m_color;
        if (ch_con > 0)
            this->m_info->m_device_picture.contrast     = this->m_contrast;
        if (ch_white > 0)
            this->m_info->m_device_picture.whiteness    = this->m_whiteness;
    }
    
    /*--------------------------------------------------------------------*
     * From linux/Documentation/video4linux/API.html:
     *
     * "Each channel can be queries with the VIDIOCGCHAN ioctl call. 
     * Before invoking this function the caller must set the channel 
     * field to the channel that is being queried. On return the 
     * struct video_channel is filled in with information about the 
     * nature of the channel itself."
     *--------------------------------------------------------------------*/
    ch_channel = ph_int32_array_find(this->m_changed_array,phCHANGE_CHANNEL,
                                    NULL);
    if (((ch_channel > 0) || (ch_init > 0)) && (this->m_channel >= 0))
    {
        this->m_info->m_device_chan.channel = this->m_channel;
        this->m_changed_channel = 1;
    }
    /* else, the channel is < 0 or the current chn # */
    

    /* settings that require the capture to not be in progress for the 
     * V4LCapture settings changes to be applied */
    ch_h = ph_int32_array_find(this->m_changed_array, phCHANGE_HEIGHT, NULL);
    ch_w = ph_int32_array_find(this->m_changed_array, phCHANGE_WIDTH, NULL);
    ch_f = ph_int32_array_find(this->m_changed_array, phCHANGE_FORMAT, NULL);

    if (ch_init > 0) ch_h = ch_w = ch_f = 1;

    if ((ch_h > 0) || (ch_w > 0) || (ch_f > 0))
    {
        /* if the retrc variable isn't set to 1, then copy these 
         * into the private values for the V4LCapture class */
        /* Settings not applied until restart */
        if ((!this->isRunning()) && (this->m_hw_mmapped == 0))
        {
            int changed_image_dimensions = 0;
            
            /* width and height will be checked for > 0 and
             * whether the value has changed. But check again
             * for fun and because the change is being checked
             * against a different variable (ie m_device_mmap) 
             * because these changes could be defered */
            
            /* use OR/|| because sometimes the change must be forced
             * to actually apply the settings */
            if ((ch_w > 0) || 
                (this->m_info->m_device_mmap.width != this->m_width))
            {
                this->m_info->m_device_mmap.width = this->m_width;
                changed_image_dimensions = 1;
            }
            /* use OR/|| because sometimes the change must be forced
             * to actually apply the settings */
            if ((ch_h > 0) || 
                (this->m_info->m_device_mmap.height != this->m_height))
            {
                this->m_info->m_device_mmap.height = this->m_height;
                changed_image_dimensions = 1;
            }
            /* use OR/|| because sometimes the change must be forced
             * to actually apply the settings */
            if ((ch_f > 0) || (this->m_current_format != this->m_format))
            {
                int32_t f = this->m_format;
                int32_t validFormats = (phImageRGB24 |
                                        phImageBGR24 |
                                        phImageRGBA32 | 
                                        phImageBGRA32 |
                                        phImageGREY8);
                changed_image_dimensions = 1;
                
                /* make sure any special flags are removed */
                f &= validFormats;
                
                switch (f)
                {
                    /* --------------------------------------------------- */
                    case phImageGREY8:
                        
                        this->m_info->m_device_mmap.format = 
                            this->m_info->m_device_picture.palette = 
                                                        VIDEO_PALETTE_GREY;
                        this->m_info->m_device_picture.depth = 8;    
                        
                        break;
                    /* --------------------------------------------------- */
                    case phImageRGBA32:
                    case phImageBGRA32:
                        
                        this->m_info->m_device_mmap.format = 
                            this->m_info->m_device_picture.palette = 
                                                        VIDEO_PALETTE_RGB32;
                        this->m_info->m_device_picture.depth = 32;    
                    
                        break;
                    /* --------------------------------------------------- */
                    /* if multiple formats are specified or the format is 
                     * invalid, then phImageRGB24 is used */
                    case phImageRGB24:
                    case phImageBGR24:
                    default:
                        
                        this->m_info->m_device_mmap.format = 
                            this->m_info->m_device_picture.palette = 
                                                        VIDEO_PALETTE_RGB24;
                        this->m_info->m_device_picture.depth = 24;
                        
                        break;
                }
                
                this->m_current_format = this->m_format = f;
            }

            /* if any of the fields changed, then apply the changes
             * to the device if it's open and set the new image size */
            if (changed_image_dimensions == 1)
            {
                phIMAGE_SIZE_IN_BYTES(this->m_image_size,
                                      this->m_info->m_device_mmap.width,
                                      this->m_info->m_device_mmap.height,
                                      this->m_current_format );
                this->m_changed_settings = 1;
            }
        }
        else
        {
            retrc = 1;
        }
    }

    ch_tuner = ph_int32_array_find(this->m_changed_array, phCHANGE_TUNER, NULL);
    if ((ch_tuner > 0) || (ch_init > 0))
    {
        if (this->m_device_fd > 0)
        {
            rc = this->ioctl_get_tuner();
            phCHECK_RC(rc,NULL,"this->ioctl_get_tuner");

            if (this->m_info->m_device_tuner.mode != VIDEO_MODE_NTSC)
            {
                this->m_info->m_device_tuner.mode = VIDEO_MODE_NTSC;

                rc = this->ioctl_set_tuner();
                phCHECK_RC(rc,NULL,"ioctl_set_tuner");
                
                this->m_changed_channel = 1;
            }
        }
    }
    
    ch_p = ph_int32_array_find(this->m_changed_array, phCHANGE_PATH, NULL);
    if ((ch_p > 0) || (ch_init > 0))
    {
        /* this->m_path is used in 'open', no special V4LCapture
         * settings have to be applied here */
        retrc = 1;
    }

    /* if the device is open, apply the settings... */
    /* can really only apply the settings if the device is open */
    /* until the device is open we're merely saving the values */
    if (this->m_device_fd > 0)
    {
        /* TODO: if reopening and stopping of the thread is necessary
         * then this is likely the place to do it */

        /* The value m_changed_channel is persistent across calls to 
         * applySettings in the case the settings aren't applied 
         * in one call of applySettings */
        if (this->m_changed_channel == 1)
        {
            /* get channel: fills the structure's fields with default values*/
            if (this->m_info->m_device_chan.channel < 0)
                this->m_info->m_device_chan.channel = 0;
                       
            /* set channel */
            rc = this->ioctl_set_channel();
            phPRINT_RC(rc,NULL,"ioctl_set_channel()");

            this->m_changed_channel = 0;
        }   

        /* The value m_changed_settings is persistent across calls to 
         * applySettings in the case the settings aren't applied 
         * in one call of applySettings */
        if (this->m_changed_settings == 1)
        {
            rc = this->ioctl_set_picture();
            phPRINT_RC(rc,NULL,"ioctl_set_picture()");

            /* Apply the picture  settings */
            this->m_changed_settings = 0;
        }
 

    }

    rc = this->phImageCapture::onApplySettings();
    phCHECK_RC(rc,NULL,"this->phImageCapture::onApplySettings() failed.");
 
    return retrc;
error:

    return phFAIL;
}

/* ---------------------------------------------------------------------- */
/* cleanup - This unmaps the hardware buffer after the thread has stopped
 * 
 */
/* ---------------------------------------------------------------------- */
int V4LCapture::cleanup()
{
    phFUNCTION("V4LCapture::cleanup()")
   
    rc = this->lock();
    phPRINT_RC(rc,NULL,"this->lock()");
    
    rc = this->unmapHWBuffer();
    phPRINT_RC(rc,NULL,"this->unmapHWBUffer()");

    rc = this->phImageCapture::cleanup();
    phPRINT_RC(rc,NULL,"this->phImageCapture::cleanup()");
    
    rc = this->unlock();
    phPRINT_RC(rc,NULL,"this->unlock()");
    
    return phSUCCESS;
}

/* ---------------------------------------------------------------------- */
#define CAPTURE_BEGIN(fd,array,frm) \
{\
    /*phDEBUG_PRINT("ioctl(%d,VIDIOCMCAPTURE,%p):%d\n",\
            fd, &spec, frm ); */\
    /*phPRINT("ioctl:VIDIOCMCAPTURE\n");*/ \
    rc = ioctl(fd, VIDIOCMCAPTURE, &array[frm] ); \
    if (errno == EINTR) rc = 0; \
    phPRINT_RC( rc, \
                "ioctl(VIDIOCMCAPTURE)",\
                "ioctl(%d,VIDIOCMCAPTURE,%p):frm%d:w%d:h%d failed",\
                fd, \
                &array[frm],\
                frm,\
                array[frm].width,\
                array[frm].height ); \
}
/* ---------------------------------------------------------------------- */
#define CAPTURE_SYNC(fd,frm) \
{\
    /*phDEBUG_PRINT( "ioctl(%d,VIDIOCSYNC,%p):%d\n", \
             fd, &frm, frm ); */\
    /*phPRINT("ioctl:VIDIOCSYNC\n");*/ \
    rc = ioctl(fd, VIDIOCSYNC, &frm); \
    if (errno == EINTR) rc = 0; \
    phPRINT_RC( rc, \
                "ioctl(VIDIOCSYNC)", \
                "ioctl(%d,VIDIOCSYNC,%p) frame:%d failed", \
                fd, \
                &frm, \
                frm ); \
}

/* ---------------------------------------------------------------------- */
void V4LCapture::print( int copy )
{   
    phFUNCTION("V4LCapture::print()")
    int locked = 0;

    if ((this->m_info == NULL) || (this->m_device_fd <= 0)) return;

    phTHIS_LOOSE_LOCK(locked);
    phPRINT("--------------------------------------------------------------------------\n");
    print_caps      (copy);
    print_channel   (copy);
    print_picture   (copy);
    print_mmap      (copy);
    print_mbuf      (copy);
    print_window    (copy);
    print_tuner     (copy);
    phPRINT("--------------------------------------------------------------------------\n");
    phTHIS_LOOSE_UNLOCK(locked);

    return;
}

/* ---------------------------------------------------------------------- */
void V4LCapture::print_caps( int copy )
{   
    phFUNCTION("V4LCapture::print_caps()")
    int locked = 0;
    
    if ((this->m_info == NULL) || (this->m_device_fd <= 0)) return;

    phTHIS_LOOSE_LOCK(locked);

    struct video_capability caps;
    /* print the capabilities */
    if (copy == 1)
        phMemcpy(&caps,&this->m_info->m_device_caps,sizeof(struct video_capability));
    else
        ioctl(this->m_device_fd,VIDIOCGCAP,&caps);
   
    v4l_print_video_capability(caps);
    
    phTHIS_LOOSE_UNLOCK(locked);

    return;
}

/* ---------------------------------------------------------------------- */
void V4LCapture::print_channel( int copy )
{   
    phFUNCTION("V4LCapture::print_channel()")
    int locked = 0;

    if ((this->m_info == NULL) || (this->m_device_fd <= 0)) return;

    phTHIS_LOOSE_LOCK(locked);

    /* Print the video channel stuff */
    struct video_channel    chan;
    if (copy == 1)
        phMemcpy(&chan,&this->m_info->m_device_chan,sizeof(struct video_channel));
    else
        ioctl(this->m_device_fd,VIDIOCGCHAN,&chan);
    
    v4l_print_video_channel(chan);

    phTHIS_LOOSE_UNLOCK(locked);

    return;
}
    
/* ---------------------------------------------------------------------- */
void V4LCapture::print_picture( int copy )
{   
    phFUNCTION("V4LCapture::print_picture()")
    int locked = 0;

    if ((this->m_info == NULL) || (this->m_device_fd <= 0)) return;

    phTHIS_LOOSE_LOCK(locked);

    /* Print the video_picture */
    struct video_picture    pict;
    if (copy == 1)
        phMemcpy(&pict,&this->m_info->m_device_picture,sizeof(struct video_picture));
    else
        ioctl(this->m_device_fd,VIDIOCGPICT,&pict);
   
    v4l_print_video_picture(pict);
    
    phTHIS_LOOSE_UNLOCK(locked);

    return;
}
    
/* ---------------------------------------------------------------------- */
void V4LCapture::print_mmap( int copy )
{   
    phFUNCTION("V4LCapture::print_mmap()")
    int locked = 0;

    if ((this->m_info == NULL) || (this->m_device_fd <= 0)) return;

    phTHIS_LOOSE_LOCK(locked);

    /* Print the video_mmap */
    struct video_mmap       mmap;
    phMemcpy(&mmap,&this->m_info->m_device_mmap,sizeof(struct video_mmap));
   
    v4l_print_video_mmap(mmap);
    
    phTHIS_LOOSE_UNLOCK(locked);

    return;
}

/* ---------------------------------------------------------------------- */
void V4LCapture::print_mbuf( int copy )
{   
    phFUNCTION("V4LCapture::print_mbuf()")
    int locked = 0;

    if ((this->m_info == NULL) || (this->m_device_fd <= 0)) return;

    phTHIS_LOOSE_LOCK(locked);

    /* Print the mbuf info */
    struct video_mbuf       mbuf;
    if (copy == 1)
        phMemcpy(&mbuf,&this->m_info->m_device_mbuf,sizeof(struct video_mbuf));
    else
        ioctl(this->m_device_fd,VIDIOCGMBUF,&mbuf);
   
    v4l_print_video_mbuf(mbuf);
    
    phTHIS_LOOSE_UNLOCK(locked);

    return;
}

/* ---------------------------------------------------------------------- */
void V4LCapture::print_window( int copy )
{   
    phFUNCTION("V4LCapture::print_window()")
    int locked = 0;
    struct video_window     win;

    if ((this->m_info == NULL) || (this->m_device_fd <= 0)) return;

    phTHIS_LOOSE_LOCK(locked);

    /* Print the window stuff */
    if (copy == 1)
        phMemcpy(&win,&this->m_info->m_device_win,sizeof(struct video_window));
    else
        ioctl(this->m_device_fd,VIDIOCGWIN,&win);
   
    v4l_print_video_window(win);
    
    phTHIS_LOOSE_UNLOCK(locked);

    return;
}
    
/* ---------------------------------------------------------------------- */
void V4LCapture::print_tuner( int copy )
{   
    phFUNCTION("V4LCapture::print_tuner()")
    int locked = 0;
    struct video_tuner      tuner;

    if ((this->m_info == NULL) || (this->m_device_fd <= 0)) return;

    phTHIS_LOOSE_LOCK(locked);

    /* Print the tuner stuff */
    if (copy == 1)
        phMemcpy(&tuner,&this->m_info->m_device_tuner,sizeof(struct video_tuner));
    else
        ioctl(this->m_device_fd,VIDIOCGTUNER,&tuner);

    v4l_print_video_tuner(tuner);

    phTHIS_LOOSE_UNLOCK(locked);

    return;
}

/* ---------------------------------------------------------------------- */
int V4LCapture::ioctl_get_capability()
{
    phFUNCTION("V4LCapture::ioctl_get_capability")
    
    if (this->m_device_fd <= 0) return phFAIL;
 
    /* Get the Capability settings from the device */
    /*phPRINT("ioctl:VIDIOCGCAP\n");*/
    rc = ioctl( this->m_device_fd, 
                VIDIOCGCAP,
                &this->m_info->m_device_caps);
    phPRINT_RC( rc, 
                "ioctl(VIDIOCGCAP)", 
                "ioctl(%d,VIDIOCGCAP,%p) failed",
                this->m_device_fd,
                &(this->m_info->m_device_caps));
    
    return rc;
} 

/* ---------------------------------------------------------------------- */
int V4LCapture::ioctl_get_mbuf()
{
    phFUNCTION("V4LCapture::ioctl_get_mbuf")
    
    if (this->m_device_fd <= 0) return phFAIL;
 
    /*phPRINT("ioctl:VIDIOCGMBUF\n");*/
    rc = ioctl(this->m_device_fd, 
               VIDIOCGMBUF, 
               &this->m_info->m_device_mbuf);
    phPRINT_RC( rc,
                "ioctl(VIDIOCGMBUF)",
                "ioctl(%d,VIDIOCGMBUF,%p) failed.",
                this->m_device_fd,
                &this->m_info->m_device_mbuf);

    return rc;
}
/* ---------------------------------------------------------------------- */
int V4LCapture::ioctl_get_tuner()
{
    phFUNCTION("V4LCapture::ioctl_get_tuner")
    
    if (this->m_device_fd <= 0) return phFAIL;
 
    /*phPRINT("ioctl:VIDIOCGTUNER\n");*/
    rc = ioctl( this->m_device_fd, 
                VIDIOCGTUNER,
                &(this->m_info->m_device_tuner) );
    phPRINT_RC( rc, 
                "ioctl(VIDIOCGTUNER)", 
                "ioctl(%d,VIDIOCGTUNER,%p)",
                this->m_device_fd,
                &this->m_info->m_device_tuner);
    return rc;
}

/* ---------------------------------------------------------------------- */
int V4LCapture::ioctl_set_channel()
{
    phFUNCTION("V4LCapture::ioctl_set_channel")
    int     channel = 0;
    short   norm    = VIDEO_MODE_NTSC;
    
    if (this->m_device_fd <= 0) return phFAIL;
    
    norm    = this->m_info->m_device_chan.norm;
    channel = this->m_info->m_device_chan.channel;

    /*phPRINT("ioctl:VIDIOCGCHAN:%d\n",channel);*/
    rc = ioctl( this->m_device_fd, 
                VIDIOCGCHAN,
                &this->m_info->m_device_chan);
    phPRINT_RC( rc,
                "ioctl(VIDIOCGCHAN)", 
                "ioctl(%d,VIDIOCGCHAN,%p)-channel:%d",
                this->m_device_fd,
                &this->m_info->m_device_chan,
                this->m_info->m_device_chan.channel);
        
    /* set image source and TV norm */
    this->m_info->m_device_chan.norm    = norm;
    this->m_info->m_device_chan.channel = channel;
 
    /*phPRINT("ioctl:VIDIOCSCHAN:%d\n",channel);*/
    rc = ioctl( this->m_device_fd, 
                VIDIOCSCHAN,
                &this->m_info->m_device_chan);
    phPRINT_RC( rc,
                "ioctl(VIDIOCSCHAN)", 
                "ioctl(%d,VIDIOCSCHAN,%p)-channel:%d",
                this->m_device_fd,
                &this->m_info->m_device_chan,
                this->m_info->m_device_chan.channel);
    
    return rc;
}

/* ---------------------------------------------------------------------- */
int V4LCapture::ioctl_set_picture()
{
    phFUNCTION("V4LCapture::ioctl_set_picture")

    if (this->m_device_fd <= 0) return phFAIL;
    
    /*phPRINT("ioctl:VIDIOCSPICT\n");*/
    rc = ioctl( this->m_device_fd,
                VIDIOCSPICT,
                &this->m_info->m_device_picture);
    phPRINT_RC( rc,
                "ioctl(VIDIOCSPICT)", 
                "ioctl(%d,VIDIOCSPICT,%p) failed",
                this->m_device_fd,
                &this->m_info->m_device_picture);
    
    return rc;
}

/* ---------------------------------------------------------------------- */
int V4LCapture::ioctl_set_window()
{
    phFUNCTION("V4LCapture::ioctl_set_window")

    if (this->m_device_fd <= 0) return phFAIL;

    this->m_info->m_device_win.clips = NULL;
    
    /*phPRINT("ioctl:VIDIOCSWIN\n");*/
    rc = ioctl( this->m_device_fd, 
                VIDIOCSWIN, 
                &(this->m_info->m_device_win) );
    phPRINT_RC(rc,
               "ioctl(VIDIOCSWIN)", 
               "ioctl(%d,VIDIOCSWIN,%p) failed",
               this->m_device_fd,
               &this->m_info->m_device_win);
    return rc;
}

/* ---------------------------------------------------------------------- */
int V4LCapture::ioctl_set_tuner()
{
    phFUNCTION("V4LCapture::ioctl_set_tuner")
    int tuner = 0;

    if (this->m_device_fd <= 0) return phFAIL;

    tuner = this->m_info->m_device_tuner.tuner;

    /*phPRINT("ioctl:VIDIOCSTUNER:%d\n",tuner);*/
    rc = ioctl( this->m_device_fd, 
                VIDIOCSTUNER,
                &(this->m_info->m_device_tuner) );
    phPRINT_RC( rc, 
                "ioctl(VIDIOCSTUNER)", 
                "ioctl(%d,VIDIOCSTUNER,%p)",
                this->m_device_fd,
                &this->m_info->m_device_tuner);

    rc = this->ioctl_set_channel();
    phPRINT_RC(rc,NULL,"ioctl_set_channel");
    
    return rc;
}

/* ---------------------------------------------------------------------- */
int V4LCapture::run()
{
    phFUNCTION("V4LCapture::run")
    
    rc = this->mapHWBuffer();
    phPRINT_RC(rc,NULL,"this->mapHWBuffer()");

    /* About using the disabled swap: */
    /* There has to be at least 2 V4L buffers for which one of the two
     * are being captured to while the other buffer is accessible to
     * listening objects/threads. 2 buffers will likely give jerky 
     * results in the frame rate than 3 buffers; which provide a smoother
     * frame rate */
    /* After starting all the capturing to the buffers, we first have 
     * to SYNC with the capture for a buffer before we can send it off
     * on another capture session. When we've sync'd with the buffer(#0) 
     * we can then take the pointer and place it into the phImage until the 
     * next buffer(#1) has been sync'd with. We can only begin a capture on 
     * the first buffer(#0) after we've taken the pointer out of the phImage
     * object. At this point we can restart the capture for the buffer #0. */
    /* buffer_ready lets the code know when the capture can be 
     * started again. This is mostly for starting and shutting down of
     * this capture thread. In the case of two buffers, we can't capture
     * to buffer #1 until the previous capture has been stopped/sync'd.
     * When starting we would be swapping #0's pointers into the phImage
     * buffer. We would then be assuming that the pointers and info we get
     * out of the phImage during this swap are #1. However, this is untrue 
     * and we need to prevent trying to start a capture on #1 until it's
     * buffer is ready. */
    int         use_disabled_swap = this->m_hw_bufferCount >= 2 ? 1 : 0;
    int        *buffer_ready      = new int[this->m_hw_bufferCount];
    int         temp_frame_index  = 0;
    
    phImage     *output_buffer  = this->getImage();
    int         output_locked   = 0;
    uint8_t     *temp           = NULL;
    
    uint32_t i = 0;
    uint32_t cur_frame = 0;
#if TIMESTUFF()
    struct timeval tv_start;
    struct timeval tv_stop;
    float tdiff;
    int32_t frames;
#endif

#if TIMESTUFF()
    tv_start.tv_sec = 0;
    tv_start.tv_usec= 0;
    tv_stop.tv_sec = 0;
    tv_stop.tv_usec= 0;
    tdiff = 0.0;
    frames = 0;
#endif

    /* local copies of V4LCapture object's member vars */
    int                     cur_fd              = 0;
    uint8_t                 *cur_imgptr         = NULL;
    int32_t                 cur_format          = 0;
    uint32_t                cur_image_size      = 0;
    uint32_t                cur_buffer_count    = 0;
    struct video_mbuf       cur_capture_buffer_info;
    struct video_mmap       cur_capture_spec;
    struct video_picture    cur_settings;
    struct video_mmap       *mmap_array         = NULL;
    
    uint32_t loop_width     = 0;
    uint32_t loop_height    = 0;
    uint32_t loop_format    = phImageNOFORMAT;
    uint32_t loop_size      = 0;
    uint8_t *loop_ptr       = NULL;
    
    /* Setup */
    cur_imgptr      = this->m_hw_buffer;
    cur_format      = this->m_current_format;
    cur_image_size  = this->m_image_size;
    cur_buffer_count= this->m_hw_bufferCount;
    cur_fd          = this->m_device_fd;
    
    phMemcpy(&cur_capture_buffer_info,
             (void *)&(this->m_info->m_device_mbuf),
             sizeof(struct video_mbuf));
    phMemcpy(&cur_capture_spec,
             (void *)&(this->m_info->m_device_mmap),
             sizeof(struct video_mmap));
    phMemcpy(&cur_settings,
             (void *)&(this->m_info->m_device_picture),
             sizeof(struct video_picture));

    phMemset(buffer_ready,0,sizeof(int) * this->m_hw_bufferCount);
    
    mmap_array = (struct video_mmap *)phCalloc(cur_buffer_count,
                                               sizeof(struct video_mmap));
    phCHECK_PTR(mmap_array,"phCalloc","phCalloc failed.");
    for (i = 0; i < this->m_hw_bufferCount; i++ )
    {
        mmap_array[i].frame = i;
        mmap_array[i].width = cur_capture_spec.width;
        mmap_array[i].height = cur_capture_spec.height;
        mmap_array[i].format = cur_settings.palette;
    }

    if (!use_disabled_swap)
    {
        if (temp == NULL)
        {
            temp = (uint8_t*)phMalloc(cur_image_size);
            phCHECK_NULLPTR(temp,"phMalloc","phMalloc failed");

            phMemset(temp,0,cur_image_size);
        }
        else
        {
            temp = (uint8_t *)phRealloc(temp,cur_image_size);
            phCHECK_NULLPTR(temp,"phRealloc","phRealloc failed");
        }
    
        /* If there is no data in the buffer or the buffer is of a different size,
         * then [re]allocate the data and set it back in so the data can be
         * swapped out and match the temp buffer */
        if (output_buffer->isNull())
        {
            /* Prepare the output_buffer */
            output_buffer->disableNotify();
            
            loop_width  = cur_capture_spec.width;
            loop_height = cur_capture_spec.height;
            loop_format = cur_format;
            loop_size   = 0; /* size: let the method figure it out */
            loop_ptr    = (uint8_t*)temp;
            
            rc = output_buffer->setImage(loop_width,
                                         loop_height,
                                         loop_format,
                                         loop_size,
                                         loop_ptr);
            phPRINT_RC(rc,NULL,"setImage");
            
            loop_size = output_buffer->getSize();
            
            output_buffer->enableNotify();
        }
    }
    else
    {
        /* disable swapping on the buffer now; just for fun */
        output_buffer->disableSwap();
    }

    /* start the first capture */
    for (i = 0; i < cur_buffer_count; i++)
    {
        CAPTURE_BEGIN( cur_fd, mmap_array, i );
    }

    /* Release the thread that spawned this one */
    /* Everything has been copied and everything is ready to start */
    rc = this->signal_running();
    phPRINT_RC(rc,NULL,"this->signal_running");
    
    DEBUG_PRINT("Thread Started\n");
    DEBUG_PRINT("output_buffer: %p\n",output_buffer);
    
    while (this->isRunning())
    {
        CAPTURE_SYNC( cur_fd, cur_frame );

        buffer_ready[cur_frame] = 1;

        if (!use_disabled_swap)
        {
            memcpy(temp,
                   (uint8_t*)(cur_imgptr + 
                              cur_capture_buffer_info.offsets[cur_frame]),
                   cur_image_size);
        
            CAPTURE_BEGIN( cur_fd, mmap_array, cur_frame );
            cur_frame = (cur_frame + 1) % cur_buffer_count;
        }
        else
        {
            temp = (uint8_t*)(cur_imgptr + 
                              cur_capture_buffer_info.offsets[cur_frame]);
        } 
        
        /* convert to RGB format, it's the specified format for image 
         * data from a capture class */
        /* V4L Format is BGR, BGRA */
        if ((cur_format == phImageRGB24) &&
            (cur_settings.palette == VIDEO_PALETTE_RGB24))
        {
            phBGR24_x_RGB24(cur_image_size,temp);
        }
        if ((cur_format == phImageRGBA32) &&
            (cur_settings.palette == VIDEO_PALETTE_RGB32))
        {
            phBGRA32_x_RGBA32(cur_image_size,temp);
        }
        
        /* if (output_buffer->tryWritelock() == 0) */
        DEBUG_PRINT("output_buffer->tryWriteLock()\n");
        if (output_buffer->writeLock() == 0)
        {
            ++output_locked;

            /* enable the swapping after we have the write lock so we
             * can swap our mmapped pointer into the object */
            if (use_disabled_swap)
                output_buffer->enableSwap();

            DEBUG_PRINT("== 0\n");
            /* This will lock(again) and unlock the image.
             * While in possession of the lock the image
             * is copied */
            loop_width  = cur_capture_spec.width;
            loop_height = cur_capture_spec.height;
            loop_format = cur_format;
            loop_size   = cur_image_size; /* size: let the method figure it out */
            loop_ptr    = temp;
            
            rc = output_buffer->swapData(   &loop_width,
                                            &loop_height,
                                            &loop_format,
                                            &loop_ptr,
                                            &loop_size
                                        );
            phPRINT_RC(rc,NULL,"output_buffer->swapData");
            
            if (use_disabled_swap)
            {
                /* make sure the swap is disabled before we unlock the
                 * image so no one else can take the pointer from the
                 * object and do bad things with it */
                output_buffer->disableSwap();
            
                temp_frame_index = cur_frame - 1;
                if (temp_frame_index < 0) 
                    temp_frame_index = cur_buffer_count - 1;

                if (buffer_ready[temp_frame_index])
                {
                    CAPTURE_BEGIN( cur_fd, mmap_array, temp_frame_index );
                    buffer_ready[temp_frame_index] = 0;
                }
                cur_frame = (cur_frame + 1) % cur_buffer_count;
            }
            /*
            phPRINT("loop w:%u h:%u f:0x%08x s:%u p:%p\n",
                  loop_width,loop_height,loop_format,loop_size,loop_ptr);
            */
            /* This is the only data that needs to be copied back from the swap 
             * operation. It's the old pointer to the data in the output_buffer.
             * All the other sizes should be the same values as the ones seen
             * locally to this function */
            temp = loop_ptr;

            output_buffer->rwUnlock();
            output_locked--;
        }

        /* make sure the size of the pointer we got from the phImage is
         * the correct size for the current format/image size being
         * captured */
        if (use_disabled_swap)
        {
            temp = NULL;
        }
        else if ((loop_size != cur_image_size) && (temp != NULL))
        {
            temp = (uint8_t *)phRealloc(temp,cur_image_size);
            phCHECK_NULLPTR(temp,"phRealloc","phRealloc failed");
        }

#if TIMESTUFF()
        /* Compare the current time to the start time to figure 
         * out how fast things are being displayed */
        
        if (frames > 30)
        {
            TIMEEND(frames);
            frames = 0;
            /* This sets the start time. We'll use the start
             * * time and compare it to the end time(at the begining
             * * of this function) to find out how many frames per second
             * * are being blitted.                     */
            TIMESTART();
        }
        frames++;
#endif

        phYield();
    }
        
    /* sync with the last frame, just because */
    for (i = 0; i < cur_buffer_count; i++ )
    {
        if (!buffer_ready[i]) /* not (buffer ready) = capture in progress */
                              /* (buffer ready) = capture not progress */
        {
            CAPTURE_SYNC( cur_fd, i );
        }
    }

    /* if we disabled the swapping capability, we're using a
     * piece of memory that can't be freed by the phImage object.
     * We need to reset it so it won't segfault. */
    if (use_disabled_swap)
    {
        loop_width  = 0;
        loop_height = 0;
        /* loop_format = phImageNOFORMAT; - not valid, can't use this */
        loop_ptr    = NULL;
        loop_size   = 0;

        phWRITELOCK_LOOSE((*output_buffer),output_locked);

        /* enable the swap so we can put NULL into the object so
         * the object won't try to free our mmapped pointer */
        output_buffer->enableSwap();
        
        rc = output_buffer->swapData(&loop_width,
                                     &loop_height,
                                     &loop_format,
                                     &loop_ptr,
                                     &loop_size
                                     );
        phPRINT_RC(rc,NULL,"output_buffer->swapData");
       
        /* disable swap because it should be, yea */
        output_buffer->disableSwap();

        phRWUNLOCK_LOOSE((*output_buffer),output_locked);
    }

    DEBUG_PRINT("Thread returning cleanly\n");
   
    phDeleteArray(buffer_ready);
    phFree(temp);
    phFree(mmap_array);

    return phSUCCESS;
    
error:
    phPROGRESS("Thread returning with error\n");
    
    phRWUNLOCK_ERROR((*output_buffer),output_locked); /* 1337 */
    phDeleteArray(buffer_ready);
    phFree(temp);
    phFree(mmap_array);
    
    rc = this->signal_error();
    phPRINT_RC(rc,NULL,"this->signal_error");
    
    return phFAIL;
}

Copyright (C) 2002 - 2007

Philip D.S. Thoren ( pthoren@users.sourceforge.net ) University Of Massachusetts at Lowell Robotics Lab

---