Help File/Documentation Issues. (Discussion Only)

[ioa747]

16 minutes ago, jpm said:

What is the effect of SmoothingModeNode is it equal to SmoothingModeDefault?

To answer your question:  (based on logic)

technically, SmoothingModeNone and SmoothingModeDefault are not necessarily the same,
although they often result in the same "aliased" visual output.

SmoothingModeDefault (0): This tells GDI+ to use the system's default behavior.
In most cases, this defaults to no smoothing (SmoothingModeNone),
but it leaves room for the GDI+ engine to decide based on the context or global settings.

SmoothingModeNone (3): This is an explicit instruction to disable all smoothing. It is a "forced" state.

In the official MSDN documentation:

SmoothingModeDefault is associated with QualityModeDefault.

SmoothingModeNone is a distinct state meant to ensure no anti-aliasing is applied, regardless of any other default system settings.

So, while the result for a user might look like "no smoothing" in both cases,
SmoothingModeNone is the precise constant to use if you want to strictly enforce the absence of any anti-aliasing.

 

https://learn.microsoft.com/en-us/windows/win32/api/gdiplusenums/ne-gdiplusenums-smoothingmode

Edited June 11 by ioa747

[jpm]

Thanks, the doc you pointed show the same

anyway I will update our doc saying no antialiasing for SmoothingModeNone 

[jpm]

Now That the doc is clear

I don't understand why the example display 1 as 2 is set

Any idea

[pixelsearch]

For the record, I don't know if _GDIPlus_GraphicsGetSmoothingMode needs to be revised or not :

Help file :

Return Value
Success: the smoothing mode. Can be one of the following:
    0 - Smoothing is not applied
    1 - Smoothing is applied using an 8 X 4 box filter
    2 - Smoothing is applied using an 8 X 8 box filter

msdn in this link

Return value
Type: SmoothingMode
If smoothing (antialiasing) is applied to this Graphics object, this method returns SmoothingModeAntiAlias.
If smoothing (antialiasing) is not applied to this Graphics object, this method returns SmoothingModeNone.
SmoothingModeAntiAlias and SmoothingModeNone are elements of the SmoothingMode enumeration.

 

[pixelsearch]

Just checked the function _GDIPlus_GraphicsGetSmoothingMode() in GDIPlus.au3
A mapping is done inside the function, which seems to match the return codes of the help file, function _GDIPlus_GraphicsGetSmoothingMode()

Switch $aCall[2]
    Case $GDIP_SMOOTHINGMODE_NONE
        Return 0
    Case $GDIP_SMOOTHINGMODE_HIGHQUALITY, $GDIP_SMOOTHINGMODE_ANTIALIAS8X4
        Return 1
    Case $GDIP_SMOOTHINGMODE_ANTIALIAS8X8
        Return 2
    Case Else
        Return 0
EndSwitch

My guess is that the return values from _GDIPlus_GraphicsGetSmoothingMode() have unfortunately been copied to the parameter $iSmooth in _GDIPlus_GraphicsSetSmoothingMode() : this created the confusion in _GDIPlus_GraphicsSetSmoothingMode()

Because there is no mapping in _GDIPlus_GraphicsSetSmoothingMode() , i.e. you can pass a value from 0 to 5 in _GDIPlus_GraphicsSetSmoothingMode() which is not indicated in the help file.

Edited June 11 by pixelsearch
typo

[jpm]

This behavior was introduced since the creation

That looks strange  to me no reference to $GDIP_SMOOTHINGMODE_HIGHSPEED

Not sure if it will introduce a regression, but for me the best is to return the real mode

[pixelsearch]

45 minutes ago, jpm said:

I don't understand why the example display 1 as 2 is set

Any idea

Jean-Paul, my preceding post should explain it, because of the mapping in _GDIPlus_GraphicsGetSmoothingMode()
If you add a line in the function, before Switch $aCall[2], add this :

ConsoleWrite($aCall[2] & @crlf)

Then you'll notice that the example will indicate

$aCall[2] = 3 ; $GDIP_SMOOTHINGMODE_NONE
$aCall[2] = 4 ; $GDIP_SMOOTHINGMODE_ANTIALIAS8X4

