Class: U3dImageLayer

Members

OPT_KEYS

Methods

_finishDebugLogEntry(entry, status, detail)

측정 항목을 한 번만 완료하고 상태별 개수와 단계별 누적/최대 시간을 갱신합니다.

Name	Type	Description
entry	Record.<string, any> | undefined	완료할 측정 항목
status	string	success, cache-hit, fallback, error, cancelled, stale 중 결과
detail	Record.<string, any>	optional 완료 원인과 마지막 상태

_getDebugLogTime()number

debugLog가 활성화된 코드에서만 고해상도 현재 시각을 조회합니다.

Returns:

Type	Description
number	밀리초 단위 현재 시각

_markDebugLogTime(entry, name)

네트워크, 부모 fallback, terrain swap처럼 비동기로 이어지는 구간의 시작 시각을 보관합니다.

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

_recordDebugLogDuration(entry, name, startTime)

동기 처리 구간의 경과 시간을 상세 항목에 기록합니다.

Name	Type	Description
entry	Record.<string, any> | undefined	측정 항목
name	string	측정 단계 이름
startTime	number	imageDebugNow()로 얻은 시작 시각

_recordDebugLogSince(entry, resultName, markName)

이전에 표시한 비동기 측정 지점부터 현재까지의 경과 시간을 기록합니다.

Name	Type	Description
entry	Record.<string, any> | undefined	측정 항목
resultName	string	결과 필드 이름
markName	string	시작 지점 이름

_recordImageDebugActivePeaks(entry)

현재 진행 요청 수와 로딩 카운터의 peak를 summary에 반영합니다.

Name	Type	Description
entry	Record.<string, any> | undefined	generation 확인에 사용할 작업 항목

_recordImageDebugSummary(name, amount, entry)

summary의 단순 누적 카운터를 현재 로그 generation에만 반영합니다.

Name	Type	Default	Description
name	string		summary 필드 이름
amount	number	1	optional 증가량
entry	Record.<string, any> | undefined		optional generation 확인에 사용할 작업 항목

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

타일 텍스처 작업 하나에 대응하는 상세 측정 항목을 생성합니다. debugLog가 꺼져 있으면 객체를 만들지 않고 즉시 반환하여 일반 실행 경로의 할당 비용을 없앱니다.

Name	Type	Description
type	string	측정 작업 유형
detail	Record.<string, any>	optional 타일, URL, 취소 설정 등 시작 시점의 정보

Returns:

Type	Description
Record.<string, any> | undefined	생성된 로그 항목

clearDebugLog()boolean

보관 중인 상세 항목과 누적 통계를 새 generation으로 초기화합니다.
초기화 전에 시작된 요청은 계속 완료될 수 있으므로 generation을 증가시킵니다. 구세대 callback은 자신의 항목은 마무리하되 새 summary에는 합산되지 않아 측정 구간이 서로 섞이지 않습니다.

Returns:

Type	Description
boolean	로그가 활성화되어 초기화했으면 true

createMeshFromTile(tile)UTerrainMesh

입력 받은 타일로부터 지형(Terrain) 매쉬를 생성하고 캐시에 등록합니다.
머터리얼은 레이어의 투명도/렌더 순서/노멀 텍스처 설정을 반영합니다.

Name	Type	Description
tile	U3dQuadTile	매쉬를 생성할 타일

Returns:

Type	Description
UTerrainMesh	생성된 지형 매쉬

createParentTexture(tile)boolean|undefined

부모 타일의 텍스처를 잘라내어 자식 타일의 텍스처로 사용합니다.
자식 타일의 텍스처 로드에 실패했거나, burnLevels 에 지정된 레벨일 때 사용됩니다.

Name	Type	Description
tile	U3dQuadTile	텍스처를 생성할 자식 타일

Returns:

Type	Description
boolean | undefined	생성 성공 시 true, 실패 시 undefined 를 반환합니다.

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

입력 받은 타일에 텍스처를 생성/적용할지 여부를 판단하여 작업을 시작합니다.
가시화 여부, 레벨, BoundingBox 교차, burnLevels 등을 검사하여 텍스처 생성 흐름을 분기합니다.

Name	Type	Default	Description
tile	U3dQuadTile		텍스처를 적용할 타일
opt	Partial.<{noParentTexture: boolean}>	{}	optional 텍스처 생성 옵션

