Add non-black brightness and contrast adjustment function and test example

grymmjack · grymmjack · commit fb383d5c95ae · 2025-09-01T11:53:55.000-04:00
diff --git a/IMGADJ/IMGADJ.BI b/IMGADJ/IMGADJ.BI
@@ -56,10 +56,12 @@ DECLARE SUB GJ_IMGADJ_HSVtoRGB (hue AS SINGLE, sat AS SINGLE, value AS SINGLE, r
 DECLARE FUNCTION GJ_IMGADJ_CreateTestImage AS LONG
 DECLARE FUNCTION GJ_IMGADJ_CreateComplexTestImage AS LONG
 DECLARE FUNCTION GJ_IMGADJ_CreateGradientTestImage AS LONG
+DECLARE FUNCTION GJ_IMGADJ_CreateTestImageWithBlack AS LONG
 DECLARE FUNCTION GJ_IMGADJ_LoadTestImage (imageType AS STRING) AS LONG
 DECLARE SUB GJ_IMGADJ_ShowComparison (originalImg AS LONG, adjustedImg AS LONG, title AS STRING)
 DECLARE FUNCTION GJ_IMGADJ_Brightness (sourceImg AS LONG, direction AS STRING, amount AS INTEGER) AS LONG
 DECLARE FUNCTION GJ_IMGADJ_Contrast (sourceImg AS LONG, direction AS STRING, amount AS INTEGER) AS LONG
+DECLARE FUNCTION GJ_IMGADJ_BrightnessContrastNonBlack (sourceImg AS LONG, brightnessDir AS STRING, brightnessAmount AS INTEGER, contrastDir AS STRING, contrastAmount AS INTEGER) AS LONG
 DECLARE FUNCTION GJ_IMGADJ_Gamma (sourceImg AS LONG, direction AS STRING, amount AS INTEGER) AS LONG
 DECLARE FUNCTION GJ_IMGADJ_Saturation (sourceImg AS LONG, direction AS STRING, amount AS INTEGER) AS LONG
 DECLARE FUNCTION GJ_IMGADJ_Hue (sourceImg AS LONG, direction AS STRING, amount AS INTEGER) AS LONG
diff --git a/IMGADJ/IMGADJ.BM b/IMGADJ/IMGADJ.BM
@@ -275,6 +275,101 @@ FUNCTION GJ_IMGADJ_Contrast (sourceImg AS LONG, direction AS STRING, amount AS I
 END FUNCTION
 
 
+''
+' Apply brightness and contrast adjustments to all non-black pixels
+' Black pixels (RGB 0,0,0) are preserved unchanged while all other pixels are adjusted
+' @param sourceImg LONG Source image handle
+' @param brightnessDir STRING "+" to increase brightness, "-" to decrease
+' @param brightnessAmount INTEGER Brightness adjustment amount (0-255)
+' @param contrastDir STRING "+" to increase contrast, "-" to decrease
+' @param contrastAmount INTEGER Contrast percentage (0-100)
+' @return LONG New image handle with adjustments applied to non-black pixels only
+' @example
+'   adjusted = GJ_IMGADJ_BrightnessContrastNonBlack(myImage, "+", 30, "+", 20)
+'   ' Increases brightness by 30 and contrast by 20% for all non-black pixels
+'
+FUNCTION GJ_IMGADJ_BrightnessContrastNonBlack (sourceImg AS LONG, brightnessDir AS STRING, brightnessAmount AS INTEGER, contrastDir AS STRING, contrastAmount AS INTEGER)
+    IF sourceImg = 0 THEN
+        GJ_IMGADJ_BrightnessContrastNonBlack = 0
+        EXIT FUNCTION
+    END IF
+    
+    DIM resultImg AS LONG
+    resultImg = _COPYIMAGE(sourceImg, 32)
+    
+    ' Calculate brightness offset
+    DIM brightnessOffset AS INTEGER
+    IF brightnessDir = "+" THEN
+        brightnessOffset = brightnessAmount
+    ELSE
+        brightnessOffset = -brightnessAmount
+    END IF
+    
+    ' Calculate contrast factor
+    DIM contrastPct AS INTEGER
+    IF contrastDir = "+" THEN
+        contrastPct = contrastAmount
+    ELSE
+        contrastPct = -contrastAmount
+    END IF
+    
+    DIM contrastFactor AS DOUBLE
+    contrastFactor = (259.0 * (contrastPct + 255.0)) / (255.0 * (259.0 - contrastPct))
+    
+    ' Apply adjustments using _MEMIMAGE for speed
+    DIM m AS _MEM
+    m = _MEMIMAGE(resultImg)
+    
+    DIM w AS INTEGER, h AS INTEGER
+    w = _WIDTH(resultImg)
+    h = _HEIGHT(resultImg)
+    
+    DIM x AS INTEGER, y AS INTEGER
+    DIM pixelColor AS _UNSIGNED LONG
+    DIM r AS INTEGER, g AS INTEGER, b AS INTEGER, a AS INTEGER
+    DIM newR AS INTEGER, newG AS INTEGER, newB AS INTEGER
+    
+    FOR y = 0 TO h - 1
+        FOR x = 0 TO w - 1
+            ' Get pixel color using _MEMGET
+            pixelColor = _MEMGET(m, m.OFFSET + (y * w + x) * 4, _UNSIGNED LONG)
+            
+            ' Extract RGBA components
+            r = _RED32(pixelColor)
+            g = _GREEN32(pixelColor)
+            b = _BLUE32(pixelColor)
+            a = _ALPHA32(pixelColor)
+            
+            ' Only adjust non-black pixels (skip if R=0, G=0, B=0)
+            IF r <> 0 OR g <> 0 OR b <> 0 THEN
+                ' Apply brightness adjustment
+                newR = r + brightnessOffset
+                newG = g + brightnessOffset
+                newB = b + brightnessOffset
+                
+                ' Apply contrast adjustment
+                newR = INT(contrastFactor * (newR - 128) + 128)
+                newG = INT(contrastFactor * (newG - 128) + 128)
+                newB = INT(contrastFactor * (newB - 128) + 128)
+                
+                ' Clamp values to valid range
+                newR = _CLAMP(newR, 0, 255)
+                newG = _CLAMP(newG, 0, 255)
+                newB = _CLAMP(newB, 0, 255)
+                
+                ' Create new pixel and store it using _MEMPUT
+                pixelColor = _RGBA32(newR, newG, newB, a)
+                _MEMPUT m, m.OFFSET + (y * w + x) * 4, pixelColor
+            END IF
+            ' Black pixels (r=0, g=0, b=0) are left unchanged
+        NEXT x
+    NEXT y
+    
+    _MEMFREE m
+    GJ_IMGADJ_BrightnessContrastNonBlack = resultImg
+END FUNCTION
+
+
 ''
 ' Adjust image gamma
 ' @param sourceImg LONG Source image handle
@@ -1577,3 +1672,140 @@ FUNCTION GJ_IMGADJ_CreateTestImage ()
     _DEST oldDest
     GJ_IMGADJ_CreateTestImage = img
 END FUNCTION
+
+
+''
+' Apply pixel scaling algorithms to images
+' Uses QB64PE's built-in pixel scalers for retro-style upscaling without blurring
+' 
+' @param sourceImg LONG Source image handle
+' @param scalerType INTEGER Type of pixel scaler to apply (use GJ_IMGADJ_PIXELSCALER_* constants)
+' @return LONG New image handle with pixel scaling applied, 0 on error
+' @example
+'   scaledImg = GJ_IMGADJ_PixelScaler(myImage, GJ_IMGADJ_PIXELSCALER_SXBR2)
+'   IF scaledImg > 0 THEN _PUTIMAGE (0, 0), scaledImg
+' @version 1.0
+' @author grymmjack
+'
+FUNCTION GJ_IMGADJ_PixelScaler (sourceImg AS LONG, scalerType AS INTEGER)
+    ' Check if source image is valid
+    IF sourceImg = 0 OR sourceImg = -1 THEN
+        PRINT "GJ_IMGADJ_PixelScaler: Invalid source image handle"
+        GJ_IMGADJ_PixelScaler = 0
+        EXIT FUNCTION
+    END IF
+    
+    ' Validate scaler type
+    IF scalerType < 0 OR scalerType > 7 THEN
+        PRINT "GJ_IMGADJ_PixelScaler: Invalid scaler type (must be 0-7)"
+        GJ_IMGADJ_PixelScaler = 0
+        EXIT FUNCTION
+    END IF
+    
+    ' Map scaler type to requirements string
+    DIM requirements AS STRING
+    SELECT CASE scalerType
+        CASE GJ_IMGADJ_PIXELSCALER_SXBR2
+            requirements = "sxbr2"
+        CASE GJ_IMGADJ_PIXELSCALER_SXBR3
+            requirements = "sxbr3" 
+        CASE GJ_IMGADJ_PIXELSCALER_SXBR4
+            requirements = "sxbr4"
+        CASE GJ_IMGADJ_PIXELSCALER_MMPX2
+            requirements = "mmpx2"
+        CASE GJ_IMGADJ_PIXELSCALER_HQ2XA
+            requirements = "hq2xa"
+        CASE GJ_IMGADJ_PIXELSCALER_HQ2XB
+            requirements = "hq2xb"
+        CASE GJ_IMGADJ_PIXELSCALER_HQ3XA
+            requirements = "hq3xa"
+        CASE GJ_IMGADJ_PIXELSCALER_HQ3XB
+            requirements = "hq3xb"
+        CASE ELSE
+            PRINT "GJ_IMGADJ_PixelScaler: Unknown scaler type"
+            GJ_IMGADJ_PixelScaler = 0
+            EXIT FUNCTION
+    END SELECT
+    
+    ' Simple approach: save to temp file, load with scaler, return result
+    DIM tempFileName AS STRING
+    tempFileName = "temp_scaler_" + _TRIM$(STR$(TIMER)) + ".png"
+    
+    ' Save source image to temporary file
+    _SAVEIMAGE tempFileName, sourceImg
+    
+    ' Check if the file was saved successfully
+    IF NOT _FILEEXISTS(tempFileName) THEN
+        PRINT "GJ_IMGADJ_PixelScaler: Failed to save temporary image file"
+        GJ_IMGADJ_PixelScaler = 0
+        EXIT FUNCTION
+    END IF
+    
+    ' Load directly from file with scaler - this is the simple working method
+    DIM scaledImg AS LONG
+    scaledImg = _LOADIMAGE(tempFileName, 32, requirements)
+    
+    ' Clean up temporary file
+    KILL tempFileName
+    
+    ' Check if loading was successful and return result
+    IF scaledImg = 0 OR scaledImg = -1 THEN
+        PRINT "GJ_IMGADJ_PixelScaler: Failed to load scaled image"
+        GJ_IMGADJ_PixelScaler = 0
+        EXIT FUNCTION
+    END IF
+    
+    GJ_IMGADJ_PixelScaler = scaledImg
+END FUNCTION
+
+
+''
+' Create a test image with distinct black areas and colored regions
+' This helps demonstrate the difference between regular and non-black adjustments
+' @return LONG Image handle with test pattern including black areas
+' @example
+'   testImg = GJ_IMGADJ_CreateTestImageWithBlack()
+'
+FUNCTION GJ_IMGADJ_CreateTestImageWithBlack ()
+    DIM img AS LONG
+    DIM w AS INTEGER, h AS INTEGER
+    w = 300
+    h = 300
+    
+    img = _NEWIMAGE(w, h, 32)
+    _DEST img
+    
+    ' Fill with a base color (dark blue)
+    CLS , _RGB32(40, 40, 100)
+    
+    ' Add some colored rectangles
+    LINE (50, 50)-(150, 150), _RGB32(200, 100, 50), BF  ' Orange rectangle
+    LINE (200, 50)-(250, 150), _RGB32(50, 200, 100), BF ' Green rectangle
+    LINE (50, 200)-(150, 250), _RGB32(150, 50, 200), BF ' Purple rectangle
+    LINE (200, 200)-(250, 250), _RGB32(200, 200, 50), BF ' Yellow rectangle
+    
+    ' Add some black areas to test the non-black function
+    LINE (75, 75)-(125, 125), _RGB32(0, 0, 0), BF     ' Black square in orange
+    LINE (175, 80)-(190, 120), _RGB32(0, 0, 0), BF    ' Black bar
+    LINE (100, 175)-(140, 190), _RGB32(0, 0, 0), BF   ' Black bar
+    LINE (225, 225)-(240, 240), _RGB32(0, 0, 0), BF   ' Black square in yellow
+    
+    ' Add some circles with black centers
+    CIRCLE (100, 100), 20, _RGB32(255, 255, 255)      ' White circle
+    PAINT (100, 100), _RGB32(0, 0, 0), _RGB32(255, 255, 255) ' Fill with black
+    
+    CIRCLE (225, 100), 15, _RGB32(255, 0, 0)          ' Red circle  
+    PAINT (225, 100), _RGB32(0, 0, 0), _RGB32(255, 0, 0) ' Fill with black
+    
+    ' Add some text areas
+    COLOR _RGB32(255, 255, 255)
+    _PRINTSTRING (10, 10), "TEST IMAGE"
+    _PRINTSTRING (10, 280), "Black areas preserved"
+    
+    ' Add some pure black lines to test edge cases
+    LINE (0, 160)-(299, 160), _RGB32(0, 0, 0)         ' Horizontal black line
+    LINE (160, 0)-(160, 299), _RGB32(0, 0, 0)         ' Vertical black line
+    
+    _DEST 0
+    GJ_IMGADJ_CreateTestImageWithBlack = img
+END FUNCTION
diff --git a/IMGADJ/README.md b/IMGADJ/README.md
@@ -14,16 +14,34 @@ Image adjustment is a common need in graphics programming, but implementing effi
 - **Memory safety** - clear ownership of returned image handles
 - **Performance** - 10-200x faster than naive implementations
 - **Real-time capability** - suitable for interactive applications
+- **Selective processing** - NEW! Non-black adjustments preserve pure black pixels
 
 The library draws inspiration from professional image editing software like Photoshop and GIMP, providing similar adjustment capabilities in a QB64PE-friendly format.
 
+### **NEW!** Selective Black Preservation
+
+The `GJ_IMGADJ_BrightnessContrastNonBlack&()` function addresses a common problem in image processing: maintaining pure black elements while adjusting the rest of the image.
+
+**Problem Solved:**
+- Traditional brightness adjustments turn black (RGB 0,0,0) pixels gray
+- Black text, outlines, borders, and UI elements lose their crispness
+- Logos and graphics with black elements become muddy
+
+**Solution Benefits:**
+- **Preserves text readability** - Black text stays perfectly black
+- **Maintains UI crispness** - Black borders and outlines remain sharp
+- **Artistic control** - Keep pure black shadows and artistic elements
+- **Logo processing** - Enhance colored portions without affecting black elements
+- **Efficient processing** - Single function combines brightness + contrast with pixel selection
+
 ## WHAT'S IN THE LIBRARY
 
 ### Core Adjustments
 | FUNCTION | PURPOSE | PARAMETERS | PERFORMANCE |
 |----------|---------|------------|-------------|
 | `GJ_IMGADJ_Brightness&()` | Adjust image brightness | `(img&, "+"/"-", amount%)` | 10-50x faster with _MEMIMAGE |
 | `GJ_IMGADJ_Contrast&()` | Adjust image contrast | `(img&, "+"/"-", percentage%)` | 10-50x faster with _MEMIMAGE |
+| `GJ_IMGADJ_BrightnessContrastNonBlack&()` | **NEW!** Adjust brightness/contrast while preserving black pixels | `(img&, brightDir$, brightAmt%, contrastDir$, contrastAmt%)` | Selective pixel processing |
 | `GJ_IMGADJ_Gamma&()` | Gamma correction | `(img&, "+"/"-", amount%)` | 100x faster with lookup tables |
 | `GJ_IMGADJ_Saturation&()` | Adjust color saturation | `(img&, "+"/"-", percentage%)` | HSV color space conversion |
 | `GJ_IMGADJ_Hue&()` | Shift hue around color wheel | `(img&, "+"/"-", degrees%)` | HSV color space conversion |
@@ -94,6 +112,7 @@ The library draws inspiration from professional image editing software like Phot
 | `GJ_IMGADJ_CreateComplexTestImage&()` | Generate test image | `()` | Complex pattern for testing |
 | `GJ_IMGADJ_CreateGradientTestImage&()` | Generate gradient | `()` | RGB gradient pattern |
 | `GJ_IMGADJ_CreateSimpleTestImage&()` | Generate simple image | `()` | Basic shapes and colors |
+| `GJ_IMGADJ_CreateTestImageWithBlack&()` | **NEW!** Generate test image with black areas | `()` | Specifically for testing non-black adjustments |
 
 ## USAGE
 
@@ -149,6 +168,33 @@ DO
 LOOP
 ```
 
+#### Non-Black Brightness/Contrast (Selective Adjustment)
+```vb
+' Perfect for preserving black text, outlines, or UI elements
+DIM imageWithBlackElements AS LONG, selectively_adjusted AS LONG
+
+' Load image with black text or graphics
+imageWithBlackElements = GJ_IMGADJ_CreateTestImageWithBlack&()
+
+' Apply strong adjustments while preserving pure black pixels
+selectively_adjusted = GJ_IMGADJ_BrightnessContrastNonBlack&(imageWithBlackElements, "+", 60, "+", 40)
+
+' Compare with regular adjustment (affects all pixels including black)
+DIM regular_adjusted AS LONG, temp AS LONG
+temp = GJ_IMGADJ_Brightness&(imageWithBlackElements, "+", 60)
+regular_adjusted = GJ_IMGADJ_Contrast&(temp, "+", 40)
+_FREEIMAGE temp
+
+' Side-by-side comparison shows black preservation
+CALL GJ_IMGADJ_ShowComparison(regular_adjusted, selectively_adjusted, "Regular vs Non-Black Adjustment")
+
+' Use cases for non-black adjustment:
+' • Photo editing with black text overlay
+' • UI graphics with black borders/outlines  
+' • Logo enhancement while preserving black elements
+' • Artistic effects maintaining pure black shadows
+```
+
 #### Batch Processing
 ```vb
 DIM images(10) AS LONG, processed(10) AS LONG
@@ -332,6 +378,10 @@ _FREEIMAGE adjusted  ' Always free when done!
 ### Amount/Percentage Parameters
 - **Brightness**: 0-255 (amount to add/subtract)
 - **Contrast**: 0-100 (percentage change)
+- **BrightnessContrastNonBlack**: 
+  - brightDir/contrastDir: "+" or "-" (direction for each adjustment)
+  - brightAmt: 0-255 (brightness amount), contrastAmt: 0-100 (contrast percentage)
+  - Only affects pixels that are NOT pure black (RGB 0,0,0)
 - **Gamma**: 0-100 (gamma multiplier = 1.0 + amount/100)
 - **Saturation**: 0-200 (percentage change)
 - **Hue**: 0-360 (degrees to shift)
diff --git a/IMGADJ/examples/brightness_contrast_nonblack_test.bas b/IMGADJ/examples/brightness_contrast_nonblack_test.bas
