comment cleanup and enum renaming for API use

2025-12-11 07:35:37 -06:00
parent 895e04b7cc
commit ec59a5f754
29 changed files with 35 additions and 119 deletions
@@ -39,10 +39,6 @@ package com.seibel.distanthorizons.api.enums;
 */
 public enum EDhApiDetailLevel
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
 	/**
 	 * detail level: 0 <Br>
 	 * width in Blocks: 1
@@ -28,10 +28,6 @@ package com.seibel.distanthorizons.api.enums.config;
 */
 public enum EDhApiBlocksToAvoid
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
 	NONE(false),
 	NON_COLLIDING(true);
 	
@@ -23,6 +23,7 @@ package com.seibel.distanthorizons.api.enums.config;
 * UNCOMPRESSED <br>
 * LZ4 <br>
 * Z_STD <br>
+ * Z_STD_STREAM <br>
 * LZMA2 <br><br>
 * 
 * Note: speed and compression ratios are examples
@@ -33,10 +34,6 @@ package com.seibel.distanthorizons.api.enums.config;
 */
 public enum EDhApiDataCompressionMode
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
 	/** 
 	 * Should only be used internally and for unit testing. <br><br> 
 	 * 
@@ -57,28 +54,32 @@ public enum EDhApiDataCompressionMode
 	LZ4(1),
 	
 	/**
-	 * Decent speed and good compression. <br><br> 
+	 * Great speed and good compression. <br><br> 
 	 *
+	 * Read Speed: 2.1 MS / DTO <br>
+	 * Write Speed: 4.9 MS / DTO <br>
+	 * Compression ratio: 0.2606 <br>
+	 */
+	Z_STD_BLOCK(4),
+	
+	/**
+	 * Similar to {@link EDhApiDataCompressionMode#Z_STD_BLOCK}
+	 * except slower. <br><br>
+	 * 
+	 * This option is only provided for legacy support when processing old databases. <br><br>
+	 * 
 	 * Read Speed: 9.31 MS / DTO <br>
 	 * Write Speed: 15.13 MS / DTO <br>
 	 * Compression ratio: 0.2606 <br>
 	 */
-	Z_STD(4),
-	
-	/**
-	 * Similar to {@link EDhApiDataCompressionMode#Z_STD}
-	 * except slower.
-	 * <br>
-	 * This option is only provided for legacy support when processing old databases.
-	 */
 	@Deprecated
 	@DisallowSelectingViaConfigGui
 	Z_STD_STREAM(2),
 	
-	
 	/** 
-	 * Extremely slow, but very good compression. <br><br> 
-	 *
+	 * Extremely slow, but very good compression. <br>
+	 * Often causes whole computer stuttering due to memory bandwidth saturation. <br><br>
+	 * 
 	 * Read Speed: 13.29 MS / DTO <br>
 	 * Write Speed: 70.95 MS / DTO <br>
 	 * Compression ratio: 0.2068 <br>
@@ -44,9 +44,9 @@ public enum EDhApiGpuUploadMethod
 	/** Fast rendering but may stutter when uploading. */
 	SUB_DATA(false, false),
 	
-	/** Don't upload, only should be used for debugging */
-	@Deprecated // TODO remove before release
-	NONE(false, false),
+	///** Don't upload, only should be used for debugging */
+	//@Deprecated
+	//NONE(false, false),
 	
 	/**
 	 * May end up storing buffers in System memory. <br>
@@ -29,10 +29,6 @@ package com.seibel.distanthorizons.api.enums.config;
 */
 public enum EDhApiGrassSideRendering
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
 	AS_GRASS,
 	FADE_TO_DIRT,
 	AS_DIRT;
@@ -31,11 +31,6 @@ package com.seibel.distanthorizons.api.enums.config;
 */
 public enum EDhApiHorizontalQuality
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
-	
 	// Note: any quadraticBase less than 2.0f has issues with DetailDistanceUtil, and will always return the lowest detail level.
 	//  So for now we are limiting the lowest value to 2.0
 	//  LOWEST was originally 1.0f and LOW was 1.5f
@@ -29,10 +29,6 @@ package com.seibel.distanthorizons.api.enums.config;
 */
 public enum EDhApiLodShading
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
 	/** 
 	 * Uses Minecraft's shading for LODs. <Br>
 	 * This means if Minecraft's shading is disabled DH's shading will be as well.
@@ -33,10 +33,6 @@ package com.seibel.distanthorizons.api.enums.config;
 */
 public enum EDhApiMcRenderingFadeMode
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
 	/**
 	 * No fading is done, there will be a pronounced border between
 	 * Minecraft and Distant Horizons. <br>
@@ -35,11 +35,6 @@ package com.seibel.distanthorizons.api.enums.config;
 */
 public enum EDhApiServerFolderNameMode
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
-	
 	/** Only use the server name */
 	NAME_ONLY,
 	
