History: Hydrax

Author: Xavier 'Xavyiy' Verguí­n González
Project: OGRE Add-on Library (water)
Version: 0.5.1
Supported Platforms: Windows, Linux, Mac
Supported Ogre Releases: 1.4, 1.6
Documentation: API Documentation(0.5 for the moment, 0.5.1 included in the sources .rar package), Demo application source code and forum support
License: GNU Lesser General Public License (free for any use)
Status and bug reports: Hydrax forum

Introduction

Hydrax is an add-on for Ogre which aim is to provide an easy-use library in order to render pretty water scenes.

It's fully configurable, all effect, such as water depth effects, smooth transitions, foam effects, caustics, underwater god rays, ... can be modified in real-time as well as all options that do not depend of shaders such as Rtt's texture quality, hydrax geometry and noise modules options, you can change between different modules(geometry and noise) on-fly, etc... Hydrax has a modulable interface wich allows any kind of water geometry, actually there're three modules availables: The infinite ocean module, based on the projected grid concept, the simple grid module and the radial grid module; of course, hydrax geometry modules and noise modules can be coded by users.

Videos

Screenshots

Underwater rendering: (With underwater reflections and sun god rays!)

Videos

• Hydrax-SkyX demo video
• FFT noise video
• 0.4 HD preview
• 0.4 preview2 (mp4, 30Mb)
• Hydrax v0.2 preview
• Hydrax v0.2 preview 2

Main features

• Realistic fresnel refraction and reflection effects
• Intelligent depth effects based on depth maps
• Smooth transitions effects: Smooth transitions with all objects in the scene using the depth map
• Caustics effects
• Sunlight effects (Colour, Position, Sun strength, area, etc...)
• Full underwater effects like underwater reflections, god rays...
• Foam effects
• Water editor
• Vertex and GPU Normals generation
• Decals support (to place any kind of texture on the water, like ship trails, water vegetables, etc)
• Modulable interface (Geometry and noise modules)
• HLSL and CG support (and GLSL in future versions)

Geometry modules:

• Projected grid
• Simple grid
• Radial grid

Noise modules:

• Perlin
• FFT

Downloads

In lack of updates from the original author, here is a Github-repository with latest community version and fixes:
(Current version 0.5.4-5 (updated 2012-11-01))
https://github.com/imperative/CommunityHydrax

All further community development, patches and modifications should be sent there.

• Precompiled demo (version 0.5.1)
  While running the demo press 'M' to switch water presets!
• Hydrax/Demo sources and media files (version 0.5.1)
  (Code::Blocks and VC++ 2005 project files included)
• Hydrax editor (with sources, version 0.5.1)
  Hydrax config files are saved in bin/release/saved
• Linux package (old version 0.3)
  Note: view Readme_Linux.txt
• Mirror of all published Hydrax files

