렌더링 파이프라인

OpenDocumentAsync 와 브라우저에 도달하는 PNG 사이에는 두 개의 뚜렷한 단계가 있습니다: viewer resolution (문서를 로드하는 엔진, 열 때 한 번 결정)와 page processing (각 요청마다 각 페이지 이미지에 대해 일어나는 일). 두 단계를 모두 알면 형식이 어떻게 렌더링되는지, 그리고 DefaultRender가 실제로 무엇을 전환하는지 이해할 수 있습니다.

1단계 — 형식 뷰어 해결

팩토리는 파일 확장자를 형식 카탈로그를 통해 뷰어에 매핑하며, 우선순위는 세 단계로 구성됩니다:

1. Custom viewers first. DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) 로 등록한 모든 항목은 모든 내장 뷰어보다 우선합니다.
2. Built-in family viewers. 카탈로그는 각 보기 가능한 확장자를 뷰어 패밀리(Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn)와 매핑하고, 각각은 자체 엔진 어댑터를 가집니다. 동일한 확장자에 대해 라이선스 플러그인이 뷰어를 제공하면 플러그인 뷰어가 내장 뷰어를 대체합니다. AddDoconut() 은 시작 시 등록된 플러그인 권한을 검증하며, 팩토리의 내장 뷰어로의 폴백은 방어적인 런타임 규칙입니다.
3. Plugin-only formats. 일부 확장자는 내장 뷰어가 전혀 없습니다 — DICOM(.dcm)은 DICOM 플러그인을 통해서만 존재합니다. 필요한 기능 없이 열면 다음과 같은 예외가 발생합니다:

LicenseException: This document type requires the 'Dicom' plugin license.

뷰어가 없는 확장자를 열면 다음 예외가 발생합니다:

FormatNotSupportedException: Document format '<extension>' is not supported.

해결이 끝나면 구성은 확정됩니다: 명시적인 구성 객체를 전달했다면 그것을 사용하고, 그렇지 않으면 카탈로그에 정의된 형식의 기본 구성을 사용합니다. DocOptions.Password 는 보호된 문서의 구성에 복사됩니다.

1b단계 — 리다이렉트 모드 (DefaultRender = false)

대부분의 형식별 구성은 DefaultRender 플래그를 제공합니다. 이 플래그는 근본적으로 다른 두 경로 중 하나를 선택합니다:

• DefaultRender = true — 문서가 네이티브하게 렌더링되어 바로 페이지 이미지가 생성됩니다.
• DefaultRender = false — 문서가 먼저 메모리 내에서 PDF로 변환되고, 원본 엔진이 해제되며 PDF 뷰어가 인계받습니다. 생성된 PDF는 실제 텍스트를 포함하므로 전체 텍스트 검색이 픽셀 정확도의 네이티브 하이라이트를 제공합니다; 변환은 사용자에게 보이지 않으므로 파이프라인은 리다이렉트된 PDF에 대해 AllowSearch와 AllowCopy를 강제로 활성화합니다.

XPS와 카탈로그의 MHT 기본값은 리다이렉트 경로를 사용합니다. PDF 프로젝션은 HTML 및 Microsoft Project와 같은 형식에 대해 네이티브 검색을 제공할 수 있습니다. 결과 PDF에 텍스트 레이어가 없는 이미지가 포함되어 있으면 표준 뷰어는 해당 픽셀을 검색할 수 없습니다.

문서가 열릴 때 사전 변환 비용을 감수하고 텍스트가 포함된 PDF 프로젝션이 필요할 경우 리다이렉트 모드를 사용하십시오.

2단계 — 페이지 이미지 파이프라인

렌더링된 페이지는 고정된 순서를 통해 요청당 처리됩니다:

raw page PNG → watermark → rotate/flip → scale → annotation burn → PNG to the response

• Watermark — 라이선스 상태(라이선스 누락, 임시 또는 구독 라이선스 만료, 도메인 불일치, 버전 오류)와 DocOptions.Watermark 에서 지정한 사용자 정의 텍스트에 따라 적용됩니다. 적절히 라이선스된 앱—또는 활성 임시 라이선스—이며 사용자 정의 워터마크가 없으면 이 단계가 건너뛰어집니다.
• Rotate/flip — 사용자가 위젯에서 설정한 페이지별 상태(90°/180°/270°, 가로/세로 플립)는 세션에 저장되어 해당 페이지가 이후 렌더링될 때마다 적용됩니다.
• Scale — 썸네일 및 줌 레벨은 렌더링된 페이지를 요청된 목표 크기로 스케일링하여 생성됩니다; 0 은 원본 크기로 제공함을 의미합니다.
• Annotation burn — 저장된 주석이 비트맵에 그려져 내보내기 및 페이지 이미지에 표시됩니다.
• Encoding — 결과는 풀링된 메모리 스트림을 사용해 PNG로 인코딩되고 HTTP 응답에 직접 기록됩니다.

미들웨어 내부에서 발생한 오류는 HTTP 오류 페이지 대신 PNG 오류 이미지(흰 배경에 빨간 텍스트)로 반환되어 위젯이 페이지 영역에 표시할 수 있습니다.

페이지 캐싱

BaseConfig.CachePages(기본값 true)는 문서 세션이 살아있는 동안 렌더링된 페이지 이미지를 메모리에 유지하여 페이지를 다시 방문해도 재렌더링되지 않게 합니다. BaseConfig.ImageResolution(25–300 DPI, 0 = 형식 기본값)은 주요 품질/메모리 조절값이며, 각 형식의 기본값은 해당 구성 페이지에 문서화되어 있습니다.

DocOptions.ImageResolution 은 폐기된 옵션이며 렌더링 품질을 제어하지 않습니다. 이전 라이브러리에서 애플리케이션을 이어받았다면 해당 값을 형식 구성으로 옮기세요 — 컴파일러가 모든 호출 지점을 알려줄 것입니다.

단일 노드와 다중 노드에서의 렌더링

위 내용은 문서를 연 세션에 대해 필요에 따라 단일 노드가 렌더링하는 방식을 설명합니다. 하나의 노드가 전체 아티팩트 세트를 렌더링하고 배포하며, 다른 노드들이 공유 스토리지에서 해당 페이지를 제공하는 배포 방식은 다른 읽기 경로를 사용합니다 — 분산 배포.

조정 위치