调用 Magnification API 实现黑屏功能

通过Windows Magnification API实现屏幕变暗保护隐私

在这篇教程中，将详细讲解如何通过Windows Magnification API实现屏幕幕布功能，类似于iPhone VoiceOver的屏幕变暗功能。这一功能可以在视障人士操作电脑期间防止他人窥视，保护隐私。

关键知识点

1. Windows Magnification API：一个用于实现屏幕放大、颜色变换等功能的API。
2. 颜色效果矩阵：通过设置颜色效果矩阵实现屏幕颜色变换，达到屏幕变暗的效果。

实现思路

1. 初始化Magnification API：调用API的初始化函数。
2. 设置颜色效果矩阵：定义两个矩阵，一个用于黑屏效果，一个用于正常颜色效果。
3. 启用和禁用屏幕幕布功能：通过设置全屏颜色效果和控制系统光标显示实现。
4. 检测当前屏幕状态：比较当前颜色效果矩阵和预定义的黑屏颜色效果矩阵。

实现步骤

1. 定义颜色效果矩阵

定义两个颜色效果矩阵，一个用于实现黑屏效果，一个用于恢复正常颜色效果。

private static MAGCOLOREFFECT g_MagEffectBlack = new MAGCOLOREFFECT
{
    transform = new float[]
    {
        0.0f, 0.0f, 0.0f, 0.0f, 0.0f,
        0.0f, 0.0f, 0.0f, 0.0f, 0.0f,
        0.0f, 0.0f, 0.0f, 0.0f, 0.0f,
        0.0f, 0.0f, 0.0f, 1.0f, 0.0f,
        0.0f, 0.0f, 0.0f, 0.0f, 1.0f
    }
};

private static MAGCOLOREFFECT g_MagEffectIdentity = new MAGCOLOREFFECT
{
    transform = new float[]
    {
        1.0f, 0.0f, 0.0f, 0.0f, 0.0f,
        0.0f, 1.0f, 0.0f, 0.0f, 0.0f,
        0.0f, 0.0f, 1.0f, 0.0f, 0.0f,
        0.0f, 0.0f, 0.0f, 1.0f, 0.0f,
        0.0f, 0.0f, 0.0f, 0.0f, 1.0f
    }
};

2. 初始化Magnification API

使用 MagInitialize 函数初始化Magnification API。

public ScreenCurtain()
{
    if (!MagInitialize())
    {
        throw new ApplicationException("API 初始化失败。");
    }
}

3. 启用和禁用屏幕幕布功能

通过设置全屏颜色效果矩阵和控制系统光标显示来启用和禁用屏幕幕布功能。

public bool Enable()
{
    return MagSetFullscreenColorEffect(ref g_MagEffectBlack) && MagShowSystemCursor(false);
}

public bool Disable()
{
    return MagSetFullscreenColorEffect(ref g_MagEffectIdentity) && MagShowSystemCursor(true);
}

4. 检测当前屏幕状态

比较当前的颜色效果矩阵和预定义的黑屏颜色效果矩阵，确定当前是否启用了屏幕幕布功能。

public bool IsEnabled()
{
    MAGCOLOREFFECT currentEffect = new MAGCOLOREFFECT { transform = new float[25] };
    if (!MagGetFullscreenColorEffect(ref currentEffect))
    {
        throw new InvalidOperationException("Could not get current color effect.");
    }
    for (int i = 0; i < 25; i++)
    {
        if (currentEffect.transform[i] != g_MagEffectBlack.transform[i])
        {
            return false;
        }
    }
    return true;
}

5. 获取单例实例

使用单例模式确保屏幕幕布功能的唯一实例。

public static ScreenCurtain GetInstance()
{
    try
    {
        if (Instance is null)
        {
            Instance = new ScreenCurtain();
        }
        return Instance;
    }
    catch (Exception)
    {
        return Instance;
    }
}

6. 资源释放

在对象销毁时调用 MagUninitialize 函数，释放资源。

~ScreenCurtain()
{
    MagUninitialize();
}

完整代码

