En esta página

Camera QML Type

Una interfaz para los ajustes de la cámara relacionados con el enfoque y el zoom. Más...

Import Statement: import QtMultimedia
In C++: QCamera

Propiedades

Señales

Métodos

Descripción detallada

El elemento «Cámara» se puede utilizar dentro de una aplicación de « CaptureSession » para grabar vídeo y tomar fotografías.

Puedes utilizar MediaDevices para ver la lista de cámaras disponibles y elegir cuál quieres utilizar.

MediaDevices {
    id: mediaDevices
}
CaptureSession {
    camera: Camera {
        cameraDevice: mediaDevices.defaultVideoInput
    }
}

En los dispositivos que lo admiten, Camera permite ajustar el enfoque y el zoom. Las propiedades minimumZoomFactor y maximumZoomFactor proporcionan el rango de factores de zoom admitidos. La propiedad zoomFactor permite cambiar el factor de zoom.

Camera {
    zoomFactor: maximumZoomFactor // zoom in as much as possible
}

Tras capturar los datos sin procesar de un fotograma de la cámara, el hardware y el software de la cámara realizan diversas tareas de procesamiento de imágenes para generar la imagen final. Esto incluye compensar el color de la luz ambiental, reducir el ruido y realizar otros ajustes en la imagen.

Puede controlar muchos de estos pasos de procesamiento a través de las propiedades de la cámara. Por ejemplo, puede configurar el balance de blancos (o temperatura de color) utilizado para procesar las imágenes:

Camera {
    whiteBalanceMode: Camera.WhiteBalanceManual
    colorTemperature: 5600
}

Para obtener más información sobre el procesamiento de imágenes de los fotogramas de la cámara, consulta «Procesamiento de imágenes de la cámara».

La mayoría de las plataformas requieren que el usuario final conceda permisos antes de que se pueda activar una cámara. Por lo tanto, se recomienda encarecidamente que los desarrolladores de aplicaciones utilicen el componente « CameraPermission » cuando trabajen con cámaras. A continuación se muestra un breve ejemplo que solicita permisos al usuario final al iniciar la aplicación y, a continuación, activa la cámara si se conceden los permisos.

CameraPermission {
    id: cameraPermission
}

Camera {
    active: cameraPermission.status === Qt.PermissionStatus.Granted
}

Component.onCompleted: cameraPermission.request()

Consulte la descripción general de la cámara para obtener más información.

Documentación de propiedades

active : bool

Indica si la cámara está activa en este momento.

cameraDevice : cameraDevice

Obtiene o establece el dispositivo de cámara activo actualmente.

Al cambiar de dispositivo de cámara, se actualizan las capacidades del objeto ` Camera`. Además, las propiedades de control del objeto ` Camera` (como ` focusMode`, ` flashMode`, ` focusDistance` y ` zoomFactor`) se actualizan de la siguiente manera:

  • Si una propiedad es compatible con el nuevo dispositivo, el valor de la propiedad se aplica al dispositivo de la cámara.
  • Si una propiedad es compatible, pero su rango de valores válidos ha cambiado, la propiedad se ajusta al nuevo rango y se aplica al dispositivo de la cámara.
  • Si el nuevo dispositivo de cámara no admite una propiedad, el valor de la misma se restablece a su valor predeterminado y no se realiza ningún cambio en el dispositivo de cámara.

cameraFormat : cameraFormat

Obtiene o establece el formato de cámara activo actualmente.

Nota: Al utilizar el backend FFMPEG en un dispositivo Android, si se solicita el formato YUV420P, se obtendrá bien un YUV420P 4:2:0 totalmente planar, bien un NV12/NV21 semiplanar. Esto depende del códec implementado por el fabricante del dispositivo.

