Qt에서 SVG 사용하기: 렌더러를 선택한 뒤 파일 확인하기

Qt Widgets 앱에서 SVG 그림을 표시하려면 QSvgWidget으로 시작하세요. 원하는 대상에 그림을 칠해야 한다면 QSvgRenderer를 사용하세요. 이 차이는 중요합니다. 고정 크기의 QImage에 한 번 칠하면 표시할 픽셀이 남지만, SVG를 보관하면 다른 크기로 다시 렌더링할 수 있습니다. Qt의 렌더링 안내는 두 방식을 설명합니다.

먼저 방식을 선택한 뒤 아트워크를 확인하세요. 브라우저 미리보기는 의도한 디자인을 보여 줄 수 있지만 Qt가 파일의 모든 기능을 지원한다는 것을 입증하지는 못합니다.

SVG를 편집하기 전에 표시 방식 선택하기

Qt는 QSvgWidget을 SVG 표시 위젯으로 설명하고 renderer()로 렌더러에 접근하도록 합니다. 이 위젯은 SvgWidgets에 속하며 CMake 의존성은 Qt6::SvgWidgets입니다. 여기서는 일반 SVG 모듈만 추가하는 오래된 예제보다 클래스 참조가 더 유용합니다.

SVG를 표시한다고 일러스트레이션 편집기가 만들어지지는 않습니다. 누군가 잎을 이동하거나 모서리 모양을 바꾸거나 떨어진 세부 요소의 색을 바꿔야 한다면 별도의 소스 마스터를 보관하세요.

전체 일러스트레이션 전에 작은 소스 시도하기

이 직접 만든 그림을 leaf.svg로 저장하세요. 채워진 잎, 밝은 잎맥, 별도의 산호색 원을 사용합니다.

<svg xmlns="http://www.w3.org/2000/svg" width="160" height="100" viewBox="0 0 160 100">
  <path d="M24 78C20 34 56 18 98 26C90 62 58 86 24 78Z" fill="#176b64"/>
  <path d="M28 74L78 38" fill="none" stroke="#fff6e8" stroke-width="5"/>
  <circle cx="126" cy="26" r="10" fill="#ec785e"/>
</svg>

넓은 캔버스는 의도적입니다. 잎이 길고 좁아진다면 곡선을 편집하기 전에 종횡비 처리를 확인하세요. 원이 사라진다면 보이는 경계를 확인하고 불러온 파일을 소스와 비교하세요. 이 작은 예제는 클리핑이나 효과에 의존하지 않고 알아보기 쉬운 세부 요소를 제공합니다.

파일 자체에 대한 배경은 SVG 형식 안내에서 벡터 도형과 비트맵을 포함한 SVG 파일의 차이를 설명합니다.

최소한의 Qt 6 Widgets 예제

main.cpp를 만드세요.

#include <QApplication>
#include <QSvgRenderer>
#include <QSvgWidget>
 
int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    if (argc != 2)
        return 1;
 
    QSvgWidget view;
    view.load(QString::fromLocal8Bit(argv[1]));
    if (!view.renderer()->isValid())
        return 2;
 
    view.renderer()->setAspectRatioMode(Qt::KeepAspectRatio);
    view.resize(400, 240);
    view.show();
    return app.exec();
}

프로그램 인수로 SVG 파일 이름을 전달하세요. 테스트 중에는 절대 경로가 좋습니다. 종료 코드 1은 예제가 파일 이름 하나를 받지 못했음을, 2는 렌더러가 유효한 문서를 보고하지 않았음을 뜻합니다. 이 코드는 샘플에서 정한 것이며 Qt 자체 오류 코드 API가 아닙니다.

isValid()는 불러온 문서를 확인합니다. 시각적 승인 테스트는 아닙니다. 명시적인 KeepAspectRatio 설정은 렌더러에 비율 유지를 요청합니다. QSvgRenderer 참조는 유효성 확인과 종횡비 모드를 설명합니다.

