Video Capture and Image Display

This section explains how to initialize a video device and display captured images on the user's display. More...

Classes

struct  CaptureFormat
 A struct containing the properties of a video capture format. More...
struct  VideoFrame
 A RGB32 image where the pixels can be accessed directly in an allocated frameBuffer. More...
struct  VideoCaptureDevice
 A struct containing the properties of a video capture device. More...

Defines

#define TT_CAPTUREFORMATS_MAX   128

Typedefs

typedef enum FourCC FourCC
 The picture format used by a capture device.
typedef struct CaptureFormat CaptureFormat
 A struct containing the properties of a video capture format.
typedef struct VideoFrame VideoFrame
 A RGB32 image where the pixels can be accessed directly in an allocated frameBuffer.
typedef struct VideoCaptureDevice VideoCaptureDevice
 A struct containing the properties of a video capture device.

Enumerations

enum  FourCC { FOURCC_NONE = 0, FOURCC_I420 = 100, FOURCC_YUY2 = 101, FOURCC_RGB32 = 102 }
 

The picture format used by a capture device.

More...

Functions

TEAMTALKDLL_API BOOL TT_GetVideoCaptureDevices (IN TTInstance *lpTTInstance, IN OUT VideoCaptureDevice *lpVideoDevices, IN OUT INT32 *lpnHowMany)
 Get the list of devices available for video capture.
TEAMTALKDLL_API BOOL TT_InitVideoCaptureDevice (IN TTInstance *lpTTInstance, IN const TTCHAR *szDeviceID, IN const CaptureFormat *lpCaptureFormat, IN const VideoCodec *lpVideoCodec)
 Initialize a video capture device.
TEAMTALKDLL_API BOOL TT_CloseVideoCaptureDevice (IN TTInstance *lpTTInstance)
 Close a video capture device.
TEAMTALKDLL_API BOOL TT_PaintVideoFrame (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN HDC hDC, IN INT32 XDest, IN INT32 YDest, IN INT32 nDestWidth, IN INT32 nDestHeight)
 Paint user's video frame using a Windows' DC (device context).
TEAMTALKDLL_API BOOL TT_PaintVideoFrameEx (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN HDC hDC, IN INT32 XDest, IN INT32 YDest, IN INT32 nDestWidth, IN INT32 nDestHeight, IN INT32 XSrc, IN INT32 YSrc, IN INT32 nSrcWidth, IN INT32 nSrcHeight)
 Paint user's video frame using a Windows' DC (device context).
TEAMTALKDLL_API BOOL TT_GetUserVideoFrame (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN OUT VOID *lpPicBuffer, IN INT32 nPicBufSize, OUT CaptureFormat *lpCaptureFormat)
 Get or query the raw RGB32 bitmap data of a user's video frame.
TEAMTALKDLL_API BOOL TT_AcquireUserVideoFrame (IN TTInstance *lpTTInstance, IN INT32 nUserID, OUT VideoFrame *lpVideoFrame)
 Extract a user's video frame by making TeamTalk allocate the image buffer.
TEAMTALKDLL_API BOOL TT_ReleaseUserVideoFrame (IN TTInstance *lpTTInstance, IN INT32 nUserID)
 Delete a user's video frame, acquired through TT_AcquireUserVideoFrame(), so its allocated resources can be released.

Detailed Description

This section explains how to initialize a video device and display captured images on the user's display.

The client is able to capture video and present them to the user application in RGB32-format and transmit the image in encoded format to other users.

Initialize Video Capture Device

To capture video the user application must first query the available capture devices by calling TT_GetVideoCaptureDevices. A VideoCaptureDevice supports a certain number of capture formats each described in the captureFormats member of CaptureFormat.

Once a device has been chosen the TT_InitVideoCaptureDevice must be called for the client instance to start capturing video frames. Use the szDevice member of VideoCaptureDevice as the device identifier for the video capture device and pass a CaptureFormat from the captureFormats array of VideoCaptureDevice. The lpVideoCodec parameter of TT_InitVideoCaptureDevice can be passed as NULL if the captured video frames do not need to be transmitted. Check out section Audio and Video Codecs on how to configure the video codec.

Display Captured Video

