The SDK Programmer Manual of Hikvision DS-4002MDI Matrix Decode Card

SDK Programmer Manual of ILDVR3000H2D&ILDVR3000H4D Matrix Decode Board


(For Windows2000/XP/Server 2003)

Version 4.15

17/Jan/2006

1


Version Description

Version4.15 (Built on Jan 17 2006) Support the import and output of file index when playing Support to capture the original uncompressed video stream before it’s output

to monitor; Support the function to create file index when playing back files, locate the

file based on time and frame number, get the start and end time of file; Support to capture a video frame and convert it to a BMP file when

decoding; Support ILDVR3000H4D card, the ILDVR3000H4D supports 8 channels’

CIF/2CIF or 4 channels’ 4CIF decoding, support 4 channels’ video and audio output;

Optimize the network decoding delay. Consummate the PCI transmission. Add 1/3 horizontal shrink, supporting 9 windows division video output.

Old Version ILDVR3000H2D (Matrix Decode Card), used to implement video matrix and hardware decode function.

1. Hardware Decode Features: Each ILDVR3000H2D can be used to decode 4 channels image; Support the images made by the following products: ILDVR3000H4C4,

ILDVR3000H4C8 and ILDVR3000H4C16; Audio output of any 2 channels selected from the 4 decoding channels; Video output of any 2 channels, each video output can be made up of 16

windows max; Support 1 channel audio preview; At present, 16 pieces of ILDVR3000H2D decode card can be installed in one

PC, which means it can support 64 decoding channels and 32 video and audio output max;

DSP resources usage of decoding one channel (Fix bit rate, stable image): CIF: 12% (512Kbps), 16% (2Mbps); 2CIF: 30% (1Mbps); DCIF: 28% (768Kbps); 4CIF: 50% (1.5Mbps), 60% (3Mbps); The decode ability is always being optimized, newer version SDK will be released.

2. Matrix Features: Video input from either the ILDVR3000H4CX ,ILDVR3000H2D board

(including the local file and network real time stream); Video output of ILDVR3000H2D card supports screen division. The screen

can be divided into 16 windows max, also can switch the image of each

2


window. Matrix control: In the PC, for each ILDVR3000H4CX encode channel and

ILDVR3000H2D decode channel, it’s image can be display in any window of any video output of any ILDVR3000H2D card.

Each ILDVR3000H2D supports 2 video output, and each output can be 4CIF resolution;

Each encode channel of ILDVR3000H4CX can support one graphic card preview and one matrix output at the same time;

Each decode channel of ILDVR3000H2D can support one graphic card preview and two matrix output at the same time;

Each video output can support picture in picture, and the location of each window can be adjust randomly;

Each video output can support 4CIF+QCIF at most, it means that output 4CIF and QCIF with the mode of “picture in picture”.

3


SDK Error Code Description

Error Code Description

HWERR_SUCCESS Success HWERR_ALLOCATE_MEMORY Memory allocate failed HWERR_INVALID_HANDLE Invalid handle HWERR_DDRAW_CREATE_FAILED Create DirectDraw failed HWERR_DDRAW_CAPS_FAULT DirectDraw get the display device

failed HWERR_SET_COOPERATIVELEVEL_FAILED DirectDraw set cooperation level

failed HWERR_PRIMARY_SURFACE_CREATE_FAILED DirectDraw create primary surface

failed HWERR_OVERLAY_CREATE_FAILED DirectDraw create overlay failed HWERR_GET_OVERLAY_ADDRESS_FAILED DirectDraw get overlay address

failed HWERR_OVERLAY_UPDATE_FAILED DirectDraw update failed HWERR_SURFACE_NULL DirectDraw surface is null HWERR_FILEHEADER_UNKNOWN File header error HWERR_CREATE_FILE_FAILED Create or open file failed HWERR_FILE_SIZE_ZERO Length of file is too short HWERR_CREATE_OBJ_FAILED Create thread or object failed HWERR_CHANNELMAGIC_MISMATCH Channel data is destroyed HWERR_PARA_OVER Parameters are illegal HWERR_ORDER Apply sequence error HWERR_COMMAND Command transfer failed HWERR_UNSUPPORTED Not supported HWERR_DSPOPEN Open DSP failed HWERR_DSPLOAD DSP code download failed HWERR_ALLOCATE_DSPMEMORY DSP memory allocate failed HWERR_DSPCHECHER DSP check failed HWERR_IMGFILE_UNKNOWN Unknown image file HWERR_INVALID_FILE Invalid file

