From 30d4d46eec03cc4300cbe2937db23507e34be06a Mon Sep 17 00:00:00 2001 From: skyjake Date: Fri, 15 Mar 2013 18:46:06 +0200 Subject: [PATCH] Documentation|gl_tex: Several apidoc fixes --- doomsday/client/include/gl/gl_tex.h | 144 ++++++++++++++++------------ doomsday/client/src/gl/gl_tex.cpp | 8 +- 2 files changed, 87 insertions(+), 65 deletions(-) diff --git a/doomsday/client/include/gl/gl_tex.h b/doomsday/client/include/gl/gl_tex.h index 340ae193f7..4043b47e0e 100644 --- a/doomsday/client/include/gl/gl_tex.h +++ b/doomsday/client/include/gl/gl_tex.h @@ -49,10 +49,11 @@ extern "C" { #endif /** - * @param pixels Luminance image to be enhanced. - * @param width Width of the image in pixels. - * @param height Height of the image in pixels. - * @param hasAlpha @c true == @a pixels is luminance plus alpha data. + * @param pixels Luminance image to be enhanced. + * @param width Width of the image in pixels. + * @param height Height of the image in pixels. + * @param hasAlpha If @c true, @a pixels is assumed to contain luminance plus alpha data + * (totaling 2 * @a width * @a height bytes). */ void AmplifyLuma(uint8_t* pixels, int width, int height, boolean hasAlpha); @@ -67,6 +68,7 @@ void AmplifyLuma(uint8_t* pixels, int width, int height, boolean hasAlpha); uint8_t* ApplyColorKeying(uint8_t* pixels, int width, int height, int pixelSize); +#if 0 // dj: Doesn't make sense, "darkness" applied to an alpha channel? /** * Sets the RGB color of transparent pixels along the image's non-transparent * areas to black. When the image is then drawn with magnification, @@ -77,26 +79,32 @@ uint8_t* ApplyColorKeying(uint8_t* pixels, int width, int height, * used by jDoom on font characters and other such graphics to make them appear * less blurry. * - * @param pixels RGBA data. Input read here, and output written here. - * @param width Width of the image in pixels. + * @param pixels RGBA data (in/out). + * @param width Width of the image in pixels. * @param height Height of the image in pixels. */ -#if 0 // dj: Doesn't make sense, "darkness" applied to an alpha channel? void BlackOutlines(uint8_t* pixels, int width, int height); #endif /** - * Spread the color of none masked pixels outwards into the masked area. + * Spread the color of non-masked pixels outwards into the masked area. * This addresses the "black outlines" produced by texture filtering due to * sampling the default (black) color. + * + * @param pixels Paletted pixel data (in/out). The size of this array + * is expected to be 2 * @a width * @a height bytes + * (the first layer is for the color indices and the second + * layer for mask values). + * @param width Width of the image in pixels. + * @param height Height of the image in pixels. */ void ColorOutlinesIdx(uint8_t* pixels, int width, int height); /** - * @param pixels RGB(a) image to be enhanced. - * @param width Width of the image in pixels. - * @param height Height of the image in pixels. - * @param pixelsize Size of each pixel. Handles 3 and 4. + * @param pixels RGB(a) image to be desaturated (in/out). + * @param width Width of the image in pixels. + * @param height Height of the image in pixels. + * @param pixelSize Size of each pixel. Handles 3 and 4. */ void Desaturate(uint8_t* pixels, int width, int height, int pixelSize); @@ -104,10 +112,10 @@ void Desaturate(uint8_t* pixels, int width, int height, int pixelSize); * @note Does not conform to any standard technique and adjustments * are applied symmetrically for all color components. * - * @param pixels RGB(a) image to be enhanced. - * @param width Width of the image in pixels. - * @param height Height of the image in pixels. - * @param pixelsize Size of each pixel. Handles 3 and 4. + * @param pixels RGB(a) image to be enhanced (in/out). + * @param width Width of the image in pixels. + * @param height Height of the image in pixels. + * @param pixelSize Size of each pixel. Handles 3 and 4. */ void EnhanceContrast(uint8_t* pixels, int width, int height, int pixelSize); @@ -120,68 +128,76 @@ void EnhanceContrast(uint8_t* pixels, int width, int height, int pixelSize); * averaging the luminosity of all pixels in the original image. * * @param pixels Luminance image to equalize. - * @param width Width of the image in pixels. + * @param width Width of the image in pixels. * @param height Height of the image in pixels. + * @param rBaMul Calculated balance multiplier is written here. + * @param rHiMul Calculated multiplier is written here. + * @param rLoMul Calculated multiplier is written here. */ -void EqualizeLuma(uint8_t* pixels, int width, int height, float* rBaMul, - float* rHiMul, float* rLoMul); +void EqualizeLuma(uint8_t* pixels, int width, int height, + float* rBaMul, float* rHiMul, float* rLoMul); /** - * @param pixels RGB(a) image to evaluate. - * @param width Width of the image in pixels. - * @param height Height of the image in pixels. - * @param color Determined average color written here. + * @param pixels RGB(a) image to evaluate. + * @param width Width of the image in pixels. + * @param height Height of the image in pixels. + * @param pixelSize Size of a pixel in bytes. + * @param color Determined average color written here. */ void FindAverageColor(const uint8_t* pixels, int width, int height, int pixelSize, ColorRawf* color); /** - * @param pixels Index-color image to evaluate. - * @param width Width of the image in pixels. - * @param height Height of the image in pixels. - * @param palette Color palette to use. + * @param pixels Index-color image to evaluate. + * @param width Width of the image in pixels. + * @param height Height of the image in pixels. + * @param palette Color palette to use. * @param hasAlpha @c true == @a pixels includes alpha data. - * @param color Determined average color written here. + * @param color Determined average color written here. */ void FindAverageColorIdx(const uint8_t* pixels, int width, int height, const struct colorpalette_s* palette, boolean hasAlpha, ColorRawf* color); /** - * @param pixels RGB(a) image to evaluate. - * @param width Width of the image in pixels. - * @param height Height of the image in pixels. - * @param color Determined average color written here. + * @param pixels RGB(a) image to evaluate. + * @param width Width of the image in pixels. + * @param height Height of the image in pixels. + * @param pixelSize Size of a pixel in bytes. + * @param line Line to evaluate. + * @param color Determined average color written here. */ void FindAverageLineColor(const uint8_t* pixels, int width, int height, int pixelSize, int line, ColorRawf* color); /** - * @param pixels Index-color image to evaluate. - * @param width Width of the image in pixels. - * @param height Height of the image in pixels. - * @param palette Color palette to use. + * @param pixels Index-color image to evaluate. + * @param width Width of the image in pixels. + * @param height Height of the image in pixels. + * @param line Line to evaluate. + * @param palette Color palette to use. * @param hasAlpha @c true == @a pixels includes alpha data. - * @param color Determined average color written here. + * @param color Determined average color written here. */ void FindAverageLineColorIdx(const uint8_t* pixels, int width, int height, int line, const struct colorpalette_s* palette, boolean hasAlpha, ColorRawf* color); /** - * @param pixels RGB(a) image to evaluate. - * @param width Width of the image in pixels. - * @param height Height of the image in pixels. - * @param alpha Determined average alpha written here. - * @param coverage Fraction representing the ratio of alpha to non-alpha pixels. + * @param pixels RGB(a) image to evaluate. + * @param width Width of the image in pixels. + * @param height Height of the image in pixels. + * @param pixelSize Size of a pixel in bytes. + * @param alpha Determined average alpha written here. + * @param coverage Fraction representing the ratio of alpha to non-alpha pixels. */ void FindAverageAlpha(const uint8_t* pixels, int width, int height, int pixelSize, float* alpha, float* coverage); /** - * @param pixels Index-color image to evaluate. - * @param width Width of the image in pixels. - * @param height Height of the image in pixels. - * @param palette Color palette to use. - * @param alpha Determined average alpha written here. + * @param pixels Index-color image to evaluate. + * @param width Width of the image in pixels. + * @param height Height of the image in pixels. + * @param palette Color palette to use. + * @param alpha Determined average alpha written here. * @param coverage Fraction representing the ratio of alpha to non-alpha pixels. */ void FindAverageAlphaIdx(const uint8_t* pixels, int width, int height, @@ -193,20 +209,20 @@ void FindAverageAlphaIdx(const uint8_t* pixels, int width, int height, * @par Algorithm * Cross spread from bottom > top, right > left (inside out). * - * @param pixels Image data to be processed. - * @param width Width of the image in pixels. - * @param height Height of the image in pixels. - * @param pixelsize Size of each pixel. Handles 1 (==2), 3 and 4. - * @param region Determined region written here. + * @param pixels Image data to be processed. + * @param width Width of the image in pixels. + * @param height Height of the image in pixels. + * @param pixelSize Size of each pixel. Handles 1 (==2), 3 and 4. + * @param region Determined region written here. */ void FindClipRegionNonAlpha(const uint8_t* pixels, int width, int height, int pixelSize, int region[4]); /** - * @param pixels RGB(a) image to be enhanced. - * @param width Width of the image in pixels. - * @param height Height of the image in pixels. - * @param pixelsize Size of each pixel. Handles 3 and 4. + * @param pixels RGB(a) image to be enhanced. + * @param width Width of the image in pixels. + * @param height Height of the image in pixels. + * @param pixelSize Size of each pixel. Handles 3 and 4. */ void SharpenPixels(uint8_t* pixels, int width, int height, int pixelSize); @@ -225,8 +241,10 @@ uint8_t* GL_ScaleBufferNearest(const uint8_t* pixels, int width, int height, * Works within the given data, reducing the size of the picture to half * its original. * - * @param width Width of the final texture, must be power of two. - * @param height Height of the final texture, must be power of two. + * @param pixels RGB(A) pixel data to process (in/out). + * @param width Width of the final texture, must be power of two. + * @param height Height of the final texture, must be power of two. + * @param pixelSize Size of a pixel in bytes. */ void GL_DownMipmap32(uint8_t* pixels, int width, int height, int pixelSize); @@ -234,11 +252,13 @@ void GL_DownMipmap32(uint8_t* pixels, int width, int height, int pixelSize); * Works within the given data, reducing the size of the picture to half * its original. * - * @param width Width of the final texture, must be power of two. - * @param height Height of the final texture, must be power of two. + * @param in Pixel data to process (paletted, in/out). + * @param fadedOut Faded result image. + * @param width Width of the final texture, must be power of two. + * @param height Height of the final texture, must be power of two. + * @param fade Fade factor (0..1). */ -void GL_DownMipmap8(uint8_t* in, uint8_t* fadedOut, int width, int height, - float fade); +void GL_DownMipmap8(uint8_t* in, uint8_t* fadedOut, int width, int height, float fade); boolean GL_PalettizeImage(uint8_t* out, int outformat, const struct colorpalette_s* palette, boolean gammaCorrect, const uint8_t* in, int informat, int width, int height); diff --git a/doomsday/client/src/gl/gl_tex.cpp b/doomsday/client/src/gl/gl_tex.cpp index 91baab997f..b0fce2d531 100644 --- a/doomsday/client/src/gl/gl_tex.cpp +++ b/doomsday/client/src/gl/gl_tex.cpp @@ -1225,11 +1225,10 @@ void BlackOutlines(uint8_t* pixels, int width, int height) } #endif -/// \todo Not a very efficient algorithm... void ColorOutlinesIdx(uint8_t* buffer, int width, int height) { - assert(buffer); - { + DENG_ASSERT(buffer); + const int numpels = width * height; uint8_t* w[5]; int x, y; @@ -1245,7 +1244,10 @@ void ColorOutlinesIdx(uint8_t* buffer, int width, int height) // | w4 | // +----+ + /// @todo Not a very efficient algorithm... + for(y = 0; y < height; ++y) + { for(x = 0; x < width; ++x) { // Only solid pixels spread.