En esta página

GaussianBlur QML Type

Aplica un efecto de desenfoque de mayor calidad. Más...

Import Statement: import Qt5Compat.GraphicalEffects
Since: QtGraphicalEffects 1.0
Inherits:

Item

Propiedades

Descripción detallada

Nota: El componente « MultiEffect » proporciona un efecto de desenfoque con algunas ventajas en cuanto al rendimiento. Para el código nuevo, debería considerarse como una alternativa al uso de Qt Graphical Effects.

El efecto GaussianBlur suaviza la imagen desenfocándola mediante un algoritmo que utiliza la función gaussiana para calcular el efecto. El efecto ofrece una calidad superior a la de FastBlur, pero su renderizado es más lento.

En concreto, modificar las propiedades del desenfoque gaussiano requerirá, en muchos casos, recompilar el código del shader desde cero, por lo que la animación de las propiedades del efecto puede tener un rendimiento deficiente, además de requerir una gran cantidad de espacio en la caché. Por lo tanto, normalmente se debería dar preferencia a FastBlur para los desenfoques animados.

FuenteEfecto aplicado

Escarabajo negro sobre una hoja

Escarabajo con desenfoque gaussiano aplicado

Nota: Este efecto está disponible cuando se ejecuta con OpenGL.

Ejemplo

El siguiente ejemplo muestra cómo aplicar el efecto.

import QtQuick
import QtGraphicalEffects

Item {
    width: 300
    height: 300

    Image {
        id: bug
        source: "images/bug.jpg"
        sourceSize: Qt.size(parent.width, parent.height)
        smooth: true
        visible: false
    }

    GaussianBlur {
        anchors.fill: bug
        source: bug
        radius: 8
        samples: 16
    }
}

Aplicar el desenfoque en tiempo real es una operación que consume muchos recursos. El desenfoque gaussiano a pantalla completa, incluso con un número moderado de muestras, solo se ejecutará a 60 fps en hardware gráfico de gama alta.

Documentación de propiedades

cached : bool

Esta propiedad permite almacenar en caché los píxeles de salida del efecto con el fin de mejorar el rendimiento del renderizado. Cada vez que se modifican las propiedades de la fuente o del efecto, es necesario actualizar los píxeles de la caché. El consumo de memoria aumenta, ya que se requiere un búfer adicional de memoria para almacenar la salida del efecto.

Se recomienda desactivar la caché cuando las propiedades de la fuente o del efecto estén animadas.

Por defecto, la propiedad está establecida en « false ».

deviation : real

Esta propiedad es un parámetro de la función gaussiana que se utiliza al calcular las ponderaciones de los píxeles vecinos para el desenfoque. Una desviación mayor hace que la imagen parezca más borrosa, pero también reduce la calidad del desenfoque. Un valor de desviación muy alto hace que el efecto se parezca un poco al que produce, por ejemplo, un algoritmo de desenfoque de caja. Un valor de desviación demasiado pequeño hace que el efecto sea insignificante para los píxeles cercanos al radio.

Curvas de la función gaussiana con diferentes valores de desviación

La imagen anterior muestra la función gaussiana con dos valores de desviación diferentes: amarillo (1) y cian (2,7). El eje y muestra las ponderaciones, mientras que el eje x muestra la distancia entre píxeles.

El valor oscila entre 0,0 (sin desviación) e inf (desviación máxima). Por defecto, la desviación está vinculada al radio. Cuando el radio aumenta, la desviación se incrementa automáticamente de forma lineal. Con un valor de radio de 8, el valor por defecto de la desviación pasa a ser aproximadamente 2,7034. Este valor ofrece un equilibrio entre la calidad del desenfoque y el grado general de desenfoque.

Ejemplos de resultados con diferentes valores de desviación

Desenfoque de baja desviación

Desenfoque de desviación media

Desenfoque por alta desviación

desviación: 1 desviación: 2 desviación: 4
radius: 8radius: 8radius: 8
samples: 16samples: 16samples: 16

radius : real

Esta propiedad define la distancia a la que se encuentran los píxeles vecinos que influyen en el desenfoque de un píxel concreto. Un radio mayor aumenta el efecto de desenfoque.

El desenfoque ideal se consigue seleccionando samples y radius de tal forma que samples = 1 + radius * 2, por ejemplo:

RadioMuestras
0 (sin desenfoque)1
13
25
37

El valor oscila entre 0,0 (sin desenfoque) e infinito. Por defecto, la propiedad está establecida en floor(samples / 2.0).

Ejemplos de resultados con diferentes valores de radio

Escarabajo sin desenfoque

Escarabajo con un desenfoque moderado

Escarabajo con un fuerte desenfoque

radio: 0 radio: 4 radio: 8
samples: 16samples: 16samples: 16
deviation: 3deviation: 3deviation: 3

Nota: La propiedad « radius » se utiliza para calcular el tamaño del búfer fuera de pantalla del efecto. Los valores más altos provocarán asignaciones de memoria más grandes.

samples : int

Esta propiedad define el número de muestras que se toman por píxel al calcular el desenfoque. Un valor más alto ofrece mejor calidad, pero ralentiza el renderizado.

Lo ideal es que este valor sea el doble del valor de radio más alto requerido más 1; por ejemplo, si el radio se anima entre 0,0 y 4,0, el número de muestras debería fijarse en 9.

Por defecto, la propiedad está establecida en « 9 ».

Nota: Esta propiedad no está pensada para ser animada. Cambiar esta propiedad puede provocar que se recompilen los shaders de OpenGL subyacentes.

source : variant

Esta propiedad define el elemento de origen al que se le va a aplicar el efecto de desenfoque.

Nota: Nose admite que el efecto se incluya a sí mismo, por ejemplo, estableciendo como origen el elemento padre del efecto.

transparentBorder : bool

Esta propiedad define el comportamiento del desenfoque cerca de los bordes del elemento, donde el desenfoque de los píxeles se ve afectado por los píxeles situados fuera de los bordes de la fuente.

Si la propiedad se establece en « true », los píxeles situados fuera de la fuente se interpretan como transparentes, lo que es similar a la extensión «clamp-to-border» de OpenGL. El desenfoque se expande ligeramente fuera del área del elemento de efecto.

Si la propiedad se establece en « false », los píxeles situados fuera del elemento de origen se interpretan como si contuvieran el mismo color que los píxeles del borde del elemento, lo que es similar al comportamiento «clamp-to-edge» de OpenGL. El desenfoque no se extiende fuera del área del elemento de efecto.

De forma predeterminada, la propiedad está establecida en « false ».

Ejemplos de resultados con diferentes valores de «transparentBorder»

Desenfoque con sujeción de bordes

Desenfoque con bordes transparentes

transparentBorder: false transparentBorder: true
radius: 8radius: 8
samples: 16samples: 16
deviation: 2,7deviation: 2,7

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.