Further preparatory refactoring and cleanup of the texture loading/pr…

…ocessing pipeline.

doomsday/build/codeblocks/doomsday.cbp

@@ -542,6 +542,7 @@
 		<Unit filename="..\..\engine\portable\src\gl_tga.c">
 			<Option compilerVar="CC" />
 		</Unit>
+		<Unit filename="..\..\engine\portable\src\image.c" />
 		<Unit filename="..\..\engine\portable\src\m_args.c">
 			<Option compilerVar="CC" />
 		</Unit>

doomsday/build/win32/doomsday_cl.rsp

@@ -44,6 +44,7 @@
  .\..\..\engine\portable\src\gl_font.c
  .\..\..\engine\portable\src\gl_draw.c
  .\..\..\engine\portable\src\gl_drawvectorgraphic.c
+ .\..\..\engine\portable\src\image.c
  .\..\..\engine\portable\src\pathdirectory.c
  .\..\..\engine\portable\src\rend_console.c
  .\..\..\engine\portable\src\rend_bias.c

doomsday/build/win32/vs8/doomsday.vcproj

@@ -1140,6 +1140,10 @@
 				RelativePath="..\..\..\engine\portable\src\gl_tga.c"
 				>
 			</File>
+			<File
+				RelativePath="..\..\..\engine\portable\src\image.c"
+				>
+			</File>
 			<File
 				RelativePath="..\..\..\engine\portable\src\m_args.c"
 				>

doomsday/engine/portable/include/gl_main.h

@@ -69,15 +69,12 @@ void            GL_SwitchTo3DState(boolean push_state, viewport_t* port);
 void            GL_Restore2DState(int step, viewport_t* port);
 void            GL_ProjectionMatrix(void);
 void            GL_InfinitePerspective(DGLdouble fovy, DGLdouble aspect, DGLdouble znear);
-void            GL_RuntimeMode(void);
 void            GL_DoUpdate(void);
 void            GL_BlendMode(blendmode_t mode);
 
 void            GL_InitRefresh(void);
 void            GL_ShutdownRefresh(void);
 void            GL_UseFog(int yes);
-//void            GL_InitVarFont(void);
-//void            GL_ShutdownVarFont(void);
 const char*     GL_ChooseFixedFont(void);
 const char*     GL_ChooseVariableFont(glfontstyle_t style, int resX, int resY);
 void            GL_LowRes(void);
@@ -105,31 +102,121 @@ void            GL_DrawElements(dglprimtype_t type, int count,
                                 const uint* indices);
 boolean         GL_Grab(int x, int y, int width, int height,
                         dgltexformat_t format, void* buffer);
-boolean         GL_TexImage(dgltexformat_t format, DGLuint palid, int width,
-                            int height, int genMips, void* data);
-int             GL_GetTexAnisoMul(int level);
 
-DGLuint         GL_CreateColorPalette(const int compOrder[3],
-                                      const byte compSize[3],
-                                      const byte* data, ushort num);
-void            GL_DeleteColorPalettes(DGLsizei n, const DGLuint* palettes);
+/**
+ * @param format  DGL texture format symbolic, one of:
+ *      DGL_RGB
+ *      DGL_RGBA
+ *      DGL_COLOR_INDEX_8
+ *      DGL_COLOR_INDEX_8_PLUS_A8
+ *      DGL_LUMINANCE
+ * @param palid  Id of the color palette to use with this texture. Only has
+ *      meaning if the input format is one of:
+ *      DGL_COLOR_INDEX_8
+ *      DGL_COLOR_INDEX_8_PLUS_A8
+ * @param width  Width of the texture, must be power of two.
+ * @param height  Height of the texture, must be power of two.
+ * @param genMips  If negative sets a specific mipmap level, e.g.:
+ *      @c -1, means mipmap level 1.
+ * @param data Ptr to the texture data.
+ *
+ * @return  @c true iff successful.
+ */
+boolean GL_TexImage(dgltexformat_t format, DGLuint palid, int width, int height,
+    int genMips, void* data);
+
+/**
+ * Given a logical anisotropic filtering level return an appropriate multiplier
+ * according to the current GL state and user configuration.
+ */
+int GL_GetTexAnisoMul(int level);
+
+/**
+ * How many mipmap levels are needed for a texture of the given dimensions?
+ *
+ * @param width  Logical width of the texture in pixels.
+ * @param height  Logical height of the texture in pixels.
+ * @return  Number of mipmap levels required.
+ */
+int GL_NumMipmapLevels(int width, int height);
+
+/**
+ * @param compOrder  Component order. Examples:
+ *                         [0,1,2] == RGB
+ *                         [2,1,0] == BGR
+ * @param compSize  Number of bits per component [R,G,B].
+ */
+DGLuint GL_CreateColorPalette(const int compOrder[3], const uint8_t compSize[3],
+    const uint8_t* data, ushort num);
+
+void GL_DeleteColorPalettes(DGLsizei n, const DGLuint* palettes);
 
