Image QML Type

이미지를 표시합니다. 더 보기...

• 상속된 멤버를 포함한 모든 멤버 목록

속성

• asynchronous : bool
• autoTransform : bool
• cache : bool
• currentFrame : int
• fillMode : enumeration
• frameCount : int
• horizontalAlignment : enumeration
• mipmap : bool
• mirror : bool
• mirrorVertically : bool (since 6.2)
• paintedHeight : real
• paintedWidth : real
• progress : real
• retainWhileLoading : bool (since 6.8)
• smooth : bool
• source : url
• sourceClipRect : rect
• sourceSize : size
• status : enumeration
• verticalAlignment : enumeration

상세 설명

Image 유형은 이미지를 표시합니다.

이미지의 소스는 source 속성을 사용하여 URL로 지정됩니다. 이미지는 PNG 및 JPEG와 같은 비트맵 형식이나 Qt SVG와 같은 벡터 그래픽 형식을 포함하여 Qt에서 지원하는 모든 표준 이미지 형식으로 제공될 수 있습니다. 애니메이션 이미지를 표시해야 하는 경우 AnimatedSprite 또는 AnimatedImage 를 사용하십시오.

width 및 height 속성이 지정되지 않은 경우, Image는 로드된 이미지의 크기를 자동으로 사용합니다. 기본적으로 항목의 너비와 높이를 지정하면 이미지가 해당 크기로 조정됩니다. 이 동작은 fillMode 속성을 설정하여 변경할 수 있으며, 이 경우 이미지가 늘어나거나 타일 형태로 배열될 수 있습니다.

"@nx" high DPI syntax 를 제공할 수 있습니다.

사용 예

다음 예제는 Image 유형의 가장 간단한 사용법을 보여줍니다.

import QtQuick

Image {
    source: "pics/qtlogo.png"
}

압축된 텍스처 파일

실행 시 기본 그래픽 API 구현에서 지원하는 경우, 이미지를 압축된 텍스처 파일 형태로 제공할 수도 있습니다. 콘텐츠는 단순한 RGB(A) 형식의 2D 텍스처여야 합니다. 지원되는 압축 방식은 기본 드라이버와 GPU에 의해서만 제한됩니다. 다음 컨테이너 파일 형식이 지원됩니다:

• PKM (Qt 5.10부터)
• KTX (Qt 5.11부터)
• ASTC (Qt 5.13부터)

transform: [ Translate { y: -myImage.height }, Scale { yScale: -1 } ]

또는

mirrorVertically: true

convert foo.png \( +clone -alpha Extract \) -channel RGB -compose Multiply -composite foo_pm.png

KTX 와 같은 컨테이너 형식과 컨테이너 파일에 저장된 실제 텍스처 데이터의 형식을 혼동하지 마십시오. 예를 들어, KTX 파일 읽기는 런타임에 어떤 GPU 드라이버가 사용되든 상관없이 모든 플랫폼에서 지원됩니다. 그러나 이것이 파일 내 데이터에 사용된 압축 텍스처 형식이 런타임에 지원된다는 것을 보장하지는 않습니다. 예를 들어, KTX 파일에 ETC2 RGBA8 형식의 압축 데이터가 포함되어 있고, 실행 시 사용되는 3D 그래픽 API 구현체가 ETC2 압축 텍스처를 지원하지 않는다면, Image 항목은 아무것도 표시하지 않을 것입니다.

압축 형식 지원이 특정 플랫폼에만 국한된다고 가정해서는 안 됩니다. 이는 해당 플랫폼에서 사용 중인 드라이버 및 3D API 구현에 따라 달라질 수도 있습니다. 실제로, 동일한 하드웨어에 대해 동일한 공급업체가 동일한 플랫폼(예: Windows)에서 구현한 서로 다른 3D 그래픽 API(예: Vulkan 및 OpenGL)는 서로 다른 압축 텍스처 형식 세트를 제공할 수 있습니다.

