_DONTBLEND wiki statement

[SMcNeill]

The command in question: https://www.qb64.org/wiki/DONTBLEND

And the statement in question: Use CLS or _DONTBLEND to make a new surface background _ALPHA 255 or opaque.

And my enquiry:  How do we use _DONTBLEND  to make a new surface background _ALPHA 255??

From my experience, _DONTBLEND doesn't change alpha levels at all.  All it does is let us set a color to exactly what we specify it to be, without blending it into the existing background.

A little test code to showcase the difference in _DONTBLEND and CLS, in regards to opaque backgrounds:

Code: QB64: [Select]

1. SCREEN _NEWIMAGE(640, 480, 32)
2. _DONTBLEND
3. PRINT HEX$(POINT(0, 0))
4. SLEEP
5. CLS
6. PRINT HEX$(POINT(0, 0))

DONTBLEND never changed the background alpha levels, whereas CLS does.  Is this a case where the wiki is giving us a wrong bit of information, or am I using the command wrong, or just interpreting something wrong?  Exactly how does it "make a new surface background _ALPHA 255 or opaque"?

[SMcNeill]

Question 2: WTH is up with the sample code provided?

Code: QB64: [Select]

1. SCREEN _NEWIMAGE(1280, 720, 32)
2. 'CLS
3. _DONTBLEND '<<< comment out to see the difference
4.  
5. LINE (100, 100)-(500, 500), _RGB32(255, 255, 0), BF
6.  
7. b& = SaveBackground&
8.  
9. PRINT "This is just test junk"
10. PRINT
11. PRINT "Hit any key and the text should disappear, leaving us our pretty yellow box."
12. SLEEP
13. RestoreBackground b&
14.  
15. END
16.  
17. FUNCTION SaveBackground&
18. SaveBackground& = _COPYIMAGE(0)
19. END FUNCTION
20.  
21. SUB RestoreBackground (Image AS LONG)
22. _PUTIMAGE (200, 200), Image, 0
23. END SUB

Exactly what the heck is this supposed to be doing? 

"Hit any key and the text should disappear, leaving us our pretty yellow box."...

...Except the text doesn't go anywhere..

I'm completely lost by this wiki entry! 

[SMcNeill]

I think this is what the wiki code is trying to demonstrate:

Code: QB64: [Select]

1. SCREEN _NEWIMAGE(1280, 720, 32)
2. 'CLS
3. _DONTBLEND '<<< comment out to see the difference
4.  
5. LINE (100, 100)-(500, 500), _RGB32(255, 255, 0), BF
6.  
7. b& = SaveBackground&
8.  
9.  
10.  
11.  
12. PRINT "This is just test junk"
13. PRINT
14. PRINT "Hit any key and the text should disappear, leaving us our pretty yellow box."
15. SLEEP
16. RestoreBackground b&
17.  
18. END
19.  
20. FUNCTION SaveBackground&
21.     SaveBackground& = _COPYIMAGE(0)
22. END FUNCTION
23.  
24. SUB RestoreBackground (Image AS LONG)
25.     _PUTIMAGE , Image, 0
26. END SUB

At first glance, it appears as if the demo is doing as the original premise states -- it's making the new image opaque, but it's not true.  A quick little change can highlight this fact, indisputably:

Code: QB64: [Select]

1. SCREEN _NEWIMAGE(1280, 720, 32)
2. 'CLS
3. _DONTBLEND '<<< comment out to see the difference
4.  
5. LINE (100, 100)-(500, 500), _RGB32(255, 255, 0), BF
6.  
7. b& = SaveBackground&
8. _SOURCE b&
9. PRINT HEX$(POINT(0, 0))
10.  
11.  
12.  
13.  
14. PRINT "This is just test junk"
15. PRINT
16. PRINT "Hit any key and the text should disappear, leaving us our pretty yellow box."
17. SLEEP
18. RestoreBackground b&
19.  
20. END
21.  
22. FUNCTION SaveBackground&
23.     SaveBackground& = _COPYIMAGE(0)
24. END FUNCTION
25.  
26. SUB RestoreBackground (Image AS LONG)
27.     _PUTIMAGE , Image, 0
28. END SUB

Notice where I have it print the hex value of point (0,0)?  It's NOT FF000000; instead, it's just 0.  No red, no blue, no green, no alpha...  It's still completely transparent!


So why are we seeing the difference in results that we're getting??

Because we have _DONTBLEND set and that pure transparent color is simply overwriting the white of the text.  With blend on, we blend transparent and white, get white, and the text remains...

_DONTBLEND didn't make the new screen opaque, or set it to have 255 alpha.  It simply changed our main screen so we didn't blend the transparent color out with the existing color...

Here's a perfect example to prove that: 

Code: QB64: [Select]

1. SCREEN _NEWIMAGE(1280, 720, 32)
2. 'CLS
3. _DONTBLEND '<<< comment out to see the difference
4.  
5. LINE (100, 100)-(500, 500), _RGB32(255, 255, 0), BF
6.  
7. b& = SaveBackground&
8.  
9.  
10. PRINT "This is just test junk"
11. PRINT
12. PRINT "Hit any key and the text should disappear, leaving us our pretty yellow box."
13. SLEEP
14.  
15. _BLEND b& 'set the copied image attribute to blend
16. _BLEND 0 'set the current page attribute to blend
17. RestoreBackground b&
18.  
19. END
20.  
21. FUNCTION SaveBackground&
22.     SaveBackground& = _COPYIMAGE(0)
23. END FUNCTION
24.  
25. SUB RestoreBackground (Image AS LONG)
26.     _PUTIMAGE , Image, 0
27. END SUB

If _dontblend had actually changed the background to having 255 alpha, we couldn't just turn blending back on and have it perform with 0 alpha levels as we're seeing.

Unless someone knows something about this command that I don't, I'm inclined to say the wiki is completely off here with what it's documenting for us. 

Or am I just missing something obvious here?

[SMcNeill]

Here's what I'd suggest changing in the entry:

• If imageHandle& is not valid, an Invalid handle error will occur.
• _DONTBLEND is faster than the default _BLEND. You may want to disable it, unless you really need to use it in 32 bit.
• 32 bit screen surface backgrounds (black) have zero _ALPHA so that they are transparent when placed over other surfaces.
• Use CLS or _DONTBLEND to make a new surface background _ALPHA 255 or opaque.
• Both _SOURCE and _DEST must have _BLEND enabled, or else colors will NOT blend.

And the examples would probably need to be rewritten so they reflect the actual behavior of the command for us.  ;)

[FellippeHeitor]

Are you editing it?