Nota: En macOS, los dispositivos de cámara se comparten entre varias aplicaciones del sistema operativo. Esto significa que otra aplicación puede anular el formato establecido por esta propiedad. Los desarrolladores de aplicaciones deben tener en cuenta que pueden recibir fotogramas de vídeo con una resolución, un formato de píxeles y una frecuencia de fotogramas diferentes a los descritos por esta propiedad. Esta propiedad no cambia cuando otra aplicación modifica el formato del dispositivo. El formato descrito por esta propiedad se puede volver a aplicar al dispositivo reactivando el método Camera.

Véase también « cameraDevice::videoFormats ».

colorTemperature : int

Obtiene o establece la temperatura de color actual.

La configuración de la temperatura de color solo tendrá efecto si se admite WhiteBalanceManual. En este caso, al establecer una temperatura superior a 0, el modo de balance de blancos se establecerá automáticamente en WhiteBalanceManual. Al establecer la temperatura en 0, el modo de balance de blancos se restablecerá a WhiteBalanceAuto.

customFocusPoint : point

Esta propiedad contiene la posición del punto de enfoque personalizado, en coordenadas relativas del fotograma. Esto significa que QPointF(0,0) apunta a la esquina superior izquierda del fotograma, y QPointF(0,5; 0,5) apunta al centro del fotograma.

Puedes comprobar si se admiten los puntos de enfoque personalizados consultando supportedFeatures() con el indicador Feature.CustomFocusPoint.

error : enumeration [read-only]

Devuelve el estado de error de la cámara.

ConstanteDescripción
Camera.NoErrorNo se ha producido ningún error.
Camera.CameraErrorSe ha producido un error.

errorString : string [read-only]

Devuelve una cadena legible que describe el estado de error de una cámara.

exposureCompensation : real

Obtiene o establece la compensación de exposición en unidades EV.

La propiedad «Compensación de exposición» permite ajustar la exposición calculada automáticamente.

exposureMode : enumeration

El modo de exposición que se está utilizando.

ConstanteDescripción
Camera.ExposureAutoModo automático.
Camera.ExposureManualModo manual.
Camera.ExposurePortraitModo de exposición de retrato.
Camera.ExposureNightModo nocturno.
Camera.ExposureSportsModo de exposición puntual.
Camera.ExposureSnowModo de exposición para nieve.
Camera.ExposureBeachModo de exposición en playa.
Camera.ExposureActionModo Acción. A partir de la versión 5.5
Camera.ExposureLandscapeModo «Paisaje». A partir de la versión 5.5
Camera.ExposureNightPortraitModo «Retrato nocturno». Desde la versión 5.5
Camera.ExposureTheatreModo teatro. Desde la versión 5.5
Camera.ExposureSunsetModo «Puesta de sol». Desde la versión 5.5
Camera.ExposureSteadyPhotoModo de foto estable. Desde la versión 5.5
Camera.ExposureFireworksModo «Fuegos de artificio». Desde la versión 5.5
Camera.ExposurePartyModo «Fiesta». Desde la versión 5.5
Camera.ExposureCandlelightModo «A la luz de las velas». Desde la versión 5.5
Camera.ExposureBarcodeModo «Código de barras». Desde la versión 5.5

Véase también isExposureModeSupported().

exposureTime : real [read-only]

Devuelve el tiempo de exposición de la cámara en segundos.

Véase también manualExposureTime.

flashMode : enumeration

Obtiene o establece un modo de flash concreto, si la cámara dispone de flash.

Asignar un modo no compatible a esta propiedad no tiene ningún efecto.

Esta propiedad solo surte efecto al capturar imágenes utilizando ImageCapture

ConstanteDescripción
Camera.FlashOffEl flash está desactivado.
Camera.FlashOnEl flash está activado.
Camera.FlashAutoFlash automático.

Véase también isFlashModeSupported(), isFlashReady() y flashReady.

flashReady : bool [read-only]

Indica si el flash está cargado y listo para su uso.

focusDistance : real