데스크톱 환경(Windows, macOS, Linux)만을 대상으로 하는 경우, 일반적으로 DXTn/BCn 형식의 사용을 고려하는 것이 좋습니다. 이러한 형식은 해당 플랫폼에서 Direct 3D, Vulkan, OpenGL 및 Metal 구현 간에 가장 폭넓은 지원을 받는 경향이 있기 때문입니다. 반면, 모바일 또는 임베디드 기기를 대상으로 할 때는 ETC2 또는 ASTC 형식이 더 나은 선택일 가능성이 높습니다. 이러한 형식은 일반적으로 해당 하드웨어의 OpenGL ES 구현에서 지원하는 형식이기 때문입니다.

데스크톱, 모바일 및 임베디드 하드웨어에서 모두 실행될 예정인 애플리케이션은 압축 텍스처의 사용을 신중하게 계획하고 설계해야 합니다. 단일 형식만으로는 충분하지 않을 가능성이 매우 높으므로, 애플리케이션은 플랫폼에 따라 분기하여 해당 플랫폼에 적합한 형식의 압축 텍스처를 사용하거나, 경우에 따라 압축 텍스처 사용을 생략해야 할 수도 있습니다.

파일 확장자의 자동 감지

source URL이 존재하지 않는 로컬 파일이나 리소스를 가리키는 경우, Image 요소는 파일 확장자를 자동으로 감지하려고 시도합니다. source URL 뒤에 지원되는 이미지 파일 확장자 중 하나를 추가하여 기존 파일을 찾을 수 있다면, 해당 파일이 로드됩니다.

파일 검색 시 먼저 압축된 텍스처 컨테이너 파일 확장자를 찾으려고 시도합니다. 검색에 실패하면 conventional image file types 에 지정된 파일 확장자로 검색을 시도합니다. 예를 들어:

// Assuming the "pics" directory contains the following files:
//   dog.jpg
//   cat.png
//   cat.pkm

Image {
    source: "pics/cat.png"     // loads cat.png
}

Image {
    source: "pics/dog"         // loads dog.jpg
}

Image {
    source: "pics/cat"         // normally loads cat.pkm, but if no OpenGL, loads cat.png instead.
}

이 기능은 서로 다른 대상 플랫폼에 다양한 이미지 자산 파일 유형을 배포하는 데 도움이 됩니다. 이는 애플리케이션 성능을 최적화하고 다양한 그래픽 하드웨어에 적응하는 데 유용할 수 있습니다.

이 기능은 Qt 5.11에서 도입되었습니다.

성능

기본적으로 로컬에 있는 이미지는 즉시 로드되며, 로드가 완료될 때까지 사용자 인터페이스가 차단됩니다. 대용량 이미지를 로드해야 하는 경우, ` asynchronous ` 속성을 활성화하여 낮은 우선순위 스레드에서 이미지를 로드하는 것이 더 나을 수 있습니다.

이미지가 로컬 리소스가 아닌 네트워크에서 가져오는 경우, 자동으로 비동기적으로 로드되며, progress 및 status 속성이 적절하게 업데이트됩니다.

이미지는 내부적으로 캐시되고 공유되므로, 여러 Image 항목이 동일한 source 를 갖는 경우 이미지의 사본은 하나만 로드됩니다.

참고: 이미지는 종종 QML 사용자 인터페이스에서 가장 많은 메모리를 차지하는 요소입니다. 사용자 인터페이스의 일부를 구성하지 않는 이미지의 경우, ` sourceSize ` 속성을 통해 크기를 제한하는 것이 좋습니다. 이는 외부 소스에서 로드되거나 사용자가 제공한 콘텐츠의 경우 특히 중요합니다.

Qt Quick 예제 - 이미지 요소( QQuickImageProvider) 및 QImageReader::setAutoDetectImageFormat()도 참조하십시오 .

속성 설명서

asynchronous : bool

