QOffscreenSurface Class
QOffscreenSurface 클래스는 기본 플랫폼의 오프스크린 표면을 나타냅니다. 더 보기...
| 헤더: | #include <QOffscreenSurface> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| 상속: | QObject 그리고 QSurface |
공개 함수
| QOffscreenSurface(QScreen *targetScreen = nullptr, QObject *parent = nullptr) | |
| virtual | ~QOffscreenSurface() |
| void | create() |
| void | destroy() |
| bool | isValid() const |
| QNativeInterface * | nativeInterface() const |
| QSurfaceFormat | requestedFormat() const |
| QScreen * | screen() const |
| void | setFormat(const QSurfaceFormat &format) |
| void | setScreen(QScreen *newScreen) |
재구현된 공용 함수
| virtual QSurfaceFormat | format() const override |
| virtual QSize | size() const override |
| virtual QSurface::SurfaceType | surfaceType() const override |
신호
| void | screenChanged(QScreen *screen) |
상세 설명
QOffscreenSurface는 QOpenGLContext 와 함께 사용하도록 설계되어, QWindow 를 생성할 필요 없이 임의의 스레드에서 OpenGL로 렌더링할 수 있게 해줍니다.
표면은 일반적으로 렌더링이 가능하지만, 표면의 픽셀에는 접근할 수 없습니다. QOffscreenSurface는 텍스처나 프레임버퍼 객체와 같은 OpenGL 리소스를 생성하는 용도로만 사용해야 합니다.
일반적으로 애플리케이션은 메인 렌더링 스레드의 지연을 방지하기 위해 QOffscreenSurface를 사용하여 별도의 스레드에서 시간이 오래 걸리는 작업을 수행합니다. QOffscreenSurface 컨텍스트에서 생성된 리소스는 메인 OpenGL 컨텍스트와 공유될 수 있습니다. 일반적인 사용 사례로는 비동기 텍스처 업로드나 QOpenGLFramebufferObject 으로의 렌더링 등이 있습니다.
오프스크린 서페이스의 구현 방식은 기본 플랫폼에 따라 다르지만, 일반적으로 픽셀 버퍼(pbuffer)를 사용합니다. 플랫폼에서 오프스크린 서페이스를 구현하거나 지원하지 않는 경우, QOffscreenSurface는 내부적으로 보이지 않는 QWindow 를 사용합니다.
참고: 일부 플랫폼에서 QOffscreenSurface가 QWindow 로 뒷받침된다는 점때문에 , 크로스 플랫폼 애플리케이션은 create()가 메인(GUI) 스레드에서만 호출되도록 보장해야 합니다. 그러면 QOffscreenSurface는 다른 스레드에서 makeCurrent()와 함께 안전하게 사용할 수 있지만, 초기화 및 소멸은 항상 메인(GUI) 스레드에서 이루어져야 합니다.
참고: 주어진 컨텍스트 및 창과 호환성이 보장되는 오프스크린 서페이스를생성하려면 , 형식을 컨텍스트 또는 창의 실제 형식, 즉 컨텍스트나 창이 생성된 후 QOpenGLContext::format() 또는 QWindow::format()에서 반환된 QSurfaceFormat 로 설정해야 합니다. QWindow::requestedFormat()에서 반환된 포맷을 setFormat()에 전달하면, 기본이 되는 윈도우 시스템 인터페이스가 창 및 pbuffer 표면에 대해 서로 다른 구성 세트를 제공할 수 있으므로 호환되지 않는 오프스크린 표면이 생성될 수 있습니다.
참고: 일부 플랫폼에서는 가능한 경우 서페이스리스 컨텍스트 확장(예: EGL_KHR_surfaceless_context)을 사용할 수 있습니다. 이 경우 기본 네이티브 서페이스가 존재하지 않습니다. QOffscreenSurface의 사용 사례(FBO로 렌더링, 텍스처 업로드)에서는 이것이 문제가 되지 않습니다.
멤버 함수 문서
[explicit] QOffscreenSurface::QOffscreenSurface(QScreen *targetScreen = nullptr, QObject *parent = nullptr)
지정된 parent 를 사용하여 targetScreen 용 오프스크린 서페이스를 생성합니다.
create()가 호출될 때까지 기본 플랫폼 서피스는 생성되지 않습니다.
setScreen() 및 create()도 참조하십시오 .
[virtual noexcept] QOffscreenSurface::~QOffscreenSurface()
화면 밖의 표면을 제거합니다.
void QOffscreenSurface::create()
오프스크린 서피스와 관련된 플랫폼 리소스를 할당합니다.
이 시점에서 setFormat()를 사용하여 설정된 서피스 형식이 실제 네이티브 서피스로 변환됩니다.
필요한 경우 destroy()를 호출하여 플랫폼 리소스를 해제하십시오.
참고: 일부 플랫폼에서는 이 함수를 메인(GUI) 스레드에서 호출해야 합니다.
destroy()도 참조하십시오 .
void QOffscreenSurface::destroy()
이 오프스크린 표면과 관련된 네이티브 플랫폼 리소스를 해제합니다.
create()도 참조하십시오 .
[override virtual] QSurfaceFormat QOffscreenSurface::format() const
QSurface::format() const를 재구현합니다.
이 오프스크린 서페이스의 실제 포맷을 반환합니다.
오프스크린 서페이스가 생성된 후, 이 함수는 해당 서페이스의 실제 서페이스 형식을 반환합니다. 플랫폼에서 요청된 형식을 충족할 수 없는 경우, 반환된 형식은 요청된 형식과 다를 수 있습니다.
setFormat(), create() 및 requestedFormat()도 참조하십시오 .
bool QOffscreenSurface::isValid() const
이 오프스크린 표면이 유효한 경우 ` true `를 반환하고, 그렇지 않은 경우 ` false`를 반환합니다.
플랫폼 리소스가 성공적으로 할당된 경우, 이 오프스크린 서페이스는 유효합니다.
create()도 참조하십시오 .
template <typename QNativeInterface> QNativeInterface *QOffscreenSurface::nativeInterface() const
지정된 유형에 대한 표면의 네이티브 인터페이스를 반환합니다.
이 함수는 QNativeInterface 네임스페이스에 정의된 QOffScreenSurface의 플랫폼별 기능에 대한 액세스를 제공합니다:
Android의 오프스크린 서페이스에 대한 네이티브 인터페이스 |
요청된 인터페이스를 사용할 수 없는 경우 nullptr 가 반환됩니다.
QSurfaceFormat QOffscreenSurface::requestedFormat() const
이 오프스크린 서피스의 요청된 서피스 포맷을 반환합니다.
요청된 형식이 플랫폼 구현에서 지원되지 않는 경우, requestedFormat은 실제 오프스크린 서피스 형식과 다를 수 있습니다.
이 값은 setFormat() 함수를 통해 설정된 값입니다.
setFormat() 및 format()도 참조하십시오 .
QScreen *QOffscreenSurface::screen() const
오프스크린 표면이 연결된 화면을 반환합니다.
setScreen()도 참조하십시오 .
[signal] void QOffscreenSurface::screenChanged(QScreen *screen)
이 신호는 오프스크린 표면의 ` screen `가 변경될 때 발생하며, 이는 ` setScreen()`를 통해 명시적으로 설정되거나, 창의 화면이 제거될 때 자동으로 변경될 수 있습니다.
void QOffscreenSurface::setFormat(const QSurfaceFormat &format)
오프스크린 서페이스를 format 로 설정합니다.
서피스 형식은 create() 함수에서 결정됩니다. create() 호출 후에 이 함수를 호출하더라도 네이티브 서피스의 서피스 형식이 다시 결정되지는 않습니다.
format(), create(), destroy()도 참조하십시오 .
void QOffscreenSurface::setScreen(QScreen *newScreen)
오프스크린 표면이 연결된 화면을 설정합니다.
오프스크린 표면이 이미 생성된 경우, 해당 표면은 newScreen 에서 다시 생성됩니다.
screen()도 참조하십시오 .
[override virtual] QSize QOffscreenSurface::size() const
QSurface::size() const를 재구현합니다.
오프스크린 서페이스의 크기를 반환합니다.
[override virtual] QSurface::SurfaceType QOffscreenSurface::surfaceType() const
QSurface::surfaceType() const를 재구현합니다.
오프스크린 서페이스의 서페이스 유형을 반환합니다.
오프스크린 서페이스의 서페이스 유형은 항상 ` QSurface::OpenGLSurface`입니다.
© 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.
