.\"Copyright 2011 (c) EPFL
.TH DTK_VIDEO_EXEC 3 2011 "EPFL" "Draw Toolkit manual"
.SH NAME
dtk_video_exec - Start/stop/pause a video texture
.SH SYNOPSIS
.LP
.B #include <dtk_video.h>
.sp
.BI "int dtk_video_exec(dtk_htex " vid ", int " command ", const void* " arg ");"
.br
.SH DESCRIPTION
.LP
This function changes the state (or playing position) of a video texture
referenced by \fIvid\fP according to the value of \fIcommand\fP:
.TP
\fBDTKV_CMD_PLAY\fP: Set the video to play. \fIarg\fP is interpreted as a
pointer to a variable of type \fBint\fP whose non zero value indicates that
the state change is asynchronous and can be finished after the function
returns. If \fIarg\fP is NULL, the change is performed synchronously.
.TP
\fBDTKV_CMD_PAUSE\fP: Set the video to pause. \fIarg\fP is interpreted as a
pointer to a variable of type \fBint\fP whose non zero value indicates that
the state change is asynchronous and can be finished after the function
returns. If \fIarg\fP is NULL, the change is performed synchronously.
.TP
\fBDTKV_CMD_SEEK\fP: Seek the video to the position specified by \fIarg\fP
which is then interpreted as a pointer to a variable of type \fBlong\fP
representing the position in milliseconds from the beginning of the video.
\fIarg\fP is allowed to be NULL. In that case, the video will be positioned
at its start.
.LP
\fIvid\fP must be a dynamic texture created by one of the functions 
\fBdtk_create_video_*\fP(3). If the video was already in the requested
state, the function will do nothing.
.LP
If the video is created from the live source (webcam, network broadcast...),
executing \fBDTKV_CMD_SEEK\fP will fail.
.SH "RETURN VALUE"
.LP
0 if the state has been changed or was already the one requested, \-1 otherwise.
.SH "SEE ALSO"
.BR dtk_load_video_file (3),
.BR dtk_load_video_gst (3),
.BR dtk_load_video_test (3),
.BR dtk_load_video_udp (3),
.BR dtk_load_video_tcp (3)