-void            GL_GetColorPaletteRGB(DGLuint id, DGLubyte rgb[3],
-                                      ushort idx);
+void GL_GetColorPaletteRGB(DGLuint id, DGLubyte rgb[3], ushort idx);
 
 boolean GL_PalettizeImage(uint8_t* out, int outformat, DGLuint palid,
     boolean gammaCorrect, const uint8_t* in, int informat, int width, int height);
 
 boolean GL_QuantizeImageToPalette(uint8_t* out, int outformat, DGLuint palid,
     const uint8_t* in, int informat, int width, int height);
 
-void            GL_DeSaturatePalettedImage(byte* buffer, DGLuint palid,
-                                           int width, int height);
+/**
+ * Desaturates the texture in the dest buffer by averaging the colour then
+ * looking up the nearest match in the palette. Increases the brightness
+ * to maximum.
+ */
+void GL_DeSaturatePalettedImage(byte* buffer, DGLuint palid, int width, int height);
 
 // Returns a pointer to a copy of the screen. The pointer must be
 // deallocated by the caller.
 unsigned char*  GL_GrabScreen(void);
 
+/**
+ * in/out format:
+ * 1 = palette indices
+ * 2 = palette indices followed by alpha values
+ * 3 = RGB
+ * 4 = RGBA
+ */
+uint8_t* GL_ConvertBuffer(const uint8_t* src, int width, int height,
+    int comps, colorpaletteid_t pal, boolean gamma, int outformat);
+
+/**
+ * @param method  Unique identifier of the smart filtering method to apply.
+ * @param src  Source image to be filtered.
+ * @param width  Logical width of the source image in pixels.
+ * @param height  Logical height of the source image in pixels.
+ * @param flags  @see imageConversionFlags.
+ * @param outWidth  Logical width of resultant image in pixels.
+ * @param outHeight  Logical height of resultant image in pixels.
+ *
+ * @return  Newly allocated version of the source image if filtered else @c == @a src.
+ */
+uint8_t* GL_SmartFilter(int method, const uint8_t* src, int width, int height,
+    int flags, int* outWidth, int* outHeight);
+
+/**
+ * Calculates the properties of a dynamic light that the given sprite frame
+ * casts. Crop a boundary around the image to remove excess alpha'd pixels
+ * from adversely affecting the calculation.
+ * Handles pixel sizes; 1 (==2), 3 and 4.
+ */
+void GL_CalcLuminance(const uint8_t* buffer, int width, int height, int comps,
+    colorpaletteid_t palid, float* brightX, float* brightY, float color[3],
+    float* lumSize);
+
+/**
+ * @param width  Logical width of the image in pixels.
+ * @param height  Logical height of the image in pixels.
+ * @param flags  @see imageConversionFlags.
+ */
+int GL_ChooseSmartFilter(int width, int height, int flags);
+
+/**
+ * The given RGB color is scaled uniformly so that the highest component
+ * becomes one.
+ */
+void amplify(float rgb[3]);
+
 // Console commands.
 D_CMD(UpdateGammaRamp);
 

doomsday/engine/portable/include/gl_tex.h

@@ -23,83 +23,163 @@
  */
 
 /**
- * Texture Manipulation Algorithms.
+ * Image manipulation and evaluation algorithms.
  */
 
