GeOnDT for JS API

Class: U3dLayer

U3dLayer

~export U3dLayer ~extends U3dObject
3D 레이어 최상위 클래스입니다.
레이어는 지도 위에 함께 그려지는 한 묶음의 데이터(영상 타일, 지형 높이, 3D 모델 등)를 담는 단위이며, U3dApp에 등록되면 매 프레임 update()가 호출되어 타일을 불러오고 자신의 Scene에 결과물을 배치합니다. 이 클래스는 직접 생성해 쓰는 것보다 U3dImageLayer, U3dHeightLayer, U3dModelLayer 같은 하위 레이어의 공통 기능 (가시화 상태, 투명도, 범위 판정, 타일 상태·취소·캐시 관리, 이벤트, 해제)을 제공하는 부모 클래스로 사용됩니다.

new U3dLayer(opt)

U3dLayer 생성자입니다.
레이어의 범위는 rectangle, extent, geoExtent 순서로 먼저 지정된 옵션 하나만 사용합니다. renderOrder를 지정하지 않으면 생성 순서에 따라 자동으로 증가하는 값이 부여됩니다. 생성만으로는 화면에 표시되지 않으며, U3dApp에 레이어를 추가해야 초기화되고 갱신이 시작됩니다.

Name	Type	Default	Description
`opt`	U3dLayerCO	{}	optional 생성자 옵션. 각 항목의 의미와 기본값은 `U3dLayerCO`를 참고하세요

Members

EVENTU3dLayerEMI

이 레이어 클래스가 dispatch하는 이벤트 이름 모음입니다. U3dLayerEMD와 같은 객체이며, 하위 레이어가 이벤트를 추가하려면 이 static 멤버를 확장한 객체로 재정의합니다.

OPT_KEYSArray.<string>

생성자 옵션에서 인식하는 키 목록입니다.
normalizeOptionKeys가 이 목록을 기준으로 옵션 키의 대소문자 표기를 정규화하므로, 하위 레이어가 새 옵션을 추가하면 이 배열을 확장해 등록해야 합니다.

initialized

레이어 초기화 완료 여부입니다. U3dApp에 등록되어 initialize()가 끝나면 true가 됩니다.

isDeBug

생성 옵션 isDeBug로 지정한 디버그 모드 여부입니다. 하위 레이어가 디버그용 추가 처리를 할지 판단하는 데 사용합니다.

Methods

add(object)

Layer에 Object3D 객체를 추가합니다.
Object3D는 three.js에서 화면에 그려지는 모든 것(Mesh, Group, Light 등)의 공통 부모 타입입니다. 추가한 객체는 레이어의 Scene에 직접 들어가며 타일 캐시로 관리되지 않으므로, 해제는 호출자가 책임집니다. Object3D가 아닌 값을 넘기면 안내 메시지만 남기고 추가하지 않습니다.

Name	Type	Description
`object`	Object3D	레이어와 함께 표시할 three.js 객체(월드 좌표 EPSG:3857 기준으로 배치)

cancelAllTile()

모든 타일의 작업을 취소합니다.

change(drawArg)

레이어 변경(change) 훅 함수입니다. 자식 클래스에서 오버라이드하여 구현합니다.
카메라 이동 등으로 보이는 영역이 바뀌었을 때 호출되며, 기본 구현은 아무 것도 하지 않습니다.

Name	Type	Description
`drawArg`	UDrawArg	optional 현재 프레임의 렌더링 문맥(카메라, 절두체, 타일 캐시, 조명 등 공유 상태)

clearDebugLog()boolean

하위 레이어가 보관 중인 디버그 로그를 초기화하기 위한 공통 API입니다.
U3dLayer는 공통 로그 저장소를 소유하지 않으므로 기본 구현에서는 아무 데이터도 변경하지 않고 false를 반환합니다. 로그 저장소를 가진 하위 레이어가 직접 오버라이드하여 진행 중인 측정과 누적 통계를 포함한 자체 상태를 안전하게 초기화해야 합니다.

Returns:

Type	Description
boolean	하위 레이어에서 로그를 초기화했으면 true. 기본 구현은 false

contain(x, y, level)boolean

x, y 위치 좌표와 레벨 값을 입력받아 해당 지점이 레이어에 포함되는지 체크합니다.

Name	Type	Description
`x`	number	3D 월드 x좌표(EPSG:3857)
`y`	number	3D 월드 y좌표(EPSG:3857)
`level`	number	타일 레벨(줌 단계). 레이어의 `minLevel`~`maxLevel` 범위를 벗어나면 포함하지 않는 것으로 봅니다

Returns:

Type	Description
boolean	지점이 레이어 범위 안이면 true. 레이어에 범위가 지정되지 않았으면 레벨 조건만 통과하면 true

createComment(tile, opt)

입력받은 타일의 코멘트 데이터를 생성하는 훅 함수입니다. 자식 클래스에서 오버라이드하여 구현합니다.

Name	Type	Description
`tile`	U3dQuadTile	대상 타일
`opt`	object	optional 호출자가 전달하는 추가 정보. 형식은 하위 레이어가 정의합니다

createHeight(tile, opt)

입력받은 타일의 높이(Height) 데이터를 생성하는 훅 함수입니다. 자식 클래스에서 오버라이드하여 구현합니다.
tileName이 HEIGHT인 레이어의 타일 프로세스가 타일마다 호출합니다.

Name	Type	Description
`tile`	U3dQuadTile	대상 타일
`opt`	object	optional 타일 프로세스가 전달하는 추가 정보. 형식은 하위 레이어가 정의합니다

createModel(tile)

입력받은 타일의 모델 데이터를 생성하는 훅 함수입니다. 자식 클래스에서 오버라이드하여 구현합니다.
tileName이 MODEL인 레이어의 타일 프로세스가 타일마다 호출합니다.

Name	Type	Description
`tile`	U3dQuadTile	대상 타일

createTexture(tile, opt)

입력받은 타일의 텍스처를 생성하는 훅 함수입니다. 자식 클래스에서 오버라이드하여 구현합니다.
tileName이 IMAGE인 레이어의 타일 프로세스가 타일마다 호출합니다.

Name	Type	Description
`tile`	U3dQuadTile	대상 타일
`opt`	object	optional 타일 프로세스가 전달하는 추가 정보. 형식은 하위 레이어가 정의합니다

debugBound(isDebug, color)boolean

레이어의 바운딩박스 디버그 헬퍼 표시 여부를 설정합니다.

Name	Type	Default	Description
`isDebug`	boolean		디버그 헬퍼 표시 여부
`color`	number	0xffff00	optional 헬퍼 색상

Returns:

Type	Description
boolean	처리 성공 여부

dispose()Promise.<boolean>

레이어를 처분(dispose)합니다.
BEFORE_DISPOSE 이벤트를 dispatch한 뒤 디버그 헬퍼·타일 작업·Scene·캐시를 해제하고 DISPOSE 이벤트를 dispatch합니다. 마지막에 이 레이어의 모든 이벤트 리스너가 제거되므로 DISPOSE 리스너는 그 전에 등록되어 있어야 합니다. 해제 후에는 isDisposed()가 true가 되며 레이어를 다시 사용할 수 없습니다.

Returns:

Type	Description
Promise.<boolean>	해제가 끝나면 true로 완료되는 Promise

getCache(tile)UMesh|undefined

입력받은 타일에 해당하는 캐시 데이터를 반환합니다.
캐시가 존재하면 해당 캐시를, 없으면 undefined 를 반환합니다.

Name	Type	Description
`tile`	U3dQuadTile	타일

Returns:

Type	Description
UMesh \| undefined	성공 시 캐시, 실패 시 undefined

getCacheByKey(key)UMesh|undefined

키 값으로 레이어의 캐시를 반환합니다.

Name	Type	Description
`key`	string	캐시 키

Returns:

Type	Description
UMesh \| undefined	레이어 캐시 값

getCacheKeys()Array.<string>

레이어의 전체 캐시 키를 반환합니다.

Returns:

Type	Description
Array.<string>	캐시 키 목록. 캐시를 사용하지 않는 레이어(`cache: false`)면 빈 배열

getCacheLength()number

레이어 캐시에 보관 중인 타일 메시 수를 반환합니다.

Returns:

Type	Description
number	캐시된 항목 수. 캐시를 사용하지 않는 레이어면 0

getCancelByTile(tile)Promise.<void>

타일을 입력받아 등록된 취소(cancel) 작업 객체를 반환합니다.

Name	Type	Description
`tile`	U3dQuadTile	대상 타일

Returns:

Type	Description
Promise.<void>	등록된 취소 작업 객체. 등록된 것이 없으면 undefined

getCenter()GooglePositionVector3|null

레이어의 센터(Center) 월드 좌표(EPSG:3857)를 반환합니다.
레이어 범위(rectangle)가 있고 앱에 등록되어 있으면 범위의 중심을, 그렇지 않고 하위 레이어가 getBoundingBox()를 제공하면 경계 상자의 중심을 반환합니다. 둘 다 없으면 null입니다.

Returns:

Type	Description
GooglePositionVector3 \| null	센터(Center) 월드 좌표. 새로 만든 객체이므로 자유롭게 수정할 수 있으며, 중심을 정할 수 없으면 null

getCenterGeographic()GeoPositionVector3|null

레이어의 센터(Center) 위경도 좌표(EPSG:4326)를 반환합니다.
getCenter()의 월드 좌표를 위경도로 변환합니다. 중심을 정할 수 없으면 "레이어 준비 안 됨" 오류 메시지를 남기고 null을 반환합니다.

Returns:

Type	Description
GeoPositionVector3 \| null	센터(Center) 위경도 좌표(x: 경도, y: 위도, z: 높이). 중심을 정할 수 없으면 null

getDebugLog()unknown

하위 레이어가 수집한 디버그 로그를 반환하기 위한 공통 API입니다.
U3dLayer는 레이어마다 서로 다른 로그 구조를 가질 수 있도록 데이터 형식을 정의하거나 내부 저장소를 생성하지 않습니다. 따라서 기본 구현은 undefined를 반환합니다. 로그를 수집하는 하위 레이어는 자신의 저장 구조에 맞게 이 메서드를 오버라이드해야 합니다.

Returns:

Type	Description
unknown	하위 레이어가 정의한 디버그 로그. 기본 구현은 undefined

getDebugLogJson(space)string|undefined

하위 레이어가 자신의 로그를 JSON 문자열로 제공하기 위한 공통 API입니다.
U3dLayer는 로그 객체의 구조와 직렬화 규칙을 알 수 없으므로 JSON.stringify를 수행하지 않으며, 기본 구현은 undefined를 반환합니다. JSON 출력이 필요한 하위 레이어가 직접 오버라이드하여 순환 참조 제거, 들여쓰기, 민감 정보 제외 등 해당 레이어에 맞는 직렬화 정책을 적용해야 합니다.

Name	Type	Default	Description
`space`	number	2	optional 하위 구현에서 사용할 수 있는 JSON 들여쓰기 공백 수

Returns:

Type	Description
string \| undefined	하위 레이어가 생성한 JSON 문자열. 기본 구현은 undefined

getGroup()UGroup

타일 결과물(메시)이 모이는 레이어의 그룹 객체를 반환합니다.
UGroup은 three.js Group을 확장한 컨테이너로 레이어 Scene 안에 있으며, 캐시된 타일 메시가 여기에 추가·제거됩니다. show(false)나 refresh()가 호출되면 비워지므로 자식 목록을 오래 보관하지 않아야 합니다.

Returns:

Type	Description
UGroup	타일 메시 컨테이너(레이어 내부 객체)

getGroupLayer()U3dGroupLayer|undefined

이 레이어를 자식으로 포함하는 그룹 레이어를 반환합니다.
그룹 레이어(U3dGroupLayer)는 여러 레이어를 묶어 함께 표시·숨김하는 상위 레이어입니다.

Returns:

Type	Description
U3dGroupLayer \| undefined	부모 그룹 레이어. 그룹에 속하지 않으면 undefined

getLoadingTile()number

로딩(Loading) 중인 타일들의 수를 반환합니다.

Returns:

Type	Description
number	로딩 중인 타일들의 수

getOpacity()number

레이어의 투명도를 반환합니다.

Returns:

Type	Description
number	투명도. 0(완전 투명)~1(불투명)

getRenderOrder()number

랜더링 우선순위(Render Order)를 반환합니다.

Returns:

Type	Description
number	랜더링 우선순위. 클수록 나중에 그려져 위에 보입니다

getScene()UScene

레이어가 소유한 Scene을 반환합니다.
Scene은 이 레이어가 그리는 모든 3D 객체를 담는 최상위 컨테이너(three.js Scene을 확장한 UScene)이며, add()/remove()로 넣은 사용자 객체와 타일 결과물을 담는 UGroup이 이 안에 들어 있습니다. 반환값은 레이어 내부 객체 자체이므로 dispose() 이후에는 사용하지 않아야 합니다.

Returns:

Type	Description
UScene	레이어의 렌더링 컨테이너

getStateTile(tile)number|undefined

타일을 입력받아 해당 타일의 상태를 반환합니다.

Name	Type	Description
`tile`	U3dQuadTile	타일

Returns:

Type	Description
number \| undefined	`UDEF.TILE_STATE` 상태 코드. 상태가 기록되지 않은 타일이면 undefined

getStateTileByKey(key)number|undefined

타일 Key를 입력받아 해당 타일의 상태를 반환합니다.

Name	Type	Description
`key`	string	타일 Key

Returns:

Type	Description
number \| undefined	`UDEF.TILE_STATE` 상태 코드. 상태가 기록되지 않은 타일이면 undefined

getStateTileKeys()Array.<string>

타일의 상태를 담고 있는 레이어의 프로퍼티(_stateTiles)의 키 값들을 반환합니다.

Returns:

Type	Description
Array.<string>	타일 Key 값

getStateTiles()Record.<string, number>

타일의 상태를 담고 있는 레이어의 프로퍼티(_stateTiles)를 반환합니다.
상태 값은 UDEF.TILE_STATE의 코드(0 없음, 1 시작, 2 로딩 중, 3 완료, 4 실패)입니다.

Returns:

Type	Description
Record.<string, number>	타일 키를 키로, 상태 코드를 값으로 갖는 객체. 내부 객체를 그대로 반환하므로 수정하면 레이어 상태가 바뀝니다

getTileCallback()U3dLayerTileCallback|undefined

레이어의 타일 종류(IMAGE/HEIGHT/MODEL)에 따라 처리 콜백(createTexture/createHeight/createModel)을 반환합니다.
앱이 레이어를 등록할 때 이 콜백을 타일 프로세스에 연결하며, USER·MEASURE 등 그 외 종류는 undefined를 반환해 연결하지 않습니다.

Returns:

Type	Description
U3dLayerTileCallback \| undefined	타일 종류에 맞는 처리 콜백 함수(bind되지 않은 메서드이므로 호출 시 레이어를 this로 지정해야 합니다)

getType()string

생성 옵션 type으로 지정한 레이어 종류 문자열을 반환합니다.
이 클래스는 값을 해석하지 않으며, 앱이나 하위 레이어가 레이어를 분류·검색하는 데 사용합니다.

Returns:

Type	Description
string	생성 옵션 `type` 값. 지정하지 않았으면 'none'

getVisible()boolean

레이어의 가시화 상태를 반환합니다.

Returns:

Type	Description
boolean	화면에 표시되는 상태면 true

getWorkingLevel2()number

레이어의 타일 프로세스에서 처리 중이거나 대기열에 있는 작업 수를 반환합니다.
"Level 2"는 처리 중인 작업 수(getWorkingCount)에 대기열 길이를 더한 값입니다.

Returns:

Type	Description
number	처리 중 + 대기 중 작업 수. 프로세스가 연결되지 않았으면 0

getWorkingLevel3()number

레이어의 타일 프로세스에서 처리 중이거나 대기열에 있는 작업 수를 반환합니다.
현재 구현은 getWorkingLevel2()와 같은 값이며, LOADED 이벤트 발생 시점을 판단하는 데 사용됩니다.

Returns:

Type	Description
number	처리 중 + 대기 중 작업 수. 프로세스가 연결되지 않았으면 0

intersectFrustum(frustum)boolean

입력받은 Frustum 과 레이어의 바운딩박스가 교차하는지 여부를 반환합니다.
Frustum(절두체)은 카메라에 실제로 보이는 공간 영역이며, 이 판정으로 화면 밖 레이어의 처리를 건너뛸 수 있습니다. 레이어에 범위가 지정되지 않아 바운딩박스가 없으면 항상 true(보이는 것으로 간주)를 반환합니다.

Name	Type	Description
`frustum`	Frustum	카메라의 가시 영역(월드 좌표 EPSG:3857 기준)

Returns:

Type	Description
boolean	가시 영역과 레이어 범위가 겹치면 true. frustum이 없으면 false

intersects(rect, level)boolean

입력받은 범위와 해당 layer 의 교차 여부를 반환합니다.

Name	Type	Description
`rect`	UGeoRect	EPSG:3857 의 좌표 값으로 지정된 범위 객체
`level`	number	범위에 해당하는 타일 레벨(줌 단계). 레이어의 `minLevel`보다 작으면 교차하지 않는 것으로 봅니다

Returns:

Type	Description
boolean	범위가 겹치면 true. 레이어에 범위가 지정되지 않았으면 레벨 조건만 통과하면 true

intersects3D(rect3d)boolean

입력받은 범위와 해당 layer 의 교차 여부를 반환합니다.

Name	Type	Description
`rect3d`	UGeoRect	WorldPosition(EPSG:3857) 값으로 지정된 범위 객체

Returns:

Type	Description
boolean	범위가 겹치면 true. 레이어에 범위가 지정되지 않았으면 항상 true

isDebugLog()boolean

레이어 생성 옵션 debugLog의 활성화 여부를 반환합니다.
이 메서드는 로그의 저장 형식이나 측정 방식에는 관여하지 않으며, 하위 레이어가 자체 디버그 로그 기능의 실행 여부를 판단하는 공통 진입점으로만 사용합니다. 하위 레이어에서 별도의 활성화 정책이 필요하면 이 메서드를 오버라이드할 수 있습니다.

Returns:

Type	Description
boolean	디버그 로그 기능 활성화 여부

isDisposed()boolean

레이어 dispose 여부를 반환합니다.

Returns:

Type	Description
boolean	dispose 됐다면 true, 안 됐으면 false

isGroupLayer()boolean

이 레이어가 그룹 레이어에 속해 있는지 여부를 반환합니다.

Returns:

Type	Description
boolean	부모 그룹 레이어가 있으면 true

isInitialized()boolean

레이어 초기화 여부를 확인합니다.

Returns:

Type	Description
boolean	초기화 했다면 true, 안 했으면 false

isLoadingTile()boolean

레이어에 로딩 중인 타일이 존재하는지 여부를 반환합니다.
true면 존재, false면 존재하지 않습니다.

Returns:

Type	Description
boolean	존재 여부

isUseShadowUpdate()boolean

그림자 업데이트 대상 여부를 반환합니다.
U3dApp은 매 프레임 일부 레이어를 순회하며 보이는 상태이고 이 값이 true인 레이어의 updateShadow()를 호출해 그림자 맵(빛이 가려지는 영역 계산 결과)을 갱신합니다.

Returns:

Type	Description
boolean	true면 앱의 그림자 갱신 순회에 포함됩니다

off(event, callback)

이벤트 리스너를 제거합니다.
event만 넘기면 그 이벤트의 모든 리스너를, 둘 다 생략하면 이 레이어의 모든 리스너를 제거합니다.

Name	Type	Description
`event`	string	optional 이벤트 종류. 이 레이어가 dispatch하는 이벤트는 `U3dLayer.EVENT`(`U3dLayerEMD`)의 값이며, 하위 레이어는 이벤트를 추가할 수 있습니다
`callback`	function \| string	optional 제거할 리스너. 등록한 콜백 함수 자체 또는 등록 시 지정한 `name`

on(event, callback, once, name)string

이벤트 리스너를 등록합니다.

Name	Type	Description
`event`	string	이벤트 종류. 이 레이어가 dispatch하는 이벤트는 `U3dLayer.EVENT`(`U3dLayerEMD`)의 값이며, 하위 레이어는 이벤트를 추가할 수 있습니다
`callback`	EventCallBack	이벤트가 발생할 때마다 실행되는 콜백 함수
`once`	boolean	optional true면 첫 발생 후 리스너를 자동 제거합니다
`name`	string	optional 리스너를 식별하는 이름. `off(event, name)`이나 `unkey(event, name)`으로 제거할 때 사용합니다

Returns:

Type	Description
string	입력한 `name`을 그대로 반환하며, 생략했으면 빈 문자열

once(event, callback, name)string

한 번만 수행되는 이벤트 리스너를 등록합니다. 처음 이벤트가 발생해 콜백이 실행되면 자동으로 제거됩니다.

Name	Type	Description
`event`	string	이벤트 종류. 이 레이어가 dispatch하는 이벤트는 `U3dLayer.EVENT`(`U3dLayerEMD`)의 값이며, 하위 레이어는 이벤트를 추가할 수 있습니다
`callback`	EventCallBack	이벤트가 발생했을 때 한 번 실행되는 콜백 함수
`name`	string	optional 리스너를 식별하는 이름. `off(event, name)`이나 `unkey(event, name)`으로 제거할 때 사용합니다

Returns:

Type	Description
string	입력한 `name`을 그대로 반환하며, 생략했으면 빈 문자열

printNotCompleteStateTiles(print)number

완료(end)되지 않은 타일들의 키 값과 상태를 콘솔에 출력합니다.

Name	Type	Default	Description
`print`	boolean	true	optional 콘솔 출력 여부. true면 출력합니다.

Returns:

Type	Description
number	완료(end)되지 않은 타일들의 수

printStateTiles(print)number

타일의 상태를 콘솔에 출력합니다.

Name	Type	Default	Description
`print`	boolean	true	optional 콘솔 출력 여부. true면 출력합니다.

Returns:

Type	Description
number	현재 구현은 집계하지 않고 항상 0을 반환합니다. 출력한 타일 수는 `getStateTileLength()`로 확인하세요

refresh()

레이어 타일 상태 및 캐시를 전부 초기화합니다.
진행 중인 타일 작업을 모두 취소(reject)하고, 캐시된 타일 메시를 해제한 뒤 그룹을 비워 다음 갱신에서 타일을 다시 불러오게 합니다. 레이어가 아직 앱에 등록되지 않아 _drawArg가 없으면 상태·작업 정리까지만 수행하고 캐시 해제는 건너뜁니다.

remove(object)

Layer에서 Object3D 객체를 제거합니다.
Scene에서 분리만 하며 geometry·material 등 자원은 해제하지 않으므로 필요하면 호출자가 dispose해야 합니다. Object3D가 아닌 값을 넘기면 안내 메시지만 남기고 아무 것도 하지 않습니다.

Name	Type	Description
`object`	Object3D	`add()`로 추가했던 three.js 객체

removeCancelByTile(tile)

타일을 입력받아 등록된 취소(cancel) 작업 객체를 제거합니다.

Name	Type	Description
`tile`	U3dQuadTile	대상 타일

resetOpacity()

레이어의 투명도를 setOpacity()로 바꾸기 전 값으로 되돌립니다. setOpacity()를 호출한 적이 없으면 아무 것도 하지 않습니다.

restartTile(tile)

타일의 상태를 초기화하여 작업을 재시작할 수 있게 합니다.

Name	Type	Description
`tile`	U3dQuadTile	대상 타일

setCancelByTile(tile, value)

타일을 입력받아 해당 타일의 취소(cancel) 작업 객체를 등록합니다.

Name	Type	Description
`tile`	U3dQuadTile	대상 타일
`value`	DeferredObject.<U3dQuadTile>	타일 작업을 취소할 때 `reject`(또는 `cancel`)가 호출되는 대기 객체. 같은 타일에 다시 등록하면 이전 값을 덮어씁니다

setOpacity(val)

레이어의 투명도를 설정합니다.
처음 호출할 때 이전 값을 보관해 두므로 resetOpacity()로 되돌릴 수 있습니다. 이 클래스는 값과 반투명 여부만 저장하며, 실제 재질에 반영하는 것은 하위 레이어의 갱신 처리에서 수행합니다.

Name	Type	Description
`val`	number	투명도. 0(완전 투명)~1(불투명) 범위로 잘라내며(clamp), undefined면 무시합니다

setRenderOrder(val)

랜더링 우선순위(Render Order)를 설정합니다.
값이 큰 레이어가 나중에 그려져 같은 위치에서는 위에 보입니다. 이 메서드는 레이어에 저장된 값만 바꾸며, 이미 생성된 Scene·그룹·타일에는 반영하지 않으므로 생성 옵션 renderOrder로 지정하는 것을 권장합니다.

Name	Type	Description
`val`	number	랜더링 우선순위. 클수록 나중에 그려집니다

setUseShadowUpdate(use)

그림자 업데이트 대상 여부를 설정합니다. 값만 저장하며, 다음 프레임의 그림자 갱신 순회부터 반영됩니다.

Name	Type	Default	Description
`use`	boolean	true	optional true면 앱의 그림자 갱신 순회에 포함하고, false면 제외합니다

show(show, refresh)

레이어의 가시화(show/hide) 여부를 설정합니다.
상태가 바뀔 때만 동작하며 SHOW/HIDE 이벤트를 dispatch합니다. 숨길 때는 타일 그룹을 비우고 타일 상태를 초기화하며 진행 중인 타일 작업을 모두 취소합니다. 보이게 하면 다음 LOADED 이벤트까지 초기 로딩 상태로 표시됩니다.

Name	Type	Default	Description
`show`	boolean		true면 표시하고 false면 숨깁니다
`refresh`	boolean	true	optional true면 앱에 즉시 다시 그리기(`forceUpdate`)를 요청합니다

unkey(event, key)

키 값으로 명시한 이벤트 리스너를 제거합니다.

Name	Type	Description
`event`	string	이벤트 종류. 이 레이어가 dispatch하는 이벤트는 `U3dLayer.EVENT`(`U3dLayerEMD`)의 값이며, 하위 레이어는 이벤트를 추가할 수 있습니다
`key`	string	제거할 리스너의 이름(`on`/`once`에 넘긴 `name`)

update(drawArg)

레이어의 매 프레임 업데이트 훅 함수입니다. 자식 클래스에서 오버라이드하여 구현합니다.
앱이 렌더링 루프에서 보이는 레이어마다 호출하며, 기본 구현은 아무 것도 하지 않습니다.

Name	Type	Description
`drawArg`	UDrawArg	optional 현재 프레임의 렌더링 문맥(카메라, 절두체, 타일 캐시, 조명 등 공유 상태)

updateHeight(args)

레이어의 높이(Height) 갱신 훅 함수입니다. 자식 클래스에서 자체 시그니처로 오버라이드하여 구현합니다.

Name	Type	Description
`args`	any	repeatable 자식 클래스에서 정의하는 인자들

Type Definitions

U3dLayerCOobject

~extends U3dObject~U3dObjectCO
U3dLayer 생성자 옵션입니다. 모든 항목이 선택이며, 레이어 범위는 rectangle, extent, geoExtent 순서로 먼저 지정된 하나만 사용합니다.

Properties:

