VideoFrame Class Reference

#include <Video/VideoFrame.H>

Collaboration diagram for VideoFrame:

[legend]List of all members.

---

Detailed Description

Simple class that encpasulates information about a video frame.

This includes information about the format in which the frame is encoded, its size, and of course the raw framebuffer data itself.

NOTE: The purpose of this class is to take the place of just passing raw buffer pointers around; instead, we wrap the buffer pointer along with associated descriptive information. However, BEWARE that we have no strong safeguards to ensure that the internal buffer pointer stays "live" for very long. If you want to keep a VideoFrame object around for a "long" time (say, holding it for longer than the function call in which you received it in the first place), then you should call deepCopyOf() on it to get a safe VideoFrame; that way the VideoFrame will make an internal private copy of the frame buffer which can live as long as the object lives without becoming corrupted.

Definition at line 71 of file VideoFrame.H.

Public Member Functions
	VideoFrame ()
	Default constructor; be sure to initialize before use, though!
	VideoFrame (const byte *data, const size_t length, const Dims &dims, const VideoFormat mode, const bool byteswap, const bool strictLength)
	Construct by borrowing 'data' buffer.
	VideoFrame (const ArrayHandle< byte > &hdl, const Dims &dims, const VideoFormat mode, const bool byteswap)
	Construct with all information needed to convert to RGB, save to disk, etc.
	VideoFrame (const Image< byte > &gray)
	Construct from a grayscale image (using VIDFMT_GREY).
	VideoFrame (const Image< PixRGB< byte > > &rgb)
	Construct from an RGB image (using VIDFMT_RGB24).
	VideoFrame (const Image< PixVideoYUV< byte > > &yuv)
	Construct from a VideoYUV image (using VIDFMT_YUV24).
	~VideoFrame ()
	Destructor.
	VideoFrame (const VideoFrame &that)
	Copy constructor.
VideoFrame &	operator= (const VideoFrame &that)
	Assignment operator.
bool	initialized () const
	Check if we have any data.
const byte *	getBuffer () const
	Get the raw buffer pointer.
size_t	getBufSize () const
	Get the length of the buffer.
const Dims &	getDims () const
	Get the dimensions of the frame.
VideoFormat	getMode () const
	Get the video mode.
bool	getByteSwap () const
	Get the byteswap state.
VideoFrame	makeBobDeinterlaced (int in_bottom_field) const
	Deinterlace the frame using the "bob" method.
VideoFrame	getFlippedHoriz () const
	Flip the frame in the horizontal direction.
std::string	diskDumpMmap (const char *fstem, bool flush=false) const
	Dump the frame to a disk file using mmap().
std::string	diskDumpStdio (const char *fstem, bool flush=false) const
	Dump the frame to a disk file using posix io functions.
Image< PixRGB< byte > >	toRgb () const
	Convert the buffer to RGB, according to its video mode.
Image< PixRGB< uint16 > >	toRgbU16 () const
void	toYuvComponents (Image< byte > &y, Image< byte > &u, Image< byte > &v) const
	Extract individual Y/U/V component images from the buffer, if possible.
Static Public Member Functions
static VideoFrame	fromFile (const char *fname, const Dims &dims, const VideoFormat mode, const bool byteswap, const bool strictLength=false)
	Pseudo-constructor that builds a VideoFrame from a raw file.
static VideoFrame	fromStream (std::istream &strm, const Dims &dims, const VideoFormat mode, const bool byteswap, const bool fail_is_fatal=true)
	Pseudo-constructor that builds a VideoFrame from an input stream.
static VideoFrame	deepCopyOf (const VideoFrame &original)
	Make a new VideoFrame object with an internal private copy of the frame data.
Classes
class	Storage
	Abstract base class for various storage back-ends. More...

---

Constructor & Destructor Documentation

VideoFrame::VideoFrame (   )

Default constructor; be sure to initialize before use, though! Definition at line 213 of file VideoFrame.C. References GVX_TRACE. Referenced by deepCopyOf(), fromStream(), getFlippedHoriz(), and makeBobDeinterlaced().