로컬 파일 시스템에 있는 이미지를 별도의 스레드에서 비동기적으로 로드하도록 지정합니다. 기본값은 false이며, 이 경우 이미지가 로드되는 동안 사용자 인터페이스 스레드가 차단됩니다. 이미지가 즉시 표시되는 것보다 사용자 인터페이스의 반응성을 유지하는 것이 더 중요한 경우, ` asynchronous `를 true로 설정하는 것이 유용합니다.

이 속성은 로컬 파일 시스템에서 읽은 이미지에 대해서만 유효하다는 점에 유의하십시오. 네트워크 리소스(예: HTTP)를 통해 로드되는 이미지는 항상 비동기적으로 로드됩니다.

autoTransform : bool

이 속성은 이미지에 EXIF 방향과 같은 이미지 변환 메타데이터를 자동으로 적용할지 여부를 지정합니다.

기본적으로 이 속성은 false로 설정되어 있습니다.

cache : bool

이미지를 캐시에 저장할지 여부를 지정합니다. 기본값은 true입니다. 큰 이미지를 다룰 때 ` cache `를 false로 설정하면, 작은 ‘UI 요소’ 이미지의 캐싱이 희생되지 않도록 할 수 있습니다.

currentFrame 현재 표시 중인 프레임입니다. 기본값은 0 입니다. 이미지에 여러 프레임이 포함된 경우, 0 과 frameCount - 1 사이의 숫자로 설정하여 다른 프레임을 표시할 수 있습니다.

frameCount 는 이미지에 포함된 프레임의 수입니다. 대부분의 이미지는 프레임이 하나뿐입니다.

fillMode : enumeration

이 속성을 설정하여 소스 이미지의 크기가 항목의 크기와 다를 때 어떻게 처리할지 정의합니다.

Image {
    width: 130; height: 100
    source: "qtlogo.png"
}

Image {
    width: 130; height: 100
    fillMode: Image.PreserveAspectFit
    source: "qtlogo.png"
}

Image {
    width: 130; height: 100
    fillMode: Image.PreserveAspectCrop
    source: "qtlogo.png"
    clip: true
}

Image {
    width: 120; height: 120
    fillMode: Image.Tile
    horizontalAlignment: Image.AlignLeft
    verticalAlignment: Image.AlignTop
    source: "qtlogo.png"
}

Image {
    width: 120; height: 120
    fillMode: Image.TileVertically
    verticalAlignment: Image.AlignTop
    source: "qtlogo.png"
}

Image {
    width: 120; height: 120
    fillMode: Image.TileHorizontally
    verticalAlignment: Image.AlignLeft
    source: "qtlogo.png"
}

clip 는 기본적으로 false 로 설정되어 있으므로, fillMode가 PreserveAspectCrop 로 설정되어 있더라도 항목이 경계 사각형 밖으로 그려질 수 있다는 점에 유의하십시오.

Qt Quick 예제 - 이미지 요소도 참조하십시오 .

이미지의 가로 및 세로 정렬을 설정합니다. 기본적으로 이미지는 중앙 정렬됩니다.

horizontalAlignment 의 유효한 값은 Image.AlignLeft, Image.AlignRight 및 Image.AlignHCenter 입니다. verticalAlignment 의 유효한 값은 Image.AlignTop, Image.AlignBottom 및 Image.AlignVCenter 입니다.

mipmap : bool

이 속성은 이미지가 크기 조정되거나 변환될 때 밉맵 필터링을 사용하는지 여부와 관계없이 적용됩니다.

밉맵 필터링은 '부드럽게(smooth)' 설정에 비해 크기를 축소할 때 더 나은 시각적 품질을 제공하지만, 성능 저하를 초래할 수 있습니다(이미지 초기화 시와 렌더링 중 모두).

기본적으로 이 속성은 false로 설정되어 있습니다.

smooth도 참조하십시오 .

mirror : bool