소스 옆에 다음 CMakeLists.txt를 사용하세요.

cmake_minimum_required(VERSION 3.16)
project(LeafPreview LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
find_package(Qt6 REQUIRED COMPONENTS Widgets Svg SvgWidgets)
add_executable(leaf_preview main.cpp)
target_link_libraries(leaf_preview PRIVATE Qt6::Widgets Qt6::Svg Qt6::SvgWidgets)

예제는 애플리케이션에 Widgets, 표시 위젯에 SvgWidgets, 렌더러 호출에 Svg를 연결합니다. Qt는 렌더러의 Svg 컴포넌트를 SvgWidgets 컴포넌트와 별도로 나열합니다.

설치된 Qt 6 개발 키트로 설정하고 빌드한 뒤 leaf.svg의 경로를 전달하여 leaf_preview를 실행하세요. 이는 문서에 기반한 소스 예제입니다. 네이티브 Qt 환경에서 컴파일하거나 실행하지 않았습니다. 채택하기 전에 대상 시스템에서 실제 빌드와 아트워크를 테스트하세요.

브라우저와 같다고 가정하지 말고 현재 지원 확인하기

현대 Qt SVG는 정적인 SVG Tiny 기능에만 제한되지 않습니다. Qt는 Qt 6.7부터 추가 요소를 기본적으로 파싱한다고 설명하며 Tiny 기능만 파싱하도록 제한하는 옵션도 제공합니다. 확장 기능 참조는 지원되는 추가 기능과 한계를 나열합니다.

구체적인 경계 하나는 clipPath입니다. 같은 페이지에서 지원하지 않는 것으로 표시합니다. 따라서 클리핑에 의존하는 파일은 브라우저에서 올바르게 보여도 소스를 살펴봐야 합니다. 일부 마스크와 필터는 지원이 문서화되어 있지만 모든 효과나 내보내기 설정의 지원을 입증하지는 않습니다.

단순한 잎은 작동하지만 큰 일러스트레이션이 다르게 보인다면 사본을 만들고 의심되는 기능을 하나씩 제거하세요. 클리핑된 아트워크는 클리핑 연산에 의존하기보다 편집기에서 원하는 보이는 도형을 만드는 방법을 고려하세요. 마스터를 교체하기 전에 결과 실루엣을 원본과 비교하세요.

텍스트는 별도로 확인해야 합니다. 글자가 바뀐다면 SVG 글꼴 문제 해결 안내를 따르세요. 글자를 도형으로 바꾸는 것은 디자인상의 절충입니다. 잘못된 파일 이름이나 누락된 모듈의 첫 해결책이 되어서는 안 됩니다.

파이프라인이 SVG를 픽셀로 바꾸는 시점 파악하기

코드가 잎을 작은 QImage에 한 번 렌더링하고 그 이미지에서 pixmap을 만든 뒤 나중에 pixmap을 확대한다고 가정해 보세요. 확대는 래스터 결과에 적용됩니다. SVG 소스는 사라지지 않았지만 이후 표시 작업은 더 이상 새 렌더링을 요청하지 않습니다.

Qt의 렌더링 안내는 이미지에 칠하는 것과 위젯의 paint 이벤트에서 칠하는 것을 구분합니다. 표시 크기가 바뀐다면 어디서 SVG를 다시 렌더링할지 결정하세요. 캐시된 비트맵을 보고 소스 자체가 크기 조절을 못 한다는 증거로 취급하지 마세요.

SVG 아이콘 세트를 준비할 때도 같은 구분이 중요합니다. 소스 경계를 일관되게 유지한 뒤 실제 사용 크기에서 각 아이콘을 판단하세요. 큰 크기에서 알아볼 수 있는 잎도 작게 표시하면 잎맥이나 떨어진 원이 사라질 수 있습니다.

모든 것을 단순화하기 전에 결과 살펴보기

비슷한 이름의 다른 내보내기 파일이 아니라 실제로 불러오는 파일에서 시작하세요. 단순한 예제가 나타나는지 확인한 뒤 원하는 크기와 크기 변경 후에 실제 아트워크를 비교하세요.

잎에서는 원이 분리된 상태로 유지되고 잎맥이 보이며 넓은 캔버스가 그림을 늘이지 않는지 확인하세요. 이는 자신의 실행을 위한 수용 기준이며 여기서 보고한 실행 결과가 아닙니다. 전체 화면이 비어 있다면 빈 SVG 확인 목록으로 보이지 않는 아트워크와 그림 경계 문제를 애플리케이션 설정 문제와 구분할 수 있습니다.

디자인에 적합하다면 사진이나 질감 있는 일러스트레이션을 래스터 에셋으로 유지하세요. SVG 선택은 아트워크의 요구 사항을 해결해야 합니다. 선택만으로 더 작은 파일, 더 빠른 렌더링, 엔진 간 동일한 출력이 입증되지는 않습니다.

래스터만 남은 경우 소스 마스터 복원하기

아이콘이 PNG나 JPG로만 남았다면 PerfectVector의 이미지 벡터화 작업 흐름으로 Qt 전달 전에 편집 가능한 SVG 아트워크를 준비할 수 있습니다. 변환 후 실루엣, 틈, 떨어진 세부 요소를 살펴보고 선택한 Qt 방식으로 SVG를 테스트하세요. 벡터화는 도형을 준비하며 렌더러 기능을 추가하거나 표시 위젯을 경로 편집기로 바꾸지 않습니다.

깨끗한 벡터 마스터가 이미 있다면 그 파일을 직접 조정하세요. 특정 기능이나 작은 크기의 세부 요소를 개선해야 할 때만 사본을 단순화하고 향후 편집을 위해 더 풍부한 소스를 유지하세요.

FAQ

QSvgWidget과 QSvgRenderer 중 무엇을 사용해야 하나요? Widgets 인터페이스에서 SVG를 표시하려면 QSvgWidget을 사용하세요. 사용자 지정 위젯이나 이미지처럼 선택한 대상에 칠하는 과정을 제어해야 한다면 QSvgRenderer를 사용하세요.

현재 Qt는 SVG Tiny만 지원하나요? Qt는 정적 SVG Tiny 지원과 Qt 6.7에서 도입된 일부 확장을 설명합니다. Tiny만 지원하거나 브라우저와 같다고 가정하지 말고 현재 기능 참조와 설정한 옵션을 확인하세요.

SVG를 pixmap에 넣은 뒤 흐려지는 이유는 무엇인가요? 먼저 고정 크기의 래스터 이미지로 렌더링했다면 그 결과를 확대할 때 픽셀이 확대됩니다. 렌더링 대상과 필요한 크기에서 SVG가 다시 렌더링되는지 검토하세요.

유효한 SVG 로딩은 모든 세부 요소가 올바르게 렌더링되었다는 증거인가요? 아닙니다. 유효성 확인은 시각적 검토를 대신하지 않습니다. 실제 대상 애플리케이션에서 경계, 비율, 작은 세부 요소, 지원 기능을 비교하세요.

Sources

1. Qt — SVG 파일 렌더링 — 표시 위젯, painter 대상, 위젯 렌더링과 중간 래스터의 차이.
2. Qt — QSvgWidget 클래스 — 표시 위젯, 렌더러 접근, SvgWidgets 의존성.
3. Qt — QSvgRenderer 클래스 — Svg 의존성, 문서 유효성, 종횡비 설정.
4. Qt — 확장 기능 — 현대적인 확장과 지원하지 않는 클리핑 경로를 포함한 명시적 기능 제한.

작은 파일 하나로 시작하여 선택한 Qt 방식에서 살펴보세요. 래스터 아트워크를 복원해야 한다면 편집 가능한 SVG 후보 파일을 준비하고 소스와 도형을 비교한 뒤 에셋 교체 전에 애플리케이션 수준 확인을 반복하세요.