VideoFrame::VideoFrame (  const byte *  data, const size_t  length, const Dims &  dims, const VideoFormat  mode, const bool  byteswap, const bool  strictLength )

Construct by borrowing 'data' buffer. The caller is responsible for ensuring that 'data' points to valid memory for as long as the VideoFrame object lives, and for freeing/deleting 'data' afterwards. If you need to hold on to the frame for a long time, then call deepCopyOf() to get a VideoFrame that can be safely held. Definition at line 225 of file VideoFrame.C. References checkDataLength(), and GVX_TRACE.

VideoFrame::VideoFrame (  const ArrayHandle< byte > &  hdl, const Dims &  dims, const VideoFormat  mode, const bool  byteswap )

Construct with all information needed to convert to RGB, save to disk, etc. Definition at line 242 of file VideoFrame.C. References checkDataLength(), and GVX_TRACE.

VideoFrame::VideoFrame (  const Image< byte > &  gray  )  [explicit]

Construct from a grayscale image (using VIDFMT_GREY). Definition at line 257 of file VideoFrame.C. References checkDataLength(), and GVX_TRACE.

VideoFrame::VideoFrame (  const Image< PixRGB< byte > > &  rgb  )  [explicit]

Construct from an RGB image (using VIDFMT_RGB24). Definition at line 271 of file VideoFrame.C. References ASSERT, checkDataLength(), and GVX_TRACE.

VideoFrame::VideoFrame (  const Image< PixVideoYUV< byte > > &  yuv  )  [explicit]

Construct from a VideoYUV image (using VIDFMT_YUV24). Definition at line 286 of file VideoFrame.C. References ASSERT, checkDataLength(), and GVX_TRACE.

VideoFrame::~VideoFrame (   )

Destructor. Definition at line 301 of file VideoFrame.C. References GVX_TRACE.

VideoFrame::VideoFrame (  const VideoFrame &  that  )

Copy constructor. Definition at line 307 of file VideoFrame.C. References GVX_TRACE.

---

Member Function Documentation

VideoFrame VideoFrame::deepCopyOf (  const VideoFrame &  original  )  [static]