Esta propiedad define la distancia de enfoque del objetivo cuando la cámara funciona en modo de enfoque manual. Los valores válidos oscilan entre 0 y 1, donde 0 es la distancia de enfoque más cercana posible y 1, la más lejana. El punto más lejano suele estar en el infinito, aunque puede que no sea así en todos los dispositivos.

Esta propiedad se aplica al dispositivo únicamente cuando « focusMode » está establecido en « Camera.FocusModeManual » y « supportedFeatures » incluye el indicador « Camera.FocusDistance ».

Si se asigna un valor a esta propiedad mientras focusMode no está establecido en Camera.FocusModeManual, la propiedad almacena el valor, pero no afecta al dispositivo hasta que Camera.FocusModeManual esté activo.

Asignar un valor fuera del rango válido [0, 1] no tiene ningún efecto sobre esta propiedad.

Si « supportedFeatures » no incluye el indicador « Camera.FocusDistance », se ignorará cualquier intento de establecer esta propiedad.

La cámara no actualizará esta propiedad cuando se encuentre en modo de enfoque automático.

El valor por defecto es 1.

focusMode : enumeration

Esta propiedad contiene el valor que controla el modo de enfoque del dispositivo de cámara. En todos los modos de enfoque automático, el dispositivo de cámara mantiene el enfoque de forma continua.

Nota: En los modos de enfoque automático y cuando sea compatible, la propiedad ` focusPoint ` proporciona información y control sobre el área de la imagen en la que se está enfocando.

ConstanteDescripción
Camera.FocusModeAutoModo de enfoque automático continuo.
Camera.FocusModeAutoNearEnfoque automático continuo, dando prioridad a los objetos cercanos a la cámara.
Camera.FocusModeAutoFarEnfoque automático continuo, dando prioridad a los objetos alejados de la cámara.
Camera.FocusModeHyperfocalEnfoque a la distancia hiperfocal, con la máxima profundidad de campo posible. Todos los objetos situados a distancias comprendidas entre la mitad de esta distancia y el infinito quedarán aceptablemente nítidos.
Camera.FocusModeInfinityEnfoque estrictamente al infinito.
Camera.FocusModeManualLa distancia de enfoque del objetivo se establece en un valor especificado por focusDistance.

Para comprobar si el dispositivo de la cámara admite un modo de enfoque concreto, pasa el valor correspondiente de « focusMode » a la función « isFocusModeSupported()» como parámetro. La función devuelve « false » si el valor del modo de enfoque no es compatible. Asignar un modo no compatible a esta propiedad no tiene ningún efecto.

Si se establece la propiedad focusMode en Camera.FocusModeManual, el objetivo se bloquea en el enfoque según focusDistance.

Véase también isFocusModeSupported().

focusPoint : point [read-only]

Devuelve el punto que el sistema de enfoque automático está utilizando actualmente para enfocar.

isoSensitivity : int [read-only]

Indica la sensibilidad ISO que utiliza actualmente la cámara.

manualExposureTime : real

Obtiene o establece un tiempo de exposición manual.

Si se establece esta propiedad en -1 (valor por defecto), la cámara determina automáticamente el tiempo de exposición.

manualIsoSensitivity : int

Describe una sensibilidad ISO ajustada manualmente

Si se establece esta propiedad en -1 (el valor por defecto), la cámara ajusta automáticamente la sensibilidad ISO.

maximumZoomFactor : real [read-only]

Esta propiedad indica el factor de zoom máximo admitido.

En las cámaras que no admiten zoom, este valor será « 1.0 ».

minimumZoomFactor : real [read-only]

Esta propiedad contiene el factor de zoom mínimo admitido.

En las cámaras que no admiten zoom, este valor será « 1.0 ».

supportedFeatures : enumeration [read-only]

Devuelve las funciones compatibles con esta cámara. El valor es una máscara de bits que puede contener cualquiera de los indicadores siguientes. Almacena una combinación OR de valores de función.

