Programming element

Description

DdsiTouchPanelAttach

This function executes when the MDD's DLL entry point receives a DLL_PROCESS_ATTACH message.

DdsiTouchPanelDetach

This function executes when the MDD's DLL entry point receives a DLL_PROCESS_DETACH message.

DdsiTouchPanelDisable

This function disables the touch screen device.

DdsiTouchPanelEnable

This function applies power to the touch screen device and initializes it for operation.

DdsiTouchPanelGetDeviceCaps

This function queries capabilities of the touch screen device.

DdsiTouchPanelGetPoint

This function returns the most recently acquired point and its associated tip state information.

DdsiTouchPanelPowerHandler

This function indicates to the driver that the system is entering or leaving the suspend state.

DdsiTouchPanelSetMode

This function sets information about the touch screen device.

VOID TouchPanelCalibrateAPoint(

  INT32 UncalX,

  INT32 UncalY,

  INT32* pCalX,

  INT32* pCalY

);

Parameters

UncalX

[in] Noncalibrated x-coordinate.

UncalY

[in] Noncalibrated y-coordinate.

pCalX

[out] Pointer to the returned calibrated x-coordinate.

pCalY

[out] Pointer to the returned calibrated y-coordinate.

BOOL

TouchPanelEnable(

                 PFN_TOUCH_PANEL_CALLBACK    pfnCallback

                 )

{

    BOOL    ReturnValue;

    //

    // Do the 'attach' code.  Normally, this would have been

    // done in the ThreadAttach block, but this driver is set

    // up to be statically linked to GWE, in which case none of

    // the DLL related calls would even be invoked.

    //

    TouchPanelpAttach();

    EnterCriticalSection( &csMutex );

    //

    // Insure the device is disabled and no one is attached to the logical

    // interrupt.

    // Power on the device.

    // Connect the logical interrupt to the device.

    //

    InterruptDone( gIntrTouch );

    InterruptDisable( gIntrTouch );

    if( SYSINTR_NOP != gIntrTouchChanged ) {

        InterruptDone( gIntrTouchChanged );

        InterruptDisable( gIntrTouchChanged );

    }

    v_pfnCgrPointCallback = pfnCallback;

    if (v_pfnCgrCallback != NULL)

        v_pfnPointCallback = v_pfnCgrCallback;

    else

        v_pfnPointCallback = pfnCallback;

    ghevCalibrationActivity = NULL;

    ReturnValue = DdsiTouchPanelEnable();

    if (ReturnValue && !InterruptInitialize(gIntrTouch, hTouchPanelEvent, NULL, 0)) {

        DEBUGMSG(ZONE_ERROR, (TEXT("TouchPanelEnable: InterruptInitialize(gIntrTouch %d failed/r/n"),

            gIntrTouch));

        DdsiTouchPanelDisable();

        ReturnValue = FALSE;

    }

    if ( ( SYSINTR_NOP != gIntrTouchChanged ) &&

        ReturnValue && !InterruptInitialize( gIntrTouchChanged, hTouchPanelEvent, NULL, 0)) {

            DEBUGMSG(ZONE_ERROR, (TEXT("TouchPanelEnable: InterruptInitialize(gIntrTouchChanged %d failed/r/n"),

                gIntrTouchChanged));

            InterruptDisable(gIntrTouch);

            DdsiTouchPanelDisable();

            ReturnValue = FALSE;

    }

    if (ReturnValue) {

        // Create the ISR thread.  If creation fails, perform cleanup and return failure.

        //

        bTerminate=FALSE;

        if (!(hThread = CreateThread( NULL, 0, TouchPanelpISR, 0, 0, NULL))) {

            TouchPanelpDetach();

            InterruptDisable(gIntrTouch);

            if( SYSINTR_NOP != gIntrTouchChanged )

                InterruptDisable(gIntrTouchChanged);

            DdsiTouchPanelDisable();

            ReturnValue = FALSE;

        } else {

            // Get thread priority from registry

            TouchPanelpGetPriority(&gThreadPriority, &gThreadHighPriority);

            // Set our interrupt thread's priority

            CeSetThreadPriority(hThread, gThreadPriority);

        }

    }

    LeaveCriticalSection(&csMutex);

    return(ReturnValue);

}

typedef struct {

    INT32   a1;

    INT32   b1;

    INT32   c1;

    INT32   a2;

    INT32   b2;

    INT32   c2;

    INT32   delta;

}   CALIBRATION_PARAMETER, *PCALIBRATION_PARAMETER;