Returns:

Type	Description
boolean | Promise.<U3dQuadTile> | undefined | null

deleteGeometry(mesh)

매쉬의 지오메트리를 해제합니다.

Name	Type	Description
mesh	Object3D	지오메트리를 해제할 매쉬

deleteMaterial(mesh)

매쉬의 머터리얼과 텍스처 맵을 해제합니다.

Name	Type	Description
mesh	Object3D	머터리얼을 해제할 매쉬

deleteMesh(mesh)

매쉬 및 자식 매쉬를 재귀적으로 해제합니다.
매쉬의 머터리얼, 지오메트리, 자식들을 모두 해제하고 자체 dispose 메서드가 있다면 호출합니다.

Name	Type	Description
mesh	Object3D | Material	해제할 매쉬 또는 머터리얼

dispose()any

데이터 캐시를 비우고 내부 자원을 정리합니다.

Returns:

Type	Description
any

disposeTerrainHandoffResidue(key, mesh)

handoff가 끝난 잔여물 메시를 씬 그룹에서 제거하고 자원을 해제합니다. 잔여물은 dispose 시점에 이미 캐시에서 제외되었으므로, 같은 키로 새로 만들어진 작업물은 건드리지 않습니다.

Name	Type	Description
key	string	잔여물이 속했던 tile key입니다.
mesh	Object3D	정리할 잔여물 메시입니다.

disposeTile(tile, opt)

입력 받은 타일을 해제합니다.
데이터 캐시에 동일 키가 있으면 얕은(shallow) 정리 콜백을 함께 전달합니다.

Name	Type	Default	Description
tile	U3dQuadTile		해제할 타일
opt	Partial.<{deletefunc: function()}>	{}	optional 타일 해제 옵션. deletefunc는 현재 레이어를 this로 사용하며 삭제 항목 하나를 전달받습니다.

fncDeleteGroup(object)

레이어 그룹에서 객체를 제거하고 깊은(deep) 방식으로 정리하는 콜백 함수입니다.
머터리얼·텍스처·지오메트리를 모두 해제하여 메모리에서 완전히 제거합니다.

Name	Type	Description
object	Object3D | Material	optional 그룹에서 제거할 객체

getBrightness()number

레이어가 출력하는 객체의 밝기 값을 반환합니다.

Returns:

Type	Description
number	밝기값

getClippingPlanes()Array.<Plane>|null

현재 설정된 클리핑 평면 목록을 반환합니다.

Returns:

Type	Description
Array.<Plane> | null	설정된 클리핑 평면 배열.

getContrast()number

레이어가 출력하는 객체의 대비 값을 반환합니다.

Returns:

Type	Description
number	대비값

getDarkColorTone()ColorRepresentation

레이어가 출력하는 객체의 어두운 영역 색상톤 값을 반환합니다.

Returns:

Type	Description
ColorRepresentation	어두운 영역 색상톤 값

getDarkColorToneEnabled()boolean

어두운 색상톤 적용 여부를 반환합니다.

Returns:

Type	Description
boolean	어두운 색상톤 적용 여부

getDarkColorToneExposure()number

레이어가 출력하는 객체의 어두운 색 적용 민감도를 반환합니다.

Returns:

Type	Description
number	어두운 색 적용 민감도

getDataCache()LRUCache|undefined

레이어의 데이터 캐시(LRU 캐시)를 반환합니다.

Returns:

Type	Description
LRUCache | undefined	데이터 캐시 객체.

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

이미지 레이어가 수집한 타일 요청 로그의 깊은 복사본을 반환합니다.
호출자가 반환 객체를 수정해도 실제 순환 버퍼와 누적 통계가 바뀌지 않도록 JSON 직렬화 방식으로 복사합니다. 평균값과 현재 요청 수처럼 매 작업마다 계산할 필요가 없는 값은 조회 시점에만 만들어 debugLog=false인 일반 실행뿐 아니라 장시간 측정 중인 실행의 기록 비용도 줄입니다.

Returns:

Type	Description
Record.<string, any> | undefined	이미지 타일 성능 관측 로그 복사본

getDebugLogJson(space)string|undefined

getDebugLog() 결과를 파일 저장이나 사용자 전달에 적합한 JSON 문자열로 반환합니다. 들여쓰기 값은 과도한 문자열 생성을 막기 위해 0~10 범위로 제한합니다.

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

Returns:

Type	Description
string | undefined	이미지 타일 성능 관측 로그 JSON

getHueRotation()number

레이어가 출력하는 객체의 색조 회전각을 도 단위로 반환합니다.

Returns:

Type	Description
number	색조 회전각(도)

getLightColorTone()ColorRepresentation

레이어가 출력하는 객체의 밝은 영역 색상톤 값을 반환합니다.

Returns:

Type	Description
ColorRepresentation	밝은 영역 색상톤 값

getLightColorToneEnabled()boolean

밝은 색상톤 적용 여부를 반환합니다.

Returns:

Type	Description
boolean	밝은 색상톤 적용 여부

getLightColorToneExposure()number

레이어가 출력하는 객체의 밝은 색 적용 민감도를 반환합니다.

Returns:

Type	Description
number	밝은 색 적용 민감도

getSaturation()number

레이어가 출력하는 객체의 채도 값을 반환합니다.

Returns:

Type	Description
number	채도값

getTileFromScene(tile)UMesh|undefined

입력 받은 타일이 현재 화면(scene)에 추가되어 있는지 확인하고, 추가되어 있으면 해당 객체를 반환합니다.

Name	Type	Description
tile	U3dQuadTile	조회할 타일

Returns:

Type	Description
UMesh | undefined	화면에 추가된 매쉬. 없으면 undefined 입니다.

isTexture(tile)boolean

입력 받은 타일에 텍스처가 적용되어 있는지 확인합니다.
매쉬, 머터리얼, 텍스처 맵, 이미지의 로드 완료 여부를 모두 검사합니다.

Name	Type	Description
tile	U3dQuadTile	확인할 타일

Returns:

Type	Description
boolean	텍스처가 있으면 true, 없으면 false 를 반환합니다.

processTexture(tile, drawArg, url, promise, options)Promise.<U3dQuadTile>

입력한 타일의 텍스처를 URL 에서 로드하여 적용합니다.
데이터 캐시에 동일 키가 존재하면 캐시 텍스처를 재사용하고, 로드 실패 시 부모 타일의 텍스처로 대체합니다.

Name	Type	Default	Description
tile	U3dQuadTile		텍스처를 적용할 타일
drawArg	UDrawArg		DrawArg
url	string		텍스처 URL
promise	DeferredObject.<U3dQuadTile>	deferred()	optional 작업 진행 상황을 전달할 deferred. 생략 시 내부에서 생성합니다.
options	ImageTextureProcessOptions		optional 하위 이미지 레이어가 선택하는 요청 처리 옵션

Returns:

Type	Description
Promise.<U3dQuadTile>	작업 완료 시 resolve 되는 deferred 객체

refresh()

레이어의 데이터 캐시를 비우고, 현재 그려진 타일들의 텍스처를 다시 로드합니다.

setApp(app)

앱을 연결하고 같은 앱의 image/vector shader layer가 공유할 terrain decal manager를 보관합니다.

Name	Type	Description
app	U3dApp	이 레이어를 소유한 앱입니다.

setBrightness(val)U3dImageLayer

레이어가 출력하는 객체의 밝기 값을 설정합니다.

Name	Type	Description
val	number	밝기값

Returns:

Type	Description
U3dImageLayer

setClippingPlanes(clippingPlanes)

레이어에 클리핑 평면을 설정합니다.
인자가 비어 있으면 기존에 설정된 클리핑 평면을 제거합니다.

Name	Type	Description
clippingPlanes	Plane	repeatable 클리핑 평면 리스트

setContrast(val)U3dImageLayer

레이어가 출력하는 객체의 대비 값을 설정합니다.

Name	Type	Description
val	number	대비값

Returns:

Type	Description
U3dImageLayer

setDarkColorTone(val)U3dImageLayer

레이어가 출력하는 객체의 어두운 영역 색상톤 값을 설정합니다.

Name	Type	Description
val	ColorRepresentation | null	색상톤 값, null 입력 시 검은색으로 초기화

Returns:

Type	Description
U3dImageLayer

setDarkColorToneEnabled(val)U3dImageLayer

어두운 색상톤 적용 여부를 설정합니다.

Name	Type	Description
val	boolean | null	적용 여부, null 입력 시 기본값으로 초기화

Returns:

Type	Description
U3dImageLayer

setDarkColorToneExposure(val)U3dImageLayer

어두운 색 적용 민감도를 설정합니다.

Name	Type	Description
val	number | null	어두운 색 적용 민감도, null 입력 시 기본값으로 초기화

Returns:

Type	Description
U3dImageLayer

setDepthWrite(tile, val)

입력 받은 타일의 머터리얼 depthWrite 값을 설정합니다.

Name	Type	Description
tile	U3dQuadTile	대상 타일
val	boolean	depthWrite 값

setHueRotation(val)U3dImageLayer

레이어가 출력하는 객체의 색조각도 값을 설정합니다.

Name	Type	Description
val	number	색조각도 값

Returns:

Type	Description
U3dImageLayer

setLightColorTone(val)U3dImageLayer

레이어가 출력하는 객체의 밝은 영역 색상톤 값을 설정합니다.

Name	Type	Description
val	ColorRepresentation | null	색상톤 값, null 입력 시 흰색으로 초기화

Returns:

Type	Description
U3dImageLayer

setLightColorToneEnabled(val)U3dImageLayer

밝은 색상톤 적용 여부를 설정합니다.

Name	Type	Description
val	boolean | null	적용 여부, null 입력 시 기본값으로 초기화

Returns:

Type	Description
U3dImageLayer

setLightColorToneExposure(val)U3dImageLayer

밝은 색 적용 민감도를 설정합니다.

Name	Type	Description
val	number | null	밝은 색 적용 민감도, null 입력 시 기본값으로 초기화

Returns:

Type	Description
U3dImageLayer

setOpacity(val)

레이어와 포함된 모든 매쉬의 머터리얼에 투명도를 설정합니다.
_forceTransparent 가 true 인 경우 자동으로 투명 모드가 활성화됩니다.

Name	Type	Description
val	number	투명도 (0~1)

setSaturation(val)U3dImageLayer

레이어가 출력하는 객체의 채도 값을 설정합니다.

Name	Type	Description
val	number	채도값

Returns:

Type	Description
U3dImageLayer

show(visible, refresh)

이미지 레이어의 가시화(show/hide) 여부를 설정합니다.

Name	Type	Description
visible	boolean	가시화 여부. true면 가시화합니다.
refresh	boolean	optional 가시화 변경 후 새로 고침 여부

update(drawArg)

매 프레임 호출되어 레이어 상태를 업데이트합니다.

Name	Type	Description
drawArg	UDrawArg	optional DrawArg. 미지정 시 업데이트를 건너뜁니다.

Type Definitions

U3dImageLayerCOobject

~extends U3dLayer~U3dLayerCO
생성자 옵션

Properties:

Name	Type	Argument	Default	Description
transparent	boolean	<optional>	false	레이어 투명 여부 false일 경우 투명도가 적용되지 않습니다.
burnLevels	Array.<number>	<optional>	[]	설정된 레벨의 타일 이미지는 부모 타일의 이미지를 내부적으로 렌더링하여 표출합니다.
flipY	boolean	<optional>	true	텍스쳐 UV Y축 반전 여부
parseFunction	function | null	<optional>	null	텍스처 파싱 커스텀 함수
useDataCache	boolean	<optional>	true	데이터 캐시 사용 여부
brightness	number	<optional>		레이어가 출력하는 객체의 밝기 값
contrast	number	<optional>		레이어가 출력하는 객체의 대비 값
saturation	number	<optional>		레이어가 출력하는 객체의 채도 값
hueRotation	number	<optional>		레이어가 출력하는 객체의 색조각도 값
lightColorTone	ColorRepresentation	<optional>	0xffffff	레이어가 출력하는 객체의 색상톤 값
darkColorTone	ColorRepresentation	<optional>	0x000000	어두운 영역에 적용할 색상톤 값
lightColorToneEnabled	boolean	<optional>	false	밝은 색상톤 적용 여부
darkColorToneEnabled	boolean	<optional>	false	어두운 색상톤 적용 여부
lightColorToneExposure	number	<optional>	1	밝은 색 적용 민감도
darkColorToneExposure	number	<optional>	1	어두운 색 적용 민감도