이 속성은 이미지를 가로로 반전(실질적으로 거울처럼 반전된 이미지를 표시)할지 여부를 결정합니다.

기본값은 false입니다.

mirrorVertically : bool [since 6.2]

이 속성은 이미지를 세로로 반전(실질적으로 거울에 비친 것처럼 표시)할지 여부를 결정합니다.

기본값은 false입니다.

이 속성은 Qt 6.2에서 도입되었습니다.

이 속성들은 실제로 그려지는 이미지의 크기를 나타냅니다. 대부분의 경우 width 및 height 와 동일하지만, Image.PreserveAspectFit 또는 Image.PreserveAspectCrop 를 사용할 때는 paintedWidth 또는 paintedHeight 가 Image 항목의 width 및 height 보다 작거나 클 수 있습니다.

progress : real [read-only]

이 속성은 이미지 로딩 진행 상황을 0.0(아직 로딩되지 않음)부터 1.0(완료됨)까지 나타냅니다.

status도 참조하십시오 .

retainWhileLoading : bool [since 6.8]

이 속성은 ` source ` 속성이 변경되고 로딩이 비동기적으로 이루어질 때의 동작을 정의합니다. 이는 ` asynchronous ` 속성이 ` true`로 설정되어 있거나, 이미지가 로컬 파일 시스템에 없는 경우에 해당합니다.

retainWhileLoading 가 false (기본값)인 경우, 기존 이미지는 즉시 제거되고 새 이미지가 로드되는 동안 컴포넌트가 비워집니다. true 로 설정된 경우, 기존 이미지는 유지되며 새 이미지가 준비될 때까지 계속 표시됩니다.

이 속성을 활성화하면 새 이미지를 로드하는 데 오랜 시간이 걸리는 경우 화면 깜빡임을 방지할 수 있습니다. 단, 새 이미지를 로드하는 동안 더블 버퍼링으로 인해 메모리 사용량이 다소 증가하는 단점이 있습니다.

이 속성은 Qt 6.8에서 도입되었습니다.

smooth : bool

이 속성은 이미지가 크기 조정되거나 변형될 때 부드럽게 필터링되는지 여부를 결정합니다. 부드러운 필터링은 시각적 품질을 향상시키지만, 일부 하드웨어에서는 처리 속도가 느려질 수 있습니다. 이미지가 원래 크기로 표시되는 경우, 이 속성은 시각적 효과나 성능에 아무런 영향을 미치지 않습니다.

기본적으로 이 속성은 true로 설정되어 있습니다.

mipmap도 참조하십시오 .

source : url

Image는 Qt에서 지원하는 모든 이미지 형식을 처리할 수 있으며, Qt에서 지원하는 모든 URL 스키마에서 이미지를 불러올 수 있습니다.

URL은 절대 URL이거나 컴포넌트의 URL을 기준으로 한 상대 URL일 수 있습니다.

QQuickImageProvider, Compressed Texture Files 및 Automatic Detection of File Extension도 참조하십시오 .

sourceClipRect : rect

이 속성을 설정하면, 로드할 원본 이미지의 직사각형 영역이 지정됩니다.

sourceClipRect 는 sourceSize 속성과 함께 작동하여, 이미지의 일부만 로드해야 할 때 시스템 리소스를 절약합니다.

Rectangle {
    width: ...
    height: ...

    Image {
       anchors.fill: parent
       source: "reallyBigImage.svg"
       sourceSize.width: 1024
       sourceSize.height: 1024
       sourceClipRect: Qt.rect(100, 100, 512, 512)
    }
}

위의 예제에서는 개념적으로 SVG 그래픽을 먼저 1024x1024로 크기를 조정한 다음, 상단 및 좌측 가장자리에서 100픽셀 떨어진 위치에서 512x512 픽셀 크기의 관심 영역을 잘라냅니다. 따라서 ` sourceSize `가 크기를 결정하지만, 실제 출력 이미지는 512x512 픽셀입니다.

