Fog Fading System

[MoCo]

Hello,

this is a small system, that adds smoothly fading fog to a map. Basically, it offers an easy to use way for interpolation between two fogs.

A good scenario for this is an automatic day/night fog-cycle for example.

If I find the time, maybe I'll include support for more than 2 fogs and area based fog later.

Right now, maybe it's more a function than a system, but you can copy everything to your map and right away use it.

Hope this might be useful for some people.

Code

// ============================================
//   Fog Fading System 
//
//   by MoCo  ([email protected])
//   v 2.2  (2009-10-07)
// ============================================
//
// ABOUT:
//  This system gives you an easy to use way for interpolating between two fogs.
//  A possible scenario is the smooth transition between day and night fog for example.  
// 
// CHANGELOG:
//  v2.2:  Fade function now takes initial and end fog as parameters, 
//         added functions for pausing and resuming fog fade, some other small changes
//  v2.1:  Compatibility with latest patch 1.24
//  v2.0:  The system now uses structures to declarate fog data.
//         It's changed to a function-based system making it more flexible. 
//
// REQUIREMENTS:
//   - vJass / JassHelper / Jass New Gen Editor   (See [url]www.wc3campaigns.net[/url])
//   - TimerUtils library [included]  (credits to Vexorian. See [url]http://www.wc3campaigns.net/showthread.php?t=101322[/url] for more information and possible updates)
//
// INSTALLATION:  
//   Just copy the 'Fog Fading System' and the 'TimerUtils' triggers to your map.
//
// USAGE:  
//   Take a look at the example trigger and check out, how things are done there.
//   The system is build around one core function, that interpolates between two given fog structures:
//
//          function FogSetFade takes fog fog1, fog fog2, real fading_duration, real period, integer style returns nothing
//
//   Paramters:
//      - fog1: the structure instance of the initial fog to be applied
//      - fog2: the structure instance of the second fog to be blend over to
//      - fading_duration: the time, to fully blend over to the new fog
//      - period: describes the smoothness. 
//        A value of 1 means, that fading is proccessed every second
//        A value of 0.1 means, that 10 fading ticks are proccessed in one single second (-> very smooth)
//        You may want to use smaller values for smaller duration periods
//      - style: fog style  (0 = linear, 1 & 2 are expon. functions)
//
//  Give credit if you use this system!
// ============================================
library FogFadingSystem requires TimerUtils
     
    globals       
        // These variables store the current values of the actual active fog
        private real fog_start = 0
        private real fog_end = 9999
        private real fog_density = 0
        private real fog_red = -1
        private real fog_green = -1
        private real fog_blue = -1
        private integer fog_style = 0
        
        // variables used for calculations
        private integer fog_fade_ticks
        private real fog_fade_amount_start
        private real fog_fade_amount_end
        private real fog_fade_amount_density
        private real fog_fade_amount_red   
        private real fog_fade_amount_green
        private real fog_fade_amount_blue
        private timer fading_timer
        private integer remaining_ticks
        private boolean onHold = false
        private real fade_period
        
    endglobals
    
    struct fog
        string name
        real start
        real end
        real density
        real red
        real green
        real blue
    endstruct
    
private function FogSetFadeCallback takes nothing returns nothing
    local timer t = GetExpiredTimer() 
    
    set remaining_ticks = GetTimerData(t) - 1 
    call SetTimerData(t, remaining_ticks ) 
    
    set fog_start   = fog_start   - fog_fade_amount_start
    set fog_end     = fog_end     - fog_fade_amount_end
    set fog_density = fog_density - fog_fade_amount_density
    set fog_red     = fog_red     - fog_fade_amount_red
    set fog_green   = fog_green   - fog_fade_amount_green
    set fog_blue    = fog_blue    - fog_fade_amount_blue
    
    call SetTerrainFogEx(fog_style, fog_start, fog_end, fog_density, fog_red, fog_green, fog_blue)

    if GetTimerData(t) <= 0 then
        call ReleaseTimer(t)
    endif

    // Below is a debug display that shows raw values each update tick
    // call DisplayTextToPlayer(GetLocalPlayer(),0,0, "FOG - start: "+R2S(fog_start)+", end: "+R2S(fog_end)+", dens: "+R2S(fog_density)+", R: "+R2S(fog_red)+", G: "+R2S(fog_green)+", B: "+R2S(fog_blue))
    
    set t = null
endfunction

function FogPauseFade takes nothing returns nothing
    call ReleaseTimer(fading_timer)
    set onHold = true
endfunction

function FogResumeFade takes nothing returns nothing
    if onHold then
        set fading_timer = NewTimer()
        call SetTimerData(fading_timer, remaining_ticks) 
        call TimerStart(fading_timer, fade_period, true, function FogSetFadeCallback)
    endif
endfunction

function FogSetFade takes fog fog1, fog fog2, real fading_duration, real period, integer style returns nothing
    set onHold = false
    set fade_period = period
    
    // if duration 0 or less: instant change
    if fading_duration <= 0 then
        set fog_start   = fog2.start  // Though, we need to update the variables
        set fog_end     = fog2.end              
        set fog_density = fog2.density
        set fog_red     = fog2.red
        set fog_green   = fog2.green
        set fog_blue    = fog2.blue 
        set fog_style   = style
        
        call SetTerrainFogEx(fog_style, fog_start, fog_end, fog_density, fog_red, fog_green, fog_blue)
        
    // Fade between fog1 and fog2
    else 
        // Set fog1 as initial fog
        set fog_start   = fog1.start  // Though, we need to update the variables
        set fog_end     = fog1.end              
        set fog_density = fog1.density
        set fog_red     = fog1.red
        set fog_green   = fog1.green
        set fog_blue    = fog1.blue 
        set fog_style   = style
        
        call SetTerrainFogEx(fog_style, fog_start, fog_end, fog_density, fog_red, fog_green, fog_blue)
        
        // Calculate fading ticks
        set fog_fade_ticks = R2I( fading_duration / period )
        
        // Calculate the color amounts to be faded every tick
        set fog_fade_amount_start   = ( fog1.start   - fog2.start   ) / fog_fade_ticks
        set fog_fade_amount_end     = ( fog1.end     - fog2.end     ) / fog_fade_ticks
        set fog_fade_amount_density = ( fog1.density - fog2.density ) / fog_fade_ticks
        set fog_fade_amount_red     = ( fog1.red     - fog2.red     ) / fog_fade_ticks
        set fog_fade_amount_green   = ( fog1.green   - fog2.green   ) / fog_fade_ticks
        set fog_fade_amount_blue    = ( fog1.blue    - fog2.blue    ) / fog_fade_ticks
        
        // Set up and start timer
        set fading_timer = NewTimer()
        call SetTimerData(fading_timer, fog_fade_ticks) 
        call TimerStart(fading_timer, period, true, function FogSetFadeCallback)
    endif
    
endfunction

endlibrary

 

[TriggerHappy]

Well, the globals should be at the top and the constants should be in all capitals.
Also, FFS_Change_Fog is an akward function name, make it more Jass-Like.
Something like, FogSetFade or something along those lines.

I think this is also missing some functionality, things like pausing the fog and resuming it when needed. Or even destroying it. And all the functions should be methods inside fog, and you could just create functions that are just wrappers for the methods if you feel it's needed.

So if you do everything I stated, I see no reason why I shouldn't approve this.

 

[MoCo]

Hi TriggerHappy,

thanks for having a look at it.

I've put up a new version featuring better names convention, the fade method now takes 2 fog parameters for a more intuitive understanding and there are functions for pausing and resuming fades.

 

[TriggerHappy]

The fog struct should still have methods. And the functions should just be wrappers for those methods.

struct fog
    method setFade takes blah returns nothing
    endmethod
endstruct

function FogSetFade takes fog f, blah returns nothing
    call f.setFade(blah)
endfunction

 

[MoCo]

Is there any advantage/difference for the user within this change?

 

[YourNameHere]

Easier to understand for unexperienced users.
It get's inlinied anyway, so where's the problem?

 

[MoCo]

There's no problem at all, just wanted to know, because I haven't used methods inside structs so far and I was wondering if there are good arguments to start using them now.

 

[azlier]

I feel that methods are unneeded here. They only add clutter in this particular scenario. Documentation on how to use the fog struct should be written soon.

The standard is that globals and structs are named in CamelCase. Constant globals should HAVE_THIS_CASE.

 

[TriggerHappy]

The struct is included, and is passed as parameters in the functions therefore it should have methods.

In my opinion of course, though I don't see how you could be opposed to it.

 

[azlier]

I do not see the need for a method. You only replace somefog.field= with somefog.setField(...). Setters and getters should be avoided when possible.

 

[azlier]

It appears there were no changes to the code.

Graveyarded.