When a video frame becomes available the event WM_TEAMTALK_USER_VIDEOFRAME is posted to the application and TT_GetUserVideoFrame can be used to extract the RGB32 image. On Windows it's also possible to call TT_PaintVideoFrame to make the client instance paint on a HWND by getting its HDC.


Define Documentation

#define TT_CAPTUREFORMATS_MAX   128

The maximum number of video formats which will be queried for a VideoCaptureDevice.


Typedef Documentation

typedef enum FourCC FourCC

The picture format used by a capture device.

See also:
CaptureFormat
VideoCaptureDevice
typedef struct CaptureFormat CaptureFormat

A struct containing the properties of a video capture format.

A struct for holding a supported video capture format by a VideoCaptureDevice.

typedef struct VideoFrame VideoFrame

A RGB32 image where the pixels can be accessed directly in an allocated frameBuffer.

Use TT_AcquireUserVideoFrame() to acquire a user's image and remember to call TT_ReleaseUserVideoFrame() when the image has been processed so TeamTalk can release its resources.

A struct containing the properties of a video capture device.

The information retrieved from the video capture device is used to initialize the video capture device using the TT_InitVideoCaptureDevice function.

See also:
TT_GetVideoCaptureDevices

Enumeration Type Documentation

enum FourCC

The picture format used by a capture device.

See also:
CaptureFormat
VideoCaptureDevice
Enumerator:
FOURCC_NONE 

Internal use to denote no supported formats.

FOURCC_I420 

Prefered image format with the lowest bandwidth usage. A 640x480 pixel image takes up 460.800 bytes.

FOURCC_YUY2 

Image format where a 640x480 pixel images takes up 614.400 bytes.

FOURCC_RGB32 

The image format with the highest bandwidth usage. A 640x480 pixel images takes up 1.228.880 bytes.


Function Documentation

TEAMTALKDLL_API BOOL TT_GetVideoCaptureDevices ( IN TTInstance lpTTInstance,
IN OUT VideoCaptureDevice lpVideoDevices,
IN OUT INT32 *  lpnHowMany 
)

Get the list of devices available for video capture.

Parameters:
lpTTInstance Pointer to client instance created by TT_InitTeamTalk.
lpVideoDevices Array of VideoCaptureDevice-stucts where lpnHowMany hold the size of the array. Pass NULL to query the number of devices.
lpnHowMany This is both an input and output parameter. If lpVideoDevices is NULL lpnHowMany will after the call hold the number of devices, otherwise it should hold the size of the lpVideoDevices array.
See also:
TT_InitVideoCaptureDevice
TEAMTALKDLL_API BOOL TT_InitVideoCaptureDevice ( IN TTInstance lpTTInstance,
IN const TTCHAR szDeviceID,
IN const CaptureFormat lpCaptureFormat,
IN const VideoCodec lpVideoCodec 
)

Initialize a video capture device.

Parameters:
lpTTInstance Pointer to client instance created by TT_InitTeamTalk.
szDeviceID The device idenfier szDeviceID of VideoCaptureDevice.
lpCaptureFormat The capture format to use, i.e. frame-rate, resolution and picture format.
lpVideoCodec Video codec to use for transmission. Use NULL or set nCodec of VideoCodec to NO_CODEC if capture device should only be used for testing locally.
See also:
TT_GetVideoCaptureDevices
TT_CloseVideoCaptureDevice
TT_EnableTransmission
TEAMTALKDLL_API BOOL TT_CloseVideoCaptureDevice ( IN TTInstance lpTTInstance  ) 

Close a video capture device.

See also:
TT_InitVideoCaptureDevice
TEAMTALKDLL_API BOOL TT_PaintVideoFrame ( IN TTInstance lpTTInstance,
IN INT32  nUserID,
IN HDC  hDC,
IN INT32  XDest,
IN INT32  YDest,
IN INT32  nDestWidth,
IN INT32  nDestHeight 
)

Paint user's video frame using a Windows' DC (device context).

Same as calling TT_PaintVideoFrameEx() like this:

       TT_PaintVideoFrameEx(lpTTInstance, nUserID, hDC, 
                            XDest, YDest, nDestWidth,
                            nDestHeight, 0, 0, 
                            src_bmp_width, src_bmp_height);
       

src_bmp_width and src_bmp_height are extracted internally from the source image.

