GFXCardProfiler Class Reference

#include <gfxCardProfile.h>

Inheritance diagram for GFXCardProfiler:

Detailed Description

Graphics Card Profile.

GFXCardProfiler provides a device independent wrapper around both the capabilities reported by the card/drivers and the exceptions recorded in various scripts.

The materials system keeps track of most caps-related rendering optimizations and/or workarounds, but it is occasionally necessary to expose capability information to higher level code (for instance, if some feature depends on a specific subset of render functionality) or to keep track of exceptions.

The proper way to fix this is to get the IHV to release fixed drivers and/or move to a single consistent rendering path that works. Of course, when you're releasing a game, especially on a timeline (or with a less than infinite budget) this isn't always a valid solution.

It's also often convenient to be able to tweak performance/detail settings based on the identified card type.

GFXCardProfiler addresses both these needs by providing two data retrieval methods and a generic interface for querying capability strings.

Note:: The GFXCardProfiler is at heart a system for implementing WORKAROUNDS. It is not guaranteed to work in all cases. The capability strings it responds to are specific to each implementation. You should be EXTREMELY careful when working with this functionality. When used in moderation it can be a project-saver, but if used to excess or without forethought it can lead to complex, hard-to-maintain code.

The first data retrieval method that the GFXCardProfiler supports is a card-specific capability query. This is implemented by each subclass. In the case of DirectX, this means using the built-in capability query. For OpenGL or other APIs, more exotic methods may be necessary. The goal of this method is to retrieve some reasonable defaults that can be overridden later if necessary.

The second data retrieval method is script based. In ./profile a collection of script files are stored. They are named in one of the forms:

 Renderer.cs
 Renderer.VendorString.CardString.cs
 Renderer.VendorString.CardString.cs
 Renderer.VendorString.CardString.VersionString.cs

These files are found and executed from most general to most specific. For instance, say we're working in the D3D renderer with an nVidia GeForce FX 5950, running driver version 53.36. The following files would be found and executed:

 D3D.cs
 D3D.nVidia.cs
 D3D.nVidia.GeForceFX5950.cs
 D3D.nVidia.GeForceFX5950.5336.cs

The general rule for turning strings into filename parts is to strip all spaces and punctuation. If a file is not found, no error is reported; it is assumed that the absence of a file means all is well.

Several functions are made available to allow simple logic in the script functions (for instance, to enable a workaround for a given range of driver versions). They are:

GFXCardProfiler::getRenderer()
GFXCardProfiler::getVendor()
GFXCardProfiler::getCard()
GFXCardProfiler::getVersion()

In addition, specific subclasses may expose other values (for instance, chipset IDs). These are made available as static members of the specific subclass. For instance, a D3D-specific chipset query may be made available as GFXD3DCardProfiler::getChipset().

Finally, once a script file has reached a determination they may indicate their settings to the GFXCardProfiler by calling GFXCardProfiler::setCapability(). For instance,

 // Indicate we can show the color red.
 GFXCardProfiler::setCapability("supportsRed", true);

