fix(renderer): separate alpha buffer and clear-color alpha concepts since they are different

- Removed unnecessary alpha-related properties from the `gl` configuration in multiple components to simplify the renderer setup.
- Introduced `clearAlpha` property to control the opacity of the clear color, enhancing flexibility for transparency settings.
- Updated documentation for `TresCanvas` and related components to clarify the new alpha handling and its implications for rendering.
- Improved type definitions to reflect the changes in the alpha configuration, ensuring better TypeScript support.

docs/.vitepress/theme/components/DonutExample.vue

@@ -2,15 +2,9 @@
 import { OrbitControls } from '@tresjs/cientos'
 import { TresCanvas } from '@tresjs/core'
 
-import { BasicShadowMap, NoToneMapping, SRGBColorSpace } from 'three'
-
 const gl = {
   clearColor: '#82DBC5',
   shadows: true,
-  alpha: false,
-  shadowMapType: BasicShadowMap,
-  outputColorSpace: SRGBColorSpace,
-  toneMapping: NoToneMapping,
 }
 </script>
 

docs/.vitepress/theme/components/FirstScene.vue

@@ -1,16 +1,10 @@
 <script setup lang="ts">
 import { OrbitControls } from '@tresjs/cientos'
-
 import { TresCanvas } from '@tresjs/core'
-import { BasicShadowMap, NoToneMapping, SRGBColorSpace } from 'three'
 
 const gl = {
   clearColor: '#82DBC5',
   shadows: true,
-  alpha: false,
-  shadowMapType: BasicShadowMap,
-  outputColorSpace: SRGBColorSpace,
-  toneMapping: NoToneMapping,
 }
 </script>
 

docs/api/tres-canvas.md

@@ -46,7 +46,7 @@ These props are passed to the WebGLRenderer constructor and cannot be changed af
 
 | Prop | Description | Default |
 | ---- | ---- | --- |
