convergence.de
 cryptolabs.org
 directfb.org
 linuxtv.org
 
 linuxtv
 projects
 developer
   DVB
    API
   DVD
   Mbone
   CVS
 download
 contact
 

DVB Video API

The DVB video device controls the MPEG2 video decoder of the DVB hardware. It can be accessed through /dev/ost/audio.

The include file video.h describes the data types and lists all i/o calls. A complete explanation of all calls can be found below:

Video API IO control calls


int open(const char *deviceName, int flags);

    FUNCTION

	This system call opens a named video device (e.g. /dev/ost/video) for subsequent
        use.
        When an open() call has succeeded, the device will be ready for use.
        The significance of blocking or non-blocking mode is described in the documentation
        for functions where there is a difference. It does not affect the semantics of the
        open() call itself. A device opened in blocking mode can later be put into non-
        blocking mode (and vice versa) using the F_SETFL command of the fcntl system
        call.  This is a standard system call, documented in the Linux manual page for fcntl.
        Only one user can open the Video Device in O_RDWR mode. All other attemts to
        open the device in this mode will fail, and an errorcode will be returned.
        If the Video Device is opened in O_RDONLY mode, the only ioctl call that can be used
        is VIDEO_GET_STATUS. All other call will return an error code.


    PARAMETERS

	const char *deviceName	Name of specific video device.  In the current
                      		implementation,  /dev/ost/video is the only
                                one available.
	int flags               A bit-wise OR of the following flags:

                                O_RDONLY read-only access

                                O_RDWR read/write access

                                O_NONBLOCK open in non-blocking mode 
				           (blocking mode is the default)
    RETURNS
    
	ENODEV                  Device driver not loaded/available.

        EINTERNAL               Internal error, possibly in the communication
                                with the DVB subsystem.

        EBUSY                   Device or resource busy.

        EINVAL                  Invalid argument.



int close(int fd);

    DESCRIPTION

	This system call closes a previously opened video device

    PARAMETERS

        int fd			File descriptor returned by a previous call to open().

    RETURNS
    
	EBADF                                   fd is not a valid open file descriptor



size_t write(int fd, const void *buf, size_t count);

    DESCRIPTION
    
	This system call is only provided if VIDEO_SOURCE_MEMORY is selected in the 
	ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in PES format.
        If O_NONBLOCK is not specified the function will block until buffer space 
	is available. The amount of data to be transferred is implied by count.

    PARAMETERS

	int fd			File descriptor returned by a previous call to open().

        void *buf		Pointer to the buffer containing the PES data.

	size_t count		Size of buf.

    RETURNS

	EPERM                   Mode VIDEO_SOURCE_MEMORY not selected.
        
	ENOMEM			Attempted to write more data than the internal buffer can hold.

	EBADF			fd is not a valid open file descriptor




int ioctl(int fd, int request = VIDEO_STOP, boolean mode); 

    FUNCTION
	
	This ioctl call asks the Video Device to stop playing the current stream.
	Depending on the input parameter, the screen can be blanked out or
	displaying the last decoded frame.

    PARAMETERS

	int fd 		File descriptor returned by a previous call to open(). 

	int request 	Equals VIDEO_STOP for this command. 

	Boolean mode 	Indicates how the screen shall be handled. 

			TRUE: Blank screen when stop. 
			FALSE: Show last decoded frame.

    RETURNS

	EBADF 		fd is not a valid open file descriptor 

	EINTERNAL 	Internal error, possibly in the communication with 
			the DVB subsystem.




int ioctl(int fd, int request = VIDEO_PLAY); 

    FUNCTION 
	
	This ioctl call asks the Video Device to start playing a video stream 
	from the selected source.

    PARAMETERS

	int fd 		File descriptor returned by a previous call to open(). 

	int request 	Equals VIDEO_PLAY for this command.


    RETURNS

	EBADF 		fd is not a valid open file descriptor 

	EINTERNAL 	Internal error, possibly in the communication with 
			the DVB subsystem.



int ioctl(int fd, int request = VIDEO_FREEZE); 

    FUNCTION 

	This ioctl call suspends the live video stream being played. 
	Decoding and playing are frozen. It is then possible to restart 
	the decoding and playing process of the video stream using 
	VIDEO_CONTINUE command. If VIDEO_SOURCE_MEMORY is selected in the
	ioctl call VIDEO_SELECT_SOURCE, the DVB-subsystem will not decode 
	any more data until the ioctl call VIDEO_FREEZE or VIDEO_PLAY is 
	performed.

    PARAMETERS 
	
	int fd 		File descriptor returned by a previous call to open(). 

	int request 	Equals VIDEO_FREEZE for this command. 

    RETURNS 

	EBADF 		fd is not a valid open file descriptor. 

	EINTERNAL 	Internal error, possibly in the communication with
			the DVB subsystem.




int ioctl(int fd, int request = VIDEO_CONTINUE); 

    FUNCTION 

	This ioctl call restarts decoding and playing processes of the video
	stream which was played before a call to VIDEO_FREEZE was made.

    PARAMETERS 

	int fd 		File descriptor returned by a previous call to open(). 

	int request 	Equals VIDEO_CONTINUE for this command.

    RETURNS 

	EBADF 		fd is not a valid open file descriptor. 

	EINTERNAL 	Internal error, possibly in the communication with 
			the DVB subsystem.




