aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/fake-w32-gdi.c
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/lib/fake-w32-gdi.c
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
1 files changed, 141 insertions, 17 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)
{