TEAMTALKDLL_API BOOL TT_PaintVideoFrameEx ( IN TTInstance lpTTInstance,
IN INT32  nUserID,
IN HDC  hDC,
IN INT32  XDest,
IN INT32  YDest,
IN INT32  nDestWidth,
IN INT32  nDestHeight,
IN INT32  XSrc,
IN INT32  YSrc,
IN INT32  nSrcWidth,
IN INT32  nSrcHeight 
)

Paint user's video frame using a Windows' DC (device context).

An application can either paint using TT_GetUserVideoFrame which provides a raw RGB32 array of the image or the application can ask the client instance to paint the image using this function.

Typically this paint operation will be called in the WM_PAINT message. Here is how the client instance paints internally:

       StretchDIBits(hDC, nPosX, nPosY, nWidth, nHeight, XSrc, YSrc, 
                     nSrcWidth, nSrcHeight, frame_buf, &bmi,
                     DIB_RGB_COLORS, SRCCOPY);
       
Parameters:
lpTTInstance Pointer to client instance created by TT_InitTeamTalk.
nUserID The user's ID. 0 for local user.
hDC The handle to the Windows device context.
XDest Coordinate of left corner where to start painting.
YDest Coordinate or top corner where to start painting.
nDestWidth The width of the image.
nDestHeight The height of the image.
XSrc The left coordinate in the source bitmap of where to start reading.
YSrc The top left coordinate in the source bitmap of where to start reading.
nSrcWidth The number of width pixels to read from source bitmap.
nSrcHeight The number of height pixels to read from source bitmap.
See also:
TT_GetUserVideoFrame
TEAMTALKDLL_API BOOL TT_GetUserVideoFrame ( IN TTInstance lpTTInstance,
IN INT32  nUserID,
IN OUT VOID *  lpPicBuffer,
IN INT32  nPicBufSize,
OUT CaptureFormat lpCaptureFormat 
)

Get or query the raw RGB32 bitmap data of a user's video frame.

Parameters:
lpTTInstance Pointer to client instance created by TT_InitTeamTalk.
nUserID The user's ID. 0 for local user.
lpPicBuffer A pointer to a preallocated buffer of the size specified by nPicBufSize. Pass NULL to query the user's video format which will put in lpCaptureFormat.
nPicBufSize The size in bytes of lpPicBuffer. The size must be width * height * 4. Use the lpCaptureFormat parameter to get the width and height. Ignored if lpPicBuffer is NULL.
lpCaptureFormat If not NULL the user's video frame format will be filled in this parameter. Use this information to calculate the size required of the lpPicBuffer parameter.
TEAMTALKDLL_API BOOL TT_AcquireUserVideoFrame ( IN TTInstance lpTTInstance,
IN INT32  nUserID,
OUT VideoFrame lpVideoFrame 
)

Extract a user's video frame by making TeamTalk allocate the image buffer.

Unlike TT_GetUserVideoFrame() this function does not require that the user preallocates a buffer which will contain the image data. Instead the image buffer is allocated in internally. REMEMBER, however, to call TT_ReleaseUserVideoFrame() when the image has been processed so the resources allocated by TeamTalk can be released.

Parameters:
lpTTInstance Pointer to client instance created by TT_InitTeamTalk.
nUserID The user's ID. 0 for local user.
lpVideoFrame The struct which will contain the image data. Note that it's the frameBuffer member of VideoFrame which will contain the image data allocated internally by TeamTalk.
Returns:
Returns TRUE if a video frame was successfully put in the lpVideoFrame parameter.
See also:
TT_GetUserVideoFrame
TT_ReleaseUserVideoFrame
TEAMTALKDLL_API BOOL TT_ReleaseUserVideoFrame ( IN TTInstance lpTTInstance,
IN INT32  nUserID 
)

Delete a user's video frame, acquired through TT_AcquireUserVideoFrame(), so its allocated resources can be released.

Parameters:
lpTTInstance Pointer to client instance created by TT_InitTeamTalk.
nUserID The user's ID. 0 for local user.
Returns:
Returns TRUE if a video frame was successfully put in the lpVideoFrame parameter.
See also:
TT_AcquireUserVideoFrame
TT_GetUserVideoFrame
Generated on Sun Mar 18 17:18:33 2012 for TeamTalk 4 C-API DLL by  doxygen 1.6.3