Difference between revisions of "ALPHA"

From QB64 Wiki
Jump to navigation Jump to search
imported>Clippy
m
imported>Odin
m (4 revisions imported)
 
(15 intermediate revisions by 4 users not shown)
Line 1: Line 1:
The {{KW|_ALPHA}} function returns the alpha channel transparency level of a color value used on a screen page or image.
+
{{DISPLAYTITLE:_ALPHA}}
 +
The [[_ALPHA]] function returns the alpha channel transparency level of a color value used on a screen page or image.
  
  
 
{{PageSyntax}}
 
{{PageSyntax}}
:{{Parameter|result&}} = {{KW|_ALPHA}}({{Parameter|colour&}} [, {{Parameter|imageHandle&}}])
+
:{{Parameter|result&}} = [[_ALPHA]]({{Parameter|color~&}} [, {{Parameter|imageHandle&}}])
  
  
 
{{PageDescription}}
 
{{PageDescription}}
* If {{Parameter|imageHandle&}} is omitted, it is assumed to be the current write page.
+
* If {{Parameter|imageHandle&}} is omitted, it is assumed to be the current write page. Invalid handles will create [[ERROR Codes|Illegal function call]] errors.
* If the image specified by {{Parameter|imageHandle&}} uses a palette, {{Parameter|colour&}} is the palette index of the color value used.
+
* [[_NEWIMAGE]] 32 bit [[SCREEN]] modes will always use an [[_UNSIGNED]] [[LONG]] ''color~&'' value.
** Color values that match the clear color set by [[_CLEARCOLOR]] have an alpha level of 0 (zero).
+
** Color values that are set as a [[_CLEARCOLOR]] always have an alpha level of 0 (transparent).
** Color values that don't match the clear color have an alpha level of 255.
+
** [[_SETALPHA]] can set any alpha level from 0 (or fully transparent) to 255 (or opaque).
** If {{Parameter|colour&}} value is outside of the range 0 to 255, an [[ERROR Codes|Illegal function call]] error will occur.
+
** Normal color values that are set by [[_RGB]] or [[_RGB32]] always have an alpha level of 255(opaque).
* If the image specified by {{Parameter|imageHandle&}} does not use a palette, {{Parameter|colour&}} is the color value used to retrieve the alpha level.
+
* In 4 (16 color) or 8 (256 color) bit palette screens the function will always return 255.
* If {{Parameter|imageHandle&}} is an invalid handle, an [[ERROR Codes|Illegal function call]] error will occur.
+
*[[_RED32]], [[_GREEN32]], [[_BLUE32]] and [[_ALPHA32]] are all equivalent to [[_RED]], [[_GREEN]], [[_BLUE]] and [[_ALPHA]] but they are highly optimized and only accept a 32-bit color (B8:G8:R8:A8). Using them (opposed to dividing then ANDing 32-bit color values manually) makes code easy to read.
*[[_RED32]], [[_GREEN32]], [[_BLUE32]] and [[_ALPHA32]] are all equivalent to [[_RED]], [[_GREEN]], [[_BLUE]] and [[_ALPHA]] but they are highly optimized and only accept a 32-bit color (B8:G8:R8:A8). Using these in your code (opposed to dividing then ANDing 32-bit color values manually) makes your code easy to read also.
+
* '''NOTE: 32 bit [[_NEWIMAGE]] screen page backgrounds are transparent black or [[_ALPHA]] 0. Use [[_DONTBLEND]] or [[CLS]] for opaque.'''
* '''NOTE: Default 32 bit backgrounds are clear black or [[_RGBA]](0, 0, 0, 0)! Use [[CLS]] to make the black opaque!'''
 
  
  
''Example:'' Finding the transparency of a 32 bit screen mode's background.
+
{{PageExamples}}
 +
''Example 1:'' Alpha transparency levels are always 255 in 4 or 8 bit screen modes.
 +
{{CodeStart}} '' ''
 +
{{Cl|SCREEN}} 13
 +
 
 +