ConstanteDescripción
Camera.ColorTemperatureLa cámara admite la configuración de un « colorTemperature » personalizado.
Camera.ExposureCompensationLa cámara admite la configuración de un « exposureCompensation » personalizado.
Camera.IsoSensitivityLa cámara admite la configuración de un « isoSensitivity » personalizado.
Camera.ManualExposureTimeLa cámara admite la configuración de un manual exposure Time.
Camera.CustomFocusPointLa cámara admite la configuración de un « custom focus point ».
Camera.FocusDistanceLa cámara admite la configuración de la propiedad « focusDistance ».

torchMode : enumeration

Obtiene o establece el modo de linterna que se está utilizando.

Una linterna es una fuente de luz continua. Se puede utilizar durante la grabación de vídeo en condiciones de poca luz. Al activar el modo linterna, normalmente se anula cualquier modo de flash que esté configurado en ese momento.

ConstanteDescripción
Camera.TorchOffLa linterna está apagada.
Camera.TorchOnLa linterna está encendida.
Camera.TorchAutoLinterna automática.

Véase también isTorchModeSupported() y flashMode.

whiteBalanceMode : enumeration

Obtiene o establece el modo de balance de blancos que se está utilizando.

ConstanteDescripción
Camera.WhiteBalanceAutoModo de balance de blancos automático.
Camera.WhiteBalanceManualBalance de blancos manual. En este modo, el balance de blancos debe configurarse con setColorTemperature()
Camera.WhiteBalanceSunlightModo de balance de blancos «Luz solar».
Camera.WhiteBalanceCloudyModo de balance de blancos para días nublados.
Camera.WhiteBalanceShadeModo de balance de blancos «sombra».
Camera.WhiteBalanceTungstenModo de balance de blancos «tungsteno» (incandescente).
Camera.WhiteBalanceFluorescentModo de balance de blancos «Fluorescente».
Camera.WhiteBalanceFlashModo de balance de blancos «Flash».
Camera.WhiteBalanceSunsetModo de balance de blancos «Puesta de sol».

Véase también isWhiteBalanceModeSupported().

zoomFactor : real

Obtiene o establece el factor de zoom actual. Los valores se limitarán entre minimumZoomFactor y maximumZoomFactor.

Documentación de Signal

void errorOccurred(Camera::Error error, string errorString)

Esta señal se emite cuando el estado de error cambia a « error ». Se proporciona una descripción del error como « errorString ».

Nota: El controlador correspondiente es onErrorOccurred.

Documentación del método

bool isExposureModeSupported(ExposureMode mode)

Devuelve «true» si se admite la exposición mode.

bool isFlashModeSupported(FlashMode mode)

Devuelve «true» si se admite el flash mode.

bool isFlashReady()

Devuelve «true» si el flash está cargado.

bool isFocusModeSupported(FocusMode mode)

Devuelve « true » si la cámara admite el enfoque « mode ».

Si se indica que Camera.FocusModeManual es compatible, se da por hecho que la función Camera.FocusDistance también lo es.

bool isTorchModeSupported(TorchMode mode)

Devuelve «true» si se admite la antorcha « mode ».

bool isWhiteBalanceModeSupported(WhiteBalanceMode mode)

Devuelve «true» si se admite el balance de blancos « mode ».

void start()

Inicia la cámara.

Es lo mismo que establecer la propiedad «active» en «true».

Si por algún motivo no se puede iniciar la cámara, se emite la señal « errorOccurred()».

void stop()

Detiene la cámara. Es lo mismo que establecer la propiedad «active» en «false».

void zoomTo(factor, rate)

Realiza un zoom hasta un factor de zoom factor utilizando rate.

El valor rate se especifica en potencias de dos por segundo. A una velocidad de 1, se tardaría 2 segundos en pasar de un factor de zoom de 1 a 4.

Nota: El uso de una velocidad específica no es compatible con todas las cámaras. Si no es compatible, el zoom se realizará lo más rápido posible.

© 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.