From a6ab18ff8e29657d66c1429182bd49bfe455aad1 Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sat, 13 Sep 2014 22:12:59 +0200 Subject: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- src/lib/fake-w32-gdi.c | 158 +++++++++++++++++++++++++++++++++----- src/lib/fake-w32-gdi.h | 198 +++++++++++++++++++++++++++++++++++++++++++++--- src/lib/gamma-w32-gdi.c | 5 +- 3 files changed, 331 insertions(+), 30 deletions(-) diff --git a/src/lib/fake-w32-gdi.c b/src/lib/fake-w32-gdi.c index f151186..8fb1ab7 100644 --- a/src/lib/fake-w32-gdi.c +++ b/src/lib/fake-w32-gdi.c @@ -37,7 +37,14 @@ /* Use dummy translation. */ -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144871(v=vs.85).aspx */ + +/** + * Get the device context for a window or the entire screen. + * + * @param hWnd The windows, `NULL` for the entire screen. + * @return The device context. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd144871(v=vs.85).aspx + */ HDC GetDC(HWND hWnd) { /* Just a non-NULL value. */ @@ -45,7 +52,15 @@ HDC GetDC(HWND hWnd) return (HDC*)16; } -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd162920(v=vs.85).aspx */ + +/** + * Free a device context. + * + * @param hWnd The window whose device context is `hDC`, `NULL` for the entire screen. + * @param hDC The device context to free. + * @return Whether the call was successful. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd162920(v=vs.85).aspx + */ int ReleaseDC(HWND hWnd, HDC hDC) { /* Always successful. */ @@ -55,7 +70,16 @@ int ReleaseDC(HWND hWnd, HDC hDC) } -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx */ + +/** + * Get information (capabilities) for a device context. + * + * @param hDC The device context. + * @param nIndex The information to retrieve, may be `COLORMGMTCAPS`. + * @return The details of the queried information, can return `CM_GAMMA_RAMP` + * if `nIndex` is `COLORMGMTCAPS`. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx + */ int GetDeviceCaps(HDC hDC, int nIndex) { /* We have gamma ramps if the user asks for colour management capabilities. */ @@ -63,7 +87,16 @@ int GetDeviceCaps(HDC hDC, int nIndex) return CM_GAMMA_RAMP + nIndex - COLORMGMTCAPS; } -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx */ + +/** + * Set the gamma ramps for a device. + * + * @param hDC The device context. + * @param lpRamp The gamma ramps joined in the order: red, green, blue. + * This is a `WORD*` casted to `void*`. + * @return Whether the call was successful. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx + */ BOOL SetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp) { /* Always successful. */ @@ -72,7 +105,16 @@ BOOL SetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp) return TRUE; } -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd316946(v=vs.85).aspx */ + +/** + * Get the current gamma ramps for a device. + * + * @param hDC The device context. + * @param lpRamp The output for the gamma ramps joined in the order: red, green, blue. + * This is a `WORD*` casted to `void*`. + * @return Whether the call was successful. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd316946(v=vs.85).aspx + */ BOOL GetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp) { /* Always successful. */ @@ -82,9 +124,21 @@ BOOL GetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp) } -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd183490(v=vs.85).aspx */ + +/** + * Get the context for a device + * + * @param lpszDriver The driver or a display device, use "DISPLAY" if you want a display. + * @param lpszDevice The name of the device. If you want a display use can use the member + * name `DeviceName` in the third parameter, an output parameter, of + * `EnumDisplayDevices`. + * @param lpszOutput We will always use `NULL` here. + * @param lpInitData We will always use `NULL` here. This should actually by a `const DEVMODE*`. + * @return - + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd183490(v=vs.85).aspx + */ HDC CreateDC(LPCTSTR restrict lpszDriver, LPCTSTR restrict lpszDevice, - void* restrict lpszOutput, void* restrict lpInitData) + LPCTSTR restrict lpszOutput, const void* restrict lpInitData) { /* `NULL` if not asking for a CRTC, otherwise a non-NULL value. */ (void) lpszOutput; @@ -94,7 +148,17 @@ HDC CreateDC(LPCTSTR restrict lpszDriver, LPCTSTR restrict lpszDevice, } -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd162609(v=vs.85).aspx */ +/** + * Get a display device by its name or index. + * + * @param lpDevice The name of the device, use `NULL` to base the call on `iDevNum` instead. + * @param iDevNum The index of the device. + * @param lpDisplayDevice Output for the found device. + * @param dwFlags Flags, we will always use zero. + * @return Whether the call was successful. Zero is also returned if `iDevNum` + * is greater than the largest device index on the system. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd162609(v=vs.85).aspx + */ BOOL EnumDisplayDevices(LPCTSTR lpDevice, restrict DWORD iDevNum, PDISPLAY_DEVICE restrict lpDisplayDevice, DWORD dwFlags) { @@ -167,7 +231,13 @@ static size_t dc_count = 0; -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144871(v=vs.85).aspx */ +/** + * Get the device context for a window or the entire screen. + * + * @param hWnd The windows, `NULL` for the entire screen. + * @return The device context. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd144871(v=vs.85).aspx + */ HDC GetDC(HWND hWnd) { /* Return the primary CRTC. */ @@ -176,7 +246,14 @@ HDC GetDC(HWND hWnd) } -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd162920(v=vs.85).aspx */ +/** + * Free a device context. + * + * @param hWnd The window whose device context is `hDC`, `NULL` for the entire screen. + * @param hDC The device context to free. + * @return Whether the call was successful. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd162920(v=vs.85).aspx + */ int ReleaseDC(HWND hWnd, HDC hDC) { /* Disconnect from the RandR display when all monitors have been closed. */ @@ -195,7 +272,16 @@ int ReleaseDC(HWND hWnd, HDC hDC) } -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx */ + +/** + * Get information (capabilities) for a device context. + * + * @param hDC The device context. + * @param nIndex The information to retrieve, may be `COLORMGMTCAPS`. + * @return The details of the queried information, can return `CM_GAMMA_RAMP` + * if `nIndex` is `COLORMGMTCAPS`. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx + */ int GetDeviceCaps(HDC hDC, int nIndex) { /* We have gamma ramps if the user asks for colour management capabilities. */ @@ -204,14 +290,22 @@ int GetDeviceCaps(HDC hDC, int nIndex) } -/* xcb violates the rule to never return struct:s. */ +/* xcb violates the rule to never return `struct`:s. */ #ifdef __GCC__ # pragma GCC diagnostic push # pragma GCC diagnostic ignored "-Waggregate-return" #endif -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx */ +/** + * Set the gamma ramps for a device. + * + * @param hDC The device context. + * @param lpRamp The gamma ramps joined in the order: red, green, blue. + * This is a `WORD*` casted to `void*`. + * @return Whether the call was successful. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx + */ BOOL SetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp) { /* We assume that our gamma ramps are of the same size @@ -226,7 +320,15 @@ BOOL SetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp) } -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd316946(v=vs.85).aspx */ +/** + * Get the current gamma ramps for a device. + * + * @param hDC The device context. + * @param lpRamp The output for the gamma ramps joined in the order: red, green, blue. + * This is a `WORD*` casted to `void*`. + * @return Whether the call was successful. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd316946(v=vs.85).aspx + */ BOOL GetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp) { xcb_randr_get_crtc_gamma_cookie_t gamma_cookie; @@ -255,9 +357,21 @@ BOOL GetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp) } -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd183490(v=vs.85).aspx */ + +/** + * Get the context for a device + * + * @param lpszDriver The driver or a display device, use "DISPLAY" if you want a display. + * @param lpszDevice The name of the device. If you want a display use can use the member + * name `DeviceName` in the third parameter, an output parameter, of + * `EnumDisplayDevices`. + * @param lpszOutput We will always use `NULL` here. + * @param lpInitData We will always use `NULL` here. This should actually by a `const DEVMODE*`. + * @return - + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd183490(v=vs.85).aspx + */ HDC CreateDC(LPCTSTR restrict lpszDriver, LPCTSTR restrict lpszDevice, - void* restrict lpszOutput, void* restrict lpInitData) + LPCTSTR restrict lpszOutput, const void* restrict lpInitData) { int crtc_index = atoi(lpszDevice); @@ -325,7 +439,17 @@ HDC CreateDC(LPCTSTR restrict lpszDriver, LPCTSTR restrict lpszDevice, #endif -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd162609(v=vs.85).aspx */ +/** + * Get a display device by its name or index. + * + * @param lpDevice The name of the device, use `NULL` to base the call on `iDevNum` instead. + * @param iDevNum The index of the device. + * @param lpDisplayDevice Output for the found device. + * @param dwFlags Flags, we will always use zero. + * @return Whether the call was successful. Zero is also returned if `iDevNum` + * is greater than the largest device index on the system. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd162609(v=vs.85).aspx + */ BOOL EnumDisplayDevices(LPCTSTR restrict lpDevice, DWORD iDevNum, PDISPLAY_DEVICE restrict lpDisplayDevice, DWORD dwFlags) { diff --git a/src/lib/fake-w32-gdi.h b/src/lib/fake-w32-gdi.h index 6c49e6c..c777fa6 100644 --- a/src/lib/fake-w32-gdi.h +++ b/src/lib/fake-w32-gdi.h @@ -30,54 +30,230 @@ #include -/* http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx */ +/** + * One of the Windows `typedef`:s for unsigned 16-bit integer. + * This is the one used in these functions. + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#WORD + */ typedef uint16_t WORD; -typedef uint32_t DWORD; + +/** + * One of the Windows `typedef`:s for unsigned 32-bit integer. + * This is the one used in these functions. + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#DWORD + */ +typedef uint32_t DWORD ; +/* XXX Documented to be 32-bit but defined as `typedef unsigned long DWORD`, which is it? */ + +/** + * One of the Windows `typedef` for booleanic values, the `int` variant. + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#BOOL + */ typedef int BOOL; + +/** + * Windows `typedef` for a device context (the 'h' stands for 'handle'.) + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#HDC + */ typedef void* HDC; + +/** + * Windows `typedef` for a window (the 'h' stands for 'handle'.) + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#HWND + */ typedef void* HWND; + +/** + * One of the Windows `typedef`:s for `void*`, a generic pointer. + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#LPVOID + */ typedef void* LPVOID; + +/** + * A silly Windows `typedef` for a `const char*`, a constant string. + * It is also defined as NUL-terminated, but so are all C-strings + * and it makes no difference. However if `UNICODE` were to be defined + * it would be `const wchar_t*`. + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#LPCTSTR + */ typedef const char* LPCTSTR; + +/** + * Even more silly. A Windows `typedef` for either `wchar_t` or + * `char`, depending on whether `UNICODE` is defined. We will + * assume `UNICODE` is not definied because that is just silly. + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#TCHAR + */ typedef char TCHAR; + +/** + * Apperently we need `TRUE` to be defined to understand code, + * at least in Windows... + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#BOOL + */ #define TRUE 1 + +/** + * Apperently we need `FALSE` to be defined to understand code, + * at least in Windows... + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#BOOL + */ #define FALSE 0 -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144871(v=vs.85).aspx */ + +/** + * Get the device context for a window or the entire screen. + * + * @param hWnd The window, `NULL` for the entire screen. + * @return The device context. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd144871(v=vs.85).aspx + */ HDC GetDC(HWND hWnd); -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd162920(v=vs.85).aspx */ +/** + * Free a device context. + * + * @param hWnd The window whose device context is `hDC`, `NULL` for the entire screen. + * @param hDC The device context to free. + * @return Whether the call was successful. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd162920(v=vs.85).aspx + */ int ReleaseDC(HWND hWnd, HDC hDC); -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx */ +/** + * Get information (capabilities) for a device context. + * + * @param hDC The device context. + * @param nIndex The information to retrieve, may be `COLORMGMTCAPS`. + * @return The details of the queried information, can return `CM_GAMMA_RAMP` + * if `nIndex` is `COLORMGMTCAPS`. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx + */ int GetDeviceCaps(HDC hDC, int nIndex) __attribute__((const)); + +/** + * Colour management capabilities + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx + */ #define COLORMGMTCAPS 1 + +/** + * Colour management capabilities: has gamma ramps + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx + */ #define CM_GAMMA_RAMP 1 -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx */ + +/** + * Set the gamma ramps for a device. + * + * @param hDC The device context. + * @param lpRamp The gamma ramps joined in the order: red, green, blue. + * This is a `WORD*` casted to `void*`. + * @return Whether the call was successful. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx + */ BOOL SetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp); -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd316946(v=vs.85).aspx */ +/** + * Get the current gamma ramps for a device. + * + * @param hDC The device context. + * @param lpRamp The output for the gamma ramps joined in the order: red, green, blue. + * This is a `WORD*` casted to `void*`. + * @return Whether the call was successful. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd316946(v=vs.85).aspx + */ BOOL GetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp); -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd183490(v=vs.85).aspx */ +/** + * Get the context for a device + * + * @param lpszDriver The driver or a display device, use "DISPLAY" if you want a display. + * @param lpszDevice The name of the device. If you want a display use can use the member + * name `DeviceName` in the third parameter, an output parameter, of + * `EnumDisplayDevices`. + * @param lpszOutput We will always use `NULL` here. + * @param lpInitData We will always use `NULL` here. This should actually by a `const DEVMODE*`. + * @return The context for the device. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd183490(v=vs.85).aspx + */ HDC CreateDC(LPCTSTR restrict lpszDriver, LPCTSTR restrict lpszDevice, - void* restrict lpszOutput, void* restrict lpInitData); + LPCTSTR restrict lpszOutput, const void* restrict lpInitData); + +/** + * This macro does not seem to have an official documentation that is correct. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd183490(v=vs.85).aspx + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd374074(v=vs.85).aspx + */ #define TEXT(X) ((LPCTSTR)(X)) -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd183569(v=vs.85).aspx */ + +/** + * Information about a display device. + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd183569(v=vs.85).aspx + */ typedef struct { + /** + * Set this to `sizeof(DISPLAY_DEVICE)`. + */ DWORD cb; + + /** + * The name of the device. + */ TCHAR DeviceName[32]; + + /** + * The status of the device, can include `DISPLAY_DEVICE_ACTIVE`. + */ DWORD StateFlags; + } DISPLAY_DEVICE; + +/** + * Appearently we are incapable of putting asterisks at the + * end of types names, so istead we preprend them with 'P'. + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd183569(v=vs.85).aspx + */ typedef DISPLAY_DEVICE* PDISPLAY_DEVICE; + +/** + * The monitor is "on". + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd183569(v=vs.85).aspx + */ #define DISPLAY_DEVICE_ACTIVE 1 -/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd162609(v=vs.85).aspx */ +/** + * Get a display device by its name or index. + * + * @param lpDevice The name of the device, use `NULL` to base the call on `iDevNum` instead. + * @param iDevNum The index of the device. + * @param lpDisplayDevice Output for the found device. + * @param dwFlags Flags, we will always use zero. + * @return Whether the call was successful. Zero is also returned if `iDevNum` + * is greater than the largest device index on the system. + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd162609(v=vs.85).aspx + */ BOOL EnumDisplayDevices(LPCTSTR restrict lpDevice, DWORD iDevNum, PDISPLAY_DEVICE restrict lpDisplayDevice, DWORD dwFlags); diff --git a/src/lib/gamma-w32-gdi.c b/src/lib/gamma-w32-gdi.c index c5dc655..8104b18 100644 --- a/src/lib/gamma-w32-gdi.c +++ b/src/lib/gamma-w32-gdi.c @@ -37,8 +37,9 @@ /** - * The gamma ramp size that devices will - * always have in Windows GDI. + * The gamma ramp size that devices will always have in Windows GDI. + * + * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx */ #define GAMMA_RAMP_SIZE 256 -- cgit v1.2.3-70-g09d2