-#ifndef LIBDENG_TEXTURES_H
-#define LIBDENG_TEXTURES_H
-
-struct image_s;
-
-boolean GL_OptimalSize(int width, int height, int* optWidth, int* optHeight,
-    boolean noStretch, boolean isMipMapped);
+#ifndef LIBDENG_IMAGE_MANIPULATION_H
+#define LIBDENG_IMAGE_MANIPULATION_H
 
 /**
- * in/out format:
- * 1 = palette indices
- * 2 = palette indices followed by alpha values
- * 3 = RGB
- * 4 = RGBA
+ * @param pixels  Luminance image to be enhanced.
+ * @param width  Logical width of the image in pixels.
+ * @param height  Logical height of the image in pixels.
+ * @param hasAlpha  @c true == @a pixels is luminance plus alpha data.
  */
-void GL_ConvertBuffer(int width, int height, int informat, int outformat,
-    const uint8_t* src, uint8_t* dst, colorpaletteid_t pal, boolean gamma);
+void AmplifyLuma(uint8_t* pixels, int width, int height, boolean hasAlpha);
 
-uint8_t* GL_ScaleBuffer32(const uint8_t* src, int width, int height, int comps,
-    int outWidth, int outHeight);
-
-void            GL_DownMipmap32(byte* in, int width, int height, int comps);
-void            GL_ConvertToAlpha(struct image_s *image, boolean makeWhite);
-void            GL_ConvertToLuminance(struct image_s *image);
-void            GL_CalcLuminance(byte* buffer, int width, int height,
-                                 int pixelsize, colorpaletteid_t palid,
-                                 float* brightX, float* brightY,
-                                 rgbcol_t* color, float* lumSize);
-byte*           GL_ApplyColorKeying(byte* buf, unsigned int pixelSize,
-                                    unsigned int width, unsigned int height);
-int             GL_ValidTexHeight2(int width, int height);
+/**
+ * Take the input buffer and convert to color keyed. A new buffer may be
+ * needed if the input buffer has three color components.
+ *
+ * @return  If the in buffer wasn't large enough will return a ptr to the
+ *      newly allocated buffer which must be freed with free(), else @a buf.
+ */
+uint8_t* ApplyColorKeying(uint8_t* pixels, int width, int height,
+    int pixelSize);
 
-void            pixBlt(byte* src, int srcWidth, int srcHeight, byte* dest,
-                       int destWidth, int destHeight, int alpha, int srcRegX,
-                       int srcRegY, int destRegX, int destRegY, int regWidth,
-                       int regHeight);
-void            averageColorIdx(rgbcol_t col, byte* data, int w, int h,
-                                colorpaletteid_t palid, boolean hasAlpha);
-void            averageColorRGB(rgbcol_t col, byte* data, int w, int h);
-int             lineAverageColorIdx(rgbcol_t col, byte* data, int w, int h,
-                                    int line, colorpaletteid_t palid,
-                                    boolean hasAlpha);
-int             lineAverageColorRGB(rgbcol_t col, byte* data, int w, int h,
-                                    int line);
-void            amplify(float* rgb);
+/**
+ * @param pixels  RGBA data. Input read here, and output written here.
+ * @param width  Logical width of the image in pixels.
+ * @param height  Logical 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.
  * This addresses the "black outlines" produced by texture filtering due to
  * sampling the default (black) color.
  */
-void ColorOutlines(uint8_t* buffer, int width, int height);
+void ColorOutlinesIdx(uint8_t* pixels, int width, int height);
 
-boolean         ImageHasAlpha(struct image_s *image);
+/**
+ * @param pixels  RGB(a) image to be enhanced.
+ * @param width  Logical width of the image in pixels.
+ * @param height  Logical 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);
 
 /**
+ * \important 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  Logical width of the image in pixels.
+ * @param height  Logical 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);
+
+/**
+ * Equalize the specified luminance map such that the minimum and maximum
+ * brightness covers the whole [0...255] range.
+ *
+ * \algorithm Calculates shift deltas for bright and dark-side pixels by
+ * averaging the luminosity of all pixels in the original image.
+ *
+ * @param pixels  Luminance image to equalize.
  * @param width  Logical width of the image in pixels.
  * @param height  Logical height of the image in pixels.
- * @param flags  @see imageConversionFlags.
  */