-| **alpha** | Controls the default clear alpha value. When set to true, the value is 0. Otherwise it's 1. | `false` |
+| **alpha** | Whether to create the WebGL context with an alpha buffer. This is a WebGL context option that must be set during context creation and cannot be changed later. When true, the canvas can be transparent, showing content behind it. | `false` |
 | **antialias** | Whether to perform antialiasing. | `true` |
 | **depth** | Whether the drawing buffer has a [depth buffer](https://en.wikipedia.org/wiki/Z-buffering) of at least 16 bits. | `true` |
 | **failIfMajorPerformanceCaveat** | Whether the renderer creation will fail upon low performance is detected. See [WebGL spec](https://registry.khronos.org/webgl/specs/latest/1.0/#5.2) for details. | `false` |
@@ -62,7 +62,8 @@ These props can be modified after renderer creation using the renderer's setter
 
 | Prop | Description | Default |
 | ---- | ---- | --- |
-| **clearColor** | The color the renderer will use to clear the canvas. | `#000000` |
+| **clearColor** | The color the renderer will use to clear the canvas. Can include alpha value (e.g. '#00808000' for fully transparent teal). | `#000000` |
+| **clearAlpha** | The opacity of the clear color (0-1). Controls the transparency of the clear color. | `1` |
 | **outputColorSpace** | Defines the output encoding | `LinearEncoding` |
 | **shadows** | Enable shadows in the renderer | `false` |
 | **shadowMapType** | Set the shadow map type | `PCFSoftShadowMap` |
@@ -165,7 +166,6 @@ The `createWebGPURenderer` will return the context so you have access to the can
 const createWebGPURenderer = async (ctx) => {
   const renderer = new WebGPURenderer({
     canvas: ctx.canvas.value,
-
   })
   await renderer.init()
 

playground/vue/src/pages/advanced/Memory.vue

@@ -1,17 +1,11 @@
 <script setup lang="ts">
 import { TresCanvas } from '@tresjs/core'
 import { TresLeches, useControls } from '@tresjs/leches'
-
-import { BasicShadowMap, NoToneMapping, SRGBColorSpace } from 'three'
 import '@tresjs/leches/styles'
 
 const gl = {
   clearColor: '#fff',
   shadows: true,
-  alpha: false,
-  shadowMapType: BasicShadowMap,
-  outputColorSpace: SRGBColorSpace,
-  toneMapping: NoToneMapping,
 }
 
 const { isVisible } = useControls({

playground/vue/src/pages/advanced/fbo/index.vue

@@ -1,17 +1,12 @@
 <script setup lang="ts">
 import { OrbitControls } from '@tresjs/cientos'
 import { TresCanvas } from '@tresjs/core'
-import { BasicShadowMap, NoToneMapping, SRGBColorSpace } from 'three'
 import FBOCube from './FBOCube.vue'
 import '@tresjs/leches/styles'
 
 const gl = {
   clearColor: '#82DBC5',
   shadows: true,
-  alpha: false,
-  shadowMapType: BasicShadowMap,
-  outputColorSpace: SRGBColorSpace,
-  toneMapping: NoToneMapping,
 }
 </script>
 

playground/vue/src/pages/advanced/manual/index.vue

@@ -21,9 +21,15 @@ useControls({
   },
 })
 
-const { clearColor, alpha, antialias, toneMapping, shadows, shadowMapType } = useControls({
+const { clearColor, clearAlpha, antialias, toneMapping, shadows, shadowMapType } = useControls({
   clearColor: '#82DBC5',
-  alpha: true,
+  clearAlpha: {
+    value: 1,
+    min: 0,
+    max: 1,
+    step: 0.01,
+    label: 'Clear Alpha',
+  },
   toneMapping: {
     value: ACESFilmicToneMapping,
     options: [
@@ -64,7 +70,7 @@ const formattedShadowMapType = computed(() => {
     :shadows="shadows"
     :shadow-map-type="formattedShadowMapType"
     :clear-color="clearColor"
-    :alpha="alpha"
+    :clear-alpha="clearAlpha"
     :antialias="antialias"
     :tone-mapping="formattedToneMapping"
     @render="onRender"

playground/vue/src/pages/advanced/on-demand/index.vue

@@ -21,9 +21,15 @@ useControls({
   },
 })
 
-const { clearColor, alpha, antialias, toneMapping, shadows, shadowMapType } = useControls({
+const { clearColor, clearAlpha, antialias, toneMapping, shadows, shadowMapType } = useControls({
   clearColor: '#82DBC5',
-  alpha: true,
+  clearAlpha: {
+    value: 1,
+    min: 0,
+    max: 1,
+    step: 0.01,
+    label: 'Clear Alpha',
+  },
   toneMapping: {
     value: ACESFilmicToneMapping,
     options: [
@@ -64,7 +70,7 @@ const formattedShadowMapType = computed(() => {
     :shadows="shadows"
     :shadow-map-type="formattedShadowMapType"
     :clear-color="clearColor"
-    :alpha="alpha"
+    :clear-alpha="clearAlpha"
     :antialias="antialias"
     :tone-mapping="formattedToneMapping"
     @render="onRender"

playground/vue/src/pages/basic/Conditional.vue

@@ -2,17 +2,13 @@
 import { OrbitControls } from '@tresjs/cientos'
 import { TresCanvas } from '@tresjs/core'
 import { TresLeches, useControls } from '@tresjs/leches'
-import { BasicShadowMap, MeshPhongMaterial, NoToneMapping, SRGBColorSpace } from 'three'
+import { MeshPhongMaterial } from 'three'
 import { reactive } from 'vue'
 import '@tresjs/leches/styles'
 
 const state = reactive({
   clearColor: '#201919',
   shadows: true,
-  alpha: false,
-  shadowMapType: BasicShadowMap,
-  outputColorSpace: SRGBColorSpace,
-  toneMapping: NoToneMapping,
 })
 
 const paneElements = reactive({

playground/vue/src/pages/basic/Primitives.vue

@@ -20,10 +20,6 @@ import '@tresjs/leches/styles'
 const gl = {
   clearColor: '#82DBC5',
   shadows: true,
-  alpha: false,
-  shadowMapType: BasicShadowMap,
-  outputColorSpace: SRGBColorSpace,
-  toneMapping: NoToneMapping,
 }
 const canvas = ref()
 const meshRef = ref()

playground/vue/src/pages/basic/index.vue

@@ -5,9 +5,15 @@ import { TresLeches, useControls } from '@tresjs/leches'
 import { OrbitControls } from '@tresjs/cientos'
 import '@tresjs/leches/styles'
 
-const { clearColor, alpha, antialias, toneMapping, shadows, shadowMapType } = useControls({
+const { clearColor, clearAlpha, alpha, toneMapping, shadows, shadowMapType } = useControls({
   clearColor: '#82DBC5',
-  alpha: true,
+  clearAlpha: {
+    value: 1,
+    min: 0,
+    max: 1,
+    step: 0.01,
+    label: 'Clear Alpha',
+  },
   toneMapping: {
     value: ACESFilmicToneMapping,
     options: [
@@ -56,8 +62,7 @@ watch(() => ctxRef.value?.context, (ctx) => {
     :shadows="shadows"
     :shadow-map-type="formattedShadowMapType"
     :clear-color="clearColor"
-    :alpha="alpha"
-    :antialias="antialias"
+    :clear-alpha="clearAlpha"
     :tone-mapping="formattedToneMapping"
   >
     <TresPerspectiveCamera :position="[5, 5, 5]" />

playground/vue/src/pages/cameras/index.vue

@@ -2,16 +2,12 @@
 import { Box } from '@tresjs/cientos'
 import { TresCanvas } from '@tresjs/core'
 import { TresLeches, useControls } from '@tresjs/leches'
-import { BasicShadowMap, NoToneMapping, OrthographicCamera, PerspectiveCamera, SRGBColorSpace } from 'three'
+import { OrthographicCamera, PerspectiveCamera } from 'three'
 import '@tresjs/leches/styles'
 
 const gl = {
   clearColor: '#82DBC5',
   shadows: true,
-  alpha: false,
-  shadowMapType: BasicShadowMap,
-  outputColorSpace: SRGBColorSpace,
-  toneMapping: NoToneMapping,
 }
 type Cam = (PerspectiveCamera | OrthographicCamera) & { manual?: boolean }
 

playground/vue/src/pages/events/index.vue

@@ -4,16 +4,11 @@ import type { ThreeEvent } from '@tresjs/core'
 import { OrbitControls, StatsGl } from '@tresjs/cientos'
 import { TresCanvas } from '@tresjs/core'
 import { TresLeches, useControls } from '@tresjs/leches'
-import { BasicShadowMap, NoToneMapping, SRGBColorSpace } from 'three'
 import '@tresjs/leches/styles'
 
 const gl = {
   clearColor: '#202020',
   shadows: true,
-  alpha: false,
-  shadowMapType: BasicShadowMap,
-  outputColorSpace: SRGBColorSpace,
-  toneMapping: NoToneMapping,
 }
 
 const { stopPropagation } = useControls({

playground/vue/src/pages/events/propagation/index.vue

@@ -3,7 +3,6 @@ import { OrbitControls } from '@tresjs/cientos'
 import {
   TresCanvas,
 } from '@tresjs/core'
-import { BasicShadowMap, NoToneMapping, SRGBColorSpace } from 'three'
 import { onUnmounted, ref } from 'vue'
 import Box from './Box.vue'
 import '@tresjs/leches/styles'
@@ -11,10 +10,6 @@ import '@tresjs/leches/styles'
 const gl = {
   clearColor: '#202020',
   shadows: true,
-  alpha: false,
-  shadowMapType: BasicShadowMap,
-  outputColorSpace: SRGBColorSpace,
-  toneMapping: NoToneMapping,
 }
 
 const showBox = ref(true)

playground/vue/src/pages/misc/directives/index.vue

@@ -1,16 +1,11 @@
 <script setup lang="ts">
 import { OrbitControls } from '@tresjs/cientos'
 import { TresCanvas } from '@tresjs/core'
-import { BasicShadowMap, NoToneMapping, SRGBColorSpace } from 'three'
 import DirectiveSubComponent from './DirectiveSubComponent.vue'
 
 const gl = {
   clearColor: '#82DBC5',
   shadows: true,
-  alpha: false,
-  shadowMapType: BasicShadowMap,
-  outputColorSpace: SRGBColorSpace,
-  toneMapping: NoToneMapping,
 }
 </script>
 

playground/vue/src/pages/misc/text3D/index.vue

@@ -2,7 +2,6 @@
 import { OrbitControls } from '@tresjs/cientos'
 import { TresCanvas } from '@tresjs/core'
 import { TresLeches, useControls } from '@tresjs/leches'
-import { BasicShadowMap, NoToneMapping, SRGBColorSpace } from 'three'
 import Text3D from './Text3D.vue'
 
 import '@tresjs/leches/styles'
@@ -10,10 +9,6 @@ import '@tresjs/leches/styles'
 const gl = {
   clearColor: '#82DBC5',
   shadows: true,
-  alpha: false,
-  shadowMapType: BasicShadowMap,
-  outputColorSpace: SRGBColorSpace,
-  toneMapping: NoToneMapping,
 }
 
 const { isVisible, text } = useControls({

playground/vue/src/pages/models/PrimitivesModel.vue

@@ -12,10 +12,6 @@ import '@tresjs/leches/styles'
 const gl = {
   clearColor: '#82DBC5',
   shadows: true,
-  alpha: false,
-  shadowMapType: BasicShadowMap,
-  outputColorSpace: SRGBColorSpace,
-  toneMapping: NoToneMapping,
 }
 
 useControls('fpsgraph')

src/components/TresCanvas.vue

@@ -273,6 +273,14 @@ export interface TresCanvasProps extends /* @vue-ignore */ WebGLRendererProps {
    * @default 'default'
    */
   powerPreference?: MaybeRefOrGetter<WebGLPowerPreference>
+  /**
+     * Whether to create the WebGL context with an alpha buffer.
+     * This is a WebGL context option that must be set during context creation and cannot be changed later.
+     * When true, the canvas can be transparent, showing content behind it.
+     * @readonly
+     * @default false
+     */
+  alpha?: MaybeRefOrGetter<boolean>
 
   /**
    * WebGL options with set methods
@@ -281,15 +289,17 @@ export interface TresCanvasProps extends /* @vue-ignore */ WebGLRendererProps {
 
   /**
    * Clear color for the canvas
-   *
+   * Can include alpha value (e.g. '#00808000' for fully transparent teal)
    */
   clearColor?: MaybeRefOrGetter<string>
 
   /**
-   * Whether to enable alpha blending
-   * @default false
+   * The opacity of the clear color (0-1)
+   * Controls the transparency of the clear color
+   * @default 1
    */
-  alpha?: MaybeRefOrGetter<boolean>
+  clearAlpha?: MaybeRefOrGetter<number>
+
   /**
    * Enable shadow rendering in the scene
    * @default false

src/core/setupRenderer.ts

@@ -45,13 +45,25 @@ const directProperties: Record<string, DirectProperty> = {
 }
 
 // Properties that use setter methods
-const rendererPropertyHandlers: Record<string, PropertyHandler<ColorRepresentation | boolean>> = {
+const rendererPropertyHandlers: Record<string, PropertyHandler<ColorRepresentation | boolean | number>> = {
   clearColor: {
-    set: (renderer, value) => renderer.setClearColor(value as ColorRepresentation),
+    set: (renderer, value) => {
+      // Check if the color string includes alpha (8 characters hex)
+      if (typeof value === 'string' && value.length === 9 && value.startsWith('#')) {
+        // Extract alpha from the last 2 characters
+        const alpha = Number.parseInt(value.slice(7, 9), 16) / 255
+        renderer.setClearAlpha(alpha)
+        // Set color without alpha
+        renderer.setClearColor(value.slice(0, 7))
+      }
+      else {
+        renderer.setClearColor(value as ColorRepresentation)
+      }
+    },
     immediate: true,
   },
-  alpha: {
-    set: (renderer, value) => renderer.setClearAlpha(value as boolean ? 0 : 1),
+  clearAlpha: {
+    set: (renderer, value) => renderer.setClearAlpha(value as number),
     immediate: true,
   },
 }