QVBaseReader Class Reference

Pure virtual base class to create input video reader components for the QVision architecture. More...

#include <QVBaseReader>

Inherited by QVDirReader, QVMPlayerReader, QVOpenCVReader, and QVYUV4MPEG2Reader.

Public Member Functions
	QVBaseReader ()
	Constructs a QVBaseReader.
	~QVBaseReader ()
	Destroys a QVBaseReader.
virtual bool	open (const QString &url_string, unsigned int &suggested_cols, unsigned int &suggested_rows, unsigned int &suggested_fps, QVVideoReader::OpenOptions &suggested_opts, QVVideoReader::TSourceMode &source_mode)=0
	Pure virtual open method.
virtual bool	close ()=0
	Pure virtual close method.
virtual bool	grab (QVImage< uChar, 1 > &imgY_R, QVImage< uChar, 1 > &imgU_G, QVImage< uChar, 1 > &imgV_B)=0
	Pure virtual grab method.
virtual int	getLength ()=0
	Pure virtual method to get the length of the video.
virtual int	getPos ()=0
	Pure virtual method to get the current position in the video.
virtual bool	seek (int pos)=0
	Pure virtual method to set the current position in the video.

Detailed Description

Pure virtual base class to create input video reader components for the QVision architecture.

Note:: Normal QVision users do not need to worry about this class and its derived classes, unless they want to implement new video sources (apart from the wide range of video sources supported by QVision; see QVVideoReader for a comprehensive list of supported video sources).

This class is pure virtual, and should not be used by normal QVision users (except when implementing their own video sources, such as, say, direct driver-based IEEE 1394 or V4L2 cameras; remember, though, that QVVideoReader can read almost any kind of video input source, including video files and live cameras, such as USB webcams, IEEE 1394 cameras, remote streaming videos and even directories of image files, among many other possibilities). Any derived classes of QVBaseReader (currently QVMPlayerReader, QVOpenCVReader, QVDirReader and QVYUV4MPEG2Reader) are the (internal) classes responsible for implementing all this functionality. This classes are not documented because they will not be used directly by final users, though taking a look at their sources could be useful for new video sources implementors.

Implementors of new kind of QVVideoReader classes should only have to redefine these six pure virtual methods:

virtual bool open(const QString & url_string,
                  unsigned int & suggested_cols,unsigned int & suggested_rows, unsigned int & suggested_fps,
                  QVVideoReader::OpenOptions & suggested_opts, QVVideoReader::TSourceMode & source_mode) = 0;

virtual bool close() = 0;

virtual bool grab(QVImage<uChar,1> &imgY_R, QVImage<uChar,1> &imgU_G, QVImage<uChar,1> &imgV_B) = 0;

virtual int getLength() = 0;

virtual int getPos() = 0;

virtual bool seek(int pos) = 0;

Whose desired behaviour is almost self-explanatory (if we are confident with the QVVideoReader class program interface):

The first one (QVBaseReader::open) should open the video source specified by the string url_string, trying to open it with the suggested cols, rows and fps. The url_string is a generic QString that will be used differenty by the diferent classes inheriting from QVBaseReader, according to their needs (see code source for those classes and QVVideoReader documentation for some examples). The same can be said for the rest of suggested parameters (rows, cols, fps and opening options). Finally, the output parameter source_mode (of type QVVideoReader::TSourceMode) will return QVVideoReader::YUVMode, QVVideoReader::RGBMode or QVVideoReader::GrayOnlyMode if the capture method of the source returns YUV, RGB or gray images, respectively, by default. If the video source allows to choose for any of these modes, this parameter could also be used as input, taking into account that it is only a recomendation and, as is the case with suggested_rows, suggested_cols and suggested_fps, the output value will be the mode that will be really used. The method must indicate a successful opening by returning true (and updating the corresponding suggested_cols, suggested_rows and suggested_fps output values to the really obtained ones, which could coincide or not with the suggested input values), or false, if there was any problem opening the source.

