Class: U3dOpenLayer

Members

OPT_KEYS

Methods

_finishDebugLogEntry(entry, status, detail)

OL 타일 측정 항목을 완료하고 상태별 개수 및 단계별 누적 시간에 반영합니다.
동일 항목이 오류와 취소 콜백 등에서 중복 완료되지 않도록 finished를 먼저 검사하며, 로그 초기화 이전 generation의 작업은 새 summary에 합산하지 않습니다.

Name	Type	Default	Description
entry	Record.<string, any> | undefined		완료할 측정 항목
status	string		success, cache-hit, failed, error, cancelled 중 작업 결과
detail	Record.<string, any>	{}	optional 실패 원인, 캔버스 크기 등 완료 시점 상세 정보

_getDebugLogTime()number

U3dOpenLayer의 동기 측정 구간에서 사용할 고해상도 현재 시각을 반환합니다. 로그 항목이 존재하는 경우에만 호출하여 측정 기능 비활성 상태의 타이머 호출 비용을 피합니다.

Returns:

Type	Description
number	performance.now 또는 Date.now 기반 밀리초 시각

_markDebugLogTime(entry, name)

비동기로 끝나는 OL 렌더링 구간의 시작 시각을 JSON 외부 WeakMap에 기록합니다. 렌더 완료, 오류 또는 취소 시 동일한 mark 이름으로 경과 시간을 계산합니다.

Name	Type	Description
entry	Record.<string, any> | undefined	측정 대상 항목
name	string	측정 지점 이름

_markDebugLogTimeOnce(entry, name)boolean

동일 비동기 구간이 여러 frame/TileQueue 호출에서 관측되더라도 최초 시각만 보존합니다. 반환값으로 이번 호출에서 실제 mark가 생성됐는지 알려 주어, 시작 대기 시간 같은 1회성 값이 후속 frame에서 덮어써지지 않도록 합니다. entry가 없는 일반 실행 경로에서는 타이머를 호출하지 않습니다.

Name	Type	Description
entry	Record.<string, any> | undefined	측정 대상 항목
name	string	최초 한 번만 기록할 측정 지점 이름

Returns:

Type	Description
boolean	이번 호출에서 mark를 새로 기록했으면 true

_recordDebugLogSince(entry, resultName, markName)

_markDebugLogTime으로 기록한 지점부터 현재까지의 비동기 경과 시간을 계산합니다. 존재하지 않는 mark는 기록하지 않아 부분적으로 시작되지 않은 작업이 잘못된 0ms 표본을 만들지 않게 합니다.

Name	Type	Description
entry	Record.<string, any> | undefined	측정 대상 항목
resultName	string	JSON에 저장할 측정 결과 이름
markName	string	이전에 기록한 측정 지점 이름

_startDebugLogEntry(type, detail)Record.<string, any>|undefined

OL 타일 작업 하나에 대응하는 측정 항목을 생성하고 순환 버퍼에 등록합니다.
JSON에는 직렬화 가능한 작업 정보만 넣고, performance.now() 기반 시작 시각은 별도 WeakMap에 저장합니다. 보관 한도를 초과하면 가장 오래된 항목부터 제거하지만 누적 통계는 삭제하지 않아 장시간 실행 전후의 정량 비교가 가능하도록 합니다.

Name	Type	Default	Description
type	string		측정 작업 유형
detail	Record.<string, any>	{}	optional 타일 좌표, OL 모드 등 작업별 상세 정보

Returns:

Type	Description
Record.<string, any> | undefined	생성된 측정 항목. 로그 비활성 상태이면 undefined

addLayer(name, callback)boolean

OL 레이어를 등록하는 함수

Name	Type	Description
name	string	레이어 이름
callback	function	레이어 생성 콜백

Returns:

Type	Description
boolean	등록 성공 시 true, 실패 시 false

clearDebugLog()boolean

U3dOpenLayer가 보관한 개별 측정 항목과 누적 통계를 모두 초기화합니다.
초기화 도중 완료되는 이전 타일 작업이 새 통계에 섞이지 않도록 generation 값을 증가시키고, 고해상도 시작 시각을 담은 WeakMap도 함께 교체합니다. debugLog가 비활성화된 레이어에서는 저장소를 새로 만들지 않고 false를 반환합니다.

Returns:

Type	Description
boolean	로그를 초기화했으면 true, 비활성 상태이면 false

createTexture(tile, opt)boolean|Promise.<void>|undefined

타일 하나를 OL map/view로 렌더링하여 Three.js 텍스처로 변환합니다.
debugLog가 활성화된 경우 전체 처리 시간과 비동기 렌더 대기처럼 사용자 환경의 병목 판단에 필요한 핵심 구간만 측정합니다. 짧은 동기 계산을 단계마다 재는 코드는 제외하여 계측 자체의 호출 수를 제한합니다.

Name	Type	Default	Description
tile	U3dQuadTile
opt	Partial.<{noParentTexture: boolean}>	{}	optional

Returns:

Type	Description
boolean | Promise.<void> | undefined

dispose()void

이 레이어가 보유한 OpenLayers 레이어 목록과 좌표 계산용 상태를 해제합니다. 마지막에는 상위 레이어의 dispose를 호출하여 공통 3D 레이어 자원도 함께 정리합니다.

Returns:

Type	Description
void