/*++

@func VOID | TouchPanelReadCalibrationPoint |

Initates the process of getting a calibration point.  This function

causes the device driver to foward the last valid x and y coordinates

between the tip states of initial down and up to the calibration callback

function. The tip state of the forwarded coordinates is reported as

initial down.

@parm LONG | UcalX |

The uncalibrated X coordinate under calibration.

@parm LONG | UcalY |

The uncalibrated Y coordinate under calibration.

@rdesc

If the function succeeds, TRUE; otherwise FALSE. Extended error information

is available via the GetLastError function.

--*/

BOOL

TouchPanelReadCalibrationPoint(

                               INT *pRawX,

                               INT *pRawY

                               )

{

    BOOL    retval;

    HANDLE  hevActivity = NULL;

    DWORD   dwStatus;

    HKEY    hk;

    NKDbgPrintfW(L"++TouchPanelReadCalibrationPoint()/r/n");

    if(!pRawX  || !pRawY ) {

        SetLastError(ERROR_INVALID_PARAMETER);       

        return ( FALSE ) ;

    }

    // Get a path to the GWES activity event.  We need to set it ourselves

    // because calibration is essentially a modal loop and doesn't put

    // events onto the user input queue, which is where this event gets

    // set inside GWES.

    // 从注册表项"System//GWE"下获取ActivityEvent的键值，它用来和GWES直接进行通信，不知道具体做些什么工作

    // 如果有人知道的话，欢迎告诉我

    dwStatus = RegOpenKeyEx(HKEY_LOCAL_MACHINE, L"System//GWE", 0, 0, &hk);

    if(dwStatus == ERROR_SUCCESS) {

        WCHAR szEventPath[MAX_PATH];

        DWORD dwSize = sizeof(szEventPath);

        DWORD dwType;

        // Read the path to the event and open it -- do this on every call

        // to this API so that we're not forced to keep an event open that

        // is almost never used.

        dwStatus = RegQueryValueEx(hk, L"ActivityEvent", NULL, &dwType, (LPBYTE) szEventPath, &dwSize);

        NKDbgPrintfW(L"Event name: %s/r/n", szEventPath);

        szEventPath[MAX_PATH - 1] = 0;      // enforce null termination

        if(dwStatus == ERROR_SUCCESS && dwType == REG_SZ) {

            hevActivity = OpenEvent(EVENT_ALL_ACCESS, FALSE, szEventPath);

        }

        RegCloseKey(hk);

    }

    EnterCriticalSection( &csMutex );

    //

    // If a calibration is already active, error.

    //

    if ( CalibrationState )

    {

        SetLastError( ERROR_POSSIBLE_DEADLOCK );

        LeaveCriticalSection( &csMutex );

        if(hevActivity != NULL) {

            CloseHandle(hevActivity);

        }

        return ( FALSE );

    }

    //

    // Set sample count and active flag.

    // Wait for calibration to happen.

    // Update the memory with the x and y coordinates.

    // Clear active flag.

    // We be done.

    // 标志呀，啥也不说了，非常重要，控制IST的

    CalibrationState = CalibrationWaiting;

    // let the IST know about the event

    // 时间呀

    ghevCalibrationActivity = hevActivity;

    LeaveCriticalSection( &csMutex );

    // 等待IST校准数据获取的结果，如果IST数据获取结束将会通过该Event通知该函数

    WaitForSingleObject( hCalibrationSampleAvailable, INFINITE );

    EnterCriticalSection( &csMutex );

    *pRawX = lCalibrationXCoord;

    *pRawY = lCalibrationYCoord;

    // 可以看到，该函数反馈给GWES的结果就是简单的False或者True

    retval = ( CalibrationState == CalibrationValid );

    CalibrationState = CalibrationInactive;

    // done with the event

    ghevCalibrationActivity = NULL;

    LeaveCriticalSection( &csMutex );

    // close the event handle

    CloseHandle(hevActivity);

    NKDbgPrintfW(L"--TouchPanelReadCalibrationPoint(x: 0x%8x, y: 0x%8x, retval= 0x%x)/r/n", *pRawX, *pRawY, retval);

    return retval;

}

/*++

Autodoc Information:

@func ULONG | TouchPanelpISR |

This routine is the thread which handles touch panel events.

The event that this thread synchronizes on is signaled by the PDD based on

the sampling rate, typically 10ms.

@rdesc

Never returns.

--*/

static ULONG

TouchPanelpISR(

               PVOID   Reserved  //@parm Reserved, not used.

               )