4


API Description 1. int __stdcall HW_InitDecDevice(long *pDeviceTotal) Description: Initialize the ILDVR3000H2D and ILDVR3000H4D card. Output parameters: pDeviceTotal: [out] total decoder channel number Return value: Error code. 2. int __stdcall HW_ReleaseDecDevice() Description: Close the ILDVR3000H2D and ILDVR3000H4D card. It must be used when the software quits. Return value: Error code. 3. int __stdcall HW_InitDirectDraw(HWND hParent, COLORREF colorKey) Description: Initialize DirectDraw. You needn’t use it if you don’t want to display the video output on VGA screen. Input parameters: hParent: the window handle. The display area must be in the window, and the display area coordinate must be the coordinate of the window. colorKey: the transparent color you will set. It likes clairvoyant film. The display image can only penetrate this kind of color. Other color will mask the display image. The display window must use this color. We suggest you to use the color not often used by other software. The value is DWORD 0x00rrggbb, the latter 3 bytes represent the value of r (red), g (green), b (blue) individually. Return value: Error code. 4. int __stdcall HW_ReleaseDirectDraw() Description: Release DirectDraw. Return value: Error code. 5. int __stdcall HW_ChannelOpen(long nChannelNum, HANDLE* phChannel) Description: Open channel to get the correspond handle. All the related operation must use the handle. Input parameters: nChannelNum: the channel number to open (start from zero).

5


Output parameters: phChannel: the channel handle. Return value: Error code. 6. int __stdcall HW_ChannelClose(HANDLE hChannel) Description: Close the channel to release the related resources. Input parameters: hChannel: the channel handle. Return value: Error code. 7. int __stdcall HW_OpenStream(HANDLE hChannel, PBYTE pFileHeadBuf,

DWORD nSize) Description: Open the stream interface (like open file). Input parameters: hChannel: the channel handle. pFileHeadBuf: the file header data buffer. nSize: the file header size. Return value: Error code. 8. int __stdcall HW_CloseStream(HANDLE hChannel) Description: Close the data stream. Input parameters: hChannel: the channel handle. Return value: Error code. 9. int __stdcall HW_InputData(HANDLE hChannel, PBYTE pBuf, DWORD

nSize) Description: You can input data after open the data stream interface. Input parameters: hChannel: the channel handle. pBuf: the buffer address. nSize: the buffer size. Return value: Return nSize if successfully, or return 0. 10. int __stdcall HW_OpenFile(HANDLE hChannel, LPTSTR sFileName)

6


Description: Open file. Input parameters: hChannel: the channel handle. sFileName: the file name. Return value: Error code. 11. int __stdcall HW_CloseFile(HANDLE hChannel) Description: Close file. Input parameters: hChannel: the channel handle. Return value: Error code. 12. int __stdcall HW_Play(HANDLE hChannel) Description: Start to play. Input parameters: hChannel: the channel handle. Return value: Error code. 13. int __stdcall HW_Stop(HANDLE hChannel) Description: Stop playing. Input parameters: hChannel: the channel handle. Return value: Error code. 14. int __stdcall HW_Pause(HANDLE hChannel, ULONG bPause) Description: Pause or continue playing. Input parameters: hChannel: the channel handle. hPause: 1 means pause, 0 means continue. Return value: Error code. 15. int __stdcall HW_PlaySound(HANDLE hChannel) Description: Open the channel sound, default is closing.

7


Input parameters: hChannel: the channel handle. Return value: Error code. 16. int __stdcall HW_StopSound(HANDLE hChannel) Description: Close the channel sound. Input parameters: hChannel: the channel handle. Return value: Error code. 17. int __stdcall HW_SetVolume(HANDLE hChannel, ULONG nVolume) Description: Adjust the sound volume. Input parameters: hChannel: the channel handle. nVolume: the sound volume, from 0 to 0xffff. Return value: Error code. 18. int __stdcall HW_RefreshSurface() Description:

