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
@@ -1431,7 +1431,7 @@ public class Config
 					.build();
 			
 			public static ConfigEntry<EDhApiDataCompressionMode> dataCompression = new ConfigEntry.Builder<EDhApiDataCompressionMode>()
-					.set(EDhApiDataCompressionMode.Z_STD)
+					.set(EDhApiDataCompressionMode.Z_STD_BLOCK)
 					// only visible via the API since there is no reason to use any compressor except ZStandard as of 2025-11-24
 					.setAppearance(EConfigEntryAppearance.ONLY_IN_API)
 					.build();
@@ -198,8 +198,8 @@ public class GLBuffer implements AutoCloseable
 		
 		switch (uploadMethod)
 		{
-			case NONE:
-				return;
+			//case NONE:
+			//	return;
 			case AUTO:
 				LodUtil.assertNotReach("GpuUploadMethod AUTO must be resolved before call to uploadBuffer()!");
 			case BUFFER_STORAGE:
@@ -26,7 +26,6 @@ import com.seibel.distanthorizons.api.enums.config.EDhApiDataCompressionMode;
 import com.seibel.distanthorizons.core.logging.DhLoggerBuilder;
 import it.unimi.dsi.fastutil.bytes.ByteArrayList;
 import net.jpountz.lz4.LZ4FrameInputStream;
-import org.apache.logging.log4j.LogManager;
 import com.seibel.distanthorizons.core.logging.DhLogger;
 import org.tukaani.xz.ResettableArrayCache;
 import org.tukaani.xz.XZInputStream;
@@ -61,7 +60,7 @@ public class DhDataInputStream extends DataInputStream
 	{
 		// Z_Std handling compression outside the stream provides a significant performance boost
 		ByteArrayInputStream byteArrayInputStream;
-		if (compressionMode == EDhApiDataCompressionMode.Z_STD)
+		if (compressionMode == EDhApiDataCompressionMode.Z_STD_BLOCK)
 		{
 			byteArrayInputStream = new ByteArrayInputStream(Zstd.decompress(byteArray));
 		}
@@ -87,7 +86,7 @@ public class DhDataInputStream extends DataInputStream
 					return stream;
 				case LZ4:
 					return new LZ4FrameInputStream(stream);
-				case Z_STD:
+				case Z_STD_BLOCK:
 					// ZStd compression should be handled before this point
 					// just return the stream
 					return stream;
@@ -20,14 +20,12 @@
 package com.seibel.distanthorizons.core.util.objects.dataStreams;

 import com.github.luben.zstd.Zstd;
-import com.github.luben.zstd.ZstdOutputStream;
 import com.seibel.distanthorizons.api.enums.config.EDhApiDataCompressionMode;
 import com.seibel.distanthorizons.core.logging.DhLoggerBuilder;
 import it.unimi.dsi.fastutil.bytes.ByteArrayList;
 import net.jpountz.lz4.LZ4Factory;
 import net.jpountz.lz4.LZ4FrameOutputStream;
 import net.jpountz.xxhash.XXHashFactory;
-import org.apache.logging.log4j.LogManager;
 import com.seibel.distanthorizons.core.logging.DhLogger;
 import org.tukaani.xz.*;

@@ -85,7 +83,7 @@ public class DhDataOutputStream extends DataOutputStream
 							//LZ4Factory.nativeInstance().fastCompressor(),
 							//XXHashFactory.nativeInstance().hash32(),
 							LZ4FrameOutputStream.FLG.Bits.BLOCK_INDEPENDENCE);
-				case Z_STD:
+				case Z_STD_BLOCK:
 					// ZStd compression should be handled after the stream is closed
 					// just return the stream
 					return stream;
@@ -127,7 +125,7 @@ public class DhDataOutputStream extends DataOutputStream
 		
 		
 		this.outputByteArray.clear();
-		if (this.compressionMode == EDhApiDataCompressionMode.Z_STD)
+		if (this.compressionMode == EDhApiDataCompressionMode.Z_STD_BLOCK)
 		{
 			this.outputByteArray.addElements(0, Zstd.compress(this.wrappedByteStream.toByteArray(), 3));
 		}
@@ -27,7 +27,6 @@ import com.seibel.distanthorizons.coreapi.util.StringUtil;
 import it.unimi.dsi.fastutil.longs.LongArrayList;
 //import org.apache.commons.compress.compressors.zstandard.ZstdCompressorOutputStream;
 import org.junit.Assert;
-import org.junit.Test;

 import java.io.*;

@@ -204,7 +203,7 @@ public class CompressionTest
 	public void Zstd() // middle of the road
 	{
 		String compressorName = "Zstd";
-		this.testCompressor(compressorName, EDhApiDataCompressionMode.Z_STD);
+		this.testCompressor(compressorName, EDhApiDataCompressionMode.Z_STD_BLOCK);
 	}
 	
 	//@Test
@@ -321,7 +321,7 @@ public class DataSourceRepoTests
 								Assert.assertFalse(pooledDto.compressedWorldCompressionModeByteArray.isEmpty());
 								
 								try (FullDataSourceV2 dataSource = pooledDto.createUnitTestDataSource();
-									FullDataSourceV2DTO compressedDto = FullDataSourceV2DTO.CreateFromDataSource(dataSource, EDhApiDataCompressionMode.Z_STD))
+									FullDataSourceV2DTO compressedDto = FullDataSourceV2DTO.CreateFromDataSource(dataSource, EDhApiDataCompressionMode.Z_STD_BLOCK))
 								{
 									repo.save(compressedDto);