int ioctl(int fd, int request = VIDEO_SELECT_SOURCE, videoStreamSource_t source); 

    FUNCTION
	
	This ioctl call informs the video device which source shall be used 
	for the input data. The possible sources are demux or memory. If 
	internal is selected, the data is feed to the Video Device through 
	the write command.

    PARAMETERS 

	int fd 		File descriptor returned by a previous call to open(). 

	int request 	Equals VIDEO_SELECT_SOURCE for this command. 

	videoStreamSource_t source 
			Indicates which source shall be used for the Video stream.

    RETURNS 

	EBADF 		fd is not a valid open file descriptor. 
	
	EINTERNAL 	Internal error, possibly in the communication with 
			the DVB subsystem.




int ioctl(int fd, int request = VIDEO_SET_BLANK, boolean mode);

    DESCRIPTION
	
	This ioctl call asks the Video Device to blank out the picture.

    PARAMETERS

	int fd			File descriptor returned by a previous call to open().

        int request		Equals VIDEO_SET_BLANK for this command.

	boolean mode		TRUE: Blank screen when stop.
                 		FALSE:  Show last decoded frame.

    RETURNS

	EBADF		      	fd is not a valid open file descriptor.

        EINTERNAL		Internal error
	
	EINVAL      		Illegal input parameter.




int ioctl(int fd, int request = VIDEO_GET_STATUS, struct videoStatus *status);

    DESCRIPTION
    
	This ioctl call asks the Video Device to return the current status of the device.

    PARAMETERS

	int fd			File descriptor returned by a previous call to open().

	int request		Equals VIDEO_GET_STATUS for this command.

	struct videoStatus      Returns the current status of the Video Device.
               *status


    RETURNS

	EBADF    		fd is not a valid open file descriptor.

	EINTERNAL  		Internal error

	EFAULT                  status points to invalid address




int ioctl(int fd, int request = VIDEO_GET_EVENT, struct videoEvent *ev);

    DESCRIPTION

	This ioctl call returns an event of type videoEvent if available.
	If an event is not available, the behavior depends on whether the device is in
	blocking or non-blocking mode.  In the latter case, the call fails immediately
	with errno set to EWOULDBLOCK. In the former case, the call blocks until an 
	event becomes available.
        The standard Linux poll() and/or select() system calls can be used with the 
	device file descriptor to watch for new events.  For select(), the file 
	descriptor should be included in the exceptfds argument, and for poll(), 
	POLLPRI should be specified as the wake-up condition.
        Read-only permissions are sufficient for this ioctl call.

    PARAMETERS
          
	int fd			File descriptor returned by a previous call to open().

        int request		Equals VIDEO_GET_EVENT for this command.

	struct videoEvent *ev 	Points to the location where the event, if any, is
                                to be stored.


    RETURNS
    
	EBADF    		fd is not a valid open file descriptor

	EFAULT                  ev points to invalid address

        EWOULDBLOCK             There is no event pending, and the device is in 
				non-blocking mode.

        EBUFFEROVERFLOW         Overflow in event queue - one or more events were lost.




int ioctl(int fd, int request = VIDEO_SET_DISPLAY_FORMAT, videoDisplayFormat_t format);

    DESCRIPTION

	This ioctl call asks the Video Device to select the video format to be applied
	by the MPEG chip on the video.

    PARAMETERS

	int fd			File descriptor returned by a previous call to open().

	int request		Equals  VIDEO_SET_DISPLAY_FORMAT for this command.

	videoDisplayFormat_t	Selects the video format to be used.
        format
        
    RETURNS
    
	EBADF			fd is not a valid open file descriptor.

	EINTERNAL		Internal error

        EINVAL			Illegal parameter format.




int ioctl(int fd, int request = VIDEO_STILLPICTURE, struct videoDisplayStillPicture *sp);

    DESCRIPTION

	This ioctl call asks the Video Device to display a still picture (I-frame). 
	The input data shall contain an I-frame. If the pointer is NULL, then the 
	current displayed still picture is blanked.
	
    PARAMETERS

	int fd			File descriptor returned by a previous call to open().

	int request		Equals VIDEO_STILLPICTURE for this command.

        struct videoDisplayStillPicture	*sp	Pointer to a location where an I-frame
                                        	and size is stored.

    RETURNS
	
	EBADF			fd is not a valid open file descriptor.

	EINTERNAL		Internal error

	EFAULT			sp points to an invalid iframe.




int ioctl(int fd, int request = VIDEO_FAST_FORWARD, int nFrames);

    DESCRIPTION
    
	This ioctl call asks the Video Device to skip decoding of N number of I-frames.
	This call can only be used if VIDEO_SOURCE_INTRENAL is selected.

    PARAMETERS
	
	int fd			File descriptor returned by a previous call to open().

	int request		Equals VIDEO_FAST_FORWARD for this command.

	int nFrames		The number of frames to skip.

    RETURNS

	EBADF			fd is not a valid open file descriptor.

	EINTERNAL               Internal error

        EPERM			Mode VIDEO_SOURCE_MEMORY not selected.

	EINVAL			Illegal parameter format.




int ioctl(int fd, int request = VIDEO_SLOWMOTION, int nFrames);

    DESCRIPTION

	This ioctl call asks the Video Device to repeat decoding frames N number of times.
	This call can only be used if VIDEO_SOURCE_MEMORY is selected.

    PARAMETERS

	int fd			File descriptor returned by a previous call to open().

	int request		Equals VIDEO_SLOWMOTION for this command.

	int nFrames		The number of frames to skip.

    RETURNS

	EBADF			fd is not a valid open file descriptor.

	EINTERNAL		Internal error

        EPERM                   Mode VIDEO_SOURCE_MEMORY not selected.

        EINVAL                  Illegal parameter format.