Refresh the display area. When location of the window (hParent in the 3rd API) is changed, you need refresh the overlay surface to fit for the new area. Return value: Error code. 19. int __stdcall HW_RestoreSurface() Description: The overlay surface may be engrossed by other software during using process. You need use this API to get the overlay surface again. The most convenient method in MFC is calling this API in the “OnPaint” function. Return value: Error code. 20. int __stdcall HW_ClearSurface() Description: Clear the data on the overlay surface. When the window is switching, the data of the last frame image will be remained on the overlay surface. If you do not want to display the data, you can use this API to clear them. Return value: Error code.

8


21. int __stdcall HW_ZoomOverlay(RECT* pSrcClientRect, RECT*

pDecScreenRect) Description: Zoom in or zoom out the certain area on the overlay surface. This is also one of methods to display in full screen. At present, there are two methods:

One is using the enlarge function of the graphic card, to enlarge the area pSrcClientRect (client area coordinate) into full screen pDecSrceenRect (screen coordinate). Please note that the pSrcClientRect must not be less that the original image size (for example, CIF image of PAL is 352*288), or the enlarged quality is bad. Please refer to the related demo source code. The other is using the enlarge function of our board. If you set DISPLAY_PARA as appropriate value, the enlarge function of card will be adjust automatically. Please note: if you use this method, when you initialize DirectDraw, hParent must be set as the whole screen, because the display area (DISPLAY_PARA) can not be greater than the hParent area. Input parameters: pSrcClientRect: the source area, client coordinate in hParent window. PDecScreenRect: the destination area, screen coordinate. Return value: Error code. 22. int __stdcall HW_StartCapFile(HANDLE hChannel, LPTSTR sFileName) Description: Capture the current data stream and save it into file. Input parameters: hChannel: the channel handle. sFileName: the file name to record the stream. Return value: Error code. 23. int __stdcall HW_StopCapFile(HANDLE hChannel) Description: Stop capturing data stream. Input parameters: hChannel: the channel handle. Return value: Error code. 24. int __stdcall HW_GetPictureSize(HANDLE hChannel, ULONG* pWidth,

ULONG* pHeight) Description: Get size of the original image in the current stream. Input Parameters:

9


hChannel: the channel handle. Output parameters: pWidth: the width of the original image. pHeight: the height of the original image. Return value: Error code. 25. int __stdcall HW_GetSpeed(HANDLE hChannel, long nSpeed) Description: Get the playing speed. Input parameters: hChannel: the channel handle. Output parameters: nSpeed: the playing speed, from –4 to +4. Return value: Error code. 26. int __stdcall HW_SetSpeed(HANDLE hChannel, long nSpeed) Description: Set the playing speed. When nSpeed = -4, it stop playing, then use HW_Pause(hChannel, 0) play frame one by one. nSpeed: -3 means 1/8; -2 means 1/4; -1 means 1/2; 0 means normal play; 1 means two times; 2 means four times; 3 means eight times and 4 means the max speed it can. Input parameters: hChannel: the channel handle. nSpeed: the playing speed. Return value: Error code. 27. int __stdcall HW_SetPlayPos(HANDLE hChannel, ULONG nPos) Description: Set playing position. Input parameters: hChannel: the channel handle. nPos: from 0 to 100 percent position of the file. Return value: Error code. 28. int __stdcall HW_GetPlayPos(HANDLE hChannel, ULONG* pPos) Description: Get the current playing position. Input parameters: hChannel: the channel handle. Output parameters:

10


pPos: the current playing position, from 0 to 100 percent. Return value: Error code. 29. int __stdcall HW_SetJumpInterval(HANDLE hChannel, ULONG nSecond) Description: Set jump time interval. Input parameters: hChannel: the channel handle. nSecond: the time interval (second). Return value: Error code. 30. int __stdcall HW_Jump(HANDLE hChannel, ULONG nDirection) Description: Jump forward or backward. You can use the macro definition: JUMP_FORWARD, JUMP_BACKWARD. Input parameters: hChannel: the channel handle. nDirection: use the macro definition. Return value: Error code. 31. int __stdcall HW_GetVersion(PHW_VERSION pVersion) Description: Get the SDK version information. Output parameters: pVersion: the version information, the structure is as following: typedef struct{ ULONG DspVersion, DspBuildNum; ULONG DriverVersion, DriverBuildNum; ULONG SDKVersion, SDKBuildNum; }HW_VERSION, PHW_VERSION; DspVersion and DspBuildNum represent the version and built number of DSP code. DriverVersion and DriverBuildNum represent the version and built number of driver. SDKVersion and SDKBuildNum represent the version and built number of SDK. Return value: Error code. 32. int __stdcall HW_GetCurrentFrameRate(HANDLE hChannel, ULONG*

pFrameRate)

11


Description: Get the current playing frame rate. Input parameters: hChannel: the channel handle. Output parameters: pFrameRate: the frame rate. Return value: Error code. 33. int __stdcall HW_GetCurrentFrameNum(HANDLE hChannel, ULONG*

pFrameNum) Description: Get the current playing frame number. Input parameters: hChannel: the channel handle. Output parameters: pFrameNum: the frame number. Return value: Error code. 34. int __stdcall HW_GetFileTotalFrames(HANDLE hChannel, ULONG*

pTotalFrames) Description: Get the file total frame number. Input parameters: hChannel: the channel handle. Output parameters: pTotalFrames: the total frame number. Return value: Error code. 35. int __stdcall HW_GetFileTime(HANDLE hChannel, ULONG* pFileTime) Description: Get the file total time. Input parameters: hChannel: the channel handle. Output parameters: pFileTime: file total time (ms). Return value: Error code. 36. int __stdcall HW_GetCurrentFrameTime(HANDLE hChannel, ULONG*

pFrameTime) Description:

12


Get the time of the current playing frame. Input parameters: hChannel: the channel handle. Output parameters: pFrameTime: time of the current playing frame (ms). Return value: Error code. 37. int __stdcall HW_GetPlayedFrames(HANDLE hChannel, ULONG

*pDecVFrames) Description: Get the frames number that have been played. Input parameters: hChannel: the channel handle. Output parameters: pDecVFrames: the frames number that have been played. Return value: Error code. 38. int __stdcall HW_SetFileEndMsg(HANDLE hChannel, HWND hWnd,

UINT nMsg) Description: Register the self-defined windows message. When the playing file is end, the end message will be post to the assigned window. Input parameters: hChannel: the channel handle. hWnd: the window handle to receive message. nMsg: self-defined windows message. Return value: Error code. 39. int __stdcall HW_SetStreamOpenMode(HANDLE hChannel, ULONG

nMode) Description: Set the stream playing parameter. Input parameters: hChannel: the channel handle. nMode: the value is from 0 to 5. 0 represents no adjustment, fits for file playback (not real time stream). Set nMode as 1, 2, 3, 4, 5 to adjust the fluency and delay of the real time stream. The bigger the value is, more fluent and more delay the real time network stream is. Return value: Error code.

13


40. int __stdcall HW_GetStreamOpenMode(HANDLE hChannel, ULONG *pMode)

Description: Get the playing parameter of current stream. Input parameters: hChannel: the channel handle. Output parameters: pMode: the value is among 0, 1, 2, 3, 4, 5. Return value: Error code. 41. int __stdcall HW_SetAudioPreview(HANDLE hChannel, BOOL bEnable) Description: Audio preview. The audio connection method is the same as that of compression board. You can only preview the audio of one channel, the audio of other channels will be closed automatically. Please note: if you want to make audio preview into effect, you must first open all channels (HW_ChannelOpen), and must open the sound of the channel (HW_PlaySound). Input parameters: hChannel: the channel handle. bEnable: TRUE to start audio preview and FALSE to close audio preview. Return value: Error code. 42. int __stdcall HW_OpenStreamEx(HANDLE hChannel, PBYTE

pFileHeadBuf, DWORD nSize) Description: Open the data stream in video and audio detaching mode. You can use No. 44 and No. 45 API to input video and audio data respectively. Input parameters: hChannel: the channel handle. pFileHeadBuf: file header data. nSize: the length of file header. Return value: Error code. 43. int __stdcall HW_CloseStreamEx(HANDLE hChannel) Description: Close the data stream that is opened in detaching mode. Input parameters: hChannel: the channel handle. Return value: Error code.

14


44. int __stdcall HW_InputVideoData(HANDLE hChannel, PBYTE pBuf, DWORD nSize)

Description: Input video data, only after the data stream is opened (HW_OpenStreamEx). Input parameters: hChannel: the channel handle. pBuf: the buffer address. nSize: the buffer size. Return value: Return nSize if success, or return 0. 45. int __stdcall HW_InputAudioData(HANDLE hChannel, PBYTE pBuf,

DWORD nSize) Description: Input audio data, only after the data stream is opened (HW_OpenStreamEx). Input parameters: hChannel: the channel handle. pBuf: the buffer address. nSize: the buffer size. Return value: Return nSize if success, or return 0. 46. unsigned int __stdcall GetBoardCount() Description: Get the board number in the system, including encode and matrix decode boards. Return value: The number of board. 47. unsigned int __stdcall GetDspCount() Description: Get the DSP number in the system. Return value: The number of DSP. 48. int __stdcall GetBoardDetail(UINT boardNum, DS_BOARD_DETAIL

*pBoardDetail) Description: Get the detail information of one board. Input parameters: boardNum: the board index. Output parameters: DS_BOARD_DETAIL *pBoardDetail: the detail information of the board. typedef struct

{

15


BOARD_TYPE_DS type; //board type BYTE sn[16]; //board serial number UINT dspCount; //DSP number on the board

UINT firstDspIndex; //the index of the first DSP on board UINT encodeChannelCount; //encode channel number on board UINT firstEncodeChannelIndex; //index of the first encode channel

UINT decodeChannelCount; //decode channel numbers on board UINT firstDecodeChannelIndex; //index of the first decode channel UINT displayChannelCount; //video output channel numbers on board UINT firstDisplayChannelIndex; //index of first video output channel

UINT reserved1; UINT reserved2;

UINT reserved3; UINT reserved4; }DS_BOARD_DETAIL;

Return value: Error code. 49. int __stdcall GetDspDetail(UINT dspNum, DSP_DETAIL *pDspDetail) Description: Get the detail information of one DSP. Input parameters: DspNum: the DSP index. Output parameters: DSP_DETAIL *pDspDetail: the detail information of the DSP. typedef struct

{ UINT encodeChannelCount; //encode channel number of the DSP

UINT firstEncodeChannelIndex; //index of the first encode channel of the DSP in all encode channels

UINT decodeChannelCount; //decode channel number of the DSP UINT firstDecodeChannelIndex; //index of the first decode channel of the DSP in all decode channels

UINT displayChannelCount; //video output channels on the DSP UINT firstDisplayChannelIndex; //index of the first video output channel of the DSP in all video output channels



}DSP_DETAIL; Return value: Error code.

16


50. int __stdcall SetDefaultVideoStandard(VideoStandard_t VideoStandard) Description: Set default video standard. The original default value is PAL. If there is no signal for all input channels, the channel will use this default video standard. All video output will use this default standard when the system start up. Note: This API must be used before InitDSPs(). Input parameters: VideoStandard_t VideoStandard: video standard. Return value: Error code. 51. unsigned int __stdcall GetDisplayChannelCount() Description: Get the video output channels number in the system. 52. int __stdcall SetDisplayStandard(UINT nDisplayChannel, VideoStandard_t

VideoStandard) Description: Set the video standard of the video output channel. Input parameters: nDisplayChannel: index of the video output channel. VideoStandard_t VideoStandard: video standard. Return value: Error code. 53. int SetDisplayRegion (UINT nDisplayChannel,

UINT nRegionCount,REGION_PARAM *pParam,UINT nReserved) Parameters: UINT nDisplayChannel Display Channel Index UINT nRegionCount the total number of regions REGION_PARAM *pParam pointer to REGION_PARAM UINT nReserved be reserved typedef struct { UINT left; Specifies the x-coordinate of the upper-left corner of region UINT top; Specifies the y-coordinate of the upper-left corner of region UINT width; Specifies the width of the region UINT height; Specifies the height of the region COLORREF color; Specifies the background color of the region UINT param; be reserved }REGION_PARAM; #define MAX_DISPLAY_REGION 16 //Each display channel can be divided to a

maximum of 16 small regions . Return Values:

17


If the function succeeds, the return value is 0. If the function fails, the return value is the error code defined on error code. For each DSP of ILDVR3000H2D and ILDVR3000H4D, the display region cann’t be greater than 2*4CIF+2*QCIF , or the function SetDisplayRegion() will return ERR_NOT_SUPPORT ,which means that the DSP doesn’t have enough resource .