{

    TOUCH_PANEL_SAMPLE_FLAGS    SampleFlags = 0;

    INT32                       RawX, CalX;

    INT32                       RawY, CalY;

    UINT32                      MaxX =  DisplayWidth * X_SCALE_FACTOR;

    UINT32                      MaxY =  DisplayHeight * Y_SCALE_FACTOR;

    UINT32                      CurrentDown = 0;

    static LONG CX;

    static LONG CY;

    static LONG XBase;

    static LONG YBase;

    static int  CalibrationSampleCount;

    static BOOL     fSetBase;

    static DWORD    BaseTime;

    static BOOL     fGotSample;

    PFN_TOUCH_PANEL_CALLBACK pfnCallback;

    // Need to be all kmode so that we can write to shared memory.

    //

    SetKMode(TRUE);

    NKDbgPrintfW(L"TouchPanelpISR/r/n");

    while  ( !bTerminate )

    {

        // IST等待Timer和Touch中断事件hTouchPanelEvent唤醒

        // gdwTouchIstTimeout = INFINITE

        WaitForSingleObject( hTouchPanelEvent, gdwTouchIstTimeout );

        EnterCriticalSection( &csMutex );

        DEBUGMSG(ZONE_THREAD, (TEXT("TCH_INTR/r/n")) );

        // Give the pdd the down state of the previous sample

        // CurrentDown：不用说了吧，就是记录Touch是否被按下，添加这个Flag的目的主要是为了配合Timer中断

        if ( CurrentDown )

            SampleFlags |= TouchSamplePreviousDownFlag;

        else

            SampleFlags &= ~TouchSamplePreviousDownFlag;

        // 废话少说，先得到触摸屏坐标点再说，同时在SampleFlags返回一些标记，包括坐标点是否有效等等

        DdsiTouchPanelGetPoint( &SampleFlags, &RawX, &RawY );    // Get the point info

            NKDbgPrintfW(L"(0) 0x%8x/r/n", SampleFlags);

        // 坐标点不合法，下次再说吧

        if ( SampleFlags & TouchSampleIgnore )

        {

            // do nothing, not a valid sample

            LeaveCriticalSection( &csMutex );

            continue;

        }

        if ( SampleFlags & TouchSampleValidFlag )

        {

            // Set the previous down state for our use, since the pdd may not

            // have preserved it.

            // 下面的四行代码和前面一段类似，为啥？微软怎么会这么傻呢？

            // 看了半天，原来是MDD层代码不信任PDD层的API DdsiTouchPanelGetPoint，担心该函数会将SampleFlags得值给Rewrite

            if ( CurrentDown )

                SampleFlags |= TouchSamplePreviousDownFlag;

            else

                SampleFlags &= ~TouchSamplePreviousDownFlag;

            CurrentDown = SampleFlags & TouchSampleDownFlag;

        }

        // 这里的CalibrationState是一个全局变量，当GWES调用TouchPanelReadCalibrationPoint获取用户的校准坐标的时候，会将其赋值为CalibrationWaiting

        // 所以，也只有在校准屏幕的时候程序才会走到这里

        if ( CalibrationState )

        {

            //

            // At this point we know that calibration is active.

            //

            // Typically, the user touches the panel then converges to the

            // displayed crosshair. When the tip state transitions to

            // the up state, we forward the last valid point to the callback

            // function.

            //

            DEBUGMSG(ZONE_SAMPLES, (TEXT("**** Calibration point (%d, %d), flags 0x%4.4X/r/n"),

                RawX, RawY, SampleFlags) );

            //  Skip if not valid.

            // 下面这三行代码纯属多余，必须砍掉，呵呵

            if ( !(SampleFlags & TouchSampleValidFlag) )

            {

                LeaveCriticalSection( &csMutex );

                continue;

            }

            NKDbgPrintfW(L"(1) 0x%8x/r/n", SampleFlags);

            //  Signal the Power Manager activity event if one has been set up

            // ghevCalibrationActivity是一个和TouchPanelReadCalibrationPoint进行通信的Event Handle

            // 该事件就是"System//GWE"下的"ActivityEvent"配置的那个事件,在TouchPanelReadCalibrationPoint中会去创建该事件

            // 这种类似的操作也是GWES中应用比较多的一种操作

            if ( ghevCalibrationActivity != NULL)

            {

                // 我猜测GWES需要这个事件做一些操作，可能会需要用该事件去告之它ISR中已经知道了要校准屏幕，现在可以为GWES提供相关的服务了

                SetEvent(ghevCalibrationActivity);

            }

            //  Must see down transition.

            //  符合下面的条件其实就是：

            //  1. 校准屏幕第一次采集到有效数据；

            //  所以，第二次采集到有效数据的话，这里的条件就不符合了

            if ( (SampleFlags & (TouchSampleDownFlag|TouchSamplePreviousDownFlag)) ==

                TouchSampleDownFlag )

            {

                CalibrationState = CalibrationDown;

                //  fSetBase用来表示是否需要设置Base时间，一般的校准屏幕时间对每个采样点的校准是由时间限制的，如果超过时间的话，自动采样结束

                fSetBase = TRUE;

                //  变量CalibrationSampleCount用来记录采样点的个数

                CalibrationSampleCount = 0;

                //  fGotSample用来标记数据是否已经采集结束

                fGotSample = FALSE;

            }

            NKDbgPrintfW(L"(2) 0x%8x/r/n", SampleFlags);

            //  Only look at stuff if we saw a down transition.

            if ( (CalibrationState == CalibrationDown) && !fGotSample )

            {

                //  值得一说的就是SampleFlags的TouchSampleDownFlag位是从PDD层返回来的，而不是在IST里面进行赋值的

                if ( SampleFlags & TouchSampleDownFlag )

                {

                    long DeltaX, DeltaY;

                    // 哈哈，拿到一次有效的数据

                    CalibrationSampleCount++;

                    CX = RawX;

                    CY = RawY;

                    if ( fSetBase )

                    {

                        XBase = CX;

                        YBase = CY;

                        BaseTime = GetTickCount();

                        fSetBase = FALSE;

                    }

                    DeltaX = CX - XBase;

                    DeltaY = CY - YBase;

                    //  超过采样点采样时间，自动采样

                    //  意思就是说，如果你拿着笔针在一个采样点上点击超过.5s依然没有拿起来的话，采样自动结束

                    if ( (GetTickCount() - BaseTime) > CAL_HOLD_STEADY_TIME )

                    {

                        fGotSample = TRUE;

                    }

                    //  如果第二次采样点与第一次采样点的偏差超过CAL_DELTA_RESET的话，需要重新开始数据的采集

                    //  意思就是说，如果你在十字号上触摸<1.5后，在不抬起来的情况下移动笔针，则你将发现.5s后自动数据采集才结束

                    else if ( ( ABS(DeltaX) > CAL_DELTA_RESET ) ||

                        ( ABS(DeltaY) > CAL_DELTA_RESET ) )

                    {

                        RETAILMSG(1, (TEXT("M %ld,%ld  %ld,%ld  %ld,%ld"),

                            XBase,YBase, CX,CY, DeltaX,DeltaY));

                        fSetBase = TRUE;

                    }

                }

                else

                {

                    NKDbgPrintfW(L"%d/%d/r/n", CalibrationSampleCount, MIN_CAL_COUNT);

                    //  They lifted the pen, see if we will accept coordinate.

                    //  当最后一次抬起笔针的时候，程序将会走到这里

                    //  针对最后笔针最后一次抬起，将会做两种处理：

                    //  1. 如果采样点个数已经>MIN_CAL_COUNT的话，结束当前采样点的采样，并通知校准线程

                    //  2. 如果采样点不足的话，则将开启下一次全新的采样过程，也即舍弃之前所有的采样点坐标

                    if ( CalibrationSampleCount >= MIN_CAL_COUNT )

                    {

                        fGotSample = TRUE;

                    }

                    else

                    {

                        CalibrationState = CalibrationWaiting;

                    }

                }

                if ( fGotSample )

                {

                    CalibrationState = CalibrationValid;

                    lCalibrationXCoord = CX;

                    lCalibrationYCoord = CY;

                    SetEvent(hCalibrationSampleAvailable);

                }

            }

            LeaveCriticalSection( &csMutex );

        }

        else

        {

            //  获取Callback函数指针，供后续调用

            //  该Callback函数在TouchPanelEnable中由GWES传递

            pfnCallback = v_pfnPointCallback;

            if ( pfnCallback != NULL )

            {

                   //  这里由PDD层代码告诉MDD层，是否需要对触摸板坐标进行校准，如果屏幕的线性度很好，就可以不需要这个步骤

                if( SampleFlags & TouchSampleIsCalibratedFlag )

                {   // Sample already calibrated by PDD

                    CalX = RawX;

                    CalY = RawY;

                }

                else

                {   // Not previously calibrated, do it now.

                    TouchPanelCalibrateAPoint( RawX, RawY, &CalX, &CalY );

                    SampleFlags |= TouchSampleIsCalibratedFlag;

                }

                LeaveCriticalSection( &csMutex );

                // Bounds check this value

                if( CalX < 0 )

                    CalX = 0;

                else if( MaxX && ((UINT32)CalX >= MaxX) )

                    CalX = MaxX - X_SCALE_FACTOR;

                if( CalY < 0 )

                    CalY = 0;

                else if( MaxY && ((UINT32)CalY >= MaxY) )

                    CalY = MaxY - Y_SCALE_FACTOR ;

                DEBUGMSG( ZONE_SAMPLES,

                    (TEXT("**** Queuing point (%d, %d), flags 0x%4.4X/r/n"),

                    CalX, CalY, SampleFlags) );

                   //  采集到数据后，通过Callback函数告知GWES

                (pfnCallback)( SampleFlags, CalX, CalY);

            }

            else

            {

                LeaveCriticalSection( &csMutex );

            }

        }

    }

    ExitThread(1);

    return ( TRUE );

}