com.threed.jpct
Class Config

java.lang.Object
  com.threed.jpct.Config

public final class Config

extends java.lang.Object

Config is used for configuring the engine. For faster access and to reduce code size, all important configuration variables are public and can be accessed directly.
For setting them programmatically, it may be more convenient to use the setParameterValue()-method instead.
Some will show effect directly after modifying them, some should be modified before doing the setup work for jPCT. This will be stated in the description of the setting.

Field Summary

static boolean	alwaysSort Forces polygon sorting regardsless of transparency or the software renderer being used.
static boolean	autoBuild Usually, one have to call build() on all objects that have to be rendered.
static boolean	autoMaintainAspectRatio Ensures that the aspect ratio doesn't change when changing framebuffer size.
static boolean	blendAlphaIfOversampling If set to true, alpha values will be blended just as colors do when using oversampling in the software renderer.
static boolean	blur Deprecated.
static float	collideEdgeMul When using the sphere-polygon collision detection for the camera, it may be useful to use a lower sphere radius for sphere-edge-collisions to ensure that the camera slides around corners in a more realistic way.
static boolean	collideEllipsoidSmoothing If this is enabled, the ellipsoid collision detection will use a kind of workaround to prevent the detection from producing jerky movement in some cases.
static float	collideEllipsoidThreshold A threshold that limits recursion for ellipsoid collision detection.
static float	collideOffset The maximum number in world units a polygon's corner and/or axis aligned bounding box/octree-node (is used) may have from a position vector to be taken into account as a potential collider in the collision detection methods.
static float	collideSectorOffset The number of units a position vector may be placed outside of a sector and still be considered as part of it as far as collision detection is concerned.
static float	defaultCameraFOV The default FOV for the camera.
static boolean	doPortalHsr Use portals and sectors to perform visibility determination.
static boolean	doSorting Perform a front-to-back sorting of polygons before rendering.
static boolean	fadeoutLight Lightsourcing may depend on distance (or not).
static float	farPlane The far clipping plane. jPCT's software renderer doesn't clip but culls on this plane.
static java.lang.Object[]	glAdditionalConfiguration Allows for giving additional configuration information to the OpenGL renderers, i.e. to bypass the actual configuration jPCT is currently using.
static int	glAnisotropy Sets the level of anisotropic filtering used by OpenGL.
static boolean	glAvoidTextureCopies When in OpenGL mode, a texture's image data will be transfered to the graphics card and a copy will be kept in the Texture object in case that software rendering will be re-enabled, for applying texture effects or for multiple uploads into multiple contexts.
static int	glAWTCommandQueueCleanup Number of buffer switches before the AWT command queue used by the AWTGLRenderer gets a clean up.
static int	glAWTCommandQueueSize Initial size of the command queue that is used by the AWTGLRenderer, i.e.
static int	glBatchSize When compiling an Object3D, the renderer has to assume an ideal batch size for the underlying hardware.
static boolean	glBlendingAffectsAlpha If set to true, the texture blending mode when using multi texturing affects the alpha channel too.
static boolean	glBufferedBlits If enabled, jPCT will aggregate blitting commands and execute them later in one call.
static int	glColorDepth The colordepth that the OpenGL framebuffer should have at least. jPCT will use any videomode that offers a colordepth equal to or larger than this value (but prefers equality).
static int	glDynamicBatchSize Similar to glBatchSize but for dynamically compiled objects.
static boolean	glFixedBlitting Some graphics cards/drivers are having problems with jPCT's 2D-blitting when Zbuffer-depth is only 16bit.
static boolean	glFlipRenderTargets If set to true, textures that are used as a render target will be flipped, which is default for the software renderer.
static boolean	glForceEnvMapToSecondStage By default, an environment map will be applied to the first texture stage if environment mapping is used on an object.
static boolean	glForceFinish Forces the renderer to do GLFinish at the end of each frame.
static boolean	glFullscreen OpenGL output may be shown in a window (default, but doesn't work well on some setups) and fullscreen.
static boolean	glIgnoreAlphaBlendingFBO When using shadow mapping on transparent polygons in combination with FBOs, some NVidia drivers are having performance problems.
static boolean	glIgnoreNearPlane If set to true, the OpenGL renderers will ignore the configured near plane for creating the frustum and use a default value instead.
static boolean	glMipmap Lets jPCT generate (and use) mipmaps for all textures when using an OpenGL renderer.This has to be set before enabling the OpenGL renderer to have an effect.
static boolean	glMultiPassSorting Enables a special sorting to increase performance when doing multi pass rendering.
static int	glOverrideStageCount A switch to override the maximum number of texture stages available. -1 means no override.
static int	glRefresh The refresh rate in Hz the desired videomode should have at least (but equality is prefered).
static boolean	glRevertADDtoMODULATE When setting this to true, every texture blending operation that uses the additive mode will be treated as if it were using modulation instead.
static float	glShadowZBias The depth bias used for shadow mapping.
static boolean	glSkipInitialization Setting this to true, makes jPCT skip any display initialization code in the OpenGL renderers.
static int	glTextureDepth Specifies the color-depth of the textures that should by used for OpenGL.
static float	glTransparencyMul Transparency in OpenGL is implemented in a way that tries to mimic the software renderer.
static float	glTransparencyOffset Transparency in OpenGL is implemented in a way that tries to mimic the software renderer.
static boolean	glTriangleStrips jPCT can render objects (or parts of objects) as triangle-strips when using OpenGL.
static boolean	glTrilinear Lets jPCT generate Mipmaps for all textures and enables trilinear filtering between them.
static boolean	glUseCaches The OpenGL renderer makes use of some simple caches to speed up framebuffer and texture access and to keep memory usage as low as possible.
static boolean	glUseDynamicVBO Experimental, not always faster.
static boolean	glUseFBO Makes jPCT use frame buffer objects (FBOs) if possible and applicable.
static boolean	glUseIgnorantBlits Forces the OpenGL renderer to skip the texture conversion from the FrameBuffer's blit(int[]...)
static boolean	glUseUnappropriateModes If set to true, the mode selection will relax the requirements one step below the step that usually makes sense.
static boolean	glUseVBO Makes jPCT use vertex buffer objects (VBOs) if possible and applicable.
static boolean	glVerbose Forces the GL-Renderer to talk to you about what he's doing when looking for videomodes and uploading textures.
static boolean	glVertexArrays jPCT can use VertexArrays to render objects.
static boolean	glVSync If set to true, vertical sync will be used if the driver supports this setting and doesn't override it itself.
static java.lang.String	glWindowName The name of the window when OpenGL is used.
static int	glZBufferDepth The bit-depth the OpenGL z-buffer should have.
static boolean	gouraud Misleading name!
static boolean	isIndoor Enables some optimizations for indoor scenes (like not clearing the framebuffer for every frame).
static float	lightDiscardDistance A vertex will only be lit by a lightsource if its distance from the light is lower than this value (in world units).
static int	lightMul An "amplifier"-value for the lightsources.
static float	linearDiv How fast a lightsource's intensity fades out with distance.
static int	loadBalancingStrategy If useMultipleThreads is used on the software renderer, you can choose the load balancing strategy with this setting.
static int	lockingTimer While waiting for a lock to be released, the waiting thread will be either paused (if lockingTimer is greater zero) for "lockingTimer" milliseconds or Thread.yield() will be called (if lockingTimer is zero).
static int	maxAnimationSubSequences The maximum number of sub-sequences an Animation may contain.
static int	maxLights The maximum number of lightsources that the Lights instance of a World may handle.
static int	maxNumberOfCores The maximum number of cores/cpus jPCT may use for multi-threaded code.
static int	maxParentObjects The maximum number of parent objects every object may have. usually, an object has only one parent object anyway.
static int	maxPolysVisible The maximum size of the VisList.
static int	maxPortalCoords The maximum number of coordinates a single portal may consist of (Portals in jPCT doesn't have to be triangles or quads, they may have any shape).
static int	maxPortals The maximum number of portals an instance of World can handle.
static int	maxTextureLayers The maximum number of texture layers jPCT can handle.
static int	maxTextures The inital number of textures the texture-manager can handle.
static boolean	mipmap Lets jPCT generate (and use) mipmaps for all textures when using the software renderer.
static boolean	mtDebug Debugging switch for multi threading...will most likely go away sometimes.
static int	nativeBufferSize The size in kb of the native buffer cache.
static float	nearPlane The near clipping plane.
static boolean	neverUseBufferedImage When JAVA2 or higher is detected, jPCT uses a BufferedImage to render into.
static boolean	oldStyle3DSLoader jPCT 1.11+ features a fixed 3DS-loader, but the fix is based on experience, not on file format specs, because they were all different and inconsistent.
static boolean	oldStyleBillBoarding jPCT 1.15+ features a fixed bill boarding approach for child/parent-relations between objects.
static int	optimizeNormalCalcTH jPCT has two different methods for calculating the vertex-normals.
static boolean	optiZ Use OptiZ optimization to speed up z-buffer access.
static int	polygonBufferSize Initial value for an internal polygon buffer of the World.
static int	polygonIDLimit A value that defines how many polygon IDs that were part of a collision will be stored before additional polygon IDs will be rejected.
static boolean	saveMemory If this is enabled, jPCT will reserve potentially needed memory only if it's REALLY needed.
static float	sectorRange A value used for sector detection similar to collideOffset.
static boolean	shareVisibilityList If this is set to true, each instance of World will use the same instance of VisList and will use the same polygon buffer object.
static boolean	spanBasedHsr Use a hidden surface removal method based on spans and sub-spans.
static float	specPow The sharpness of specular highlights.
static float	specTerm An "amplifier"-value for specular highlights.
static boolean	synchronizedRendering Only applies to multi-threaded renderers.
static boolean	texelFilter Use texel-filtering to avoid the blocky look of point sampling.
static long	unloadTimeout Timeout value in ms after which a threaded renderer is allowed to remove the unload request of textures that have never been used by the renderer from the queue.
static boolean	useBB Use the bounding box every Object3D has for faster clipping and culling.
static boolean	useFastCollisionDetection Uses the axis aligned bounding box every object has (should have...) to optimize collision detection.
static boolean	useFastSpecular Use fast specular lighting (if it's used at all).
static boolean	useFramebufferWithAlpha A software renderer only setting.
static boolean	useFrustumCulling Use frustum culling to speed up geometry calculations.
static boolean	useLocking jPCT may use locking for the rotation and translation matrices when rendering the objects.
static boolean	useMultipassStriping jPCT offers a method to rebuild an object so that it consists of triangle strips instead of single triangles.
static boolean	useMultipleThreads An switch to make jPCT use multi-threading for some operations.
static boolean	useMultiThreadedBlitting Only serves a purpose when useMultipleThreads is set to true and software rendering is being used.
static boolean	useNormalsFromOBJ By default, jPCT calculates normals based on the mesh's geometry when calling build().
static boolean	useRotationPivotFrom3DS By default, jPCT calculates a rotation pivot based on the mesh's geometry when calling build().
static java.lang.String	VERSION Deprecated.
static boolean	viewportOffsetAffectsRenderTarget If set to true, any offset to the viewport will affect the render target as well.
static float	viewportOffsetX Shifts the (normalized) viewport into x-direction, i.e. a value of 0.5 lets the rendering start in the middle of the framebuffer so that only the leftmost half of the image is visible in the right half of the framebuffer.
static float	viewportOffsetY Shifts the (normalized) viewport into y-direction, i.e. a value of 0.5 lets the rendering start in the middle of the Framebuffer so that only the uppermost half of the image is visible in the bottom of the framebuffer.
static boolean	zTrick Use zTrick to avoid clearing the z-buffer.

Method Summary

static java.lang.String[]	getParameterNames() Returns the names of all public fields in Config, all configuration options.
static java.lang.Object	getParameterValue(java.lang.String name) Gets the current value of the parameter with the given name.
static java.lang.String	getVersion() Returns the version of this release.
static void	glSetDesiredVideoMode(int colorDepth, int zDepth, int refresh, boolean fullscreen) This static method should help to set the desired video-mode for OpenGL.
static void	glSetDesiredVideoMode(VideoMode vm, boolean fullscreen) This static method should help to set the desired video-mode for OpenGL.
static void	setParameterValue(java.lang.String name, java.lang.Object value) Sets a parameter with the given name to a value.
static void	tuneForIndoor() Enables a preset configuration for indoor-rendering.
static void	tuneForOutdoor() Enables a preset configuration for outdoor-rendering.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VERSION

public static final java.lang.String VERSION

Deprecated.

The version of this release

See Also:

getVersion(), Constant Field Values

saveMemory

public static boolean saveMemory

If this is enabled, jPCT will reserve potentially needed memory only if it's REALLY needed. Default is true.

shareVisibilityList

public static boolean shareVisibilityList

If this is set to true, each instance of World will use the same instance of VisList and will use the same polygon buffer object. It's initialized when the first instance of World is initialized with the current value of maxPolysVisible. This can help to save some memory if multiple Worlds are used. But be careful when working with different Worlds in different Threads or when rendering more then one world in a frame ot one world into multiple frames.

See Also:

World.decoupleVisibilityList()

polygonBufferSize

public static int polygonBufferSize

Initial value for an internal polygon buffer of the World. This buffer this automatically resized if needed, but that may take some time. Choose a low value to keep memory usage low, choose a higher value to minimize resizing. Default is -1, which means that this buffer has the same size as the VisList (which is usually not needed). This is a tribute to versions prior to 1.05, who did this by default. The OpenGL renderer doesn't use this buffer, so you can safely set it to 1 if no software rendering is used at all.

useLocking

public static boolean useLocking

jPCT may use locking for the rotation and translation matrices when rendering the objects. See the corresponding methods in World for more details. Default is false.

See Also:

World.lockMatrices(), World.unlockMatrices()

lockingTimer

public static int lockingTimer

While waiting for a lock to be released, the waiting thread will be either paused (if lockingTimer is greater zero) for "lockingTimer" milliseconds or Thread.yield() will be called (if lockingTimer is zero). Default is 0 (Thread.yield()).

See Also:

World.lockMatrices(), World.unlockMatrices()

defaultCameraFOV

public static float defaultCameraFOV

The default FOV for the camera. Takes effect at startup and when a new camera is created. Default is 1.25.

autoMaintainAspectRatio

public static boolean autoMaintainAspectRatio

Ensures that the aspect ratio doesn't change when changing framebuffer size. Setting this to false causes xFOV and yFOV to be both set to FOV. If it's set to true, only xFOV will be set to FOV and yFOV will automatically be adjusted to a FOV-value that maintains the aspect ratio. If yFOV is set explicitly in the camera, this setting will be ignored. Default is true.

neverUseBufferedImage

public static boolean neverUseBufferedImage

When JAVA2 or higher is detected, jPCT uses a BufferedImage to render into. If neverUseBufferedImage is set to true, this optimization won't be made when creating a new framebuffer and MemoryImageSource will be used instead. Default is false.

useFramebufferWithAlpha

public static boolean useFramebufferWithAlpha

A software renderer only setting. By enabling this, the BufferedImage (if available) for the framebuffer supports an alpha channel. Everything rendered by jPCT will get an alpha value of 255. Default is false. If you set this to true, be sure that you really have to.

maxTextures

public static int maxTextures

The inital number of textures the texture-manager can handle. The manager wil increase the value if needed. This is in for historical reaons. No need to adjust it. Default is 256.

maxPolysVisible

public static int maxPolysVisible

The maximum size of the VisList. This represents the number of polygons jPCT can display on screen per frame. If the polygon number surpasses this value, all additional polygons will be rejected and not drawn. This value has to be modified before instanciating a world. Default is 20000.

maxLights

public static int maxLights

The maximum number of lightsources that the Lights instance of a World may handle. Has to be modified before constructing the World to take effect. Default is 32.

maxTextureLayers

public static int maxTextureLayers

The maximum number of texture layers jPCT can handle. This feature is supported by the OpenGL renderer only. This has nothing to do (at least not directly) with the number of texture stages that the used hardware supports. If you are adding more than the hardware allows to, jPCT will switch from multi texturing to multi pass rendering. Default is 16.

maxAnimationSubSequences

public static int maxAnimationSubSequences

The maximum number of sub-sequences an Animation may contain. The default is 20 (for most MD2).

collideOffset

public static float collideOffset

The maximum number in world units a polygon's corner and/or axis aligned bounding box/octree-node (is used) may have from a position vector to be taken into account as a potential collider in the collision detection methods.
A polygon will be considered as a potential collider if its first corner falls within a box with the length of 2*collideOffset and the position vector used in the detection as midpoint.
This value may has be adjusted if the scaling of the world changes or the movement speed of the camera is set to a very value high. Setting this to a unnecessary high value reduces performance of collision detection while setting it to a too low value can cause the collision detection to fail.
If the automated collision detection optimization is used on an object, this value won't affect performance that much anymore. Anyway, it's taken as an upper bound for the algorithm and for bounding box/octree-node processing, so it may still be required to adjust it. Default is 40.

See Also:

Object3D.setCollisionOptimization(boolean)

collideEdgeMul

public static float collideEdgeMul

When using the sphere-polygon collision detection for the camera, it may be useful to use a lower sphere radius for sphere-edge-collisions to ensure that the camera slides around corners in a more realistic way. On the other hand, this may also cause some "bouncing" in other areas. Therefor, if the radius should be lowered, this value has to be adjusted. A value of 1f means, that the same radius is used for sphere-edge and sphere-polygon intersections. A lower value will lower the radius for sphere-edge and higher values than 1f are possible, but don't make much sense. Negative values will result in undefined behaviour. Default is 1f.

collideSectorOffset

public static float collideSectorOffset

The number of units a position vector may be placed outside of a sector and still be considered as part of it as far as collision detection is concerned. This value is important for detecting the collision with parts of the sector the direction vector points to (in other words: where the entity moves into). A value too high may cause unnecessary checsk while a value too low may cause collision detection to fail at sector borders. Default is 3.

collideEllipsoidThreshold

public static float collideEllipsoidThreshold

A threshold that limits recursion for ellipsoid collision detection. If the lenght of the current velocity (after collision) is lower than the initial velocity multiplied by with value, the recursion will stop. Setting this to the very low value will make the collision detection more accurate, but may also result in accuracy problems where collisions are detected that don't happen. Default is 0.1f.

collideEllipsoidSmoothing

public static boolean collideEllipsoidSmoothing

If this is enabled, the ellipsoid collision detection will use a kind of workaround to prevent the detection from producing jerky movement in some cases. On the other hand, this may cause problems on high polygon objects (in theory...i never experienced it). It's enabled by default.
1.04+ should fix the problem by applying a bugfix to the ellipsoid collision detection. So this setting will most likely be deprecated in future versions.

useFastCollisionDetection

public static boolean useFastCollisionDetection

Uses the axis aligned bounding box every object has (should have...) to optimize collision detection. There should be not need to set this to false (maybe in a very special situation where there is always a collision between objects...but even then...well...). Default is true.

nearPlane

public static float nearPlane

The near clipping plane. Software and OpenGL renderer will behave different for values other than 1f. jPCT culls on this plane, it doesn't really clip... Default is 1.
The OpenGL renderers are ignoring this value for frustum creation unless you set glIgnoreNearPlane to false.
You may as well override this value in an instance of World.

See Also:

World.setClippingPlanes(float, float)

farPlane

public static float farPlane

The far clipping plane. jPCT's software renderer doesn't clip but culls on this plane. Default is 1000.
You may as well override this value in an instance of World.

See Also:

World.setClippingPlanes(float, float)

viewportOffsetX

public static float viewportOffsetX

Shifts the (normalized) viewport into x-direction, i.e. a value of 0.5 lets the rendering start in the middle of the framebuffer so that only the leftmost half of the image is visible in the right half of the framebuffer. Useful for implementing sidebars and similar stuff. When using software rendering, the polygons are culled but not clipped against the viewport's boundaries for performance/implementation reasons. Possible values are in the range of ]-1;1[, default is 0. This setting has NO influence on blitting into the framebuffer but the methods in Interact2D take it into account.

viewportOffsetY

public static float viewportOffsetY

Shifts the (normalized) viewport into y-direction, i.e. a value of 0.5 lets the rendering start in the middle of the Framebuffer so that only the uppermost half of the image is visible in the bottom of the framebuffer. Useful for implementing sidebars and similar stuff. When using software rendering, the polygons are culled but not clipped against the viewport's boundaries for performance/implementation reasons. Possible values are in the range of ]-1;1[, default is 0. This setting has NO influence on blitting into the framebuffer but the methods in Interact2D take it into account.

viewportOffsetAffectsRenderTarget

public static boolean viewportOffsetAffectsRenderTarget

If set to true, any offset to the viewport will affect the render target as well. If false, it won't. Default is false.

maxPortalCoords

public static int maxPortalCoords

The maximum number of coordinates a single portal may consist of (Portals in jPCT doesn't have to be triangles or quads, they may have any shape). This value has to be modified before constructing a World. Default is 8.

maxPortals

public static int maxPortals

The maximum number of portals an instance of World can handle. This value has to be modified before constructing a world. Default is 0.

maxParentObjects

public static int maxParentObjects

The maximum number of parent objects every object may have. usually, an object has only one parent object anyway. Default is 2.

sectorRange

public static float sectorRange

A value used for sector detection similar to collideOffset. Normally, there should be no need to modify this value. Default is 30.

See Also:

collideOffset

useFastSpecular

public static boolean useFastSpecular

Use fast specular lighting (if it's used at all). Fast specular is calculated using Schlick's method instead of Blinn's. Schlick's is faster while Blinn's is more "specular". Default is true.

gouraud

public static boolean gouraud

Misleading name! This doesn't toogle gouraud shading (that's not possible anyway in jPCT) but it disables all lighting but ambient if set to false. Default is true

fadeoutLight

public static boolean fadeoutLight

Lightsourcing may depend on distance (or not). This value can be overriden in World. Default is true.

See Also:

World.setLightAttenuation(int, float)

lightMul

public static int lightMul

An "amplifier"-value for the lightsources. The intensity of every lightsource will be multiplied with this value to get the final intensity. For compiled objects, this has no meaning. They will always be rendered with an implicit value of 1. Default is 10.

linearDiv

public static float linearDiv

How fast a lightsource's intensity fades out with distance. A higher value lets the lightsource fade out slower while a lower value lets the lightsource fade out faster. This value can be overriden for a light source in World. Default is 50.

See Also:

World.setLightAttenuation(int, float)

specTerm

public static float specTerm

An "amplifier"-value for specular highlights. Specular lighting has to be used on objects for this setting to take effect. Default is 10.

specPow

public static float specPow

The sharpness of specular highlights. Specular lighting has to be used on objects for this setting to take effect. Default is 6.

lightDiscardDistance

public static float lightDiscardDistance

A vertex will only be lit by a lightsource if its distance from the light is lower than this value (in world units). A value of -1 means, that all lightsources will influence a vertex regardless of their distance. If many lightsources are being used, this may improve lighting performance. This value can be overriden for a light source in World. Default is -1.

See Also:

World.setLightDiscardDistance(int, float)

blur

public static boolean blur

Deprecated.

Enables/Disables motion blur. Motion blur requires that the objects to blur are rendered in front of the background color. This setting is ignored by the OpenGL-renderer.
This setting will go away in future versions. Deprecating it is the first step. If you really need this feature, please let me know and i might change my mind...

optiZ

public static boolean optiZ

Use OptiZ optimization to speed up z-buffer access. This setting is ignored by the OpenGL-renderer. Default is true.

zTrick

public static boolean zTrick

Use zTrick to avoid clearing the z-buffer. This reduces z-buffer accuracy from 32 to 31 bits. zTrick works only if the whole screen is filled with polygons every frame (like when using indoor rendering) and Config.isIndoor is set to true. Otherwise, z-buffer errors will occur. This setting is ignored by the OpenGL-renderer. Default is false.

spanBasedHsr

public static boolean spanBasedHsr

Use a hidden surface removal method based on spans and sub-spans. This may help and won't hurt, so it shouldn't be required to disable it. This setting is ignored by the OpenGL-renderer. Default is true.

texelFilter

public static boolean texelFilter

Use texel-filtering to avoid the blocky look of point sampling. Texel filtering does cost some performance (but not much) and may introduce artifacts in some cases. Filtering is only applied to texels that are "in need of" and ignored when using OpenGL. Default is true.

isIndoor

public static boolean isIndoor

Enables some optimizations for indoor scenes (like not clearing the framebuffer for every frame). Should be enabled if indoor rendering is performed. Default is false.

doPortalHsr

public static boolean doPortalHsr

Use portals and sectors to perform visibility determination. Portals and sectors need to be set up correctly for this option to be enabled. Refer to the documentation of portals and objects for further information about this topic. Don't enable portal rendering when octrees are being used. It's not possible to combine the two in JPCT and doing so will result in an unpredictable behaviour! Default is false.

See Also:

Object3D, Portals

doSorting

public static boolean doSorting

Perform a front-to-back sorting of polygons before rendering. Albeit the sorting costs some performance, it helps OptiZ and the span based HSR approach to perform well. This setting is ignored by the OpenGL-renderer. Default is true.

alwaysSort

public static boolean alwaysSort

Forces polygon sorting regardsless of transparency or the software renderer being used. Default is true.

useFrustumCulling

public static boolean useFrustumCulling

Use frustum culling to speed up geometry calculations. Default is true.

useBB

public static boolean useBB

Use the bounding box every Object3D has for faster clipping and culling. No need to disable this. Default is true

optimizeNormalCalcTH

public static int optimizeNormalCalcTH

jPCT has two different methods for calculating the vertex-normals. One is faster for smaller objects while the other is (much!) faster for more complex ones. For objects with a triangle-count below this value, the first method will be used and for objects with a higher triangle count, the second method will be used. Default is 500.

useMultipleThreads

public static boolean useMultipleThreads

An switch to make jPCT use multi-threading for some operations. This affects the GLRenderer (The AWTGLRenderer is multi-threaded anyway) and the software renderer but in different ways. It can only make sense when the system has 2 or more cores/cpus. A hyper threading system will most likely not benefit from it.

useMultiThreadedBlitting

public static boolean useMultiThreadedBlitting

Only serves a purpose when useMultipleThreads is set to true and software rendering is being used. Then, you can enable multi threaded blitting of the rendered image to screen. This usually isn't worth it, which is why it defaults to false.

loadBalancingStrategy

public static int loadBalancingStrategy

If useMultipleThreads is used on the software renderer, you can choose the load balancing strategy with this setting. Currently available are
0 = static balancing (default), good for scenes where geometry and coverage are equally distributed. 1 = dynamic balancing, good for scenes that don't cover the whole screen or that change often.

maxNumberOfCores

public static int maxNumberOfCores

The maximum number of cores/cpus jPCT may use for multi-threaded code. This affects the software renderer only ATM and only if useMultipleThreads is set to true. Default is 4, which matches a quad core.

mtDebug

public static boolean mtDebug

Debugging switch for multi threading...will most likely go away sometimes.

glTransparencyOffset

public static float glTransparencyOffset

Transparency in OpenGL is implemented in a way that tries to mimic the software renderer. If one is using OpenGL only or can live with different output, the offset in the formula used to calculate the actual transparency from an object's transparency value can be changed to broaden the range. The actual formula is trans=offset+objTrans*mul, default for offset is 0.7f. This setting is ignored by the software renderer.

glTransparencyMul

public static float glTransparencyMul

Transparency in OpenGL is implemented in a way that tries to mimic the software renderer. If one is using OpenGL only or can live with different output, the multiplicator in the formula used to calculate the actual transparency from an object's transparency value can be changed to broaden the range. The actual formula is trans=offset+objTrans*mul, default for mul is 0.06f. This setting is ignored by the software renderer.

glShadowZBias

public static float glShadowZBias

The depth bias used for shadow mapping. Default is 0.5f, which is quite small. This value will be added to the z-value of polygons used for rendering a shadow map. If you are experiencing shadowing artifacts on polygons, play around with this setting.

glFullscreen

public static boolean glFullscreen

OpenGL output may be shown in a window (default, but doesn't work well on some setups) and fullscreen. This has to be set before enabling the OpenGL-renderer.

glColorDepth

public static int glColorDepth

The colordepth that the OpenGL framebuffer should have at least. jPCT will use any videomode that offers a colordepth equal to or larger than this value (but prefers equality). The software renderer always uses 24bit. On a current graphics adapter, 32bit should be fine for Windows. On Linux, there are no 32bit modes reported by the driver. Use 24bit instead. Default is 32.

See Also:

FrameBuffer.getVideoModes(int)

glZBufferDepth

public static int glZBufferDepth

The bit-depth the OpenGL z-buffer should have. The software renderer always uses 32bit. Default is 24.

See Also:

FrameBuffer.getVideoModes(int)

glRefresh

public static int glRefresh

The refresh rate in Hz the desired videomode should have at least (but equality is prefered). This value is only of interest if fullscreen mode is being used. If it's set to 0, jPCT will pick a mode regardless of the refresh rate. Default is 60.

See Also:

FrameBuffer.getVideoModes(int)

glOverrideStageCount

public static int glOverrideStageCount

A switch to override the maximum number of texture stages available. -1 means no override. Other valid values are 1 to 4. Can be useful to simulate the results that a 2 (or even 1) texture stage device may create when jPCT is running on a hardware that actually supports more. Has to be set before enabling the renderer to show an effect. Default is -1.

glMultiPassSorting

public static boolean glMultiPassSorting

Enables a special sorting to increase performance when doing multi pass rendering. This may create slightly different results when using transparency on a multi pass object, but that isn't a good idea anyway, so...
Default is true.

glAdditionalConfiguration

public static java.lang.Object[] glAdditionalConfiguration

Allows for giving additional configuration information to the OpenGL renderers, i.e. to bypass the actual configuration jPCT is currently using. Currently, the array may contain a org.lwjgl.opengl.PixelFormat and/or org.lwjgl.opengl.DisplayMode. If provided, jPCT will use those instead of trying to determine its own one. How to create these instances is up to you.

glMipmap

public static boolean glMipmap

Lets jPCT generate (and use) mipmaps for all textures when using an OpenGL renderer.This has to be set before enabling the OpenGL renderer to have an effect. Default is true.

mipmap

public static boolean mipmap

Lets jPCT generate (and use) mipmaps for all textures when using the software renderer. Mipmaps are applied per polygon in the software renderer (like the old Riva 128 chip was doing it too...:-)), not per pixel.
Default is false.

glTrilinear

public static boolean glTrilinear

Lets jPCT generate Mipmaps for all textures and enables trilinear filtering between them. This has to be set before enabling the OpenGL renderer to have an effect. Default is false.

glAnisotropy

public static int glAnisotropy

Sets the level of anisotropic filtering used by OpenGL. Default is 0, which means that nothing will be set and the driver presets will be used.

glTextureDepth

public static int glTextureDepth

Specifies the color-depth of the textures that should by used for OpenGL. Possible values are 32 for a 8/8/8/8, 16 for a 4/4/4/4 format and -1 for a "best fit" setting determined by the OpenGL implementation (= GL_RGBA). Default is 32.

glTriangleStrips

public static boolean glTriangleStrips

jPCT can render objects (or parts of objects) as triangle-strips when using OpenGL. This is usually faster (but not as much as one may think) and so it's enabled by default. If problems occur, this setting may be changed to false to see if the strips are causing the problem. Triangle strips won't be used, if the software renderer is enabled (even when using the OpenGL renderer in addition). Default is true.

See Also:

Object3D.createTriangleStrips(), World.createTriangleStrips(), useMultipassStriping

glVertexArrays

public static boolean glVertexArrays

jPCT can use VertexArrays to render objects. This is usually faster for scenes with quite a lot of triangles. When using VertexArrays, the glTriangleStrip setting will be ignored. However, creating triangle-strips for the object may still increase performance. Default is true.

See Also:

Object3D.createTriangleStrips()

glWindowName

public static java.lang.String glWindowName

The name of the window when OpenGL is used. Default is "jPCT".

glForceFinish

public static boolean glForceFinish

Forces the renderer to do GLFinish at the end of each frame. This is slower and usually not needed. It's advised to leave this setting to default, which is false.

glForceEnvMapToSecondStage

public static boolean glForceEnvMapToSecondStage

By default, an environment map will be applied to the first texture stage if environment mapping is used on an object. When combining it with multi texturung, this may not always be want one wants, because the lighting calculations of OpenGL may give you undesired results by applying the lighting to the environment map instead of the base map. To work around this problem, you can force jPCT to use the second texture stage for environment mapping, if (and only if) the object uses multiple stages. However, jPCT doesn't check if a particular polygon uses multiple stages. So if you are forcing environment mapping to stage 2, make sure that your multi textured object all have that stage for all polygons and that the correct textures are assigned. Default is false.

glFixedBlitting

public static boolean glFixedBlitting

Some graphics cards/drivers are having problems with jPCT's 2D-blitting when Zbuffer-depth is only 16bit. Setting this to true, enables a fix for this problem but may cause very subtle artifacts (i never experienced one but you never know...). Default is true.

glBufferedBlits

public static boolean glBufferedBlits

If enabled, jPCT will aggregate blitting commands and execute them later in one call. In theory, this should be faster than the default method. In practice, it isn't (at least not in my tests). However, it may be faster on some machines, which why it can be enabled here. Anyway, default is false.

glVerbose

public static boolean glVerbose

Forces the GL-Renderer to talk to you about what he's doing when looking for videomodes and uploading textures. Default is false.

glAvoidTextureCopies

public static boolean glAvoidTextureCopies

When in OpenGL mode, a texture's image data will be transfered to the graphics card and a copy will be kept in the Texture object in case that software rendering will be re-enabled, for applying texture effects or for multiple uploads into multiple contexts. If this is not required, you can get rid of this copy by setting this to true. This may save some memory, but it's likely to produce errors and crashes in case your expectations aren't correct on how the textures are used. Take care!

glAWTCommandQueueSize

public static int glAWTCommandQueueSize

Initial size of the command queue that is used by the AWTGLRenderer, i.e. when rendering into an AWTGLCanvas. The queue will be expanded if needed by this amount. Default is 1000.

glAWTCommandQueueCleanup

public static int glAWTCommandQueueCleanup

Number of buffer switches before the AWT command queue used by the AWTGLRenderer gets a clean up. This is an internal process that should remain unnoticed and there is usually no need to change this setting.

glSkipInitialization

public static boolean glSkipInitialization

Setting this to true, makes jPCT skip any display initialization code in the OpenGL renderers. This can be useful to make jPCT render into an SWT component (for example). Initializing the display is totally up to you in this case. For normal use of jPCT, this isn't needed. Default is false.

glUseIgnorantBlits

public static boolean glUseIgnorantBlits

Forces the OpenGL renderer to skip the texture conversion from the FrameBuffer's blit(int[]...)-method except for the first time. In other words: If this is set to true, an int[]-array that should be used for blitting will be converted into a texture exactly one time and this texture will be used from there on as long as the size of the int[]-array to blit doesn't change. This is much faster, but depending on the application, it may blit nonsense. Default is false.

glUseCaches

public static boolean glUseCaches

The OpenGL renderer makes use of some simple caches to speed up framebuffer and texture access and to keep memory usage as low as possible. If, for whatever reason, these caches seem to cause trouble... here is the option to disable them. But don't disable them without need, because it may hurt performance tremendously. Default is true.

glUseFBO

public static boolean glUseFBO

Makes jPCT use frame buffer objects (FBOs) if possible and applicable. In case of compability problems with render to texture and/or shadow mapping, try setting this to false. It will hurt performance though. Set this before enabling a renderer. Default is true.
NOTE: This value will be adjusted by jPCT after initializing an OpenGL-renderer to the actually used state.

glUseVBO

public static boolean glUseVBO

Makes jPCT use vertex buffer objects (VBOs) if possible and applicable. If set to false, jPCT will revert to display lists instead. Set this before enabling a renderer. Default is true.

glUseDynamicVBO

public static boolean glUseDynamicVBO

Experimental, not always faster. Default is false.

glIgnoreAlphaBlendingFBO

public static boolean glIgnoreAlphaBlendingFBO

When using shadow mapping on transparent polygons in combination with FBOs, some NVidia drivers are having performance problems. Setting this to true treats transparent as opaque polygons and the problems are gone. However, the shadows may suck visually. Default is false.

glRevertADDtoMODULATE

public static boolean glRevertADDtoMODULATE

When setting this to true, every texture blending operation that uses the additive mode will be treated as if it were using modulation instead.

glFlipRenderTargets

public static boolean glFlipRenderTargets

If set to true, textures that are used as a render target will be flipped, which is default for the software renderer. This works only with FBOs disabled. Default is now false (was true in version prior to 1.15).

glBlendingAffectsAlpha

public static boolean glBlendingAffectsAlpha

If set to true, the texture blending mode when using multi texturing affects the alpha channel too. If set to false, this won't happen, which was the default in 1.15 and lower. This doesn't affect multi pass rendering. Default is true. NOTE: This value will be adjusted by jPCT after initializing an OpenGL-renderer to the actually used state.

glVSync

public static boolean glVSync

If set to true, vertical sync will be used if the driver supports this setting and doesn't override it itself. Enabling vertical sync may reduce performance but prevents tearing. Default is false (=off). Set this before enabling an OpenGL renderer.

glUseUnappropriateModes

public static boolean glUseUnappropriateModes

If set to true, the mode selection will relax the requirements one step below the step that usually makes sense. This can be required if the driver has some problems to report a correct mode albeit he could enable it anyway. Default is false.

glBatchSize

public static int glBatchSize

When compiling an Object3D, the renderer has to assume an ideal batch size for the underlying hardware. If that size is too small or too large, performance may suffer or polygons are missing. The default is 8000. If you are experiencing problems or crashes, try if it helps to lower this value (and post your findings in the forum!).

glDynamicBatchSize

public static int glDynamicBatchSize

Similar to glBatchSize but for dynamically compiled objects. This value is significantly lower than the one for static object by default, because there were some problems with some NVidia drivers if the value is too high. Default is 2000.

glIgnoreNearPlane

public static boolean glIgnoreNearPlane

If set to true, the OpenGL renderers will ignore the configured near plane for creating the frustum and use a default value instead. If it's false, the near plane will be used. Default is true.
Don't set this to false when using the software renderer.

polygonIDLimit

public static int polygonIDLimit

A value that defines how many polygon IDs that were part of a collision will be stored before additional polygon IDs will be rejected. Default is 50.

useMultipassStriping

public static boolean useMultipassStriping

jPCT offers a method to rebuild an object so that it consists of triangle strips instead of single triangles. This may be useful when using the OpenGL renderer, because it may increase performance in geometry limited situations. Using a multipass-approach for this is slower but usually generates better strips. Default is true.

See Also:

Object3D.createTriangleStrips(), World.createTriangleStrips(), glTriangleStrips

oldStyle3DSLoader

public static boolean oldStyle3DSLoader

jPCT 1.11+ features a fixed 3DS-loader, but the fix is based on experience, not on file format specs, because they were all different and inconsistent. If you are getting wrong object colors or an error message, adjust this to true and see if it helps.

useRotationPivotFrom3DS

public static boolean useRotationPivotFrom3DS

By default, jPCT calculates a rotation pivot based on the mesh's geometry when calling build(). However, you might as well take the rotation pivot from the 3DS file. Setting this to true will force jPCT to use that pivot instead. Default is false.

useNormalsFromOBJ

public static boolean useNormalsFromOBJ

By default, jPCT calculates normals based on the mesh's geometry when calling build(). However, you might as well take the normals from an OBJ-file. Setting this to true will force jPCT to use these normals instead. Default is false.

oldStyleBillBoarding

public static boolean oldStyleBillBoarding

jPCT 1.15+ features a fixed bill boarding approach for child/parent-relations between objects. However, an application may rely on the former approach. By setting this to true, you can mimic the old behaviour. Default is false.

autoBuild

public static boolean autoBuild

Usually, one have to call build() on all objects that have to be rendered. By setting this to true, jPCT will do this automatically if you omit it. However, this may cause problems with applications that rely (for whatever reason) on unbuild objects. Therefore, it's false by default.

blendAlphaIfOversampling

public static boolean blendAlphaIfOversampling

If set to true, alpha values will be blended just as colors do when using oversampling in the software renderer. When set to false, they won't. Default is false.

nativeBufferSize

public static int nativeBufferSize

The size in kb of the native buffer cache. Setting this to 0 will turn native buffer caching off. Setting this to a very high value may lead, depending on the application, to a kind of memory leak. Default is 1024.

synchronizedRendering

public static boolean synchronizedRendering

Only applies to multi-threaded renderers. If set to true, each buffer has to be rendered before being filled with data again. If false, the rendering might skip buffers if filling is much faster than rendering. Default is false.

unloadTimeout

public static long unloadTimeout

Timeout value in ms after which a threaded renderer is allowed to remove the unload request of textures that have never been used by the renderer from the queue. Default is 500ms.

Method Detail

getVersion

public static java.lang.String getVersion()

Returns the version of this release. Use this instead of VERSION.

Returns:

the current version

setParameterValue

public static void setParameterValue(java.lang.String name,
                                     java.lang.Object value)

Sets a parameter with the given name to a value. This method can be used to access the configuration variables via their names instead of setting them directly. This is more suitable for setting them from some configuration file's data, but its slower than direct access, because it uses reflection.

Parameters:

name - the name

value - the value

getParameterValue

public static java.lang.Object getParameterValue(java.lang.String name)

Gets the current value of the parameter with the given name. Because if type of the value is unknown, this method simply returns an Object. It's up to you to convert it correctly.

Parameters:

name - the name

Returns:

the value

getParameterNames

public static java.lang.String[] getParameterNames()

Returns the names of all public fields in Config, all configuration options.

Returns:

the names in no particular order

tuneForIndoor

public static void tuneForIndoor()

Enables a preset configuration for indoor-rendering. This method assumes that portal rendering should be used too, so it sets this to true. Keep this in mind when using this method in applications that don't use portal rendering. This method doesn't do anything more than setting the configuration variables to the most common indoor settings. Not all variables are affected by this.

tuneForOutdoor

public static void tuneForOutdoor()

Enables a preset configuration for outdoor-rendering. This method doesn't do anything more than setting the configuration variables to the most common outdoor settings. Not all variables are affected by this.

glSetDesiredVideoMode

public static void glSetDesiredVideoMode(int colorDepth,
                                         int zDepth,
                                         int refresh,
                                         boolean fullscreen)

This static method should help to set the desired video-mode for OpenGL. All this method does is to set glXXXX-Parameters accordingly but it may look cleaner in an application to use this method instead of accessing all four configuration parameters directly. These settings have to be changed before enabling the OpenGL renderer to have an effect. Setting the values does in no way guarantee that a mode with these settings is available. The resolution is not set here but taken from the dimensions of the framebuffer.

Parameters:

colorDepth - the colordepth in bits

zDepth - the depth of the z-buffer in bits

refresh - the refresh rate

fullscreen - fullscreen should be used (true) or not (false)

glSetDesiredVideoMode

public static void glSetDesiredVideoMode(VideoMode vm,
                                         boolean fullscreen)

This static method should help to set the desired video-mode for OpenGL. All this method does is to set glXXXX-Parameters accordingly but it may look cleaner in an application to use this method instead of accessing all four configuration parameters directly. These settings have to be changed before enabling the OpenGL renderer to have an effect. Setting the values does in no way guarantee that a mode with these settings is available. The resolution is not set here but taken from the dimensions of the framebuffer.

Parameters:

vm - the video-mode to be set

fullscreen - fullscreen should be used (true) or not (false)

See Also:

FrameBuffer.getVideoModes(int)