ClippingPlaneCollection.js 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764
  1. import AttributeCompression from "../Core/AttributeCompression.js";
  2. import Cartesian2 from "../Core/Cartesian2.js";
  3. import Cartesian3 from "../Core/Cartesian3.js";
  4. import Cartesian4 from "../Core/Cartesian4.js";
  5. import Check from "../Core/Check.js";
  6. import Color from "../Core/Color.js";
  7. import defaultValue from "../Core/defaultValue.js";
  8. import defined from "../Core/defined.js";
  9. import destroyObject from "../Core/destroyObject.js";
  10. import DeveloperError from "../Core/DeveloperError.js";
  11. import Event from "../Core/Event.js";
  12. import Intersect from "../Core/Intersect.js";
  13. import Matrix4 from "../Core/Matrix4.js";
  14. import PixelFormat from "../Core/PixelFormat.js";
  15. import Plane from "../Core/Plane.js";
  16. import ContextLimits from "../Renderer/ContextLimits.js";
  17. import PixelDatatype from "../Renderer/PixelDatatype.js";
  18. import Sampler from "../Renderer/Sampler.js";
  19. import Texture from "../Renderer/Texture.js";
  20. import ClippingPlane from "./ClippingPlane.js";
  21. /**
  22. * Specifies a set of clipping planes. Clipping planes selectively disable rendering in a region on the
  23. * outside of the specified list of {@link ClippingPlane} objects for a single gltf model, 3D Tileset, or the globe.
  24. * <p>
  25. * In general the clipping planes' coordinates are relative to the object they're attached to, so a plane with distance set to 0 will clip
  26. * through the center of the object.
  27. * </p>
  28. * <p>
  29. * For 3D Tiles, the root tile's transform is used to position the clipping planes. If a transform is not defined, the root tile's {@link Cesium3DTile#boundingSphere} is used instead.
  30. * </p>
  31. *
  32. * @alias ClippingPlaneCollection
  33. * @constructor
  34. *
  35. * @param {Object} [options] Object with the following properties:
  36. * @param {ClippingPlane[]} [options.planes=[]] An array of {@link ClippingPlane} objects used to selectively disable rendering on the outside of each plane.
  37. * @param {Boolean} [options.enabled=true] Determines whether the clipping planes are active.
  38. * @param {Matrix4} [options.modelMatrix=Matrix4.IDENTITY] The 4x4 transformation matrix specifying an additional transform relative to the clipping planes original coordinate system.
  39. * @param {Boolean} [options.unionClippingRegions=false] If true, a region will be clipped if it is on the outside of any plane in the collection. Otherwise, a region will only be clipped if it is on the outside of every plane.
  40. * @param {Color} [options.edgeColor=Color.WHITE] The color applied to highlight the edge along which an object is clipped.
  41. * @param {Number} [options.edgeWidth=0.0] The width, in pixels, of the highlight applied to the edge along which an object is clipped.
  42. *
  43. * @demo {@link https://sandcastle.cesium.com/?src=3D%20Tiles%20Clipping%20Planes.html|Clipping 3D Tiles and glTF models.}
  44. * @demo {@link https://sandcastle.cesium.com/?src=Terrain%20Clipping%20Planes.html|Clipping the Globe.}
  45. *
  46. * @example
  47. * // This clipping plane's distance is positive, which means its normal
  48. * // is facing the origin. This will clip everything that is behind
  49. * // the plane, which is anything with y coordinate < -5.
  50. * var clippingPlanes = new Cesium.ClippingPlaneCollection({
  51. * planes : [
  52. * new Cesium.ClippingPlane(new Cesium.Cartesian3(0.0, 1.0, 0.0), 5.0)
  53. * ],
  54. * });
  55. * // Create an entity and attach the ClippingPlaneCollection to the model.
  56. * var entity = viewer.entities.add({
  57. * position : Cesium.Cartesian3.fromDegrees(-123.0744619, 44.0503706, 10000),
  58. * model : {
  59. * uri : 'model.gltf',
  60. * minimumPixelSize : 128,
  61. * maximumScale : 20000,
  62. * clippingPlanes : clippingPlanes
  63. * }
  64. * });
  65. * viewer.zoomTo(entity);
  66. */
  67. function ClippingPlaneCollection(options) {
  68. options = defaultValue(options, defaultValue.EMPTY_OBJECT);
  69. this._planes = [];
  70. // Do partial texture updates if just one plane is dirty.
  71. // If many planes are dirty, refresh the entire texture.
  72. this._dirtyIndex = -1;
  73. this._multipleDirtyPlanes = false;
  74. this._enabled = defaultValue(options.enabled, true);
  75. /**
  76. * The 4x4 transformation matrix specifying an additional transform relative to the clipping planes
  77. * original coordinate system.
  78. *
  79. * @type {Matrix4}
  80. * @default Matrix4.IDENTITY
  81. */
  82. this.modelMatrix = Matrix4.clone(
  83. defaultValue(options.modelMatrix, Matrix4.IDENTITY)
  84. );
  85. /**
  86. * The color applied to highlight the edge along which an object is clipped.
  87. *
  88. * @type {Color}
  89. * @default Color.WHITE
  90. */
  91. this.edgeColor = Color.clone(defaultValue(options.edgeColor, Color.WHITE));
  92. /**
  93. * The width, in pixels, of the highlight applied to the edge along which an object is clipped.
  94. *
  95. * @type {Number}
  96. * @default 0.0
  97. */
  98. this.edgeWidth = defaultValue(options.edgeWidth, 0.0);
  99. /**
  100. * An event triggered when a new clipping plane is added to the collection. Event handlers
  101. * are passed the new plane and the index at which it was added.
  102. * @type {Event}
  103. * @default Event()
  104. */
  105. this.planeAdded = new Event();
  106. /**
  107. * An event triggered when a new clipping plane is removed from the collection. Event handlers
  108. * are passed the new plane and the index from which it was removed.
  109. * @type {Event}
  110. * @default Event()
  111. */
  112. this.planeRemoved = new Event();
  113. // If this ClippingPlaneCollection has an owner, only its owner should update or destroy it.
  114. // This is because in a Cesium3DTileset multiple models may reference the tileset's ClippingPlaneCollection.
  115. this._owner = undefined;
  116. var unionClippingRegions = defaultValue(options.unionClippingRegions, false);
  117. this._unionClippingRegions = unionClippingRegions;
  118. this._testIntersection = unionClippingRegions
  119. ? unionIntersectFunction
  120. : defaultIntersectFunction;
  121. this._uint8View = undefined;
  122. this._float32View = undefined;
  123. this._clippingPlanesTexture = undefined;
  124. // Add each ClippingPlane object.
  125. var planes = options.planes;
  126. if (defined(planes)) {
  127. var planesLength = planes.length;
  128. for (var i = 0; i < planesLength; ++i) {
  129. this.add(planes[i]);
  130. }
  131. }
  132. }
  133. function unionIntersectFunction(value) {
  134. return value === Intersect.OUTSIDE;
  135. }
  136. function defaultIntersectFunction(value) {
  137. return value === Intersect.INSIDE;
  138. }
  139. Object.defineProperties(ClippingPlaneCollection.prototype, {
  140. /**
  141. * Returns the number of planes in this collection. This is commonly used with
  142. * {@link ClippingPlaneCollection#get} to iterate over all the planes
  143. * in the collection.
  144. *
  145. * @memberof ClippingPlaneCollection.prototype
  146. * @type {Number}
  147. * @readonly
  148. */
  149. length: {
  150. get: function () {
  151. return this._planes.length;
  152. },
  153. },
  154. /**
  155. * If true, a region will be clipped if it is on the outside of any plane in the
  156. * collection. Otherwise, a region will only be clipped if it is on the
  157. * outside of every plane.
  158. *
  159. * @memberof ClippingPlaneCollection.prototype
  160. * @type {Boolean}
  161. * @default false
  162. */
  163. unionClippingRegions: {
  164. get: function () {
  165. return this._unionClippingRegions;
  166. },
  167. set: function (value) {
  168. if (this._unionClippingRegions === value) {
  169. return;
  170. }
  171. this._unionClippingRegions = value;
  172. this._testIntersection = value
  173. ? unionIntersectFunction
  174. : defaultIntersectFunction;
  175. },
  176. },
  177. /**
  178. * If true, clipping will be enabled.
  179. *
  180. * @memberof ClippingPlaneCollection.prototype
  181. * @type {Boolean}
  182. * @default true
  183. */
  184. enabled: {
  185. get: function () {
  186. return this._enabled;
  187. },
  188. set: function (value) {
  189. if (this._enabled === value) {
  190. return;
  191. }
  192. this._enabled = value;
  193. },
  194. },
  195. /**
  196. * Returns a texture containing packed, untransformed clipping planes.
  197. *
  198. * @memberof ClippingPlaneCollection.prototype
  199. * @type {Texture}
  200. * @readonly
  201. * @private
  202. */
  203. texture: {
  204. get: function () {
  205. return this._clippingPlanesTexture;
  206. },
  207. },
  208. /**
  209. * A reference to the ClippingPlaneCollection's owner, if any.
  210. *
  211. * @memberof ClippingPlaneCollection.prototype
  212. * @readonly
  213. * @private
  214. */
  215. owner: {
  216. get: function () {
  217. return this._owner;
  218. },
  219. },
  220. /**
  221. * Returns a Number encapsulating the state for this ClippingPlaneCollection.
  222. *
  223. * Clipping mode is encoded in the sign of the number, which is just the plane count.
  224. * Used for checking if shader regeneration is necessary.
  225. *
  226. * @memberof ClippingPlaneCollection.prototype
  227. * @returns {Number} A Number that describes the ClippingPlaneCollection's state.
  228. * @readonly
  229. * @private
  230. */
  231. clippingPlanesState: {
  232. get: function () {
  233. return this._unionClippingRegions
  234. ? this._planes.length
  235. : -this._planes.length;
  236. },
  237. },
  238. });
  239. function setIndexDirty(collection, index) {
  240. // If there's already a different _dirtyIndex set, more than one plane has changed since update.
  241. // Entire texture must be reloaded
  242. collection._multipleDirtyPlanes =
  243. collection._multipleDirtyPlanes ||
  244. (collection._dirtyIndex !== -1 && collection._dirtyIndex !== index);
  245. collection._dirtyIndex = index;
  246. }
  247. /**
  248. * Adds the specified {@link ClippingPlane} to the collection to be used to selectively disable rendering
  249. * on the outside of each plane. Use {@link ClippingPlaneCollection#unionClippingRegions} to modify
  250. * how modify the clipping behavior of multiple planes.
  251. *
  252. * @param {ClippingPlane} plane The ClippingPlane to add to the collection.
  253. *
  254. * @see ClippingPlaneCollection#unionClippingRegions
  255. * @see ClippingPlaneCollection#remove
  256. * @see ClippingPlaneCollection#removeAll
  257. */
  258. ClippingPlaneCollection.prototype.add = function (plane) {
  259. var newPlaneIndex = this._planes.length;
  260. var that = this;
  261. plane.onChangeCallback = function (index) {
  262. setIndexDirty(that, index);
  263. };
  264. plane.index = newPlaneIndex;
  265. setIndexDirty(this, newPlaneIndex);
  266. this._planes.push(plane);
  267. this.planeAdded.raiseEvent(plane, newPlaneIndex);
  268. };
  269. /**
  270. * Returns the plane in the collection at the specified index. Indices are zero-based
  271. * and increase as planes are added. Removing a plane shifts all planes after
  272. * it to the left, changing their indices. This function is commonly used with
  273. * {@link ClippingPlaneCollection#length} to iterate over all the planes
  274. * in the collection.
  275. *
  276. * @param {Number} index The zero-based index of the plane.
  277. * @returns {ClippingPlane} The ClippingPlane at the specified index.
  278. *
  279. * @see ClippingPlaneCollection#length
  280. */
  281. ClippingPlaneCollection.prototype.get = function (index) {
  282. //>>includeStart('debug', pragmas.debug);
  283. Check.typeOf.number("index", index);
  284. //>>includeEnd('debug');
  285. return this._planes[index];
  286. };
  287. function indexOf(planes, plane) {
  288. var length = planes.length;
  289. for (var i = 0; i < length; ++i) {
  290. if (Plane.equals(planes[i], plane)) {
  291. return i;
  292. }
  293. }
  294. return -1;
  295. }
  296. /**
  297. * Checks whether this collection contains a ClippingPlane equal to the given ClippingPlane.
  298. *
  299. * @param {ClippingPlane} [clippingPlane] The ClippingPlane to check for.
  300. * @returns {Boolean} true if this collection contains the ClippingPlane, false otherwise.
  301. *
  302. * @see ClippingPlaneCollection#get
  303. */
  304. ClippingPlaneCollection.prototype.contains = function (clippingPlane) {
  305. return indexOf(this._planes, clippingPlane) !== -1;
  306. };
  307. /**
  308. * Removes the first occurrence of the given ClippingPlane from the collection.
  309. *
  310. * @param {ClippingPlane} clippingPlane
  311. * @returns {Boolean} <code>true</code> if the plane was removed; <code>false</code> if the plane was not found in the collection.
  312. *
  313. * @see ClippingPlaneCollection#add
  314. * @see ClippingPlaneCollection#contains
  315. * @see ClippingPlaneCollection#removeAll
  316. */
  317. ClippingPlaneCollection.prototype.remove = function (clippingPlane) {
  318. var planes = this._planes;
  319. var index = indexOf(planes, clippingPlane);
  320. if (index === -1) {
  321. return false;
  322. }
  323. // Unlink this ClippingPlaneCollection from the ClippingPlane
  324. if (clippingPlane instanceof ClippingPlane) {
  325. clippingPlane.onChangeCallback = undefined;
  326. clippingPlane.index = -1;
  327. }
  328. // Shift and update indices
  329. var length = planes.length - 1;
  330. for (var i = index; i < length; ++i) {
  331. var planeToKeep = planes[i + 1];
  332. planes[i] = planeToKeep;
  333. if (planeToKeep instanceof ClippingPlane) {
  334. planeToKeep.index = i;
  335. }
  336. }
  337. // Indicate planes texture is dirty
  338. this._multipleDirtyPlanes = true;
  339. planes.length = length;
  340. this.planeRemoved.raiseEvent(clippingPlane, index);
  341. return true;
  342. };
  343. /**
  344. * Removes all planes from the collection.
  345. *
  346. * @see ClippingPlaneCollection#add
  347. * @see ClippingPlaneCollection#remove
  348. */
  349. ClippingPlaneCollection.prototype.removeAll = function () {
  350. // Dereference this ClippingPlaneCollection from all ClippingPlanes
  351. var planes = this._planes;
  352. var planesCount = planes.length;
  353. for (var i = 0; i < planesCount; ++i) {
  354. var plane = planes[i];
  355. if (plane instanceof ClippingPlane) {
  356. plane.onChangeCallback = undefined;
  357. plane.index = -1;
  358. }
  359. this.planeRemoved.raiseEvent(plane, i);
  360. }
  361. this._multipleDirtyPlanes = true;
  362. this._planes = [];
  363. };
  364. var distanceEncodeScratch = new Cartesian4();
  365. var oct32EncodeScratch = new Cartesian4();
  366. function packPlanesAsUint8(clippingPlaneCollection, startIndex, endIndex) {
  367. var uint8View = clippingPlaneCollection._uint8View;
  368. var planes = clippingPlaneCollection._planes;
  369. var byteIndex = 0;
  370. for (var i = startIndex; i < endIndex; ++i) {
  371. var plane = planes[i];
  372. var oct32Normal = AttributeCompression.octEncodeToCartesian4(
  373. plane.normal,
  374. oct32EncodeScratch
  375. );
  376. uint8View[byteIndex] = oct32Normal.x;
  377. uint8View[byteIndex + 1] = oct32Normal.y;
  378. uint8View[byteIndex + 2] = oct32Normal.z;
  379. uint8View[byteIndex + 3] = oct32Normal.w;
  380. var encodedDistance = Cartesian4.packFloat(
  381. plane.distance,
  382. distanceEncodeScratch
  383. );
  384. uint8View[byteIndex + 4] = encodedDistance.x;
  385. uint8View[byteIndex + 5] = encodedDistance.y;
  386. uint8View[byteIndex + 6] = encodedDistance.z;
  387. uint8View[byteIndex + 7] = encodedDistance.w;
  388. byteIndex += 8;
  389. }
  390. }
  391. // Pack starting at the beginning of the buffer to allow partial update
  392. function packPlanesAsFloats(clippingPlaneCollection, startIndex, endIndex) {
  393. var float32View = clippingPlaneCollection._float32View;
  394. var planes = clippingPlaneCollection._planes;
  395. var floatIndex = 0;
  396. for (var i = startIndex; i < endIndex; ++i) {
  397. var plane = planes[i];
  398. var normal = plane.normal;
  399. float32View[floatIndex] = normal.x;
  400. float32View[floatIndex + 1] = normal.y;
  401. float32View[floatIndex + 2] = normal.z;
  402. float32View[floatIndex + 3] = plane.distance;
  403. floatIndex += 4; // each plane is 4 floats
  404. }
  405. }
  406. function computeTextureResolution(pixelsNeeded, result) {
  407. var maxSize = ContextLimits.maximumTextureSize;
  408. result.x = Math.min(pixelsNeeded, maxSize);
  409. result.y = Math.ceil(pixelsNeeded / result.x);
  410. return result;
  411. }
  412. var textureResolutionScratch = new Cartesian2();
  413. /**
  414. * Called when {@link Viewer} or {@link CesiumWidget} render the scene to
  415. * build the resources for clipping planes.
  416. * <p>
  417. * Do not call this function directly.
  418. * </p>
  419. */
  420. ClippingPlaneCollection.prototype.update = function (frameState) {
  421. var clippingPlanesTexture = this._clippingPlanesTexture;
  422. var context = frameState.context;
  423. var useFloatTexture = ClippingPlaneCollection.useFloatTexture(context);
  424. // Compute texture requirements for current planes
  425. // In RGBA FLOAT, A plane is 4 floats packed to a RGBA.
  426. // In RGBA UNSIGNED_BYTE, A plane is a float in [0, 1) packed to RGBA and an Oct32 quantized normal,
  427. // so 8 bits or 2 pixels in RGBA.
  428. var pixelsNeeded = useFloatTexture ? this.length : this.length * 2;
  429. if (defined(clippingPlanesTexture)) {
  430. var currentPixelCount =
  431. clippingPlanesTexture.width * clippingPlanesTexture.height;
  432. // Recreate the texture to double current requirement if it isn't big enough or is 4 times larger than it needs to be.
  433. // Optimization note: this isn't exactly the classic resizeable array algorithm
  434. // * not necessarily checking for resize after each add/remove operation
  435. // * random-access deletes instead of just pops
  436. // * alloc ops likely more expensive than demonstrable via big-O analysis
  437. if (
  438. currentPixelCount < pixelsNeeded ||
  439. pixelsNeeded < 0.25 * currentPixelCount
  440. ) {
  441. clippingPlanesTexture.destroy();
  442. clippingPlanesTexture = undefined;
  443. this._clippingPlanesTexture = undefined;
  444. }
  445. }
  446. // If there are no clipping planes, there's nothing to update.
  447. if (this.length === 0) {
  448. return;
  449. }
  450. if (!defined(clippingPlanesTexture)) {
  451. var requiredResolution = computeTextureResolution(
  452. pixelsNeeded,
  453. textureResolutionScratch
  454. );
  455. // Allocate twice as much space as needed to avoid frequent texture reallocation.
  456. // Allocate in the Y direction, since texture may be as wide as context texture support.
  457. requiredResolution.y *= 2;
  458. if (useFloatTexture) {
  459. clippingPlanesTexture = new Texture({
  460. context: context,
  461. width: requiredResolution.x,
  462. height: requiredResolution.y,
  463. pixelFormat: PixelFormat.RGBA,
  464. pixelDatatype: PixelDatatype.FLOAT,
  465. sampler: Sampler.NEAREST,
  466. flipY: false,
  467. });
  468. this._float32View = new Float32Array(
  469. requiredResolution.x * requiredResolution.y * 4
  470. );
  471. } else {
  472. clippingPlanesTexture = new Texture({
  473. context: context,
  474. width: requiredResolution.x,
  475. height: requiredResolution.y,
  476. pixelFormat: PixelFormat.RGBA,
  477. pixelDatatype: PixelDatatype.UNSIGNED_BYTE,
  478. sampler: Sampler.NEAREST,
  479. flipY: false,
  480. });
  481. this._uint8View = new Uint8Array(
  482. requiredResolution.x * requiredResolution.y * 4
  483. );
  484. }
  485. this._clippingPlanesTexture = clippingPlanesTexture;
  486. this._multipleDirtyPlanes = true;
  487. }
  488. var dirtyIndex = this._dirtyIndex;
  489. if (!this._multipleDirtyPlanes && dirtyIndex === -1) {
  490. return;
  491. }
  492. if (!this._multipleDirtyPlanes) {
  493. // partial updates possible
  494. var offsetX = 0;
  495. var offsetY = 0;
  496. if (useFloatTexture) {
  497. offsetY = Math.floor(dirtyIndex / clippingPlanesTexture.width);
  498. offsetX = Math.floor(dirtyIndex - offsetY * clippingPlanesTexture.width);
  499. packPlanesAsFloats(this, dirtyIndex, dirtyIndex + 1);
  500. clippingPlanesTexture.copyFrom(
  501. {
  502. width: 1,
  503. height: 1,
  504. arrayBufferView: this._float32View,
  505. },
  506. offsetX,
  507. offsetY
  508. );
  509. } else {
  510. offsetY = Math.floor((dirtyIndex * 2) / clippingPlanesTexture.width);
  511. offsetX = Math.floor(
  512. dirtyIndex * 2 - offsetY * clippingPlanesTexture.width
  513. );
  514. packPlanesAsUint8(this, dirtyIndex, dirtyIndex + 1);
  515. clippingPlanesTexture.copyFrom(
  516. {
  517. width: 2,
  518. height: 1,
  519. arrayBufferView: this._uint8View,
  520. },
  521. offsetX,
  522. offsetY
  523. );
  524. }
  525. } else if (useFloatTexture) {
  526. packPlanesAsFloats(this, 0, this._planes.length);
  527. clippingPlanesTexture.copyFrom({
  528. width: clippingPlanesTexture.width,
  529. height: clippingPlanesTexture.height,
  530. arrayBufferView: this._float32View,
  531. });
  532. } else {
  533. packPlanesAsUint8(this, 0, this._planes.length);
  534. clippingPlanesTexture.copyFrom({
  535. width: clippingPlanesTexture.width,
  536. height: clippingPlanesTexture.height,
  537. arrayBufferView: this._uint8View,
  538. });
  539. }
  540. this._multipleDirtyPlanes = false;
  541. this._dirtyIndex = -1;
  542. };
  543. var scratchMatrix = new Matrix4();
  544. var scratchPlane = new Plane(Cartesian3.UNIT_X, 0.0);
  545. /**
  546. * Determines the type intersection with the planes of this ClippingPlaneCollection instance and the specified {@link TileBoundingVolume}.
  547. * @private
  548. *
  549. * @param {Object} tileBoundingVolume The volume to determine the intersection with the planes.
  550. * @param {Matrix4} [transform] An optional, additional matrix to transform the plane to world coordinates.
  551. * @returns {Intersect} {@link Intersect.INSIDE} if the entire volume is on the side of the planes
  552. * the normal is pointing and should be entirely rendered, {@link Intersect.OUTSIDE}
  553. * if the entire volume is on the opposite side and should be clipped, and
  554. * {@link Intersect.INTERSECTING} if the volume intersects the planes.
  555. */
  556. ClippingPlaneCollection.prototype.computeIntersectionWithBoundingVolume = function (
  557. tileBoundingVolume,
  558. transform
  559. ) {
  560. var planes = this._planes;
  561. var length = planes.length;
  562. var modelMatrix = this.modelMatrix;
  563. if (defined(transform)) {
  564. modelMatrix = Matrix4.multiply(transform, modelMatrix, scratchMatrix);
  565. }
  566. // If the collection is not set to union the clipping regions, the volume must be outside of all planes to be
  567. // considered completely clipped. If the collection is set to union the clipping regions, if the volume can be
  568. // outside any the planes, it is considered completely clipped.
  569. // Lastly, if not completely clipped, if any plane is intersecting, more calculations must be performed.
  570. var intersection = Intersect.INSIDE;
  571. if (!this.unionClippingRegions && length > 0) {
  572. intersection = Intersect.OUTSIDE;
  573. }
  574. for (var i = 0; i < length; ++i) {
  575. var plane = planes[i];
  576. Plane.transform(plane, modelMatrix, scratchPlane); // ClippingPlane can be used for Plane math
  577. var value = tileBoundingVolume.intersectPlane(scratchPlane);
  578. if (value === Intersect.INTERSECTING) {
  579. intersection = value;
  580. } else if (this._testIntersection(value)) {
  581. return value;
  582. }
  583. }
  584. return intersection;
  585. };
  586. /**
  587. * Sets the owner for the input ClippingPlaneCollection if there wasn't another owner.
  588. * Destroys the owner's previous ClippingPlaneCollection if setting is successful.
  589. *
  590. * @param {ClippingPlaneCollection} [clippingPlaneCollection] A ClippingPlaneCollection (or undefined) being attached to an object
  591. * @param {Object} owner An Object that should receive the new ClippingPlaneCollection
  592. * @param {String} key The Key for the Object to reference the ClippingPlaneCollection
  593. * @private
  594. */
  595. ClippingPlaneCollection.setOwner = function (
  596. clippingPlaneCollection,
  597. owner,
  598. key
  599. ) {
  600. // Don't destroy the ClippingPlaneCollection if it is already owned by newOwner
  601. if (clippingPlaneCollection === owner[key]) {
  602. return;
  603. }
  604. // Destroy the existing ClippingPlaneCollection, if any
  605. owner[key] = owner[key] && owner[key].destroy();
  606. if (defined(clippingPlaneCollection)) {
  607. //>>includeStart('debug', pragmas.debug);
  608. if (defined(clippingPlaneCollection._owner)) {
  609. throw new DeveloperError(
  610. "ClippingPlaneCollection should only be assigned to one object"
  611. );
  612. }
  613. //>>includeEnd('debug');
  614. clippingPlaneCollection._owner = owner;
  615. owner[key] = clippingPlaneCollection;
  616. }
  617. };
  618. /**
  619. * Function for checking if the context will allow clipping planes with floating point textures.
  620. *
  621. * @param {Context} context The Context that will contain clipped objects and clipping textures.
  622. * @returns {Boolean} <code>true</code> if floating point textures can be used for clipping planes.
  623. * @private
  624. */
  625. ClippingPlaneCollection.useFloatTexture = function (context) {
  626. return context.floatingPointTexture;
  627. };
  628. /**
  629. * Function for getting the clipping plane collection's texture resolution.
  630. * If the ClippingPlaneCollection hasn't been updated, returns the resolution that will be
  631. * allocated based on the current plane count.
  632. *
  633. * @param {ClippingPlaneCollection} clippingPlaneCollection The clipping plane collection
  634. * @param {Context} context The rendering context
  635. * @param {Cartesian2} result A Cartesian2 for the result.
  636. * @returns {Cartesian2} The required resolution.
  637. * @private
  638. */
  639. ClippingPlaneCollection.getTextureResolution = function (
  640. clippingPlaneCollection,
  641. context,
  642. result
  643. ) {
  644. var texture = clippingPlaneCollection.texture;
  645. if (defined(texture)) {
  646. result.x = texture.width;
  647. result.y = texture.height;
  648. return result;
  649. }
  650. var pixelsNeeded = ClippingPlaneCollection.useFloatTexture(context)
  651. ? clippingPlaneCollection.length
  652. : clippingPlaneCollection.length * 2;
  653. var requiredResolution = computeTextureResolution(pixelsNeeded, result);
  654. // Allocate twice as much space as needed to avoid frequent texture reallocation.
  655. requiredResolution.y *= 2;
  656. return requiredResolution;
  657. };
  658. /**
  659. * Returns true if this object was destroyed; otherwise, false.
  660. * <br /><br />
  661. * If this object was destroyed, it should not be used; calling any function other than
  662. * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.
  663. *
  664. * @returns {Boolean} <code>true</code> if this object was destroyed; otherwise, <code>false</code>.
  665. *
  666. * @see ClippingPlaneCollection#destroy
  667. */
  668. ClippingPlaneCollection.prototype.isDestroyed = function () {
  669. return false;
  670. };
  671. /**
  672. * Destroys the WebGL resources held by this object. Destroying an object allows for deterministic
  673. * release of WebGL resources, instead of relying on the garbage collector to destroy this object.
  674. * <br /><br />
  675. * Once an object is destroyed, it should not be used; calling any function other than
  676. * <code>isDestroyed</code> will result in a {@link DeveloperError} exception. Therefore,
  677. * assign the return value (<code>undefined</code>) to the object as done in the example.
  678. *
  679. * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
  680. *
  681. *
  682. * @example
  683. * clippingPlanes = clippingPlanes && clippingPlanes .destroy();
  684. *
  685. * @see ClippingPlaneCollection#isDestroyed
  686. */
  687. ClippingPlaneCollection.prototype.destroy = function () {
  688. this._clippingPlanesTexture =
  689. this._clippingPlanesTexture && this._clippingPlanesTexture.destroy();
  690. return destroyObject(this);
  691. };
  692. export default ClippingPlaneCollection;