The second (QVBaseReader::close) must close the video source, returning true on success.

The third (QVBaseReader::grab) must grab either the Y, U and V channel images in the corresponding variable parameters, with respective sizes $cols \times rows$ , $cols/2 \times rows/2$ and $cols/2 \times rows/2$ , or the R, G and B channel images, in this case the three of them with $cols \times rows$ size. If the YUV or RGB images are the ones that the method will fill is determined by the value source_mode returned by the open method (see QVVideoReader::TSourceMode). In all cases the values cols and rows (i.e., the size of the output images) will correspond with the values suggested_cols and suggested_rows as returned by the corresponding open method. The grab method should return true if grabbing was succesful, or false otherwise (for example, if the video source was closed).

The fourth method (QVBaseReader::getLength) must return the length of the video, as an integer value. This value is usually expressed in total number of frames, though it can also be 0 if it is not available (for example, for live video cameras), or even in any other integer units (such as seconds, milliseconds, or whatever, depending on the kind of video source).

The fifth method (QVBaseReader::getPos) must return the current position in the video, again as an integer value (the same comments for units on the former method apply).

Finally, the sixth method (QVBaseReader::seek) must set, if possible, the current position on the video, again in the same units as the former two methods, returning true if the seek operation was succesful.

Remarks:

Remember that each video source will have a preferred Gray, YUV or RGB output mode. Thus, if a given source has, say, a YUV output preferred mode (such as in a QVMPlayerReader, for example), there is no point in performing a YUV to RGB conversion inside the corresponding inheriting class of QVBaseReader, because this is implemented for every video source in the more general class QVVideoReader (which is itself client of this QVBaseReader class). An analogous argument holds for the converse case -preferred output mode RGB (as in a QVOpenCVReaderBlock), and desired YUV output-, as well as for image rescalings (resizing), which are also implemented in QVVideoReader, and thus should not be performed by the inheriting class. Thus, the suggested cols and rows parameters should only be treated by the video source itself (for example, to suggest an adequate opening size for a camera), and not as a rescaling after the capture (which is in any case performed by the client class QVVideoReader).

Anyway, the QVision library currently only makes these conversions/resizings if the Intel IPP library module has been enabled; otherwise, the user will be presented an according error message, and will be requested to use the other set of three images, and then perform the conversion in its own program.

When reimplementing this class for gray only sources, use QVVideoReader::GrayOnlyMode (see QVVideoReader::TSourceMode) and fill the Y image in the reimplemented grab method with the gray image, and then two 128 valued images downscaled to 1/2 of its size for the U and V channels.

Of course, in every case the reimplemented grab method for the QVBaseReader subclass must return R, G and B or Y, U and V images with corresponding correct sizes (i.e., same sizes for R, G, and B channels, and U and V channels half sized with respect to the Y channel). Otherwise a fatal error will occur when trying to read from the video source, and the application will immediately abort.

See also:: QVVideoReader QVVideoReaderBlock

Definition at line 136 of file qvbasereader.h.

Constructor & Destructor Documentation

QVBaseReader::QVBaseReader ( ) [inline]

Constructs a QVBaseReader.

Definition at line 140 of file qvbasereader.h.

QVBaseReader::~QVBaseReader ( ) [inline]

Destroys a QVBaseReader.

Definition at line 143 of file qvbasereader.h.

Member Function Documentation

virtual bool QVBaseReader::open	(	const QString &	url_string,
		unsigned int &	suggested_cols,
		unsigned int &	suggested_rows,
		unsigned int &	suggested_fps,
		QVVideoReader::OpenOptions &	suggested_opts,
		QVVideoReader::TSourceMode &	source_mode
	)			`[pure virtual]`

Pure virtual open method.