Name	Type	Argument	Default	Description
`cache`	boolean	<optional>	true	타일 메시를 키별로 보관하는 캐시를 사용할지 여부. false면 `getCache()` 계열이 항상 undefined/빈 값을 반환합니다
`classType`	string	<optional>	'U3dLayer'	메시지와 메타데이터에 표시할 클래스 이름
`visible`	boolean	<optional>	false	생성 직후 화면에 표시할지 여부
`crs`	string	<optional>	'EPSG:3857'	레이어 데이터의 좌표계 코드
`ext`	string	<optional>	'.png'	타일 데이터 파일 확장자
`tileName`	string	<optional>	'TEXTURE'	레이어를 연결할 타일 프로세스 종류(`UDEF.PROCESS.TYPE`의 값). TEXTURE(영상), HEIGHT(지형 높이), MODEL(3D 모델), USER·MEASURE(사용자 프로세스)
`minLevel`	number	<optional>	0	타일을 표시하는 최소 레벨(줌 단계). 이보다 낮은 레벨에서는 범위 판정이 항상 false입니다
`maxLevel`	number	<optional>	19	타일을 표시하는 최대 레벨(줌 단계)
`renderOrder`	number	<optional>		랜더링 우선순위. 클수록 나중에 그려져 위에 보이며, 생략하면 생성 순서대로 증가하는 값이 자동 부여됩니다
`opacity`	number	<optional>	1	레이어 투명도. 0(완전 투명)~1(불투명)이며 1보다 작으면 반투명 레이어로 처리됩니다
`opacityDist`	number	<optional>	0.02	객체 출력 애니메이션에서 프레임마다 바뀌는 투명도 변화량(0~1 단위)
`animation`	boolean	<optional>	false	객체가 나타날 때 투명도 애니메이션을 사용할지 여부
`baseUrl`	string	<optional>		타일·데이터 요청의 기준 URL (camelCase)
`isDeBug`	boolean	<optional>	false	디버그 모드 여부. 하위 레이어가 디버그용 추가 처리를 할지 판단하는 데 사용합니다
`debugLog`	boolean	<optional>	false	성능 측정 로그 사용 여부
`debugLogLimit`	number	<optional>	500	하위 레이어가 메모리에 보관할 디버그 로그의 최대 개수. 0 이하이거나 숫자가 아니면 500으로 교정됩니다
`rectangle`	UGeoRect	<optional>		레이어 범위(월드 좌표 EPSG:3857의 직사각형). 지정하면 `extent`, `geoExtent`는 무시됩니다
`extent`	Array.<number>	<optional>		레이어 범위를 월드 좌표(EPSG:3857) 배열 `[minX, minY, maxX, maxY]`로 지정
`geoExtent`	Array.<number>	<optional>		레이어 범위를 위경도(EPSG:4326) 배열 `[minLon, minLat, maxLon, maxLat]`로 지정
`rectangle3d`	UGeoRect	<optional>		직사각형 범위(3D)
`groupLayer`	U3dGroupLayer	<optional>		이 레이어를 자식으로 갖는 부모 그룹 레이어
`useShadowUpdate`	boolean	<optional>	true	앱의 그림자 갱신 순회에 포함할지 여부
`type`	string	<optional>	'none'	레이어 종류 문자열. 이 클래스는 해석하지 않으며 앱·하위 레이어가 분류에 사용합니다

U3dLayerEMIobject

U3dLayer가 dispatch하는 이벤트 이름 모음(U3dLayerEMD, U3dLayer.EVENT)의 형식입니다. 각 값은 on()/once()에 넘기는 이벤트 종류 문자열입니다.

Properties:

Name	Type	Description
`CREATE`	string	레이어 생성 시 호출 layer-create
`LOADED`	string	레이어 작업 완료 시 호출 layer-loaded
`UPDATE`	string	레이어 update 실행 시 호출 layer-update
`BEFORE_DISPOSE`	string	레이어 삭제 전 호출 layer-before-dispose
`DISPOSE`	string	레이어 삭제 완료 후 호출 layer-dispose
`SHOW`	string	레이어 visible 속성이 true로 변경 시 호출 layer-show
`HIDE`	string	레이어 visible 속성이 false로 변경 시 호출 layer-hide