clr~& = {{Cl|_RGBA}}(255, 0, 255, 192) 'returns closest palette color attribute
 +
{{Cl|PRINT}} "Color:"; clr~&
 +
 
 +
{{Cl|COLOR}} clr~&
 +
{{Cl|PRINT}} "Alpha:"; {{Cl|_ALPHA}}(clr~&)
 +
 
 +
{{Cl|END}}
 +
{{CodeEnd}}
 +
{{OutputStart}}{{text|Color 36|#FFFFFF}}
 +
{{text|Alpha: 255|#FF00FF}}
 +
{{OutputEnd}}
 +
: ''Explanation:'' [[_RGBA]] cannot change the [[_ALPHA]] level. [[_ALPHA32]] would return 0 on any non-32 bit image or page.
 +
 
 +
 
 +
''Example 2:'' Finding the transparency of a 32 bit screen mode's background before and after [[CLS]].
 
{{CodeStart}} '' ''
 
{{CodeStart}} '' ''
 
{{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(640, 480, 32)
 
{{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(640, 480, 32)
x = {{Cl|POINT}}(1, 1)
+
BG& = {{Cl|POINT}}(1, 1)
{{Cl|PRINT}} "Alpha ="; {{Cl|_ALPHA}}(x); "Press a key to use CLS!"
+
{{Cl|PRINT}} "Alpha ="; {{Cl|_ALPHA}}(BG&); "Press a key to use CLS!"
 
K$ = INPUT$(1)                   
 
K$ = INPUT$(1)                   
 
{{Cl|CLS}}
 
{{Cl|CLS}}
x = {{Cl|POINT}}(1, 1)
+
BG& = {{Cl|POINT}}(1, 1)
{{Cl|PRINT}} "CLS Alpha ="; {{Cl|_ALPHA}}(x) '' ''
+
{{Cl|PRINT}} "CLS Alpha ="; {{Cl|_ALPHA}}(BG&) '' ''
 
{{CodeEnd}}
 
{{CodeEnd}}
: ''Explanation:'' You need to set the ALPHA value to 255 using [[CLS]] to make the black background opaque!
+
{{OutputStart}}CLS Alpha = 255  {{OutputEnd}}
 +
: ''Explanation:'' Set the ALPHA value to 255 using [[CLS]] to make the background opaque when overlaying pages.
  
  
 
{{PageSeeAlso}}
 
{{PageSeeAlso}}
 
* [[_ALPHA32]], [[_SETALPHA]]
 
* [[_ALPHA32]], [[_SETALPHA]]
 +
* [[_RGBA]], [[_RGBA32]] {{text|(set color with alpha)}}
 +
* [[_CLEARCOLOR]], [[_CLEARCOLOR (function)]]
 
* [[_RED]], [[_GREEN]], [[_BLUE]]
 
* [[_RED]], [[_GREEN]], [[_BLUE]]
 
* [[_RED32]], [[_GREEN32]]. [[_BLUE32]]
 
* [[_RED32]], [[_GREEN32]]. [[_BLUE32]]
* [[_CLEARCOLOR]], [[_CLEARCOLOR (function)]]
 
 
* [[CLS]], [[COLOR]], [[Images]]
 
* [[CLS]], [[COLOR]], [[Images]]
  
  
 
{{PageNavigation}}
 
{{PageNavigation}}

Latest revision as of 03:16, 1 November 2017

The _ALPHA function returns the alpha channel transparency level of a color value used on a screen page or image.


Syntax

result& = _ALPHA(color~& [, imageHandle&])


Description

  • If imageHandle& is omitted, it is assumed to be the current write page. Invalid handles will create Illegal function call errors.
  • _NEWIMAGE 32 bit SCREEN modes will always use an _UNSIGNED LONG color~& value.
    • Color values that are set as a _CLEARCOLOR always have an alpha level of 0 (transparent).
    • _SETALPHA can set any alpha level from 0 (or fully transparent) to 255 (or opaque).
    • Normal color values that are set by _RGB or _RGB32 always have an alpha level of 255(opaque).
  • In 4 (16 color) or 8 (256 color) bit palette screens the function will always return 255.
  • _RED32, _GREEN32, _BLUE32 and _ALPHA32 are all equivalent to _RED, _GREEN, _BLUE and _ALPHA but they are highly optimized and only accept a 32-bit color (B8:G8:R8:A8). Using them (opposed to dividing then ANDing 32-bit color values manually) makes code easy to read.
  • NOTE: 32 bit _NEWIMAGE screen page backgrounds are transparent black or _ALPHA 0. Use _DONTBLEND or CLS for opaque.


Examples

Example 1: Alpha transparency levels are always 255 in 4 or 8 bit screen modes.

SCREEN 13 clr~& = _RGBA(255, 0, 255, 192) 'returns closest palette color attribute PRINT "Color:"; clr~& COLOR clr~& PRINT "Alpha:"; _ALPHA(clr~&) END

Color 36 Alpha: 255

Explanation: _RGBA cannot change the _ALPHA level. _ALPHA32 would return 0 on any non-32 bit image or page.


Example 2: Finding the transparency of a 32 bit screen mode's background before and after CLS.

SCREEN _NEWIMAGE(640, 480, 32) BG& = POINT(1, 1) PRINT "Alpha ="; _ALPHA(BG&); "Press a key to use CLS!" K$ = INPUT$(1) CLS BG& = POINT(1, 1) PRINT "CLS Alpha ="; _ALPHA(BG&)

CLS Alpha = 255

Explanation: Set the ALPHA value to 255 using CLS to make the background opaque when overlaying pages.


See also



Navigation:
Keyword Reference - Alphabetical
Keyword Reference - By Usage
Main Wiki Page