getBoundingBox()Box3|undefined

레이어의 바운딩 박스(Bounding Box)를 반환하는 함수

Returns:

Type	Description
Box3 | undefined	바운딩 박스

getDebugLog()Record.<string, any>|undefined

U3dOpenLayer가 수집한 OL 타일 렌더링 로그의 복사본을 반환합니다.
외부 코드가 내부 순환 버퍼를 수정하지 못하도록 JSON 직렬화/역직렬화 방식으로 깊은 복사하며, 조회 시점의 레이어 이름과 클래스 타입을 반영합니다. 단계별 평균값은 누적 합계와 표본 수를 이용해 조회 시 계산하므로, 매 타일 기록 과정에는 평균 계산 비용을 추가하지 않습니다.

Returns:

Type	Description
Record.<string, any> | undefined	U3dOpenLayer 전용 성능 측정 로그 복사본

getDebugLogJson(space)string|undefined

U3dOpenLayer 전용 측정 로그를 공유하거나 파일로 저장할 수 있는 JSON 문자열로 반환합니다.
로그 구조를 알고 있는 이 하위 레이어에서 직접 직렬화하며, 들여쓰기 값은 과도하게 큰 문자열이 생성되지 않도록 0~10 범위로 제한합니다.

Name	Type	Default	Description
space	number	2	optional JSON 들여쓰기 공백 수

Returns:

Type	Description
string | undefined	U3dOpenLayer 측정 로그 JSON 문자열

refresh()void

텍스처 및 타일 상태를 다시 만들기 전에 기존 공유 source를 폐기 대상으로 전환합니다.
실제 source 해제는 진행 중인 타일 작업이 분리된 이후로 지연되므로, refresh 도중 사용 중인 source가 먼저 dispose되는 문제 없이 변경된 스타일·URL·파라미터로 새 source를 만들 수 있습니다.

Returns:

Type	Description
void

removeLayer(name)

이름으로 등록된 OL 레이어를 제거하는 함수

Name	Type	Description
name	string	제거할 레이어 이름

removeLayerAll()

등록된 OL 레이어 전체를 제거하는 함수

setParameter(param)

OL 레이어 callback에 전달할 파라미터를 갱신합니다.
source가 레이어 단위로 유지되므로 파라미터 변경 뒤에도 기존 source를 계속 사용하면 URL이나 source 옵션이 반영되지 않을 수 있습니다. 따라서 기존 공유 source는 retired 처리하고 다음 타일 요청에서 새로 생성합니다. 현재 렌더링 중인 타일은 refCount가 0이 된 뒤 기존 source를 안전하게 해제합니다.

Name	Type	Description
param	object	설정할 파라미터

setTileBackgroundColor(color)

타일 데이터의 픽셀 정보가 없을 시, 기본으로 적용될 색상을 설정합니다. null입력시 투명처리

Name	Type	Default	Description
color	ColorRepresentation	null

Type Definitions

OLLayerobject

OL 레이어 객체 (실제 동작에 필요한 멤버만 정의)

Properties:

Name	Type	Description
dispose	function
getSource	function
setSource	function

OLMapobject

OL 맵 인스턴스 (실제 동작에 필요한 멤버만 정의)

Properties:

Name	Type	Argument	Description
promise_	DeferredObject.<boolean>	<optional>
ukey_	any	<optional>
once	function
getLayers	function
removeLayer	function
setSize	function
render	function
resetForRendererPoolIdle	function
setTarget	function
setView	function
dispose	function

OLViewobject

OL 뷰 인스턴스

Properties:

Name	Type	Description
dispose	function

U3dOpenLayerCOobject

~extends U3dImageLayer~U3dImageLayerCO
U3dOpenLayer 생성자 옵션

Properties:

Name	Type	Argument	Default	Description
reverseX	boolean	<optional>	false	X축 반전 여부
reverseY	boolean	<optional>	false	Y축 반전 여부
layers	Array.<{name: string, callback: function()}>	<optional>	[]	OL 레이어 목록
oldebug	boolean	<optional>	true	OL 디버그 모드 사용 여부
parameter	object	<optional>	{}	OL 레이어 파라미터
srs	string	<optional>		소스 좌표계
crs	string	<optional>	'EPSG:3857'	대상 좌표계
boundingbox	Object | Partial.<{minz: number, maxz: number}>	<optional>		레이어 바운딩 박스
tileBackgroundColor	ColorRepresentation	<optional>		타일 데이터의 픽셀 정보가 없을 시, 기본으로 적용될 색상, 미입력시 투명 처리
sourceTileCacheLimit	number	<optional>	512	공유 OL source의 타일 캐시별 최대 보관 개수. 사용 중인 타일 렌더링이 모두 종료된 시점에 오래된 타일부터 제거
olRendererPoolSize	number	<optional>	24	정상 완료된 UMap/UView renderer bundle의 레이어별 최대 idle 보관 개수. 0이면 풀을 비활성화하고 타일 작업이 끝날 때마다 폐기
useNotFoundPass	boolean	<optional>	false	같은 URL에서 HTTP 404가 3회 연속 확인되면 레이어 refresh 전까지 후속 네트워크 요청을 생략하고 즉시 타일 오류로 처리할지 여부

U3dOpenLayerTileobject

U3dOpenLayer 내부에서 접근하는 타일 내부 프로퍼티 정의