Reimplementations of this method should open the video source specified by url_string, trying to open it with the suggested cols, rows and fps. The method must indicate a successful opening by returning true (and updating the corresponding suggested_cols, suggested_rows and suggested_fps output values to the really obtained ones, which could coincide or not with the suggested input values), or false, if there was any problem opening the source. The same can be said for the suggested opening options. Finally, the output parameter source_mode will return QVVideoReader::YUVMode, QVVideoReader::RGBMode or QVVideoReader::GrayOnlyMode if the capture method of the source returns YUV, RGB or gray images, respectively, by default. If the video source allows to choose for any of three modes, this parameter could also be used as input, taking into account that it is only a recomendation and, as is the case with suggested_rows, suggested_cols and suggested_fps, the output value will be the mode that will be really used.

Parameters:

	url_string	QString determining the video source.
	suggested_cols	Suggested number of columns (as input). On return contains real number of columns (as output).
	suggested_rows	Suggested number of rows (as input). On return contains real number of rows (as output).
	suggested_fps	Suggested fps (as input). On return contains real fps (as output).
	suggested_opts	Suggested options (as input).
	source_mode	Set to suggested source mode (as input) and set to source preferred mode (on output).

Returns:: true if success, false in case of failure.

Referenced by QVVideoReader::open().

virtual bool QVBaseReader::close ( ) [pure virtual]

Pure virtual close method.

Reimplementations of this method should close the video source.

Returns:: true if success, false in case of failure.

Referenced by QVVideoReader::close().

virtual bool QVBaseReader::grab	(	QVImage< uChar, 1 > &	imgY_R,
		QVImage< uChar, 1 > &	imgU_G,
		QVImage< uChar, 1 > &	imgV_B
	)			`[pure virtual]`

Pure virtual grab method.

Reimplementations of this method should grab Y, U and V channel images in the corresponding variable parameters, with respective sizes $cols \times rows$ , $cols/2 \times rows/2$ and $cols/2 \times rows/2$ (with cols and rows as returned by the open() method), if the preferred source mode as returned by open was QVVideoReader::GrayOnlyMode or QVVideoReader::YUVMode, or the R, G and B channels all with sizes $cols \times rows$ , if the preferred source mode returned by open was QVVideoReader::RGBMode. In every case the method must return true if grabbing was succesful, or false otherwise (for example, if the camera was closed). When reimplementing this class for gray only sources (@ ref QVVideoReader::GrayOnlyMode), fill the Y image in the reimplemented grab method with the gray image, and then two 128 valued images downscaled to 1/2 of its size (cols and rows) for the U and V channels.

Parameters:

	imgY_R	On return, contains the grabbed Y/R image.
	imgU_G	On return, contains the grabbed U/G image.
	imgV_B	On return, contains the grabbed V/B image.

Returns:: true if success, false in case of failure.

Referenced by QVVideoReader::grab().

virtual int QVBaseReader::getLength ( ) [pure virtual]

Pure virtual method to get the length of the video.

Reimplementations of this method should inform of the length of the video, as an integer value. This value should preferrably be in total number of frames units, though it can also be in any other integer units (such as seconds, milliseconds, or whatever) if frames units are not managed by the corresponding video source. Also, a length equal to 0 should be returned if the information is not available (for example, for live cameras, remote streaming videos, and the like).

Returns:: Total number of frames (or any other length unit; see above) of video source.

Referenced by QVVideoReader::getLength().

virtual int QVBaseReader::getPos ( ) [pure virtual]

Pure virtual method to get the current position in the video.

Reimplementations of this method should inform of the current position in the video (usually in number of frames units, but could also be in other units, such as seconds or milliseconds; see comments on method getLength above).

Returns:: Current position in video source.

Referenced by QVVideoReader::getPos().

virtual bool QVBaseReader::seek ( int pos ) [pure virtual]

Pure virtual method to set the current position in the video.

Reimplementations of this method should set the current position in the video (in number of frames units, but could also be in other units, such as seconds or milliseconds; see comments on method getLength above).

Parameters:

pos

Desired position in video source.

Returns:: true if success, false in case of failure.

Referenced by QVVideoReader::seek().

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

src/qvio/qvbasereader.h

QVBaseReader Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation