Here is how DCCAPI works:


PREPARING DEVICE
=====================



User driver creates a DCCDEV object instance that represents DCC card:

    DCCDEV *CreateDCCInstance(void);


Then initializes it, with PDX (pointer to device extension) with function:

    BOOL InitializeDevice( DCCDEV *device, PDEVICE_EXTENTION initialized_pdx );//*

This step is assigning the piece of hardware to the instance of DCCDEV.
Then before capture start DMA descriptor and DMA trash area must be assigned for the device.
DMA descriptor is used for building DMA descriptors, and DMA trash is used to copy unwanted data into it.

    BOOL AssignDeviceDMADesc(DCCDEV* device, PDMAACCESSIBLE desc);
    
    BOOL AssignDeviceDMATrash(DCCDEV* device, PPLANE trashplane);

Those steps must be preformed before capture will start or stopped.





PREPARING FRAMES
====================




Right now, user may create frames using:

    FRAME *CreateFrame(void);


And assign DMA areas, and specify format of the allocated frame:


    BOOL AssignFramePlanes(FRAME *frame, PDMAACCESSIBLE p1, int s1, PDMAACCESSIBLE p2, int s2, PDMAACCESSIBLE p3, int s3);//*

    BOOL AssignFrameFormat(FRAME *frame, int width, int height, CAPTURE_FORMAT format);
        
    
It is important - those operation will fail if frame is queued, queued frame cannot be operated.




To identyify the frame, it may assign the >>frame index<< field: (note: this will change in next release)


    void SetFrameIndex(FRAME *frame, int index);

That field is only for user driver use may be obtained later using:

    int GetFrameIndex(FRAME *frame); 



At any moment, user may read the frame status:

    unsigned int GetFrameStatus(FRAME *p_frame);//*


Available statuses are:

    #define FRS_INITIALIZED             1
    #define FRS_QUEUED                  2
    #define FRS_LOCKED                  4
    #define FRS_GOTIMAGE                8
    #define FRS_RESOLUTION_ASSIGNED     16
    #define FRS_FORMAT_ASSIGNED         32
    #define FRS_PLANE1_ASSIGNED         128
    #define FRS_PLANE2_ASSIGNED         256
    #define FRS_PLANE3_ASSIGNED         512




CAPTURING
==========


Right now, after user created the DCC instance, assigned it to DCC Hardware, and created frames, frames
may be pushed into capture queue:


    BOOL PushFrame( DCCDEV *device, FRAME *frame );
    
Push operation will only succeed with frames that are not already queued (FRS_QUEUED) and they must be initialized, 
resolution, format and planes must be assigned (FRS_INITIALIZED, FRS_RESOLUTION_ASSIGNED, FRS_FORMAT_ASSIGNED, FRS_PLANEx_ASSIGNED).

(Fixme: only plane 0 is tested). 
Flag FRS_QUEUED is asserted, flag ~FRS_GOT_IMAGE is removed.


Frame sequence number is cleared.