일부 이미지 형식은 지정된 영역만 렌더링하여 CPU 시간을 절약할 수 있습니다. 다른 형식은 먼저 전체 이미지를 불러온 다음 지정된 영역으로 잘라내야 합니다.

sourceClipRect 를 undefined 로 설정하여 이 속성을 지우면 전체 이미지를 다시 불러올 수 있습니다.

sourceSize : size

이 속성은 전체 프레임 이미지의 확대/축소된 너비와 높이를 저장합니다.

이미지 렌더링을 확대/축소하는 ` width ` 및 ` height ` 속성과는 달리, 이 속성은 로드된 이미지에 대해 저장되는 최대 픽셀 수를 설정하여 대용량 이미지가 필요 이상의 메모리를 사용하지 않도록 합니다. 예를 들어, 이 속성을 사용하면 `Image` 객체의 ` width ` 및 ` height ` 값과 관계없이 메모리에 저장된 이미지의 크기가 1024x1024 픽셀을 초과하지 않도록 보장합니다:

Rectangle {
    width: ...
    height: ...

    Image {
       anchors.fill: parent
       source: "reallyBigImage.jpg"
       sourceSize.width: 1024
       sourceSize.height: 1024
    }
}

이미지의 실제 크기가 sourceSize보다 큰 경우, 이미지는 축소됩니다. 크기의 한 축만 0보다 큰 값으로 설정된 경우, 다른 축은 원본 이미지의 종횡비를 유지하도록 비례하여 설정됩니다. ( fillMode 는 이와 별개입니다.)

sourceSize.width와 sourceSize.height가 모두 설정된 경우, 이미지는 지정된 크기에 맞도록 축소되며(PreserveAspectCrop 또는 PreserveAspectFit이 사용된 경우는 예외로, 이 경우 자르기/맞추기에 최적의 크기에 맞춰 조정됨), 이미지의 종횡비는 유지됩니다. 확대/축소 후 이미지의 실제 크기는 Item::implicitWidth 및 Item::implicitHeight 를 통해 확인할 수 있습니다.

소스가 본질적으로 크기 조정이 가능한 이미지(예: SVG)인 경우, 이 속성은 본래 크기와 관계없이 로드된 이미지의 크기를 결정합니다. 이 속성을 동적으로 변경하지 마십시오. SVG 렌더링은 일반 이미지에 비해 속도가 느립니다.

소스가 확장 불가능한 이미지(예: JPEG)인 경우, 로드된 이미지의 크기는 이 속성이 지정하는 크기를 초과하지 않습니다. 일부 형식(현재는 JPEG만 해당)의 경우, 전체 이미지가 실제로 메모리에 로드되지 않을 수 있습니다.

sourceClipRect 속성도 설정된 경우, sourceSize 가 확대/축소 비율을 결정하지만, 클립 사각형의 크기로 잘리게 됩니다.

sourceSize를 undefined 로 설정하면 이미지의 원래 크기로 초기화할 수 있습니다.

Qt Quick 예제 - 포인터 핸들러도참조하십시오 .

status : enumeration [read-only]

이 속성은 이미지 로딩 상태를 나타냅니다. 다음 중 하나일 수 있습니다:

이 상태를 사용하여 최신 정보를 제공하거나 상태 변경에 대해 어떤 방식으로든 대응하십시오. 예를 들어, 다음과 같은 조치를 취할 수 있습니다:

• 상태 변경을 트리거할 수 있습니다:

  State { name: 'loaded'; when: image.status == Image.Ready }

• onStatusChanged 신호 핸들러를 구현합니다:

  Image {
      id: image
      onStatusChanged: if (image.status == Image.Ready) console.log('Loaded')
  }

• 상태 값에 바인딩하기:

  Text { text: image.status == Image.Ready ? 'Loaded' : 'Not loaded' }

progress도 참조하십시오 .