Make a new VideoFrame object with an internal private copy of the frame data. This allows the returned VideoFrame object to be long-lived (on the other hand, the original VideoFrame's buffer is prone to being eventually overwritten by the frame grabber or movie stream that originally produced it). Definition at line 386 of file VideoFrame.C. References rutz::scoped_ptr< T >::get(), getBufSize(), GVX_TRACE, initialized(), itsByteSwap, itsData, itsDims, itsMode, itsStorage, and VideoFrame(). Referenced by GenericFrame::deepCopyOf(), and DisplayController::setBackground().

std::string VideoFrame::diskDumpMmap (  const char *  fstem, bool  flush = false )  const

Dump the frame to a disk file using mmap(). A filename extension appropriate to the frame's VideoFormat will be added to the given filename stem. Returns the full filename of the file that was actually written. Parameters: flush  if true, then do an fsync() on the file before returning Definition at line 653 of file VideoFrame.C. References addExtension(), ASSERT, getBufSize(), GVX_TRACE, and PLFATAL. Referenced by dummy_namespace_to_avoid_gcc411_bug_DiskDataStream_C::DiskDumpJob::run(), and YuvWriter::writeFrame().

std::string VideoFrame::diskDumpStdio (  const char *  fstem, bool  flush = false )  const

Dump the frame to a disk file using posix io functions. A filename extension appropriate to the frame's VideoFormat will be added to the given filename stem. Returns the full filename of the file that was actually written. Parameters: flush  if true, then do an fsync() on the file before returning Definition at line 697 of file VideoFrame.C. References addExtension(), getBufSize(), GVX_TRACE, and PLFATAL. Referenced by dummy_namespace_to_avoid_gcc411_bug_DiskDataStream_C::DiskDumpJob::run().

VideoFrame VideoFrame::fromFile (  const char *  fname, const Dims &  dims, const VideoFormat  mode, const bool  byteswap, const bool  strictLength = false )  [static]

Pseudo-constructor that builds a VideoFrame from a raw file. Parameters: strictLength  if true, then we will throw an error if the data length of the file is larger the length that would be expected based on the given Dims and VideoFormat; if the file length is too small, we will unconditionally throw an error regardless of whether strictLength is true Definition at line 339 of file VideoFrame.C. References checkDataLength(), itsByteSwap, itsData, itsDataLength, itsDims, itsMode, itsStorage, and rutz::scoped_ptr< T >::reset(). Referenced by YuvParser::getFrame().

VideoFrame VideoFrame::fromStream (  std::istream &  strm, const Dims &  dims, const VideoFormat  mode, const bool  byteswap, const bool  fail_is_fatal = true )  [static]

Pseudo-constructor that builds a VideoFrame from an input stream. Definition at line 361 of file VideoFrame.C. References data, ArrayData< T >::dataw(), getFrameSize(), LFATAL, NO_INIT, ArrayHandle< T >::uniq(), and VideoFrame(). Referenced by YuvParser::getFrame(), and MrawvDecoder::readFrame().

const byte* VideoFrame::getBuffer (   )  const [inline]

Get the raw buffer pointer. Definition at line 136 of file VideoFrame.H. Referenced by VideoFormatConverter::apply(), GenericFrame::asGrayU16(), GenericFrame::asGrayU8Layout(), GenericFrame::asGrayU8NTSCLayout(), convertVideoFrameToAVFrame(), SDLdisplay::displayVideoOverlay(), SDLdisplay::displayVideoOverlay_image(), SDLdisplay::displayVideoOverlay_pos(), IntegerInput::fromVideo(), getFlippedHoriz(), makeBobDeinterlaced(), operator==(), HashOutputSeries::Impl::printHash(), toYuvComponents(), MrawvEncoder::writeFrame(), MgzEncoder::writeFrame(), and UcbMpegEncoder::writeVideoFrame().

size_t VideoFrame::getBufSize (   )  const

Get the length of the buffer. Definition at line 411 of file VideoFrame.C. References ASSERT, getFrameSize(), and GVX_TRACE. Referenced by VideoFormatConverter::apply(), deepCopyOf(), diskDumpMmap(), diskDumpStdio(), IntegerInput::fromVideo(), operator==(), HashOutputSeries::Impl::printHash(), toRgb(), toRgbU16(), MrawvEncoder::writeFrame(), MgzEncoder::writeFrame(), and UcbMpegEncoder::writeVideoFrame().

bool VideoFrame::getByteSwap (   )  const [inline]

Get the byteswap state. Definition at line 148 of file VideoFrame.H. Referenced by VideoFormatConverter::apply(), GenericFrame::frameSpec(), getFlippedHoriz(), makeBobDeinterlaced(), and MgzEncoder::writeFrame().

const Dims& VideoFrame::getDims (   )  const [inline]

Get the dimensions of the frame. Definition at line 142 of file VideoFrame.H. Referenced by VideoFormatConverter::apply(), GenericFrame::asGrayU16(), GenericFrame::asGrayU8Layout(), GenericFrame::asGrayU8NTSCLayout(), convertVideoFrameToAVFrame(), SDLdisplay::displayVideoOverlay(), SDLdisplay::displayVideoOverlay_image(), SDLdisplay::displayVideoOverlay_pos(), IntegerInput::fromVideo(), GenericFrame::getDims(), getFlippedHoriz(), makeBobDeinterlaced(), toYuvComponents(), UcbMpegEncoder::writeVideoFrame(), and FfmpegEncoder::writeVideoFrame().

VideoFrame VideoFrame::getFlippedHoriz (   )  const

Flip the frame in the horizontal direction. For now, this only works with VIDFMT_YUV420P frames (which are typically read from ffmpeg and displayed in SDL). Definition at line 585 of file VideoFrame.C. References ArrayData< T >::dataw(), getBuffer(), getByteSwap(), getDims(), getFrameSize(), GVX_TRACE, Dims::h(), h, i, LFATAL, NO_INIT, src, ArrayHandle< T >::uniq(), VideoFrame(), Dims::w(), and w. Referenced by cacheFrame().

VideoFormat VideoFrame::getMode (   )  const [inline]

Get the video mode. Definition at line 145 of file VideoFrame.H. Referenced by VideoFormatConverter::apply(), GenericFrame::asGrayU16(), GenericFrame::asGrayU8Layout(), GenericFrame::asGrayU8NTSCLayout(), coerceVideoFormat(), convertVideoFrameToAVFrame(), SDLdisplay::displayVideoOverlay(), SDLdisplay::displayVideoOverlay_image(), SDLdisplay::displayVideoOverlay_pos(), doRescale(), LuminanceOfilt::filterFrame(), ColorizeOfilt::filterFrame(), CoerceVideoFormatOfilt::filterFrame(), GenericFrame::frameSpec(), IntegerInput::fromVideo(), makeBobDeinterlaced(), operator==(), MgzEncoder::writeFrame(), SDLdisplayStream::writeFrame(), and UcbMpegEncoder::writeVideoFrame().

bool VideoFrame::initialized (   )  const [inline]

Check if we have any data. Definition at line 133 of file VideoFrame.H. References Dims::isNonEmpty(). Referenced by GenericFrame::asVideo(), cacheFrame(), deepCopyOf(), main(), HalfFieldDeinterlacer< BottomField >::readFrame(), and BobDeinterlacer::readFrame().

VideoFrame VideoFrame::makeBobDeinterlaced (  int  in_bottom_field  )  const

Deinterlace the frame using the "bob" method. Parameters: in_bottom_field  determines whether to return the rescaled top field or rescaled bottom field Definition at line 531 of file VideoFrame.C. References bobDeinterlace(), ArrayData< T >::dataw(), getBuffer(), getByteSwap(), getDims(), getFrameSize(), getMode(), getScanlineWidth(), GVX_TRACE, Dims::h(), h, NO_INIT, src, ArrayHandle< T >::uniq(), VideoFrame(), Dims::w(), and w. Referenced by HalfFieldDeinterlacer< BottomField >::readFrame(), and BobDeinterlacer::readFrame().

VideoFrame & VideoFrame::operator= (  const VideoFrame &  that  )

Assignment operator. Definition at line 322 of file VideoFrame.C. References rutz::scoped_ptr< T >::get(), GVX_TRACE, itsByteSwap, itsData, itsDataLength, itsDims, itsMode, itsStorage, and rutz::scoped_ptr< T >::reset().

Image< PixRGB< byte > > VideoFrame::toRgb (   )  const

Convert the buffer to RGB, according to its video mode. Definition at line 725 of file VideoFrame.C. References fromARGB(), fromBayer(), fromMono(), fromRGB(), fromRGB555(), fromRGB565(), fromVideoHM12(), fromVideoYUV24(), fromVideoYUV410P(), fromVideoYUV411(), fromVideoYUV411P(), fromVideoYUV420P(), fromVideoYUV422(), fromVideoYUV422P(), fromVideoYUV444(), fromVideoYUV444P(), getBufSize(), GVX_TRACE, LFATAL, p, and s. Referenced by GenericFrame::asRgbU8Layout(), convertAVFrameToRGB(), operator==(), UcbMpegEncoder::writeVideoFrame(), and FfmpegEncoder::writeVideoFrame().

void VideoFrame::toYuvComponents (  Image< byte > &  y, Image< byte > &  u, Image< byte > &  v )  const

Extract individual Y/U/V component images from the buffer, if possible. This function will LFATAL() if the VideoFrame data is in a non-YUV mode (such as RGB or grayscale), so you need to check the data mode is appropriate before trying to call this function. Depending on the data mode, the individual component images may not be all the same size; in particular, the y component is likely to be at the full image size, while the u and v components may be downscaled by a factor of 2 or 4. So, you will need to check the Dims of the result images before doing further processing with them. Definition at line 798 of file VideoFrame.C. References buf, convertToString(), getBuffer(), getDims(), LFATAL, and Dims::sz().

---

The documentation for this class was generated from the following files:

• src/Video/VideoFrame.H
• src/Video/VideoFrame.C

---