So when you set 0, the get returns 3 (ok with msdn : SmoothingModeNone) mapped to 0
when you set 2, the get returns 4 (ok with msdn : SmoothingModeAntiAlias) mapped to 1

@ioa747 it would be great if you try the example and set 5 (can't do it on my computer), I wonder if $aCall[2] would return 5, because the mapping in _GDIPlus_GraphicsGetSmoothingMode() accepts a return of 5 ($GDIP_SMOOTHINGMODE_ANTIALIAS8X8) but msdn doesn't indicate a return of 5 (msdn indicates two returns only : 3 & 4)

 

[jpm]

Do You agree to change the doc for _GDIPlus_GraphicsSetSmoothingMode()?

        $GDIP_SMOOTHINGMODE_DEFAULT  (0) - Smoothing is not applied.
        $GDIP_SMOOTHINGMODE_HIGHSPEED (1) - Smoothing is applied using an 8 X 4 box filter, no anti-aliasing applied.
        $GDIP_SMOOTHINGMODE_HIGHQUALITY (2) - Smoothing is applied using general high quality, not specifically an 8x4 filter.
        $GDIP_SMOOTHINGMODE_NONE (3) - Specifies that no smoothing Aliasing is applied.
        $GDIP_SMOOTHINGMODE_ANTIALIAS8X4 (4) ; Specifies that smoothing is applied using an 8 X 4 box filter (alias $GDIP_SMOOTHINGMODE_ANTIALIAS).
        $GDIP_SMOOTHINGMODE_ANTIALIAS8X8 (5 ); Specifies that smoothing is applied using an 8 X 8 box filter.
 

[jpm]

_GDIPlus_PenSetColor() return GDIP_SMOOTHINGMODE_ANTIALIAS8X8

[pixelsearch]

20 minutes ago, jpm said:

Do You agree to change the doc for _GDIPlus_GraphicsSetSmoothingMode()?

Yes Jean-Paul, it looks great.
But if you don't mind, I would like you to test and Set 5 in the example : $GDIP_SMOOTHINGMODE_ANTIALIAS8X8 (5)
Then please check what is the return in the function _GDIPlus_GraphicsGetGmoothingMode
, by adding 1 line before the mapping :

ConsoleWrite($aCall[2] & @crlf) ; <========== add this line

Switch $aCall[2]
    Case $GDIP_SMOOTHINGMODE_NONE
        Return 0
    Case $GDIP_SMOOTHINGMODE_HIGHQUALITY, $GDIP_SMOOTHINGMODE_ANTIALIAS8X4
        Return 1
    Case $GDIP_SMOOTHINGMODE_ANTIALIAS8X8
        Return 2
    Case Else
        Return 0
EndSwitch

What will show $aCall[2] in this specific case ?

 

Edited June 11 by pixelsearch

[jpm]

did you check _GDIPlus_PenSetColor() example?

[ioa747]

28 minutes ago, pixelsearch said:

it would be great if you try the example and set 5

with

Func _GDIPlus_GraphicsGetSmoothingMode($hGraphics)
    Local $aCall = DllCall($__g_hGDIPDll, "int", "GdipGetSmoothingMode", "handle", $hGraphics, "int*", 0)
    If @error Then Return SetError(@error, @extended, -1)
    If $aCall[0] Then Return SetError(10, $aCall[0], -1)

    ConsoleWrite("> GDIPlus :: $aCall[2]=" & $aCall[2] & @CRLF) ; 🚧

    Switch $aCall[2]
        Case $GDIP_SMOOTHINGMODE_NONE
            Return 0
        Case $GDIP_SMOOTHINGMODE_HIGHQUALITY, $GDIP_SMOOTHINGMODE_ANTIALIAS8X4
            Return 1
        Case $GDIP_SMOOTHINGMODE_ANTIALIAS8X8
            Return 2
        Case Else
            Return 0
    EndSwitch
EndFunc   ;==>_GDIPlus_GraphicsGetSmoothingMode

 

 

expandcollapse popup

#include <GDIPlus.au3>
#include <GUIConstantsEx.au3>
#include <MsgBoxConstants.au3>

Example()

Func Example()
    Local $hGUI = GUICreate("GDI+ test", 640, 480)
    GUISetState(@SW_SHOW)

    _GDIPlus_Startup()
    Local $hGraphics = _GDIPlus_GraphicsCreateFromHWND($hGUI)
    Local $hPen = _GDIPlus_PenCreate()
    _GDIPlus_GraphicsDrawLine($hGraphics, 40, 40, 600, 440, $hPen) ;draw a test line to show smoothing effect (default no smoothing)
    ConsoleWrite("Smoothing0 enabled: " & _GDIPlus_GraphicsGetSmoothingMode($hGraphics) & @CRLF)


    _GDIPlus_GraphicsSetSmoothingMode($hGraphics, 1) 
    _GDIPlus_GraphicsDrawLine($hGraphics, 600, 40, 40, 440, $hPen) ;draw a test line to show smoothing effect
    ConsoleWrite("Smoothing1 enabled: " & _GDIPlus_GraphicsGetSmoothingMode($hGraphics) & @CRLF)

    _GDIPlus_GraphicsSetSmoothingMode($hGraphics, 2) 
    _GDIPlus_GraphicsDrawLine($hGraphics, 580, 40, 40, 420, $hPen) ;draw a test line to show smoothing effect
    ConsoleWrite("Smoothing2 enabled: " & _GDIPlus_GraphicsGetSmoothingMode($hGraphics) & @CRLF)

    _GDIPlus_GraphicsSetSmoothingMode($hGraphics, 3) 
    _GDIPlus_GraphicsDrawLine($hGraphics, 20, 40, 600, 420, $hPen) ;draw a test line to show smoothing effect
    ConsoleWrite("Smoothing3 enabled: " & _GDIPlus_GraphicsGetSmoothingMode($hGraphics) & @CRLF)

    _GDIPlus_GraphicsSetSmoothingMode($hGraphics, 4) 
    _GDIPlus_GraphicsDrawLine($hGraphics, 560, 40, 40, 400, $hPen) ;draw a test line to show smoothing effect
    ConsoleWrite("Smoothing4 enabled: " & _GDIPlus_GraphicsGetSmoothingMode($hGraphics) & @CRLF)

    _GDIPlus_GraphicsSetSmoothingMode($hGraphics, 5) 
    _GDIPlus_GraphicsDrawLine($hGraphics, 540, 40, 40, 380, $hPen) ;draw a test line to show smoothing effect
    ConsoleWrite("Smoothing5 enabled: " & _GDIPlus_GraphicsGetSmoothingMode($hGraphics) & @CRLF)


    While 1
        Switch GUIGetMsg()
            Case $GUI_EVENT_CLOSE
                ExitLoop
        EndSwitch
    WEnd

    ;cleanup resources
    _GDIPlus_PenDispose($hPen)
    _GDIPlus_GraphicsDispose($hGraphics)
    _GDIPlus_Shutdown()
    GUIDelete($hGUI)
EndFunc   ;==>Example

 

> GDIPlus :: $aCall[2]=3
Smoothing0 enabled: 0
> GDIPlus :: $aCall[2]=3
Smoothing1 enabled: 0
> GDIPlus :: $aCall[2]=4
Smoothing2 enabled: 1
> GDIPlus :: $aCall[2]=3
Smoothing3 enabled: 0
> GDIPlus :: $aCall[2]=4
Smoothing4 enabled: 1
> GDIPlus :: $aCall[2]=5
Smoothing5 enabled: 2
>

 

[ioa747]

4 minutes ago, jpm said:

did you check _GDIPlus_PenSetColor() example?

with "C:\Program Files (x86)\AutoIt3\Examples\Helpfile\_GDIPlus_PenSetColor.au3"

> GDIPlus :: $aCall[2]=3
> GDIPlus :: $aCall[2]=4
> GDIPlus :: $aCall[2]=5

 

[pixelsearch]

Can't test it on my computer as I don't have access to $GDIP_SMOOTHINGMODE_ANTIALIAS8X8 (5)
If @OSBuild > 5999 Then ... won't let me access it

No big deal Jean-Paul.
The fact that you and ioa747 got a return of 5 indicate that the mapping is done correctly :

Switch $aCall[2]
        Case $GDIP_SMOOTHINGMODE_NONE
            Return 0
        Case $GDIP_SMOOTHINGMODE_HIGHQUALITY, $GDIP_SMOOTHINGMODE_ANTIALIAS8X4
            Return 1
        Case $GDIP_SMOOTHINGMODE_ANTIALIAS8X8 ; <====== triggered when Set was 5 (tested by ioa747 & jpm)
            Return 2
        Case Else
            Return 0
EndSwitch

 

[pixelsearch]

...which means the msdn link indicates insufficient return values :

Return value
Type: SmoothingMode
If smoothing (antialiasing) is applied to this Graphics object, this method returns SmoothingModeAntiAlias (4)
If smoothing (antialiasing) is not applied to this Graphics object, this method returns SmoothingModeNone (3)

msdn omits a 3rd possible return value : SmoothingModeAntiAlias8x8  (5)

Edit: or maybe when they refer to "SmoothingModeAntiAlias", they include 4 & 5 return values

Edited June 11 by pixelsearch

[ioa747]

What did I conclude?

To add more clarity, the confusion in the documentation stems from the fact that the GDI+ API evolved in two distinct phases

Phase 1 (The Legacy Era):
The original constants were mapped to the basic QualityMode enum:

0 (Default)

1 (HighSpeed)   => which now calls the 3

2 (HighQuality) => which now calls the 4

Phase 2 (The GDIPVER >= 0x0110 Era):
When the API was updated to support more specific algorithms,
they introduced new constants that were actually just different ways to request the same or improved filters:

3 (None - explicitly added for clarity)

4 (AntiAlias8x4)

5 (AntiAlias8x8)

The 'Collision':
The Help File's error is that it tries to describe the modern API (4 & 5) using the legacy integer mappings (1 & 2).

If we explain in the docs that 1 and 2 are legacy high-level modes,
while 4 and 5 are the specific algorithmic implementations introduced in the 0x0110 update,
developers will finally understand why there are multiple ways to achieve similar visual results.

[pixelsearch]

and now it's time for lunch, with 2 hours late, see you ioa747 & jpm, it was an interesting exchange !

[jpm]

@ioa747 is this correct for _GDIPlus_GraphicsSetSmoothingMode()

        $GDIP_SMOOTHINGMODE_DEFAULT  (0) - Smoothing is not applied.
        $GDIP_SMOOTHINGMODE_HIGHSPEED (1) - Smoothing is not applied.
        $GDIP_SMOOTHINGMODE_HIGHQUALITY (2) - Smoothing is applied using an 8 X 4 box filter (no antialiasing).
        $GDIP_SMOOTHINGMODE_NONE (3) - Smoothing is not applied.
        $GDIP_SMOOTHINGMODE_ANTIALIAS8X4 (4) - Smoothing is applied using an 8 X 4 box filter (alias $GDIP_SMOOTHINGMODE_ANTIALIAS).
        $GDIP_SMOOTHINGMODE_ANTIALIAS8X8 (5 ) - Smoothing is applied using an 8 X 8 box filter.
 

[ioa747]

Yes, this mapping is correct.
It accurately reflects the constants in GDIPlusConstants.au3 and clarifies the legacy vs. modern modes.

small suggestions to make it perfect:

For $GDIP_SMOOTHINGMODE_HIGHQUALITY (2): Maybe add a note: "Maps to the High Quality preset, which utilizes an 8x4 box filter."
This clarifies that it is a preset rather than a raw filter setting.
Please remove the "(no antialiasing)" part. Since it is a 'High Quality' preset that often utilizes box filters for smoothing, stating it has 'no antialiasing' is contradictory and could confuse developers.

For the Legacy Modes (0, 1, 3): Since they all result in "Smoothing not applied", grouping them or clearly stating that they are functionally identical for the end-user will save developers a lot of time.

Edited June 11 by ioa747

[pixelsearch]

Maybe you'll be interested by some explanations found in the Remarks section of the SmoothingMode enumeration on msdn :

Remarks

Smoothing performed by an 8 X 4 box filter gives better results for nearly vertical lines than it does for nearly horizontal lines.
Smoothing performed by an 8 X 8 box filter gives equally good results for nearly vertical and nearly horizontal lines.
The 8x8 algorithm produces higher quality smoothing but is slower than the 8 X 4 algorithm.