-int GL_ChooseSmartFilter(int width, int height, int flags);
+void EqualizeLuma(uint8_t* pixels, int width, int height, float* rBaMul,
+    float* rHiMul, float* rLoMul);
+
+/**
+ * @param pixels  RGB(a) image to evaluate.
+ * @param width  Logical width of the image in pixels.
+ * @param height  Logical height of the image in pixels.
+ * @param color  Determined average color written here.
+ */
+void FindAverageColor(const uint8_t* pixels, int width, int height,
+    int pixelSize, float color[3]);
+
+/**
+ * @param pixels  Index-color image to evaluate.
+ * @param width  Logical width of the image in pixels.
+ * @param height  Logical height of the image in pixels.
+ * @param palid  Unique identifier of the color palette to use.
+ * @param hasAlpha  @c true == @a pixels includes alpha data.
+ * @param color  Determined average color written here.
+ */
+void FindAverageColorIdx(const uint8_t* pixels, int width, int height,
+    colorpaletteid_t palid, boolean hasAlpha, float color[3]);
+
+/**
+ * @param pixels  RGB(a) image to evaluate.
+ * @param width  Logical width of the image in pixels.
+ * @param height  Logical height of the image in pixels.
+ * @param color  Determined average color written here.
+ */
+void FindAverageLineColor(const uint8_t* pixels, int width, int height,
+    int pixelSize, int line, float color[3]);
+
+/**
+ * @param pixels  Index-color image to evaluate.
+ * @param width  Logical width of the image in pixels.
+ * @param height  Logical height of the image in pixels.
+ * @param palid  Unique identifier of the color palette to use.
+ * @param hasAlpha  @c true == @a pixels includes alpha data.
+ * @param color  Determined average color written here.
+ */
+void FindAverageLineColorIdx(const uint8_t* pixels, int width, int height,
+    int line, colorpaletteid_t palid, boolean hasAlpha, float color[3]);
+
+/**
+ * Calculates a clip region for the image that excludes alpha pixels.
+ * \algorithm: Cross spread from bottom > top, right > left (inside out).
+ *
+ * @param pixels  Image data to be processed.
+ * @param width  Logical width of the image in pixels.
+ * @param height  Logical 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  Logical width of the image in pixels.
+ * @param height  Logical 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);
+
+uint8_t* GL_ScaleBuffer(const uint8_t* pixels, int width, int height,
+    int pixelSize, int outWidth, int outHeight);
+
+uint8_t* GL_ScaleBufferNearest(const uint8_t* pixels, int width, int height,
+    int pixelSize, int outWidth, int outHeight);
+
+/**
+ * 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.
+ */
+void GL_DownMipmap32(uint8_t* pixels, int width, int height, int pixelSize);
 
 /**
- * @param method  Unique identifier of the smart filtering method to apply.
- * @param src  Source image to be filtered.
- * @param width  Logical width of the source image in pixels.
- * @param height  Logical height of the source image in pixels.
- * @param flags  @see imageConversionFlags.
- * @param outWidth  Logical width of resultant image in pixels.
- * @param outHeight  Logical height of resultant image in pixels.
+ * Works within the given data, reducing the size of the picture to half
+ * its original.
  *
- * @return  Newly allocated version of the source image if filtered else @c == @a src.
+ * @param width  Width of the final texture, must be power of two.
+ * @param height  Height of the final texture, must be power of two.
  */
-uint8_t* GL_SmartFilter(int method, const uint8_t* src, int width, int height,
-    int flags, int* outWidth, int* outHeight);
+void GL_DownMipmap8(uint8_t* in, uint8_t* fadedOut, int width, int height,
+    float fade);
 
-#endif /* LIBDENG_TEXTURES_H */
+#endif /* LIBDENG_IMAGE_MANIPULATION_H */