NAME

       dtk_load_video_file - Load an video file as a texture

SYNOPSIS

       #include <dtk_video.h>

       dtk_htex dtk_load_video_file(int flags, const char *filename);

DESCRIPTION

       This  function  loads  the video file specified by filename argument as a dynamic texture.
       The texture will then been tracked by an internal texture manager so that  the  next  call
       using  the  same  filename  argument will return the same texture handle, thus sparing the
       resources of the system.  If  not  specified  by  flags  the  video  will  not  be  played
       immediately and dtk_video_exec(3) should be called to do start playing.

       The  argument  flags  is  used  to  modify  the  creation. It should contains a bitwise OR
       combination of the following flags:

              DTK_AUTOSTART : Indicates that the video should start immediately after creation.

              DTK_NOBLOCKING : Indicates that the creation function should not block waiting that
              the video pipeline is fully running.

       A  dynamic  texture can be used the same way as a static texture (for example image file).
       The only difference is that the content of the  texture  changes  automatically  with  the
       stream  of  video.  This  means  that  every time a shape using this texture is drawn, the
       latest frame available from the video stream will be mapped on the shape.

       There is no need for a valid window to create successfully a texture,  i.e.   creation  of
       textures  are  completely  decoupled from the creation of others resources and can even be
       created in one thread to be used in another one.

       Once  a   the   texture   is   stopped   being   used,   it   should   be   destroyed   by
       dtk_destroy_texture(3).

RETURN VALUE

       In  case  of  success, the function returns the handle to the created texture.  In case of
       failure, NULL is returned.

THREAD SAFETY

       dtk_load_video_file() is thread-safe.

SEE ALSO

       dtk_destroy_texture(3), dtk_video_exec(3), dtk_video_getstate(3)