ERR_INVALID_DEVICE:nDisplayChannel is overflowed. ERR_INVALID_ARGUMENT:nRegionCount is overflowed，The parameter left and

width are not multiples of 16, the parameter top and height are not multiples of 8. Other error will make the function return ERR_KERNEL. Remarks:

Divide the display channel to multi regions. The parameter left and width must be multiples of 16, the parameter top and height must be multiples of 8.

54. unsigned int FillDisplayRegion (UINT nDisplayChannel,UINT

nRegion,unsigned char *pImage) Parameters: UINT nDisplayChannel Display Channel Index UINT nRegion region to be filled unsigned char * pImage pointer to YUV420 data buffer Return Values: If the function succeeds, the return value is 0. If the function fails, the return value is the error code defined on error code.

ERR_INVALID_DEVICE:nDisplayChannel is overflowed，the nRegion is invalid. Other error will make the function return ERR_KERNEL.

Remarks: Fill display region with picture files。The height and width of picture pointed by pImage must be he same as The height and width of the current region which is set by function SetDisplayRegion(),or the picture cann’t be showed normally . If the current region is displaying video ,please stop displaying it at first or the picture cann’t be displayed .

55. unsigned int SetDisplayRegionPosition (UINT nDisplayChannel,UINT nRegion,UINT nLeft,UINT nTop) Parameters:

UINT nDisplayChannel Display Channel Index UINT nRegion region to be adjusted UINT nLeft, the position after being adjusted

UINT nTop the position after being adjusted Return Values: If the function succeeds, the return value is 0. If the function fails, the return value is the error code defined on error code.

ERR_INVALID_DEVICE:nDisplayChannel is overflowed,the nRegion is invalid. Other error will make the function return ERR_KERNEL.

18


Remarks: Adjust the position of display region.

56. unsigned int FillDisplayRegion (UINT nDisplayChannel,UINT

nRegion,unsigned char *pImage) Parameters: UINT nDisplayChannel Display Channel Index UINT nRegion region to be filled unsigned char * pImage pointer to YUV420 data buffer Return Values: If the function succeeds, the return value is 0. If the function fails, the return value is the error code defined on error code.

ERR_INVALID_DEVICE:nDisplayChannel is overflowed，the nRegion is invalid. Other error will make the function return ERR_KERNEL.

Remarks: Fill display region with picture files。The height and width of picture pointed by pImage must be he same as The height and width of the current region which is set by function SetDisplayRegion(),or the picture cann’t be showed normally . If the current region is displaying video ,please stop displaying it at first or the picture cann’t be displayed .

57. unsigned int SetEncoderVideoExtOutput(UINT nEncodeChannel,UINT nPort,BOOL bOpen,UINT nDisplayChannel,UINT nDisplayRegion,UINT nReserved) Parameters: UINT nEncodeChannel Encode Channel Index UINT nPort Output port of encode channel(must be 0 or 1) BOOL bOpen Open/Close UINT nDisplayChannel Display Channel Index UINT nDisplayRegion Display region of current display channel UINT nReserved be reserved Return Values: If the function succeeds, the return value is 0. If the function fails, the return value is the error code defined on error code.

ERR_INVALID_DEVICE:nEncodeChannel is overflowed, nPort is greater than 1, nDisplayChannel is overflowed, nDisplayRegion is invalid.

Other error will make the function return ERR_KERNEL Remarks: Set video output of encode channel(matrix output). Output the preview video of channel nEncodeChannel to the region nDisplayRegion of display channel nDisplayChannel .The parameter nPort must be 0 or 1.(Each encode channel supports two video output at the same time maximally).If the parameter bOpen is equal to 0,then nDisplayChannel and

19


nDisplayRegion are meaningless. 58. unsigned int SetDecoderAudioOutput(UINT nDecodeChannel,BOOL

bOpen,UINT nOutputChannel) Parameters: UINT nDecodeChannel Decode Channel Index BOOL bOpen Open/Close UINT nOutputChannel index of audio output channel Return Values: If the function succeeds, the return value is 0. If the function fails, the return value is the error code defined on error code.

ERR_INVALID_DEVICE:nDecodeChannel is overflowed, nOutputChannel is greater than 1.

