StrobeAPI Implementation

[fuzun]

Pull request for the v1: https://github.com/FWGS/xash3d/pull/343 Discussion: https://forums.blurbusters.com/viewtopic.php?f=7&t=3815

News (v3):

• Complete refactor due to OOP implementation.
• Now developers can develop their own Strobe implementation based on Strobe api (by deriving StrobeAPI abstract class).
• Multiple Strobe implementations can work simultaneously.
• Bug fixes.
• ...

News (v2):

• Rewritten from scratch.
• Supports phase matching.
• Burn-in prevention. -> r_strobe_swapinterval .
• New debug mode! (turn on with r_strobe_debug <0|1>)
• Brightness reduction statistics in debug stats.
• PWM (Simulated) statistics in debug stats.
• Experimental "Badness" function in debug stats.
• Some bug fixes.
• Stability analyzing to auto disable strobing (r_strobe_cooldown ) - stats in debug stats.
• ...

Todo:

• Making menu entry for enabling strobe mode.
• Implement high precision timer to keep the internal phase on track with monitor. (In case of freezes etc.) * Thanks @mdrejhon .
• Make swapping transition seamless by rendering non-opaque frames. * Thanks @mdrejhon .
• Move "Strobe" to separate files.

Sample screenshot from the debug mode: https://camo.githubusercontent.com/081e3641e118be7554e42f54149dc9ce5c862724/68747470733a2f2f7667792e6d652f54646634675a2e706e67

This pull request will be edited and updated! It stands for review now. (9.03.2018)

[a1batross]

Great, I will review it ASAP.

[fuzun]

In maintenance... Will be reopened.

[fuzun]

@a1batross - Take a look. OOP in C :) I hope you like macros.

I could not do some of your suggestions yet, but will try to do.

[a1batross]

Well... I think I need to write something like contributing recommendations.

[a1batross]

https://github.com/FWGS/xash3d/blob/master/CONTRIBUTING.md

Oops. I forgot about it.

[a1batross]

Just comment here, when it will be ready.

I also will merge it for upcoming code base sync with Xash3D 1.0.

[fuzun]

@a1batross Will FPS be global ? You have mentioned about flag operations, does version 1.0 contain new macros for that purpose ? And I have used some reserved keywords like "this" thinking it would not matter since it is a c file and therefore must be treated as c code, should I revert it to _this ?

Also will white color be added to the color table? I think it can be added after the "default" color (+1 increased array size).

[fuzun]

https://github.com/fuzun/strobe-api

[fuzun]

How to hook a StrobeAPI derived work (StrobeAPI implementation) into xash3d ?

• in cl_view.c V_PostRender function, this part can be modified:

  ifdef STROBE_ENABLED

      // if ( STROBE_TEMPLATE )
      //  STROBE_TEMPLATE->STROBE_IMPL_FUNC_DEBUGHANDLER( &STROBE_TEMPLATE );
      if ( STROBE_CORE )
          STROBE_CORE->STROBE_IMPL_FUNC_DEBUGHANDLER( &STROBE_CORE );

  endif

  Debug handling function (printing informative strobe debugging text output from StrobeAPI) of your Strobe implementation can be called here.

• in gl_rmain.c R_EndFrame function, this part can be modified:

  ifdef STROBE_ENABLED

  // StrobeAPI.Invoker( STROBE_INVOKE(STROBE_TEMPLATE) ); StrobeAPI.Invoker( STROBE_INVOKE(STROBE_CORE) );

  else

  • Check r_strobe_template.c.TEMPLATE and r_strobe_template.h.TEMPLATE files. They are templates for creating a new StrobeAPI implementation. They can be used as a base and for actual implementation Strobe-Core (r_strobe_core.h and r_strobe_core.c) can be inspected.

How StrobeAPI and StrobeAPI implementations exposed to xash3d ?

• A structure which contains console variables and Invoker, Constructor and Destructor functions are exposed through "StrobeAPI" instance of the structure.
• R_InitStrobeAPI( ) from StrobeAPI for registering console variables is exposed.
• Constructor, destructor, reinit, main functions from StrobeAPI implementations are exposed while being guarded by StrobeAPI macros.
• Bunch of macros starting with STROBE or _STROBE from StrobeAPI are exposed.
• Bunch of structures starting with STROBE or StrobeAPI_ from StrobeAPI are exposed.
• An implementation structure and its instance from StrobeAPI implementation are exposed while being guarded by StrobeAPI macros.
• StrobeAPI and StrobeAPI implementation generic functions and private variables etc. are NOT exposed.
• Contents of r_strobe_apiprotected.h are not exposed.
• If STROBE_DISABLED is defined, nothing is exposed.

Console variables

• r_strobe : For setting Strobe method. 1: NORMAL - BLACK , 2 : NORMAL - BLACK - BLACK, -3: BLACK - BLACK - BLACK - NORMAL . Set 0 to disable strobing.
• r_strobe_swapinterval : For setting phase swap interval of Strobing. (in seconds). May cause image retention if set to 0 in some monitors (0 disables phase swapping).
• r_strobe_debug : For informing StrobeAPI instance to do something with StrobeAPI informative debug output text. Strobe-Core implementation shows the output text in right-up corner of the screen. (0 or 1)
• r_strobe_cooldown : When standard deviation of collected FPS values in a certain time period exceeds the determined limit, strobing gets disabled for a time period. This cvar sets the time period of how long strobing is disabled when there is instability. Should be set 0 to disable instability induced strobing cooldown.
• deviation limit (not implemented): Standard deviation limit of FPS values collected in a time period.
• count of collected fps values (not implemented): How many FPS values should be collected before calculating standard deviation.

These variables are common in all StrobeAPI implementations because they are defined in StrobeAPI. In future these variables should be defined in implementations instead of StrobeAPI.

[a1batross]

Good. I will test it ASAP and merge for old engine. New engine isn't ready for public and things may change, but I hope new engine will support strobing too.

I have a question, though. Will strobing help to defeat motion blur at 60 Hz? I got a new device recently, it's 60 Hz but too blurry.

[fuzun]

I never intended to make this C89 compatible but for some reason compiler that Travis using can not compile if variables are defined in for statements due to "C89 compatibility". It does not need variables to be defined at start of a block.

I have a 60 hz screen and I am not satisfied with the strobing performance. Because even with the least aggressive strobe method (1 or -1), effective fps drops to 60/2 = 30 fps and frequency of signal drops to 30 hz. I find 30 fps/hz to be not enough for games xash3d support. r_strobe -2 method makes effective fps 40 but signal frequency (I call it PWM simulation) drops to 20 hz (60 * 1/3). I think at 20 hz it should not be even called as "strobing".

When I overclock the screen to 75 hz, strobing does not become annoying. So I think 75hz might be bare minimum for strobing.

I have another 60 hz screen that I overclocked it to 108 hz. Strobing helps too much for eliminating motion blur however that screen has only 220 cd/m2 peak brightness and even with least aggressive strobe method, screen becomes too dark. It also had image retention problem but it is fixed with r_strobe_swapinterval setting thanks to @mdrejhon .

And the last monitor I tested strobing is 144 hz. It has built-in hardware strobing so effective fps does not drop. The game is playable even with aggressive strobe methods like r_strobe = 2, 3 or -2 . I think that performance of software strobe method is like 30-35% of the built in hardware strobing.

There is an utility called CRU (Custom resolution utility) for overclocking monitors. I suggest you to try it.

As for this pull request, there are a few things that need to be corrected. They are not critical so you can merge it in my opinion. When I have time I will try to update it.