以下是实现屏幕幕布功能的完整代码示例：

using System;
using System.Runtime.InteropServices;

namespace WinFormsEx
{
    [StructLayout(LayoutKind.Sequential)]
    public struct MAGCOLOREFFECT
    {
        [MarshalAs(UnmanagedType.ByValArray, SizeConst = 25)]
        public float[] transform;
    }

    class ScreenCurtain
    {
        [DllImport("Magnification.dll", SetLastError = true)]
        [return: MarshalAs(UnmanagedType.Bool)]
        private static extern bool MagInitialize();
        [DllImport("Magnification.dll", SetLastError = true)]
        [return: MarshalAs(UnmanagedType.Bool)]
        private static extern bool MagUninitialize();
        [DllImport("Magnification.dll", SetLastError = true)]
        [return: MarshalAs(UnmanagedType.Bool)]
        private static extern bool MagSetFullscreenColorEffect(ref MAGCOLOREFFECT pEffect);
        [DllImport("Magnification.dll", SetLastError = true)]
        [return: MarshalAs(UnmanagedType.Bool)]
        private static extern bool MagGetFullscreenColorEffect(ref MAGCOLOREFFECT pEffect);
        [DllImport("Magnification.dll", SetLastError = true)]
        [return: MarshalAs(UnmanagedType.Bool)]
        private static extern bool MagShowSystemCursor(bool fShowCursor);

        private static ScreenCurtain Instance = null;

        private static MAGCOLOREFFECT g_MagEffectBlack = new MAGCOLOREFFECT
        {
            transform = new float[]
            {
                0.0f, 0.0f, 0.0f, 0.0f, 0.0f,
                0.0f, 0.0f, 0.0f, 0.0f, 0.0f,
                0.0f, 0.0f, 0.0f, 0.0f, 0.0f,
                0.0f, 0.0f, 0.0f, 1.0f, 0.0f,
                0.0f, 0.0f, 0.0f, 0.0f, 1.0f
            }
        };

        private static MAGCOLOREFFECT g_MagEffectIdentity = new MAGCOLOREFFECT
        {
            transform = new float[]
            {
                1.0f, 0.0f, 0.0f, 0.0f, 0.0f,
                0.0f, 1.0f, 0.0f, 0.0f, 0.0f,
                0.0f, 0.0f, 1.0f, 0.0f, 0.0f,
                0.0f, 0.0f, 0.0f, 1.0f, 0.0f,
                0.0f, 0.0f, 0.0f, 0.0f, 1.0f
            }
        };

        public ScreenCurtain()
        {
            if (!MagInitialize())
            {
                throw new ApplicationException("API 初始化失败。");
            }
        }

        public bool Enable()
        {
            return MagSetFullscreenColorEffect(ref g_MagEffectBlack) && MagShowSystemCursor(false);
        }

        public bool Disable()
        {
            return MagSetFullscreenColorEffect(ref g_MagEffectIdentity) && MagShowSystemCursor(true);
        }

        public bool IsEnabled()
        {
            MAGCOLOREFFECT currentEffect = new MAGCOLOREFFECT { transform = new float[25] };
            if (!MagGetFullscreenColorEffect(ref currentEffect))
            {
                throw new InvalidOperationException("Could not get current color effect.");
            }
            for (int i = 0; i < 25; i++)
            {
                if (currentEffect.transform[i] != g_MagEffectBlack.transform[i])
                {
                    return false;
                }
            }
            return true;
        }

        public static ScreenCurtain GetInstance()
        {
            try
            {
                if (Instance is null)
                {
                    Instance = new ScreenCurtain();
                }
                return Instance;
            }
            catch (Exception)
            {
                return Instance;
            }
        }

        ~ScreenCurtain()
        {
            MagUninitialize

();
        }
    }
}

参考资料

• (1) 《Windows Magnification API》: https://learn.microsoft.com/en-us/windows/win32/api/_magapi/
• (2) NVDA Vision Screen Curtain function: https://github.com/nvaccess/nvda/blob/master/source/visionEnhancementProviders/screenCurtain.py