@@ -34,11 +34,6 @@ package com.seibel.distanthorizons.api.enums.config;
@Deprecated // not currently in use, if the config this enum represents is re-implemented, the deprecated flag can be removed
 public enum EDhApiVanillaOverdraw
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
-	
 	/**
 	 * Don't draw LODs where a minecraft chunk could be.
 	 * Use Overdraw Offset to tweak the border thickness.
@@ -28,10 +28,6 @@ package com.seibel.distanthorizons.api.enums.config;
 */
 public enum EDhApiWorldCompressionMode
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
 	/** 
 	 * Every block/biome change is recorded in the database. <br>
 	 * This is what DH 2.0 and 2.0.1 all used by default and will store a lot of data. 
@@ -35,10 +35,6 @@ import com.seibel.distanthorizons.api.enums.config.DisallowSelectingViaConfigGui
 */
 public enum EDhApiQualityPreset
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
 	@DisallowSelectingViaConfigGui
 	CUSTOM,
 	
@@ -34,10 +34,6 @@ import com.seibel.distanthorizons.api.enums.config.DisallowSelectingViaConfigGui
 */
 public enum EDhApiThreadPreset
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
 	@DisallowSelectingViaConfigGui
 	CUSTOM,
 	
@@ -33,11 +33,6 @@ package com.seibel.distanthorizons.api.enums.rendering;
 */
 public enum EDhApiDebugRendering
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
-	
 	/** LODs are rendered normally */
 	OFF,
 	
@@ -33,10 +33,6 @@ package com.seibel.distanthorizons.api.enums.rendering;
@Deprecated
 public enum EDhApiFogDrawMode
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
 	/**
 	 * Use whatever Fog setting Optifine is using.
 	 * If Optifine isn't installed this defaults to {@link EDhApiFogDrawMode#FOG_ENABLED}.
@@ -30,11 +30,6 @@ package com.seibel.distanthorizons.api.enums.rendering;
 */
 public enum EDhApiFogFalloff
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
-	
 	LINEAR(0),
 	EXPONENTIAL(1),
 	EXPONENTIAL_SQUARED(2);
@@ -33,11 +33,6 @@ package com.seibel.distanthorizons.api.enums.rendering;
 */
 public enum EDhApiHeightFogDirection
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
-	
 	ABOVE_CAMERA                (true,  true,  false),
 	BELOW_CAMERA                (true,  false, true),
 	ABOVE_AND_BELOW_CAMERA      (true,  true,  true),
@@ -29,11 +29,6 @@ package com.seibel.distanthorizons.api.enums.rendering;
 */
 public enum EDhApiRendererMode
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
-	
 	DEFAULT,
 	DEBUG,
 	DISABLED;
@@ -29,11 +29,6 @@ package com.seibel.distanthorizons.api.enums.rendering;
 */
 public enum EDhApiTransparency
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
-	
 	DISABLED(false, false),
 	FAKE(true, true),
 	COMPLETE(true, false);
@@ -34,11 +34,6 @@ package com.seibel.distanthorizons.api.enums.worldGeneration;
 */
 public enum EDhApiDistantGeneratorMode
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
-	
 	/** Don't generate any new terrain, just generate LODs for already generated chunks. */
 	PRE_EXISTING_ONLY((byte) 1),
 	
@@ -31,11 +31,6 @@ package com.seibel.distanthorizons.api.enums.worldGeneration;
 */
 public enum EDhApiDistantGeneratorProgressDisplayLocation
 {
-	// Reminder:
-	// when adding items up the API minor version
-	// when removing items up the API major version
-	
-	
 	OVERLAY,
 	CHAT,
 	LOG,
@@ -161,6 +161,11 @@ public interface IDhApiTerrainDataRepo
 	//=========//
 	
 	/** 
+	 * Creates a new cache you manage that can be used to speed up repeat
+	 * read operations. <br>
+	 * Without a cache each operation must: hit the backing database file,
+	 * decompress it, and parse it; which is a fairly slow process. <br>
+	 * 
 	 * @return a {@link IDhApiTerrainDataCache} backed by {@link java.lang.ref.SoftReference}'s.
 	 * @since API 5.0.0
 	 */
@@ -31,7 +31,7 @@ import java.util.List;
 * Contains a list of {@link DhApiTerrainDataPoint} representing the blocks in a Minecraft chunk.
 *
 * @author Builderb0y, James Seibel
- * @version 2024-7-21
+ * @version 2025-12-11
 * @since API 2.0.0
 * 
 * @see IDhApiWrapperFactory