GFXCardProfiler may be queried from script by calling GFXCardProfiler::queryProfile() - for instance:

 GFXCardProfiler::queryProfile("supportsRed"); // Query without default.
 GFXCardProfiler::queryProfile("supportsRed", false"); // Query with default.

As in the C++ code, if a capability string isn't found and no default is found, a console error will be reported.

icpi Internal Card Profile Interface

This is the interface implemented by subclasses of this class in order to provide implementation-specific information about the current card/drivers.
Basically, the implementation needs to provide some unique strings:

mVersionString indicating the current driver version of the card in question. (For instance, "53.36")
mCardDescription indicating the name of the card ("Radeon 8500")
getRendererString() indicating the name of the renderer ("DX9", "GL1.2"). Each card profiler subclass must return a unique constant so we can keep data separate. Bear in mind that punctuation is stripped from filenames.

The profiler also needs to implement setupCardCapabilities(), which is responsible for querying the active device and setting defaults based on the reported capabilities, and _queryCardCap, which is responsible for recognizing and responding to device-specific capability queries.

const String & getVersionString () const

const String & getCardString () const

const String & getChipString () const

U32 getVideoMemoryInMB () const

virtual const String & getRendererString () const =0

virtual void setupCardCapabilities ()=0

virtual bool _queryCardCap (const String &query, U32 &foundResult)=0

Implementation specific query code.

virtual bool _queryFormat (const GFXFormat fmt, const GFXTextureProfile *profile, bool &inOutAutogenMips)=0

String mVersionString

String mCardDescription

String mChipSet

U32 mVideoMemory

Public Member Functions

ecpi External Card Profile Interface

GFXCardProfiler ()

Called for a profile for a given device.

virtual ~GFXCardProfiler ()

virtual void init ()=0

Set load script files and generally initialize things.

U32 queryProfile (const String &cap)

Called to query a capability.

U32 queryProfile (const String &cap, U32 defaultValue)

Same as queryProfile(), but a default can be specified to indicate what value should be returned if the profiler doesn't know anything about it.

void setCapability (const String &cap, U32 value)

Set the specified capability to the specified value.

bool checkFormat (const GFXFormat fmt, const GFXTextureProfile *profile, bool &inOutAutogenMips)

Queries support for the specified texture format, and texture profile.

Protected Member Functions

helpergroup Helper Functions

Various helper functions.

void loadProfileScript (const char *scriptName)

Load a specified script file from the profiles directory, if it exists.

void loadProfileScripts (const char *render, const char *vendor, const char *card, const char *version)

Load the script files in order for the specified card profile tuple.

char * strippedString (const char *string)

Protected Attributes

Map< String, U32 > mCapDictionary

Capability dictionary.

Constructor & Destructor Documentation

GFXCardProfiler::GFXCardProfiler ( )

Called for a profile for a given device.

virtual GFXCardProfiler::~GFXCardProfiler ( ) [virtual]

Member Function Documentation

const String& GFXCardProfiler::getVersionString ( ) const [inline]

const String& GFXCardProfiler::getCardString ( ) const [inline]

const String& GFXCardProfiler::getChipString ( ) const [inline]

U32 GFXCardProfiler::getVideoMemoryInMB ( ) const [inline]

virtual const String& GFXCardProfiler::getRendererString ( ) const [pure virtual]

Implemented in GFXD3D8CardProfiler, GFXD3D9CardProfiler, and GFXGLCardProfiler.

virtual void GFXCardProfiler::setupCardCapabilities ( ) [protected, pure virtual]

Implemented in GFXD3D8CardProfiler, GFXD3D9CardProfiler, and GFXGLCardProfiler.

virtual bool GFXCardProfiler::_queryCardCap	(	const String &	query,
		U32 &	foundResult
	)			`[protected, pure virtual]`

Implementation specific query code.

This function is meant to be overridden by the specific implementation class.

Some query strings are handled by the external implementation while others must be done by the specific implementation. This is given first chance to return a result, then the generic rules are applied.

Parameters:

	query	Capability being queried.
	foundResult	Result to return to the caller. If the function returns true then this value is returned as the result of the query.

Implemented in GFXD3D8CardProfiler, GFXD3D9CardProfiler, and GFXGLCardProfiler.

virtual bool GFXCardProfiler::_queryFormat	(	const GFXFormat	fmt,
		const GFXTextureProfile *	profile,
		bool &	inOutAutogenMips
	)			`[protected, pure virtual]`

Implemented in GFXD3D8CardProfiler, GFXD3D9CardProfiler, and GFXGLCardProfiler.

void GFXCardProfiler::loadProfileScript ( const char * scriptName ) [protected]

Load a specified script file from the profiles directory, if it exists.

void GFXCardProfiler::loadProfileScripts	(	const char *	render,
		const char *	vendor,
		const char *	card,
		const char *	version
	)			`[protected]`

Load the script files in order for the specified card profile tuple.

char* GFXCardProfiler::strippedString ( const char * string ) [protected]

virtual void GFXCardProfiler::init ( ) [pure virtual]

Set load script files and generally initialize things.

Implemented in GFXD3D8CardProfiler, GFXD3D9CardProfiler, and GFXGLCardProfiler.

U32 GFXCardProfiler::queryProfile ( const String & cap )

Called to query a capability.

Given a query string it returns a bool indicating whether or not the capability holds. If you call this and cap isn't recognized then it returns false and prints a console error.

U32 GFXCardProfiler::queryProfile	(	const String &	cap,
		U32	defaultValue
	)

Same as queryProfile(), but a default can be specified to indicate what value should be returned if the profiler doesn't know anything about it.

If cap is not recognized, defaultValue is returned and no error is reported.

void GFXCardProfiler::setCapability	(	const String &	cap,
		U32	value
	)

Set the specified capability to the specified value.

bool GFXCardProfiler::checkFormat	(	const GFXFormat	fmt,
		const GFXTextureProfile *	profile,
		bool &	inOutAutogenMips
	)

Queries support for the specified texture format, and texture profile.

Member Data Documentation

String GFXCardProfiler::mVersionString [protected]

String GFXCardProfiler::mCardDescription [protected]

String GFXCardProfiler::mChipSet [protected]

U32 GFXCardProfiler::mVideoMemory [protected]

Map<String, U32> GFXCardProfiler::mCapDictionary [protected]

Capability dictionary.