Linux install packs (by user SanguinarioJoe):
(None of these links seem to work anymore, but the same packages seem to be in the "Mirror of all published Hydrax files" link right above this.

• libhydrax_0.5.4-Ubuntu2.tar.gz
• hydrax-demo_0.5.4-Ubuntu1.tar.gz
• file overview of user SanguinarioJoe - maybe there is a newer version available

Support the author

If you have loved Hydrax, consider making a donation: (Xavyiy)

Current development status 2012-11

There hasn't been any activity from Hydrax author for a while, and many others has been finding bugs on the forum and even developing some new features. However since there was no central public place for Hydrax code, people have been just making their changes public on the forums in different places. So now I've tried to gather together all those fixes and start a community-maintained repository of the “latest” version of Hydrax. (https://github.com/imperative/CommunityHydrax)

If you find any bugs or develop new features which you feel should be a part of generic Hydrax (and not some specific modification for your application), please add them to this repository. Either send a pull request or ask me (“heavydist” on the forums) to add you to the repository. You can even help the project by for example incorporating the demo into the repository, or writing documentation, etc...

Also, here are some notes and some ad-hoc documentation which I've compiled based on my experiments with Hydrax.
Current status (what works).
If you start up the Hydrax/SkyX demo, you may notice that it only allows you to choose the Direct3D rendering system, and as it turns out, that's not a coincidence. Many things did not work correctly for my project in OpenGL, and it seems that Hydrax did not fully support it. However the things that didn't/don't work are due to lack of testing, not due to not being implemented, so you should be able to easily fix them.

The situation with shaders requires special attention: original hydrax provides a choice of which shader language to use: Cg, HLSL or GLSL. All the shaders used by Hydrax are gynamically generated in MaterialManager.cpp and not stored in any resources. For example the dynamic generation can remove some textures from the shader if you shutdown certain functions of Hydrax.

But the choice of shader language has created a lot of problems: in most cases, both the original author and some of the people working on the project have only been testing one shader language (the one they've been using in their project), and different things have worked differently in different languages. You can find many threads on the forum about things working in HLSL, but not in GLSL, or looking one way in cg, but not in HLSL, etc. This is both because there are different parts of code generating different shader language code, but also because there seem to be some subtle caveats, like HLSL and cg not being *exactly* the same, even though they appear to, or cg shaders handling differently in Direct3D or OpenGL, etc.

The described problem, as well as the fact that everything that is needed for Hydrax can be done in cg, which compiles both for OpenGL and DirectX, I don't see the point in maintaining the support for different shader languages or even it's purpose from the beginning.

I've been only developing the cg version of shaders, and I advice you to do the same. At this point (0.5.4 unofficial) cg seem to be the version where most features work.

Things that people often ask about and that don't seem to be implemented right now are multiple hydraxes in the same scene and water which does not have the default planar shape perpendicular to y-axis. Both of them could be implemented of course, but you would have to really get familiar with how Hydrax is built and make a lot of modifications to it. Please submit a patch to the repo if you do though.

Otherwise just check out the Demo to see how to use it and play with parameters, it's all pretty obvious.

Currently known “bugs”:
The certain bugs I know about I've put into the Community Hydrax code, but these are more cases of strange behaviour which I am not sure are due to a bug in Hydrax, they probably just due to me not using it correctly. But if you would stumble upon these, at least you will know how to fix them:
Normal calculation in NM_VERTEX
In MaterialManager.cpp there is a clause that calculates a term called dotProduct (in the shader) differently for NM_VERTEX than it does for the other two types of rendering. In my application that caused the term to always be 0, and the water was not rendered correctly.
If you want to know if your water suffers from this, try to set globalTransparency Hydrax config value to 0 and check if the water looks fine. If there are like no reflections at all, you have this problem.
(also this is the problem to fix if your image suffers from distant horizon looking too sharp)
Fix: changed

else
	{
		FragmentProgramData +=
			"float dotProduct=dot(-camToSurface,pixelNormal);\n"; 
	}

to

else
	{
		FragmentProgramData +=
			"float dotProduct=dot(camToSurface,pixelNormal);\n"; // was -camToSurface
	}

This bug seemed to be the same in both OpenGL and DirectX.

Reflection flipped:
For some reason DirectX and OpenGL handles a certain parameter differently in the cg shader, which for my application caused the reflection to be flipped in one of them or the other. And it only happened in some weird conditions, like other compositors being added to the scene, obscure...
Anyway, if you do have this problem, you WILL know, the reflection looks completely fucked up, like this: http://www.youtube.com/watch?v=DC1SV41lypI
But the fix is simple:
Find the line

"float3 reflection=tex2D(uReflectionMap,ProjectionCoord.xy+pixelNormalModified);\n" +

and insert this right before it:

"ProjectionCoord.y = 1.0 - ProjectionCoord.y;\n" +

Roadmap

Version 0.6:

Library:

• Improve underwater rendering. Update underwater depth calculations based on the distance, like the Crysis (Crytek) approach.
• Improve Perlin and FFT normal map generator shaders
• GLSL shaders
• Multi-camera rendering support
• Ogre 1.7.X native support

Editor:

• Port RBGui to Ogre 1.7.X
• Port the editor to Ogre 1.7.X

Demo:

Examples:

• Advanced example: using custom textures for depth calculations (0.5 version feature)
• Advanced example: creating ship trails (decals).

Tutorials:

• Creating custom geometry and noise modules

See also

• Hydrax forum - News, details, questions, bug reports
• Hydrax API documentation
• Managed Hydrax Wrapper - For use with Mogre
• EGO Game Editor - Has support for Hydrax