Other error will make the function return ERR_KERNEL. Remarks: Set audio output of decode channel .Output the decode audio of channel nDecodeChannel to the audio output channel nOutputChannel on the ILDVR3000H4D and ILDVR3000H2D card; ILDVR3000H2D card includes 2 audio output channel; ILDVR3000H4D card includes 4 audio output channel; For ILDVR3000H2D , the parameter nOutputChannel should be 0 or 1; For ILDVR3000H4D , the parameter nOutputChannel should be 0,1,0 or 1; If other audo of decode channel is outputting the audio on the audio output channel nOutputChannel, the SDK will stop the output at first ,then output current audio channel;

59. unsigned int SetDecoderVideoOutput(UINT nDecodeChannel,UINT nPort,BOOL bOpen,UINT nDisplayChannel,UINT nDisplayRegion,UINT nReserved) Parameters: UINT nDecodeChannel Decode Channel Index UINT nPort output port of decode channel(0 or 1) BOOL bOpen Open/Close UINT nDisplayChannel Display Channel Index UINT nDisplayRegion Display region of current display channel UINT nReserved be reserved Return Values: If the function succeeds, the return value is 0. If the function fails, the return value is the error code defined on error code.

ERR_INVALID_DEVICE:nDecodeChannel is overflow, nPort is greater than 1,

nDisplayChannel is overflow: nDisplayRegion is invalid .

Other error will make the function return ERR_KERNEL. Remarks:

20


Set video output of decode channel(internal output on ILDVR3000H2D and ILDVR3000H4D). Output the video of channel nDecodeChannel to the region nDisplayRegion of display channel nDisplayChannel (0~3). The parameter nPort must be 0 or 1.(Each decode channel supports two video output at the same time maximally). ILDVR3000H2D card includes 2 display channel; ILDVR3000H4D card includes 4 display channel; For ILDVR3000H2D , the parameter nDisplayChannel should be 0 or 1; For ILDVR3000H4D , the parameter nDisplayChannel should be 0,1,0 or 1; If Open is equal to 0,then nDisplayChannel and nDisplayRegion are meaningless.

This function is special condition of function SetDecoderVideoExtOutput(). The function SetDecoderVideoExtOutput can send the decode video to other ILDVR3000H2D

and ILDVR3000H4D card (span video from one matrix decode card to another card)so that the video can be output by other matrix decode card . To display and output the decode video on current matrix decode card, either of function SetDecoderVideoOutput and SetDecoderVideoExtOutput can be called .

60. unsigned int SetDecoderVideoExtOutput(UINT nDecodeChannel,UINT

nPort,BOOL bOpen,UINT nDisplayChannel,UINT nDisplayRegion,UINT nReserved) Parameters: UINT nDecodeChannel Decode Channel Index UINT nPort Output port of decode channel(0 or 1) BOOL bOpen Open/Close UINT nDisplayChannel Display Channel Index UINT nDisplayRegion Display region of current display channel UINT nReserved be reserved Return Values: If the function succeeds, the return value is 0. If the function fails, the return value is the error code defined on error code.

ERR_INVALID_DEVICE:nDecodeChannel is overflow, nPort is greater than 1,

nDisplayChannel is overflow, nDisplayRegion is invalid .

Other error will make the function return ERR_KERNEL. Remarks: Set external video output of decode channel(external output on matrix decode card). Output the video of channel nDecodeChannel to the region nDisplayRegion of display channel nDisplayChannel (zero-based index ,0,1,2,3,4,5….depends on the number of nDisplayChannel). The parameter nPort must be 0 or 1.(Each decode channel supports two video output at the same time maximally). ILDVR3000H2D card includes 2 display channel; ILDVR3000H4D card includes 4 display channel; If Open is equal to 0,then nDisplayChannel and nDisplayRegion are meaningless.

21


Compared with the function SetDecoderVideoOutput,the function SetDecoderVideoExtOutput can output the video by spanning the video from one matrix decode card to another card.

