aboutsummaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorMattias Andrée <maandree@operamail.com>2014-09-13 22:12:59 +0200
committerMattias Andrée <maandree@operamail.com>2014-09-13 22:12:59 +0200
commita6ab18ff8e29657d66c1429182bd49bfe455aad1 (patch)
treeb7a206c71fe6919c9991ce047008fc3024890e06 /src
parentupdate todo (diff)
downloadlibgamma-a6ab18ff8e29657d66c1429182bd49bfe455aad1.tar.gz
libgamma-a6ab18ff8e29657d66c1429182bd49bfe455aad1.tar.bz2
libgamma-a6ab18ff8e29657d66c1429182bd49bfe455aad1.tar.xz
doc
Signed-off-by: Mattias Andrée <maandree@operamail.com>
Diffstat (limited to '')
-rw-r--r--src/lib/fake-w32-gdi.c158
-rw-r--r--src/lib/fake-w32-gdi.h198
-rw-r--r--src/lib/gamma-w32-gdi.c5
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 <stdint.h>
-/* 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