61. int __stdcall HW_GetYV12Image(HANDLE hChannel, PBYTE pBuffer,

ULONG nSize) Description: Capture current displaying image, YV12 format. Input parameters: hChannel: the channel handle. pBuffer: the buffer to save data. The size of buffer must be greater than or equal to (*pWidth)*(*pHeight)*3/2. In YV12 format, each pixel need 3/2 byte. nSize: the size of the buffer. Return value: Error code. 62. int __stdcall HW_ConvertToBmpFile(BYTE *pBuf, ULONG nSize, ULONG

nWidth, ULONG nHeight, char *sFileName, ULON nReserved) Description: Convert the YV12 image into bitmap. Input parameters: pBuf: the buffer storing YV12 image. nSize: the size of buffer. nWidth: width of the image. nHeight: height of the image. sFileName: the bmp file name. nReserved: reserved. Return value: Error code. 63. int HW_SetFileRef(HANDLE hChannel,

BOOL bEnable, FILE_REF_DONE_CALLBACK FileRefDoneCallback)

Parameters: hChannel channel handle bEnable： Enable to create file index or not FileRefDoneCallback： the callback function to be called after the file index is

createdsuccesfully typedef void (*FILE_REF_DONE_CALLBACK)(UINT nChannel, UINT nSize);

Parameters: nChannel: channel index nSize： the size of file index.

Return Values: Error code.

22


Remarks: Set file index. 64. int HW_GetFileAbsoluteTime( HANDLE hChannel,

SYSTEMTIME *pStartTime,SYSTEMTIME *pEndTime) Parameters:

hChannel channel handle pStartTime start time of playing file (The parameter millisecond in the

SYSTEMTIME is invalid, it is always zero ) pEndTime end time of playing file (The parameter millisecond in the

SYSTEMTIME is invalid, it is always zero ) Return Values:

Error code. Remarks:

Get the start and end time of playing file(absolute time). The parameter millisecond in the SYSTEMTIME is invalid, it is always zero. 65. int HW_GetCurrentAbsoluteTime(HANDLE hChannel,

SYSTEMTIME *pTime) Parameters:

hChannel channel handle pTime the current absolute time in the position where is playing

back Return Values:


Get the current absolute time in the position where is playing back(The parameter millisecond in the SYSTEMTIME is invalid, it is always zero ) 66. int HW_LocateByAbsoluteTime(HANDLE hChannel,SYSTEMTIME time)

Parameters: hChannel channel handle time the absolute time to be located


Remarks: Locate the file by absolute time. This function takes effect after the file index

is created successfully. To get the start and end absolute time, call API HW_GetFileAbsoluteTime().

67. HW_LocateByFrameNumber(HANDLE hChannel,UINT frmNum)

Parameters: hChannel channel handle frmNum frame number

23



Remarks: Locate the file by frame number. This function takes effect after the file index

is created successfully. To get the total frame number of file, call API HW_GetFileTotalFrames ().

68. int HW_ExportFileRef(HANDLE hChannel,char *pBuffer,UINT nSize)

Parameters: hChannel channel handle pBuffer the buffer to export file index nSiz buffer size, must be greater than the size of file index.

The size of file index can be gotten from the callback function of HW_SetFileRef()


Remarks: Export file index

69. int HW_ImportFileRef(HANDLE hChannel,char *pBuffer,UINT nSize) Parameters:

hChannel channel handle pBuffer the buffer to import file index nSize buffer size


Remarks: Import file index . To import file index, the application software should stop creating file index

in function HW_SetFileRef() ,then import file index after calling function HW_OpenFile().

70. int RegisterDisplayVideoCaptureCallback(IMAGE_STREAM_CALLBACK

DisplayVideoCaptureCallback,void *context) Parameters:

DisplayVideoCaptureCallback callback function Context context

Callback function Explanation: void (*IMAGE_STREAM_CALLBACK)(UINT channelNumber ,void *context) UINT channelNumber Display Channel Index void *context context provided when calling this function Return Values:


24


Register callback function of get original image stream that is output to monitor, .The application can get realtime YUV420 data (without any compression) .

71. int SetDisplayVideoCapture(UINT nDisplayChannel, BOOL bStart,

UINT fps,UINT width,UINT height,unsigned char *imageBuffer) Parameters:

nDisplayChannel display channel bStart TRUE/ Start Capture，FALSE/Stop Capture fps Frame Rate width Image Width, at present ,it must be 704 height Image height, at present ,it must be 576(PAL) or 480(NTSC) imageBuffer address of image buffer


Remarks: Call this function to start or stop getting the original image stream that is output to monitor，the speed depends on the frequency of host ‘s CPU.

25

Documents

The SDK Programmer Manual of Hikvision DS-4002MDI Matrix Decode Card