Microsoft DirectX 8.1 Common Framework samples in the SDK ... · You can find further explanations of the graphics and multimedia concepts and terms discussed throughout the Microsoft®

MicrosoftDirectX8.1

CommonFramework

ThissourcecodeisfurnishedtohelpyougetupandrunningwithDirectXmorequickly.ItisintendedtoillustratehowDirect3Dworks,andreducethetimeittakestobuildsimpleapplicationsthatallowyoutoexperiment.ItisusedbythesamplesintheSDK.AllofthissourcecodelivesintheSamples\Multimedia\Common\SrcdirectorywhichcanbeinstalledduringtheSDKinstall.

Thiscodeisnotintendedtobecutandpasteintoaproductionapplication.Thisisnotbecauseitispoorlywritten,butratherthatitisnotdesignedforproduction.Noattempthasbeenmadetooptimizeitforperformance.Verylittleerrorcheckinghasbeenaddedasitobscuresthefunctionality.UsetocodetoexperimentwithDirect3Dtounderstandhowitworks.

Classes NamesCD3DApplicationCD3DArcBallCD3DCameraCD3DFrameCD3DFileCD3DFontCD3DMeshCD3DScreenSaver

Functions NamesD3DUtil_CreateTextureD3DUtil_CreateVertexShaderD3DUtil_GetCubeMapVertexD3DUtil_GetRotationFromCursorD3DUtil_InitMaterialD3DUtil_InitLightD3DUtil_SetColorKey

D3DUtil_SetDeviceCursor

Structures NamesD3DModeInfoD3DWindowedModeInfoD3DDeviceInfoD3DAdapterInfoMonitorInfoRenderUnit

Macros Names

ErrorCodes Names

MicrosoftDirectX8.1(C++)

Direct3DXShaderAssemblersReferenceThissectioncontainsreferenceinformationforthevertexandpixelshaderassemblersprovidedbytheDirect3DXutilitylibrary.

VertexShaderAssemblerReferencePixelShaderAssemblerReference

AlloftheexamplesyntaxusedinthisdocumentationisintendedtodemonstratehowtowriteshaderswhenusingtheDirect3DXvertexandpixelshaderassemblers.


IntroducingDirectX8.1Microsoft®DirectX®isasetoflow-levelapplicationprogramminginterfaces(APIs)forcreatinggamesandotherhigh-performancemultimediaapplications.Itincludessupportfortwo-dimensional(2-D)andthree-dimensional(3-D)graphics,soundeffects,music,inputdevices,andnetworkedapplicationssuchasmultiplayergames.

ThisdocumentprovidesintroductoryinformationaboutDirectX8.1.Informationisdividedintothefollowingsections.

What'sNewinDirectX8.1DirectX8.1ComponentsUsingtheDirectX8.1DocumentationDirectXToolsProgrammingDirectXwithC/C++FurtherInformation


What'sNewinDirectX8.1Microsoft®DirectX®8.1isamajorreleaseprimarilyforgraphics.Itincludesseveralnewfeaturesforgraphics,andbugfixesforMicrosoftDirectInput®andMicrosoftDirectPlay®.

NewToolsinDirectX

AppWizard.ThistoolprovidesanapplicationwizardforcreatingaDirectXapplicationwithanycombinationofDirectXcomponents.Thistoolisinstalledduringthesoftwaredevelopmentkit(SDK)installandcanbeaccessedwithinMicrosoftVisualStudio®whencreatinganewapplication.FormoreinformationseeAppWizard.ErrorLookupTool.Usethistooltotakethehexadecimalerrorcodesandlookupatext-basederrormessage.ThistoolisinstalledaspartoftheSDKinstallandcanbeaccessedfromStart,Programs,MicrosoftDirectX8.1SDK,DirectXUtilities,DirectXErrorLookup.

NewFeaturesinDirectXGraphics

Expandedpixelshaderfunctionalitywithnewversion1.2,1.3,and1.4.ExpandedthefunctionalityoftheDirect3DX(D3DX)utilitylibraryformeshes,textures,bumpmapping,textures,andquaternions.MeshView.Thistoolprovidesaneasywaytoload,view,andmodifymeshes,andgenerallyexerciseD3DXfunctionalityonprogressivemeshes.Formoreinformationaboutthetool,seeMeshViewHelp.Anewscreensaversampleisincludedthatisbuiltonthescreensaversampleframework.Thenewframeworkincludessupportformultiplemonitors.Addednewsamples.Reorganizedthedocumentationintoreferenceandprogrammingguides.Expandedshadersandeffectssections.

FormoreinformationseeWhat'sNewinGraphics,orseeeachofthecomponents.

NewFeaturesinDirectInput

Version8.1primarilyincludesperformanceimprovementsforDirectInput.

Formoreinformation,seeWhat'sNewinDirectInput.

NewFeaturesinDirectPlay

Version8.1primarilyincludesperformanceimprovementsforDirectPlay.

Formoreinformation,seeWhat'sNewinDirectPlay.

NewFeaturesinDirectX8.0

CompleteintegrationofDirectDrawandDirect3DMicrosoftDirectDraw®andMicrosoftDirect3D®aremergedintoasingleDirectXGraphicscomponent.Theapplicationprogramminginterface(API)hasbeenextensivelyupdatedtomakeiteveneasiertouseandtosupportthelatestgraphicshardware.

DirectMusicandDirectSoundmoreintegratedMicrosoftDirectMusic®andMicrosoftDirectSound®aremoretightlyintegratedthanwithDirectX7.0.WavefilesorresourcescannowbeloadedbytheDirectMusicloaderandplayedthroughtheDirectMusicperformance,synchronizedwithMIDInotes.

DirectPlayupdatedTheDirectPlaycomponenthasbeenextensivelyupdatedtoincreaseitscapabilitiesandimproveitsease-of-use.Inparticular,DirectPlaynowsupportsvoicecommunicationbetweenplayers.

DirectInputupdatedDirectInputintroducesonemajornewfeature:actionmapping.Actionmappingenablesyoutoestablishaconnectionbetweeninputactionsandinputdevices,whichdoesnotdependontheexistenceofparticulardeviceobjects.Itsimplifiestheinputloopandreducestheneedforcustomgamedrivers,customdeviceprofilers,andcustomconfigurationofuserinterfacesingames.

DirectShowincludedinDirectXMicrosoft®DirectShow®isnowpartofDirectXandhasbeenupdatedforthisrelease.

DebugbuildavailableYoucanusetheDirectXControlPanelApplicationtoswitchbetweenthedebugandretailbuildsofDirectInput,Direct3D,andDirectMusic.Toenablethisfeature,selectDebugwhenyouinstallthesoftwaredevelopmentkit(SDK).Thisoptioninstallsbothdebugandretaildynamic-linklibraries(DLLs)onyoursystem.TheRetailoptioninstallsonlytheretailDLLs.


DirectX8.1ComponentsMicrosoft®DirectX®8.1ismadeupofthefollowingcomponents.

DirectXGraphicscombinestheMicrosoftDirectDraw®andMicrosoftDirect3D®componentsofpreviousDirectXversionsintoasingleapplicationprogramminginterface(API)thatyoucanuseforallgraphicsprogramming.ThecomponentincludestheDirect3DXutilitylibrarythatsimplifiesmanygraphicsprogrammingtasks.DirectXAudiocombinestheMicrosoftDirectSound®andMicrosoftDirectMusic®componentsofpreviousDirectXversionsintoasingleAPIthatyoucanuseforallaudioprogramming.MicrosoftDirectInput®providessupportforavarietyofinputdevices,includingfullsupportforforce-feedbacktechnology.MicrosoftDirectPlay®providessupportformultiplayernetworkedgames.MicrosoftDirectShow®providesforhigh-qualitycaptureandplaybackofmultimediastreams.MicrosoftDirectSetupisasimpleAPIthatprovidesone-callinstallationoftheDirectXcomponents.


UsingtheDirectX8.1Documentation

Thefollowingconventionsareusedinthesyntaxofmethods,functions,andotherAPIelements,aswellasinexplanatorymaterialandsamplecode.

Convention Meaning

Italictext

Denotesaplaceholderorvariable.Youmustprovidetheactualvalue.Forexample,thestatementSetCursorPos(X,Y)requiresyoutosubstitutevaluesfortheXandYparameters.

BoldtextDenotesafunction,procedure,structure,macro,interface,method,datatype,orotherkeywordintheprogramminginterfaceorlanguage.

[] Enclosesoptionalparameters.... Specifiesthattheprecedingitemmayberepeated.FULLBOLDCAPITALS Usedformosttypeandstructurenames.

FULLCAPITALS Usedforenumerationvalues,flags,andconstants.monospace Usedforcodeexamplesandsyntaxspacing..

.

.

Representsanomittedportionofasampleapplication.


FurtherInformationYoucanfindfurtherexplanationsofthegraphicsandmultimediaconceptsandtermsdiscussedthroughouttheMicrosoft®DirectX®documentation,aswellasinformationonMicrosoft®Windows®programmingingeneral,inthefollowingsources:

Bargen,BradleyandPeterDonnelly,InsideDirectX,Microsoft®Press®,1998.Begault,DurandR.,3-DSoundforVirtualRealityandMultimedia,AcademicPress,1994.Blinn,James,JimBlinn'sCorner:ATripDowntheGraphicsPipeline,MorganKaufmann,1996.Dodge,CharlesandThomasA.Jerse,ComputerMusic:Synthesis,Composition,andPerformance,SchirmerBooks,1997(2ndedition).Foley,JamesD.,ComputerGraphics:PrinciplesandPractice,Addison-Wesley,1991(2ndedition).Hearn,DonaldandM.PaulineBaker,ComputerGraphics,Prentice-Hall,1986.Kientzle,Tim,AProgrammer'sGuidetoSound,Addison-WesleyDevelopersPress,1998.Kovach,PeterJ.,InsideDirect3D,MicrosoftPress,2000.Petzold,Charles,ProgrammingWindows98,MicrosoftPress,1998(5thedition).Thompson,Nigel,3DGraphicsProgrammingforWindows,MicrosoftPress,1996.Watt,AlanH.,andMarkWatt,AdvancedAnimationandRenderingTechniques,Addison-Wesley,1992.

AdditionalsourcesfortheconceptsandtermsassociatedwithCOMcanbefoundinthefollowingsources:

Brockschmidt,Kraig,InsideOLE2,MicrosoftPress,1995(2ndedition).Rogerson,DaleE.,InsideCOM,MicrosoftPress,1997.


MeshViewHelpMenuDescriptions

File

OpenMeshFile

Opensadialogtoselectafileinthe.xor.mfileformattobeloadedandviewed.

OpenPMeshFile

Opensadialogtoselectafileintheprogressivemeshformattobeloadedandviewed.

CreateShape

Opensasub-dialogtocreatesomebasicshapesthataredefinedprogrammatically(text,polygon,box,cylinder,torus,teapot,sphere,cone).

SaveMeshAs

Opensadialogtosavetheselectedmeshtoafile.Thefilecanbewrittenasatextorbinaryfile.

CloseSelected

Closesanddeletesthecurrentlyselectedmesh.

CloseNonSelected

Closesanddeletesthemeshesthatarenotcurrentlyselected.

View

Wireframe

Viewallcontentinwireframemode.

Edges

Viewallcontentinsolid-shadedmodewiththeedgesdrawninblack.

Creases

Highlightthecreasesonthevisiblemeshes.Acreaseisanedgewithavertexthathasadifferentpieceofdataonitformultiplefacesthatrefertoit,thatis,adifferentnormalforthevertexperface.

Strips

Showthestripsthataregeneratedbythismeshinblue.Thebluelinegoesfromthecenterofeachtriangletothenexttriangleinthetrianglestrip.

Adjacency

Showtheadjacencyofthepolygonsinameshbydrawingalinefromthecenterofapolygontothecenteroftheadjacentpolygon.

BoundingBox

Drawtheboundingboxesforthevisiblemeshes.

Normals

Drawthenormalsoftheverticesonthevisiblemeshesinyellow.

TextureCoords

Showthetexturecoordinatesfortheviewedgeometryasraysprojectingfromthevertices.BecauseavertexinMicrosoft®Direct3D®canhaveuptoeighttexturecoordinates,usersmustspecifywhichsetstheywouldliketoview.Thisviewingmodeisespeciallyusefulwhenthetexturecoordinatesarefilledwithtangentsforuseinpixelshadersforexample.

Textures

Displaythetexturesonthevisiblegeometry.

Lighting

Showthegeometryinthescenewithlightingcalculationsstillon.

Culling

Performbackfacecullingonthevisiblegeometrywhendisabledpolygonsfacingawayfromthecameraarenotdrawn.

Hierarchy

Displaytheframehierarchyofthemeshesthatarecurrentlyloaded.Thisisdisplayedinaseparatefloatingwindow.Tomakethewindowdisappear,ontheViewmenu,cleartheHierarchycommand.

PlayAnimation

Playthecurrentanimationforthecurrentlyloadedgeometryifoneexists.

PauseAnimation

Stoptheanimationatthecurrentframewhenplaying.

NormalSpeed

InterpretthetimevalueintheanimationfromanXfileas4800unitspersecond.Otherwise,theinterpretedvalueis30unitspersecond.

MeshOps

Optimize

Optimizesthecurrentlyselectedmeshwiththeselectedoptimizationmethod.SeetheMicrosoft®Direct3DXreferencepagestoseethedifferencesinmethods.

WeldVertices

Removesduplicateverticesandmakespolygonsthatusetheseverticesusethenondeletedvertex.

SplitMesh

Splitstheselectedmeshintomultiplemeshesthatarelessthanspecifiedsizeinverticesandfaces.

CollapseMeshes

Collapsesthecurrentlyselectedmeshesintoasinglemesh.

ResetMatrices

Resetsthematricesfortheframesthatareloadedtotheirinitialposition.

MeshProperties

Showstheselectedmesh'sFVFrenderstatesandwhetherornotitisa32bitmesh.

SkinningMethod

Allowstheusertoselecttheskinningmethodwhileanimatingaskinnedmesh.Thechoicesarenonindexed,indexed,andsoftwareskinning.

FaceSelection

Entersamodefortheusertoselectanindividualfaceonthecurrentmesh.

VertexSelection

Entersamodefortheusertoselectanindividualvertexonthecurrentmesh.

PMeshes

ConvertSelectedtoPM

Converttheselectedmeshtoaprogressivemesh.Theconversionusestheerrorparametersthatareenteredinadialogbox.FormoreinformationontheseparametersrefertotheDirect3DXdocumentationofprogressivemeshes.

SnapshottoMesh

Convertthecurrentprogressivemeshobjecttoastaticmeshobjectusingthecurrentsettingsoftheprogressivemesh.

SetnumberofFaces

Setthecurrentnumberoffacesintheprogressivemeshtoaspecificnumber.

SetnumberofVertices

Setthecurrentnumberofverticesintheprogressivemeshtoaspecificnumber.

Trim

Settheminimumandmaximumnumberoffacesforaprogressivemesh.Oncetheuserhassetthetrimvaluestothedesiredminimumandmaximum,theprogressivemeshcanbetrimmedtotheselectedvalues,therebyreducingthedynamicrangeoftheprogressivemesh.

N-Patches

N-PatchSelected

DrawthecurrentobjectasanN-Patchesobject.ThescrollbarinthismodeselectstheamountofN-Patchiterationsforthecurrentobject.

SnapShottomesh

ConverttheselectedobjecttoastaticmeshbasedonthecurrentN-Patchsettingstocreateahigh-resolutionstaticmesh.

IconsandUsage

Icons

SelectionModes

Thefirstthreeiconsareeasywaysfortheusertoselecttheselectionmode.TheyareMeshSelectionMode(Arrow),FaceSelectionMode(yellowoutlinedtriangle),andVertexSelectionMode(Redpointhighlightedtriangle).ThesearethesamemodesthatareavailablefromthemenusinMeshOps.

DisplayModes

Thenexticonsareeasywaystoselectthemostcommondisplaymodesforgeometry.TheyareShadedmode(nonoutlinedtri-colorcube),Wireframemode(wireframecube),andEdgemode(outlinedtri-colorcube).ThesearethesamemodesthatareavailablefromthemenusinView.

TopologyDisplaymodes

Thenexticonsdisplayspecifictopologicalinformationaboutthegeometrydisplayed.Theyareadjacency(A),Strips(S),Creases(C),andNormals(N).ThesearethesamemodesthatareavailablefromthemenusinView.

Info

Thenexticonistheinfobuttonthatwilldisplayinformationaboutthecurrentlyselectedelement.

AnimationControls

Thelasttwoiconsareanimationcontrolsforplayingandpausingtheanimationforthecurrentlyvisiblemesh.

StatusBar

ThestatusbarinMViewdisplaysthecurrentstatusofthevisiblegeometry.The

orderfromlefttorightofthedisplayedinformationiscurrentlyselectedelement(faceorvertexonly),Meshmode(polygon,Pmesh,orpMesh),displayframespersecond,displaytrianglespersecond,numberofdisplayedtriangles,andnumberofdisplayedvertices.

ScrollBar

Thescrollbarwillappearintwoofthethreemeshmodes,pMeshandnPatchmode.InpMeshmode,thescrollbarindicatestherangeofdisplayedtrianglesfortheprogressivemesh.Youcanslidethescrollbarupordowntochangethenumberoftrianglesdisplayed.InnPatchmode,thescrollbarindicateshowmanynPatchlevelsarebeingused.Asthescrollbarismovedupordown,thenumberofnPatchinteractionsperformedareadjustedaccordingly.

MoreInformation

FormoreinformationonanyofthefunctionsusedbyMView,refertotheDirect3DXdocumentationincludedintheMicrosoft®DirectX®softwaredevelopmentkit(SDK).


MoireSample

Description

ThemoiresampleshowshowtousetheMicrosoft®DirectX®softwaredevelopmentkit(SDK)screensaverframeworktowriteascreensaverthatusesMicrosoft®Direct3D®.Thescreensaverframeworkissimilartothesampleapplicationframework,usingmanymethodsandvariableswiththesamenames.Afterwritingaprogramwiththescreensaverframework,youendupwithafully-functionalMicrosoft®Windows®screensaver,ratherthanwitharegularWindowsapplication.

Themoirescreensaverappearsasamesmerizingsequenceofspinninglinesandcolors.Itusestexturetransformationandalphablendingtocreateahighlyanimatedscene,eventhoughthepolygonsthatmakeupthescenedonotmoveatall.

Path

Source:(SDKroot)\Samples\Multimedia\Direct3D\ScreenSavers\Moire

Executable:(SDKroot)\Samples\Multimedia\Direct3D\Bin

User'sGuide

Moire.scrcanbestartedinfivemodes:configuration,preview,full,test,andpassword-change.Youcanchoosesomemodesbyclickingtherightmousebutton(right-click)onthemoire.scrfileandchoosingConfigureorPreview.Oryoucanstartmoire.scrfromthecommandlinewiththefollowingcommand-lineparameters:-c Configurationmode-t Testmode-p Previewmode-a Password-changemode-s Fullmode

Whenthescreensaverisrunninginfullmode,pressanykeyormovethemousetoexit.

ProgrammingNotes

ProgramsthatusethescreensaverframeworkareverysimilartoprogramsthatusetheDirect3Dsampleapplicationframework.Eachscreensaverneedstocreateaclassderivedfromthemainapplicationclass,CD3DScreensaver.Toprovidefunctionalityspecifictoeachscreensaver,thescreensaverimplementsitsownversionsofthevirtualfunctionsFrameMove,Render,InitDeviceObjects,andsoforth.

Screensaverscanbewrittentobemultimonitor-compatible,withoutmuchextraeffort.Ifyoudonotwantyourscreensavertorunonmultiplemonitors,youcanjustsetthem_bOneScreenOnlyvariabletoTRUE.ThisvalueissettoFALSEbydefault.ThefunctionSetDevicewillbecalledeachtimethedevicechanges.ThewaythatmoiredealswiththisistocreateastructurecalledDeviceObjects,whichcontainsalldevice-specificpointersandvalues.CMoireScreensaverholdsanarrayofDeviceObjectsstructures,calledm_DeviceObjectsArray.WhenSetDeviceiscalled,m_pDeviceObjectsischangedtopointtotheDeviceObjectsstructureforthespecifieddevice.Whenrendering,m_rcRenderTotalreferstotherenderingareathatspansallmonitors,andm_rcRenderCurDevicereferstotherenderingareaforthecurrentdevice'smonitor.ThefunctionSetProjectionMatrixshowsonewaytosetupaprojectionmatrixthatmakesproperuseofthesevariablestoeitherrenderascenethatspansallthemonitors,ordisplayacopyofthesceneoneachmonitor.Theprojectionmatrixuseddependsonthevalueofm_bAllScreensSame,whichyoucanenabletheusertocontrolintheconfigurationdialog.

TheReadSettingsfunctioniscalledbythescreensaverframeworkatprogramstartuptime,toreadvariousscreensaversettingsfromtheregistry.DoConfigiscalledwhentheuserwantstoconfigurethescreensaversettings.Theprogramshouldrespondtothisbycreatingadialogboxwithcontrolsforthevariousscreensaversettings.ThisdialogboxshouldalsohaveabuttoncalledDisplaySettingswhich,whenpressed,shouldcallDoScreenSettingsDialog.Thiscommondialogboxallowstheusertoconfigurewhatrendereranddisplaymodeshouldbeusedoneachmonitor.Youshouldsetthemembervariablem_strRegPathtoaregistrypaththatwillholdthescreensaver'ssettings.Youcanusethisvariableinyourregistryread/writefunctions.Thescreensaver

frameworkwillalsousethisvariabletostoreinformationaboutthedefaultdisplaymodeinsomecases.

ThissampleusescommonDirectXcodethatconsistsofprogrammingelementssuchashelperfunctions.ThiscodeissharedwithothersamplesintheDirectXSDK.Youcanfindthecommonheadersandsourcecodein(SDKroot)\Samples\Multimedia\Common.


What'sNewinDirectXGraphicsThissectiondescribesMicrosoft®DirectX®graphicsfeaturesthatarenewinDirectX8.x.

Toseewhat'snewinallofDirectX,seeWhat'snewinDirectX8.1.


PixelShaders

Addedpixelshaderversions1.2,1.3,and1.4.Thesenewversionsexpandexistingfunctionalitythroughamorepowerfulsetofinstructions,registers,andmodifiersforprogrammingpixelshaders.

NewD3DXFunctionality

MeshAPI

AddedmeshfunctionalitytoimproveperformanceusingD3DXConvertMeshSubsetToStripsandD3DXConvertMeshSubsetToSingleStrip.UsetheOptimizedMeshsampletounderstandimprovingmeshperformance.ImprovedsupportforprogressivemesheswithOptimizeBaseLOD,TrimByVerticesandTrimByFaces.AddedD3DXSplitMeshtohelpsplitmeshesintosmallermeshes.

BumpMapping

AddedD3DXComputeTangenttocreateaper-vertexcoordinatesystembasedontexturecoordinategradients.D3DXComputeNormalMapconvertsaheightfieldtoanormalmap.

MeshViewTool

Thistoolprovidesaneasywaytoload,view,andmodifymeshes,andgenerallyexerciseDirect3DX(D3DX)functionalityonprogressivemeshes.Thistoolisinstalledaspartofthesoftwaredevelopmentkit(SDK)installandcanbeaccessedfromStart/Programs/MicrosoftDirectX8.1SDK/DirectXUtilities/DirectXMeshView.Formoreinformationaboutthetool,seeMeshViewHelp.

EffectFramework

Effects.Addedstringsupport,addedcomments,andremovedFourCC

constraints.EffectframeworkAPI.Supportforstatesavingandrestoring,supportforhandlingOnLostandOnReset,supportSet*()afterBegin().AlloftheID3DXTechniquefunctionalityhasbeenmovedintotheID3DXEffectinterfacetosimplifytheeffectinterface.

TextureLibrary

ImplementedahigherqualityDXTnencodingalgorithm.UseD3DXGetImageInfoFromtogetimageinformationbeforeloadingit.Includessupportfordynamictextures.D3DXSaveSurfaceToFilesupports8-bitpaletted.bmpfilesand24-bitRGB.ddsfilesinallformats:mipmaps,cubemaps,volumes.D3DPOOL_SCRATCHallowscreationofresourcesthatarenotlimitedbydevicecapabilities.Theycanbecreatedanddestroyed,lockedandunlocked.Theseresourcescanbesettoadeviceandusedinrendering.UsewithD3DXtoconverttosomethinguseablesuchasloadingahigh-precisionheightfieldandconvertingtoanormalmap.Texturefillfunctions,D3DXFillTexture,D3DXFillCubeTexture,andD3DXFillVolumeTexture.

MathLibrary

Newmathfunctions:AdditionalsupportforsphericalquadraticquaternioninterpolationusingD3DXQuaternionSquadSetup.UseitwithD3DXQuaternionSquad.D3DXMatrixMultiplyTransposeformatricesinvertexshadersandD3DXFresnelTerm.Mathlibrary.AddedCPUspecificoptimizationsformostimportantfunctionsfor3DNow,SSE,andSSE2.Supportfor16-bytealignedmatricesusingD3DXMATRIXA16.

Samples

Severalnewsampleshavebeenincludedtodemonstrateculling,lighting,volumefog,andself-shadowingusingashadowvolume.Anewscreensaversampleisincludedthatisbuiltonthescreensaversampleframework.Thenewframeworkincludessupportformultiplemonitors.

DocumentationUpgrades

DXGraphicsSDKDocs.ThegraphicsSDKdocumentationhasbeenreorganizedintotwosections:aReferencesectionandaProgrammersGuide.Newsectionsforcreatingprogrammablevertexshaders,pixelshaders,andeffectshavebeenaddedtotheProgrammersGuide.TheglobalilluminationequationsandtheMathematicsofLightingsectionhavebeenrewrittenandexamplesincluded.


ThisversionmaintainsbackwardcompatibilitybyexposingandsupportingobjectsandinterfacesofferedbypreviousreleasesofDirectX.However,manynewfeaturesandperformanceenhancementshavealsobeenaddedtotheMicrosoftDirect3D®APIinterfaces.

PixelandVertexShaders

ThetwoprogrammablesectionsoftheDirect3Darchitecturearevertexshadersandpixelshaders.Vertexshadersareinvokedpriortovertexassemblyandoperateonvertices.PixelshadersareinvokedafteranyDrawPrimitiveorDrawIndexedPrimitivecallsandgeneratethepixelsthatarewrittentotherendertarget.Theadditionofprogrammableshadersforvertexandpixeloperationsprovidestheframeworkforreal-timeprogrammableeffectsthatrivalmoviequality.Theinnovativefreedomthatthisprogrammabilitygivesbacktogamedevelopers—byallowingthemtoimplementwhatevereffecttheyseefitwiththeprogrammablepipeline—hasthepotentialtounlockanewroundofincrediblegames.PixelandvertexshaderscanbewrittenusingASCIIfiles,thustheshaderfilescanbeupdatedatruntimewithoutrecompilingthesourceapplication.

Effects

Allowsyoutochangehowanobjectisrendered,basedonthehardwarecapabilitiesofthemachineyourapplicationisrunningon.EffectsarewrittenusingASCIIfiles,thustheeffectfilecanbeupdatedatruntimewithoutrecompilingthesourceapplication.

CompleteIntegrationofDirectDrawandDirect3D

Simplifiesapplicationinitializationandimprovesdataallocationandmanagementperformance,whichreducesthememoryfootprint.Also,theintegrationofthegraphicsAPIsenableparallelvertexinputstreamsformoreflexiblerendering.

MultisamplingRenderingSupport

Enablesfull-sceneantialiasingandmultisamplingeffects,suchasmotionbluranddepth-of-field.

PointSprites

Enableshigh-performancerenderingofparticlesystemsforsparks,explosions,rain,snow,andsoon.

3-DVolumetricTextures

Enablesrange-attenuationinper-pixellightingandvolumetricatmosphericeffects,andcanbeappliedtomoreintricategeometry.

Higher-OrderPrimitiveSupport

Enhancestheappearanceofthree-dimensional(3-D)contentandfacilitatesthemappingofcontentfrommajor3-Dauthoringtools.

Higher-LevelTechnologies

Includes3-Dcontent-creationtoolplug-ins(forexporttoDirect3D)forskinnedmeshesthatuseavarietyofDirect3Dtechniques,multiresolutionlevel-of-detail(LOD)geometry,andhigher-ordersurfacedata.

IndexedVertexBlending

Extendsgeometryblendingsupporttoallowthematricesusedforvertexblendingtobereferredtousingamatrixindex.

ExpansionoftheDirect3DXUtilityLibrary

Containsawealthofnewfunctionality.TheDirect3DXutilitylibraryisahelperlayerthatsitsontopofDirect3Dtosimplifycommontasksencounteredby3-Dgraphicsdevelopers.Includesaskinninglibrary,supportforworkingwithmeshes,andfunctionstoassemblevertexandpixelshaders.About20newfunctionshavebeenaddedforDirectX8.1.NotethatthefunctionalitysuppliedbyD3D_OVERLOADS,firstintroducedwithDirectX5.0,hasbeenmovedtotheDirect3DXutilitylibrary.


What'sNewinDirectInputNewFeaturesforDirectInput8.1

Microsoft®DirectX®8.1isamajorreleaseprimarilyforDirectXgraphics.TheimprovementsforMicrosoftDirectInput®areprimarilyperformanceenhancements.

TofindoutmoreaboutthenewfeaturesinDirectX,seeWhat'sNewinDirectX8.1.

NewFeaturesforDirectInput8.0

ThefollowingaresomeofthenewfeaturesinDirectInput.

ActionmappingDirectInputforDirectX8.0introducesamajornewfeature:actionmapping.Actionmappingenablesyoutoestablishaconnectionbetweeninputactionsandinputdevicesthatdoesnotdependontheexistenceofparticulardeviceobjects(suchasspecificbuttonsoraxes).Actionmappingsimplifiestheinputloopandreducestheneedforcustomgamedrivers,customdeviceprofilers,andcustomconfigurationuserinterfacesingames.

Formoreinformation,seeActionMapping.

NewDirectInputobjectfeaturesTheDirectInputobjectisnowrepresentedbytheIDirectInput8interface.Anewhelperfunction,DirectInput8Create,createstheobjectandretrievesthisinterface.IDirectInput8hasanewCLSIDandcannotbeobtainedbycallingQueryInterfaceonaninterfacetoobjectsoftheclassCLSID_DirectInputusedinearlierDirectXversions.

NewkeyboardpropertiesTwokeyboardpropertieshavebeenadded:DIPROP_KEYNAME,whichretrievesalocalizedkeyname,andDIPROP_SCANCODE,whichretrievesthescancode.

JoysticksliderdatainrglSliderarrayJoysticksliderdatathatwasassignedtothez-axisofaDIJOYSTATEorDIJOYSTATE2structureunderearlierDirectXversionswillnowbefoundintherglSliderarrayofthosesamestructures.

MicrosoftDirectX8.1(pixelshaderversions1.0,1.1,1.2,1.3,1.4)

Instructions

Pixelshaderscontainthefollowingtypesofinstructions.

AVersioninstructiondefinestheshaderversion.Thereisonlyoneversioninstructioninashaderanditisthefirstinstructioninashader.Constantinstructionsdefineconstants.Theseinstructionsmustbeaftertheversioninstructionandbeforeanyarithmeticortextureaddressinstructions.APhaseinstructionsplitsashaderintotwosections:phase1andphase2.Eachphasehasseparatearithmeticandtextureaddressinstructionlimits.Version1.4istheonlyversionthatsupportsthephaseinstruction.Arithmeticinstructionsincludecommonmathematicaloperationssuchasaddandsubtract,multiply,andtakingadotproduct.TextureAddressinstructionsmanipulatetexturecoordinatedatathatisassociatedwithtexturestages.

Theinstructionsarelistedbelow.

Versioninstructions Version1.0 1.1 1.2 1.3 1.4

ps x x x x x

Constantinstructions Version1.0 1.1 1.2 1.3 1.4

def x x x x x

Phaseinstructions Version1.0 1.1 1.2 1.3 1.4

phase x

Arithmeticinstructions Version1.0 1.1 1.2 1.3 1.4

add x x x x xbem xcmp x x xcnd x x x x xdp3 x x x x xdp4 x x x

lrp x x x x xmad x x x x xmov x x x x xmul x x x x xnop x x x x xsub x x x x x

Textureaddressinstructions Version1.0 1.1 1.2 1.3 1.4

tex x x x xtexbem x x x xtexbeml x x x xtexcoord x x x xtexcrd xtexdepth xtexdp3 x xtexdp3tex x xtexkill x x x x xtexld xtexm3x2depth xtexm3x2pad x x x xtexm3x2tex x x x xtexm3x3 x xtexm3x3pad x x x xtexm3x3tex x x x xtexm3x3spec x x x xtexm3x3vspec x x x xtexreg2ar x x x xtexreg2gb x x x xtexreg2rgb x x

MicrosoftDirectx8.1(pixelshaderversions1.0,1.1,1.2,1.3,1.4)

Registers

Registersholddataforusebythepixelshader.Registersarefullydescribedinthefollowingsections.

RegisterTypes.Describesthefourtypesofregistersavailableandtheirpurposes.ReadPortCount.Detailstherestrictionsonusingmultipleregistersinasingleinstruction.Read-only,Read/Write.Describeswhichregisterscanbeusedforreading,writing,orboth.Range.Detailstherangeofthecomponentdata.

RegisterTypes

RegisterstransferdatatotheshaderALUandstoretemporaryresults.Thetablebelowidentifiesthefourtypesofregistersandthenumberavailableineachshaderversion.

Registername Type Versions1.0 1.1 1.2 1.3 1.4

cn Constantregister 8 8 8 8 8rn Temporaryregister 2 2 2 2 6tn Textureregister 4 4 4 4 6vn Colorregister 2 2 2 2 2inphase2

Constantregisterscontainconstantdataorganizedinfourfixed-pointvalues.DatacanbeloadedintoaconstantregisterusingSetPixelShaderConstantoritcanbedefinedusingthedefshaderinstruction.Constantregistersarenotusablebytextureaddressinstructions.Theonlyexceptionisthetexm3x3specinstruction,whichusesaconstantregistertosupplyaneye-rayvector.

Temporaryregistersareusedtostoreintermediateresults,asfourfixed-pointvalues.r0additionallyservesasthepixelshaderoutput.Thevalueinr0attheendoftheshaderisthepixelcolorfortheshader.

Shaderpre-processingwillfailCreatePixelShaderonanyshaderthatattemptstoreadfromatemporaryregisterthathasnotbeenwrittenbyapreviousinstruction.D3DXAssembleShaderwillfailsimilarly,assumingvalidationisenabled(donotuseD3DXASM_SKIPVALIDATION).

TextureregistersPixelshaderversion1.1to1.3

Forpixelshaderversion1.1to1.3,textureregisterscontaintexturedata,organizedinfourfixed-pointvalues.Texturedataisloadedintoatextureregisterwhenatextureissampled.Texturesamplingusestexturecoordinatestolookup,orsample,acolorvalueatthespecified(u,v,w,q)coordinateswhiletakingintoaccountthetexturestagestateattributes.Thetexturecoordinatedataisinterpolatedfromthevertextexturecoordinatedataandisassociatedwithaspecifictexturestage.Thereisadefaultone-to-oneassociationbetweentexturestagenumberandtexturecoordinatedeclarationorder.Bydefault,thefirstsetoftexturecoordinatesdefinedinthevertexformatisassociatedwithtexturestage0.

Forthesepixelshaderversions,textureregistersbehavejustliketemporaryregisterswhenusedbyarithmeticinstructions.Forpixelshaderversion1.0,textureregistersareread-onlytoarithmeticinstructions.

Pixelshaderversion1.4

Forpixelshaderversion1.4,textureregisters(t#)containread-onlytexturecoordinatedata.Thismeansthatthetexturecoordinatesetandthetexturestagenumberareindependentfromeachother.Thetexturestagenumber(fromwhichtosampleatexture)isdeterminedbythedestinationregisternumber(r0tor5).Forthetexldinstruction,thetexturecoordinatesetisdeterminedbythesourceregister(t0tot5),sothetexturecoordinatesetcanbemappedtoanytexturestage.Inaddition,thesourceregister(specifyingtexturecoordinates)fortexldcanalsobeatemporaryregister(r#),inwhichcasethecontentsofthetemporaryregisterareusedastexturecoordinates.

Forthispixelshaderversion,textureregisterscontaintexture

coordinatedataandarealsoavailabletotextureaddressinginstructionsassourceparameters.

Colorregisterscontainper-pixelcolorvalues.Thevaluesareobtainedbyper-pixeliterationofthediffuseandspecularcolorvaluesinthevertexdata.Colorregistersstoredatainfourfixed-pointvalues.Forpixelshaderversion1.4shaders,colorregistersareavailableonlyduringthesecondphase.

IftheshademodeissettoD3DSHADE_FLAT,theapplicationiterationofbothvertexcolors(diffuseandspecular)isdisabled.Regardlessoftheshademode,fogwillstillbeiteratedbythepipelineifpixelfogisenabled.Keepinmindthatfogisappliedlaterinthepipelinethanthepixelshader.

Itiscommontoloadthev0registerwiththevertexdiffusecolordata.Itisalsocommontoloadthev1registerwiththevertexspecularcolordata.

Inputcolordatavaluesareclamped(saturated)totherange0through1becausethisisthevalidinputrangeforcolorregistersinthepixelshader.

Pixelshadershavereadonlyaccesstocolorregisters.Thecontentsoftheseregistersareiteratedvalues,butiterationisperformedatmuchlowerprecisionthantexturecoordinates.

ReadPortLimit

Thereadportlimitspecifiesthenumberofdifferentregistersofeachregistertypethatcanbeusedasasourceregisterinasingleinstruction.


cn Constantregister 2 2 2 2 2rn Temporaryregister 2 2 2 2 3tn Textureregister 1 2 3 3 1vn Colorregister 1 2 2 2 2

Forexample,thecolorregistersforalmostallversionshaveareadportlimitof

two.Thismeansthatasingleinstructioncanuseamaximumoftwodifferentcolorregisters(v0andv1forinstance)assourceregisters.Thisexampleshowstwocolorregistersbeingusedinthesameinstruction.Asshowninthetable,twocolorregisterscanbeusedineveryversionexcept1.0.

madr0,v0,v1,v1//Thisisvalidforversions1.1,1.2,1.3,1.4.

Anyvaliddestinationregistercanbeusedinthesameinstructionbecausereadportcountrestrictionsdonotaffectdestinationregisters.

Destinationregistersareindependentofthereadportcountrestrictions.

Forco-issuedinstructions,themaximumnumberofdifferentregisters(ofthesametype)thatcanbeusedacrosstwoco-issuedinstructionsisthree.Thisistrueforallshaderversions.

Read-only,Read/Write

Theregistertypesareidentifiedaccordingtoread-only(RO)capabilityorread/write(RW)capabilityinthefollowingtable.Read-onlyregisterscanbeusedonlyassourceregistersinaninstruction;theycanneverbeusedasadestinationregister.


cn Constantregister RO RO RO RO ROrn Temporaryregister RW RW RW RW RWtn Textureregister Seefollowingnote RW RW RW ROvn Colorregister RO RO RO RO RO

RegistersthatareRWcapablecanbeusedtostoreintermediateresults.Thisincludesthetemporaryregistersandtextureregistersforsomeoftheshaderversions.

Note

Forpixelshaderversion1.0,textureregistersareRWfortextureaddressing

instructions,butROforarithmeticinstructions.Forpixelshaderversion1.4,textureregistersareROfortextureaddressinginstructions,andtextureregisterscanbeneitherreadfromnorwrittentobyarithmeticinstructions.Also,becausetextureregistershavebecometexturecoordinateregisters,havingROaccessisnotaregressionofpreviousfunctionality.

Range

Therangeisthemaximumandminimumregisterdatavalue.Therangesvarybasedonthetypeofregister.TherangesforsomeoftheregisterscanbequeriedfromthedevicecapsusingGetDeviceCaps.

Registername Type Range Versions

cnConstantregister -1to+1 All

versions

rnTemporaryregister

-MaxPixelShaderValueto+MaxPixelShaderValue

Allversions

tnTextureregister

-MaxPixelShaderValueto+MaxPixelShaderValue 1.0to1.3

-MaxTextureRepeatto+MaxTextureRepeat 1.4

vn Colorregister 0to+1 Allversions

Earlypixelshaderhardwarerepresentsdatainregistersusingafixed-pointnumber.Thislimitsprecisiontoamaximumofapproximatelyeightbitsforthefractionalpartofanumber.Keepthisinmindwhendesigningashader.

Forpixelshaderversion1.0to1.3,MaxTextureRepeatmustbeaminimumofone.For1.4,MaxTextureRepeatmustbeaminimumofeight.


Modifiers

Modifiersareusedtomodifyinstructions,sourceregisters,anddestinationregisters.

InstructionmodifiersSourceregistermodifiersSourceregisterselectorsDestinationregisterwritemasks

TextureRegisterModifiers

Pixelshaderversion1.4includestwonewinstructions,texldandtexcrd,whichcontaincustomregistermodifierfunctionality.Theseinstructionssupportdifferentregistermodifiers,registerselectors,andregisterwritemasks.Formoreinformation,seeTextureRegisterModifiers.


D3DXConvertMeshSubsetToStripsConvertthespecifiedmeshsubsetintoaseriesofstrips.

HRESULTD3DXConvertMeshSubsetToStrips(

LPD3DXBASEMESHMeshIn,

DWORDAttribId,

DWORDIBOptions,

LPDIRECT3DINDEXBUFFER8*ppIndexBuffer,

DWORD*pNumIndices,

LPD3DXBUFFER*ppStripLengths,

DWORD*pNumStrips,

);

Parameters

MeshIn[in]PointertoaID3DXBaseMeshinterface,representingthemeshtoconverttostrips.

AttribId[in]AttirbuteIDofthemeshsubsettoconverttostrips.

IBOptions[in]AcombinationofoneormoreflagsfromtheD3DXMESHenumeration,specifyingoptionsforthecreateindexbuffer.

ppIndexBuffer[out]PointertoanID3DXBufferobject,representingtheindexbuffercontainingthestrips.

pNumIndices[out]NumberofindicesinthebufferreturnedintheppIndexBufferparameter.

ppStripLengths[out]BuffercontaininganarrayofoneDWORDperstrip,intheindexbufferthatspecifiesthelengthofthatstrip.

pNumStrips[out]Numberofindividualstripsintheindexbufferandcorrespondingstriplengtharray.

ReturnValues

Ifthefunctionsucceeds,thereturnvalueisD3D_OK.

Ifthefunctionfails,thereturnvaluecanbeoneofthefollowingvalues.

D3DERR_INVALIDCALLE_OUTOFMEMORY

Requirements

Header:DeclaredinD3dx8mesh.h.ImportLibrary:UseD3dx8.lib.


D3DXConvertMeshSubsetToSingleStripConvertsthespecifiedmeshsubsetintoasingletrianglestrip.

HRESULTD3DXConvertMeshSubsetToSingleStrip(

LPD3DXBASEMESHMeshIn,

DWORDAttribId,

DWORDIBOptions,

LPDIRECT3DINDEXBUFFER8*ppIndexBuffer,

DWORD*pNumIndices

);

Parameters

MeshIn[in]PointertoaID3DXBaseMeshinterface,representingthemeshtoconverttoastrip.

AttribId[in]AttirbuteIDofthemeshsubsettoconverttostrips.

IBOptions[in]AcombinationofoneormoreflagsfromtheD3DXMESHenumeration,specifyingoptionsforthecreateindexbuffer.

ppIndexBuffer[out]PointertoanID3DXBufferobject,representingtheindexbuffercontainingthestrip.

pNumIndices[out]NumberofindicesinthebufferreturnedintheppIndexBufferparameter.

ReturnValues




Requirements



OptimizedMeshSample

Description

TheOptimizedMeshsampleillustrateshowtoloadandoptimizeafile-basedmeshusingtheMicrosoft®Direct3DXmeshutilityfunctions.

FormoreinformationonDirect3DX,refertotheMicrosoft®DirectX®SDKdocumentation.

Path

Source:(SDKroot)\Samples\Multimedia\Direct3D\OptimizedMesh

Executable:(SDKroot)\Samples\Multimedia\Direct3D\Bin

User'sGuide

Thefollowingtableliststhekeysthatareimplemented.Youcanusemenucommandsforthesamecontrols.

Key ActionENTER Startsandstopsthescene.SPACEBAR Advancesthescenebyasmallincrement.

F2 Promptstheusertoselectanewrenderingdeviceordisplaymode.

ALT+ENTER Togglesbetweenfull-screenandwindowedmodes.ESC Exitstheapplication.CTRL-O Opensmeshfile.CTRL-M Togglesoptimizedmesh.

ProgrammingNotes

ManyMicrosoftDirect3D®samplesintheDirectXSDKusefile-basedmeshes.However,theOptimizedMeshsampleisagoodexampleofthebasiccode

necessaryforloadingamesh.TheD3DXmeshloadingfunctionalitycollapsestheframehierarchyofan.xfileintoonemesh.

Forothersamples,thebarebonesD3DXmeshfunctionalityiswrappedinacommonclassCD3DMesh.Ifyouwanttokeeptheframehierarchy,youcanusethecommonclassCD3DFile.

ThissampleusescommonDirectXcodethatconsistsprogrammingelementssuchashelperfunctions.ThiscodeissharedwithothersamplesintheDirectXSDK.Youcanfindthecommonheadersandsourcecodein(SDKroot)\Samples\Multimedia\Common.


D3DXSplitMeshSplitsameshintomeshessmallerthanthespecifiedsize.

HRESULTD3DXSplitMesh(

CONSTLPD3DXMESHpMeshIn,

CONSTDWORD*pAdjacencyIn,

CONSTDWORDMaxSize,

CONSTDWORDOptions,

DWORD*pMeshesOut,

LPD3DXBUFFER*ppMeshArrayOut,

LPD3DXBUFFER*ppAdjacencyArrayOut,

LPD3DXBUFFER*ppFaceRemapArrayOut,

LPD3DXBUFFER*ppVertRemapArrayOut,

);

Parameters

pMeshIn[in]PointertoanID3DXMeshinterface,representingthesourcemesh.

pAdjacencyIn[in]PointertoanarrayofthreeDWORDsperfacethatspecifythethreeneighborsforeachfaceinthemeshtobesimplified.

MaxSize[in]Maximumnumberofverticesorfacesinthenewmesh.

Options[in]Optionflagsforthenewmeshes.

pMeshesOut[out,retval]Numberofmeshesreturned.

ppMeshArrayOut[out,retval]BuffercontaininganarrayofID3DXMeshinterfacesforthenewmeshes.

ppAdjacencyArrayOut[out,retval]Buffercontaininganarrayofadjacencyarraysforthenewmeshes.Thisparameterisoptional.SetittoNULLifitisunused.

ppFaceRemapArrayOut[out,retval]Buffercontaininganarrayoffaceremaparraysforthenewmeshes.Thisparameterisoptional.SetittoNULLifitisunused.

ppVertRemapArrayOut[out,retval]Buffercontaininganarrayofvertexremaparraysforthenewmeshes.Thisparameterisoptional.SetittoNULLifitisunused.

ReturnValues



D3DERR_INVALIDCALLD3DXERR_INVALIDDATAE_OUTOFMEMORY

Requirements



D3DXComputeTangentComputesapervertexcoordinatesystembasedontexturecoordinategradients.

HRESULTD3DXComputeTangent(

LPD3DXMESHInMesh,

DWORDTexStage,

LPD3DXMESHOutMesh,

DWORDTexStageUVec,

DWORDTexStageVVec,

DWORDWrap,

DWORD*pAdjacency

);

Parameters

InMesh[in]PointertoanID3DXMeshinterface,representingtheinputmesh.

TexStage[in]Texturecoordinatesetininputmeshtouseforgradients.

OutMesh[out]PointertoanID3DXMeshinterface,representingthereturnedmesh.

TexStageUVec[in]TexturecoordinatesetinoutputmeshtoreceiveUtangentvector.SetthisvaluetoD3DX_COMP_TANGENT_NONEifyoudonotwanttogenerateaUtangentvector.

TexStageVVec[in]TexturecoordinatesetinoutputmeshtoreceiveVtangentvector.SetthisvaluetoD3DX_COMP_TANGENT_NONEifyoudonotwanttogenerateaVtangentvector.

Wrap[in]Setthisvalueto0fornowrappingor1towrapintheUandVdirections.

pAdjacency[out]PointertoanarrayofthreeDWORDsperfacethatspecifythethreeneighborsforeachfaceinthecreatedmesh.

ReturnValues




Remarks

SettingbothTexStageVVecandTexStageWVectoD3DX_COMP_TANGENT_NONEwillcausethismethodtofail,sinceithasnothingtodo.

Requirements



D3DXComputeNormalMapConvertsaheightmapintoanormalmap.The(x,y,z)componentsofeachnormalaremappedtothe(r,g,b)channelsoftheoutputtexture.

HRESULTD3DXComputeNormalMap(

LPDIRECT3DTEXTURE8pTexture,

LPDIRECT3DTEXTURE8pSrcTexture,

CONSTPALETTEENTRY*pSrcPalette,

DWORDFlags,

DWORDChannel,

FLOATAmplitude

);

Parameters

pTexture[out,retval]PointertoanIDirect3DTexture8interface,representingthedestinationtexture.

pSrcTexture[in,retval]PointertoanIDirect3DTexture8interface,representingthesourceheight-maptexture.

pSrcPalette[in]PointertoaPALETTEENTRYtypethatcontainsthesourcepaletteof256colorsorNULL.

Flags[in]OneormoreD3DX_NORMALMAPflagsthatcontrolgenerationofnormalmaps.

Channel[in,out]OneD3DX_CHANNELflagspecifyingthesourceofheightinformation.

Amplitude[in]Constantvaluebywhichtheheightinformationismultiplied.

ReturnValues


Ifthefunctionfails,thereturnvaluecanbethefollowingvalue.

D3DERR_INVALIDCALL

Remarks

Thismethodcomputesthenormalbyusingthecentraldifferencewithakernelsizeof3×3.RGBchannelsinthedestinationcontainbiased(x,y,z)componentsofthenormal.

Requirements

Header:DeclaredinD3dx8tex.h.ImportLibrary:UseD3dx8.lib.


ID3DXEffectThemethodsfromtheID3DXTechniqueinterfacehavebeenmovedintotheID3DXEffectinterfaceforMicrosoft®DirectX®8.1.

TheID3DXEffectinterfaceisusedtosetandqueryeffects,andtochoosetechniques.Aneffectobjectcancontainmultipletechniquestorenderthesameeffect.

TheID3DXEffectinterfaceisobtainedbycallingD3DXCreateEffectorD3DXCreateEffectFromFile.ThemethodsoftheID3DXEffectinterfacecanbeorganizedintothefollowinggroups.

Copying CloneEffectGetCompiledEffect

EffectParameters

SetDwordSetFloatSetMatrixSetPixelShaderSetStringSetTextureSetVectorSetVertexShader

EffectParameterInformation

GetDwordGetFloatGetMatrixGetParameterDescGetPixelShaderGetStringGetTextureGetVectorGetVertexShaderGetDesc

Information GetDeviceGetPassDesc

Techniques

FindNextValidTechniqueGetTechniqueGetTechniqueDescSetTechniqueValidate

TechniqueApplicationBeginEndPass

Miscellaneous OnLostDeviceOnResetDevice

TheID3DXEffectinterface,likeallCOMinterfaces,inheritsfromtheIUnknownInterface.

TheLPD3DXEFFECTtypeisdefinedasapointertotheID3DXEffectinterface.

typedefstructID3DXEffect*LPD3DXEFFECT;

Requirements

Header:DeclaredinD3dx8effect.h.ImportLibrary:UseD3dx8.lib.

SeeAlso

D3DXCreateEffect,D3DXCreateEffectFromFile,D3DXCreateEffectFromResource


D3DXSaveSurfaceToFileSavesasurfacetoafile.

HRESULTD3DXSaveSurfaceToFile(

LPCTSTRpDestFile,

D3DXIMAGE_FILEFORMATDestFormat,

LPDIRECT3DSURFACE8pSrcSurface,

CONSTPALETTEENTRY*pSrcPalette,

CONSTRECT*pSrcRect

);

Parameters

pDestFile[in]Filenametosavethesurfaceto.

DestFormat[in]D3DXIMAGE_FILEFORMATspecifyingfileformattousewhensaving.

pSrcSurface[in]PointertoIDirect3DSurface8interface,containingtheimagetobesaved.

pSrcPalette[in]PointertoaPALETTEENTRYstructurecontainingapaletteof256colors.ThisparametercanbeNULL.

pSrcRect[in]PointertoaRECTstructure.Specifiesthesourcerectangle.SetthisparametertoNULLtospecifytheentireimage.

ReturnValues


Ifthefunctionfails,thereturnvaluecanbethefollowing.

D3DERR_INVALIDCALL

Remarks

Thisfunctionsupportsthefollowingfileformats:.bmpand.dds.

Thisfunctionhandlesconversiontoandfromcompressedtextureformats.

ThisfunctionsupportsbothUnicodeandANSIstrings.

Requirements


SeeAlso

D3DXSaveTextureToFile,D3DXSaveVolumeToFile


D3DXFillTextureUsesauser-providedfunctiontofilleachtexelofeachmiplevelofagiventexture.

HRESULTD3DXFillTexture(

LPDIRECT3DTEXTURE8pTexture,

LPD3DXFILL2DpFunction,

LPVOIDpData

);

Parameters

pTexture[out,retval]PointertoanIDirect3DTexture8interface,representingthefilledtexture.

pFunction[in]PointertoaLPD3DXFILL2Duser-providedevaluatorfunction,whichwillbeusedtocomputethevalueofeachtexel.

pData[in]Pointertoanarbitraryblockofuser-defineddata.ThispointerwillbepassedtothefunctionprovidedinpFunction.

ReturnValues


Ifthefunctionfails,thereturnvaluecanbethefollowingvalues.

D3DERR_INVALIDCALL

Requirements



D3DXFillCubeTextureUsesauser-providedfunctiontofilleachtexelofeachmiplevelofagivencubetexture.

HRESULTD3DXFillCubeTexture(

LPDIRECT3DCUBETEXTURE8pTexture,


LPVOIDpData

);

Parameters

pTexture[out,retval]PointertoanIDirect3DCubeTexture8interface,representingthefilledtexture.

pFunction[in]PointertoaLPD3DXFILL3Duser-providedevaluatorfunction,whichwillbeusedtocomputethevalueofeachtexel.


ReturnValues



D3DERR_INVALIDCALL

Requirements



D3DXFillVolumeTextureUsesauser-providedfunctiontofilleachtexelofeachmiplevelofagiventexture.

HRESULTD3DXFillVolumeTexture(

LPDIRECT3DVOLUMETEXTURE8pVolumeTexture,


LPVOIDpData

);

Parameters

pVolumeTexture[out,retval]PointertoanIDirect3DVolumeTexture8interface,representingthefilledtexture.

pFunction[in]PointertoanLPD3DXFILL3Duser-providedevaluatorfunction,whichwillbeusedtocomputethevalueofeachtexel.


ReturnValues


Ifthefunctionfails,thereturnvaluecanbethefollowingvalue.

D3DERR_INVALIDCALL

Remarks

Ifthevolumeisnondynamic(becauseofausageparametersetto0atthecreation)andlocatedinvideomemory(thememorypoolsettoD3DPOOL_DEFAULT),D3DXFillVolumeTexturewillfailbecauseDirect3DX

cannotlocknondynamicvolumeslocatedinvideomemory.

Requirements



D3DXQuaternionSquadSetupSetupcontrolpointsforsphericalquadrangleinterpolation.

voidD3DXQuaternionSquadSetup(

D3DXQUATERNION*pAOut,

D3DXQUATERNION*pBOut,

D3DXQUATERNION*pCOut,

CONSTD3DXQUATERNION*pQ0,



CONSTD3DXQUATERNION*pQ3

);

Parameters

pAOut[out]PointertoAOut.

pBOut[out]PointertoBOut.

pCOut[out]PointertoCOut.

pQ0[in]Pointertotheinputcontrolpoint,Q0.




Remarks

Thisfunctionoperatesasshownbelow.Ittakesfourcontrolpoints(Q0,Q1,Q2,Q3),whicharesuppliedtotheinputspQ0,pQ1,pQ2,andpQ3.Thefunctionthenaltersthesevaluestofindacurvethatflowsalongtheshortestpath.Thevaluesofq0,q2,andq3arecalculatedasshownbelow.

q0=|Q0+Q1|<|Q0-Q1|?-Q0:Q0

q2=|Q1+Q2|<|Q1-Q2|?-Q2:Q2

q3=|Q2+Q3|<|Q2-Q3|?-Q3:Q3

HavingcalculatedthenewQvalues,thevaluesforAOut,BOut,andCOutarecalculatedasshownbelow.

AOut=q1*e[-0.25*(Ln[Exp(q1)*q2]+Ln[Exp(q1)*q0])]

BOut=q2*e[-0.25*(Ln[Exp(q2)*q3]+Ln[Exp(q2)*q1])]

COut=q2

Note:

LnistheAPImethodD3DXQuaternionLn

ExpistheAPImethodD3DXQuaternionExp

Example

Thefollowingexampleshowshowtouseasetofquaternionkeys(Q0,Q1,Q2,Q3)tocomputetheinnerquadranglepoints(A,B,C).Thisensuresthatthetangentsarecontinuousacrossadjacentsegments.

AB

Q0Q1Q2Q3

ThisishowyoucaninterpolatebetweenQ1andQ2.

//rotationaboutthezaxis

D3DXQUATERNIONQ0=D3DXQUATERNION(0,0,0.707f,-.707f);

D3DXQUATERNIONQ1=D3DXQUATERNION(0,0,0.000f,1.000f);



D3DXQUATERNIONA,B,C,Qt;

FLOATtime=0.5f;

D3DXQuaternionSquadSetup(&A;,&B;,&C;,&Q0;,&Q1;,&Q2;,&Q3;);

D3DXQuaternionSquad(&Qt;,&Q1;,&A;,&B;,&C;,time);

Note:

Cis+/-Q2dependingontheresultofthefunction

Qtistheresultofthefunction

Theresultisarotationof45degreesaroundthezaxisfortime=0.5.

Requirements

Header:DeclaredinD3dx8math.h.ImportLibrary:UseD3dx8.lib.

SeeAlso

D3DXQuaternionSquad


D3DXQuaternionSquadInterpolatesbetweenquaternions,usingsphericalquadrangleinterpolation.

D3DXQUATERNION*D3DXQuaternionSquad(

D3DXQUATERNION*pOut,


CONSTD3DXQUATERNION*pA,

CONSTD3DXQUATERNION*pB,

CONSTD3DXQUATERNION*pC,

FLOATt

);

Parameters

pOut[in,out]PointertotheD3DXQUATERNIONstructurethatistheresultoftheoperation.

pQ1[in]PointertoasourceD3DXQUATERNIONstructure.

pA[in]PointertoasourceD3DXQUATERNIONstructure.

pB[in]PointertoasourceD3DXQUATERNIONstructure.

pC[in]PointertoasourceD3DXQUATERNIONstructure.

t[in]Parameterthatindicateshowfartointerpolatebetweenthequaternions.

ReturnValues

PointertoaD3DXQUATERNIONstructurethatistheresultofthesphericalquadrangleinterpolation.

Remarks

Thisfunctionusesthefollowingsequenceofsphericallinearinterpolation

operations:Slerp(Slerp(pQ1,pC,t),Slerp(pA,pB,t),2t(1-t))

ThereturnvalueforthisfunctionisthesamevaluereturnedinthepOutparameter.Inthisway,theD3DXQuaternionSquadfunctioncanbeusedasaparameterforanotherfunction.

Requirements


SeeAlso

D3DXQuaternionExp,D3DXQuaternionLn,D3DXQuaternionSquadSetup


D3DXMatrixMultiplyTransposeDeterminestheproductoftwomatrices,followedbyatranspose.

D3DXMATRIX*D3DXMatrixMultiplyTranspose(

D3DXMATRIX*pOut,

CONSTD3DXMATRIX*pM1,

CONSTD3DXMATRIX*pM2

);

Parameters

pOut[in,out]PointertotheD3DXMATRIXstructurethatistheresultoftheoperation.

pM1[in]PointertoasourceD3DXMATRIXstructure.

pM2[in]PointertoasourceD3DXMATRIXstructure.

ReturnValues

PointertoaD3DXMATRIXstructurethatistheproductoftwomatrices.

Remarks

TheresultrepresentsthetransformationM2,followedbythetransformationM1,tranposedbyT(Out=T(M1*M2)).

ThereturnvalueforthisfunctionisthesamevaluereturnedinthepOutparameter.Inthisway,theD3DXMatrixMultiplyTransposefunctioncanbeusedasaparameterforanotherfunction.

Thisfunctionisusefultosetmatricesasconstantsforvertexandpixelshaders.

Requirements


SeeAlso

D3DXMatrixMultiply,D3DXQuaternionMultiply


D3DXFresnelTermCalculatetheFresnelterm.

FLOATD3DXFresnelTerm(

FLOATCosTheta,

FLOATRefractionIndex,

);

Parameters

CosTheta[in]Thevaluemustbebetween0and1.

RefractionIndex[in]therefractionindexofamaterial.Thevaluemustbegreaterthan1.

ReturnValues

ThisfunctionreturnstheFresneltermforunpolarizedlight.CosThetaisthecosineoftheincidentangle.

Requirements



SamplesDirectXGraphicsC/C++Samples

ThefollowingsamplesarebuiltonabaseclassthatincludesMicrosoft®Windows®andMicrosoft®Direct3D®functionality.ThisbaseclassprovidesmanyofthebasicfeaturesinaWindowsapplication,suchascreatingwindowsandhandlingmessages.ThesamplesincludeaderivedclassthatoverridesthemethodsnecessarytoaddDirect3Dfeatures,suchasbumpmaps,vertexblending,andvolumetextures.Formoreinformationaboutthesamplearchitecture,seeSampleFramework.

BillboardSampleBumpEarthSampleBumpLensSampleBumpUnderwaterSampleBumpWavesSampleBumpSelf-ShadowSampleClipMirrorSampleCubeMapSampleCullSampleDolphinVSSampleDotProduct3SampleDXTexToolEmbossSampleEnhancedMeshSampleFishEyeSampleLightingSampleMFCFogSampleMFCPixelShaderSampleMFCTexSampleMoireSampleOptimizedMeshSamplePickSamplePointSpritesSampleProgressiveMeshSample

RTPatchSampleShadowVolumeSampleSkinnedMeshSampleSphereMapSampleStencilDepthSampleStencilMirrorSampleText3DSampleVertexBlendSampleVertexShaderSampleVolumeFogSampleVolumeTextureSampleWaterSample

TheApplicationWizardisavailabletohelpgenerateMicrosoft®DirectX®applications.

AlthoughDirectXsamplesincludeMicrosoft®VisualC++®projectworkspacefiles,youmightneedtoverifyothersettingsinyourdevelopmentenvironmenttoensurethatthesamplescompileproperly.Formoreinformation,seeCompilingDirectXSamplesandOtherDirectXApplications.

SeeAlso

DirectXGraphicsC/C++Tutorials


DirectXGraphicsThissectionprovidesinformationaboutusingtheMicrosoft®DirectX®Graphicsapplicationprogramminginterfaces(APIs).

AswithothercomponentsofDirectX,DirectXGraphicscanbeusedwithC,C++,andMicrosoft®VisualBasic®.

RoadmapDiscoverthefeaturesofMicrosoft®DirectX8.1®inthreeways.

What'sNewinDirectXGraphics

ThissectionhighlightsnewfeaturesandfunctionalityofthiscomponentinDirectX8.1.IfyouhaveusedMicrosoft®Direct3D®orMicrosoft®DirectDraw®before,readthissectionfirstbecausemuchhaschangedsinceDirectX7.0.

ProgrammersGuide

Thissectioncontainsarchitecturedescriptions,functionalblockdiagrams,descriptionsofthebuildingblocksinthepipeline,codesnippets,andsampleapplications.

Reference

ThissectioncontainsthereferencepagesfortheDirect3Dapplicationprogramminginterface(API).ThisincludesthesyntaxfortheAPImethods,functions,instructions,anddatastructures.ItincludesanexplanationofhowtheAPImethodworks,andoftenincludescodesnippets.


ReferenceThissectioncontainsthereferencepagesfortheMicrosoft®Direct3D®applicationprogramminginterface(API).Informationiscontainedinthefollowingsections.

Direct3DC/C++Reference

Direct3DXC/C++Reference

VertexShaderReference

PixelShaderReference

EffectFileReferenceXFileC/C++Reference


ProgrammersGuideThisguidecontainsadescriptionofthegraphicspipelineimplementedbyMicrosoft®Direct3D®.Itisaguidefordeveloperswhoareimplementingthree-dimensional(3-D)graphicsfunctionalityintotheirapplications.Theguidecontainsarchitecturedescriptions,functionalblockdiagrams,anddescriptionsofthebuildingblocksinthepipeline,aswellascodesnippetsandsampleapplications.Theinformationisdividedintothefollowingsections:

GettingStartedwithDirect3D

Thissectioncontainsbothanoverviewofthepipelineandtutorialsthatcanhelpyougetasimplegraphicsapplicationrunninginafewminutes.

UsingDirect3D

Thissectionexplainshowtousethefixedfunctionpipeline.Includedherearethebasicfunctionalstepsinthegraphicspipeline:convertinggeometry,addinglighting,andrenderingoutput.

ProgrammablePipeline

Thissectioncoversthenewprogrammableextensionstothepipeline.Includedherearedetailsaboutusingvertexshadersformanipulatingobjectgeometry,pixelshadersforcontrollingpixelshading,andeffectsandeffectfilesforbuildingapplicationsthatcanrunonavarietyofhardwareplatforms.

AdvancedTopics

Thissectioncontainsexamplesofdifferenttypesofspecialeffectsyoucanimplement.Topicssuchasenvironmentandbumpmapping,antialiasing,vertexblending,andtweeningshowhowtoapplyleading-edgespecialeffectstoyourapplication.

Samples

Thissectioncontainssampleapplications.

Direct3DAppendix

Thissectioncontainsdetailsonadditionaltopics,suchasXFilesandgraphicsstate.

FormoreinformationaboutspecificAPImethods,seetheReferencepages.

MicrosoftDirectX8.1(shaderversions1.0,1.1)

VertexShaders

PrevioustoMicrosoft®DirectX®8.n,Microsoft®Direct3D®operatedafixedfunctionpipelineforconvertingthree-dimensional(3-D)geometrytorenderedscreenpixels.TheusersetsattributesofthepipelinethatcontrolhowDirect3Dtransforms,lights,andrenderspixels.Thefixedfunctionvertexformatisdeclaredatcompiletimeanddeterminestheinputvertexformat.Oncedefined,theuserhaslittlecontroloverpipelinechangesduringruntime.

Programmableshadersaddanewdimensiontothegraphicspipelinebyallowingthetransform,lighting,andrenderingfunctionalitytobemodifiedatruntime.Ashaderisdeclaredatruntimebut,oncedone,theuserisfreetochangewhichshaderisactiveaswellastocontroltheshaderdatadynamicallyusingstreamingdata.Thisgivestheuseranewlevelofdynamicflexibilityoverthewaythatpixelsarerendered.

Avertexshaderfilecontainsvertexshaderinstructions.Vertexshaderscancontrolvertexcolorandhowtexturesareappliedtovertices.Lightingcanbeaddedthroughtheuseofvertexshaderinstructions.TheshaderinstructionfilecontainsASCIItextsoitisreadableandinsomewayslookssimilartoassemblylanguage.AvertexshaderisinvokedafteranyDrawPrimitiveorDrawIndexedPrimitivecall.ShaderscanbedynamicallyswitchedusingSetVertexShadertospecifyanewshaderfile,orbychangingtheinstructionsintheASCIItextshaderfileusingthestreamingdatainputs.TheVertexShaderAssemblerReferencehasacompletelistingofshaderinstructions.

Foradditionalinformation,seethefollowingsections.

CreateaVertexShader

Thissectioncontainsacodesamplethatusesavertexshadertoapplyaconstantcolortoobjectvertices.Thisexamplecontainsadetailedexplanationofthemethodsused.

Shader2-Applyvertexcolors

Additionalexamplesshowsmorecodesamplesthataddtexturesandblendvertexcolorsandtextures.

Shader3-Applyatexturemap


Shader4-Applyatexturemapwithlighting


Debugging


PixelShaders

BeforeMicrosoft®DirectX®8.x,Microsoft®Direct3D®usedafixedfunctionpipelineforconvertingthree-dimensional(3-D)geometrytorenderedscreenpixels.TheusersetsattributesofthepipelinethatcontrolhowDirect3Dtransforms,lights,andrenderspixels.Thefixedfunctionvertexformatisdeclaredatcompiletimeanddeterminestheinputvertexformat.Oncedefined,theuserhaslittlecontroloverpipelinechangesduringruntime.

Shadersaddanewdimensiontothegraphicspipelinebyallowingthevertextransform,lighting,andindividualpixelcoloringfunctionalitytobeprogrammed.Pixelshadersareshortprogramsthatexecuteforeachpixelwhentrianglesarerasterized.Thisgivestheuseranewlevelofdynamicflexibilityoverthewaythatpixelsarerendered.

ApixelshadercontainspixelshaderinstructionsmadeupofASCIItext.Arithmeticinstructionscanbeusedtoapplydiffuseand/orspecularcolor.Textureaddressinginstructionsprovideavarietyofoperationsforreadingandapplyingtexturedata.Functionalityisavailableformaskingandswappingcolorcomponents.TheshaderASCIItextlookssimilartoassemblylanguageandisassembledusingDirect3DXassemblerfunctionsfromeitheratextstringorafile.TheassembleroutputisaseriesofopcodesthatanapplicationmayprovidetoDirect3DbymeansofIDirect3DDevice8::CreatePixelShader.ThePixelShaderReferencehasacompletelistingofshaderinstructions.

Tounderstandmoreaboutpixelshaders,seethefollowingsections.

CreateaPixelShadercontainsacodesamplethatusesapixelshadertoapplyGouraudinterpolateddiffusecolorstoanobject.Thisexamplecontainsadetailedexplanationofthemethodsused.TextureConsiderationsdetailsthetexturestagestatesthatareignoredduringpixelshaders.ConfirmingPixelShaderSupportgivesamoredetailedexplanationofthestructuresforenumeratingpixelshadersupport.PixelShaderExamplesshowsmorecodesamplesthataddtexturesandblendvertexcolorsandtextures.ConvertingTextureOperationsgivesexamplesofconvertingtextureoperationstopixelshaderinstructions.

Debuggingprovidesdebugginginformation.


EffectsMicrosoft®Direct3D®providesarichfeaturesetforcreatingcomplexandvisuallyrealisticthree-dimensional(3-D)scenes.Effectfileshelpyouwriteanapplicationthatusesalltherenderingcapabilitiesforthehardwareonwhichitruns.Effectsareacollectionofdifferentrenderingtechniquesthatcanfitontoavarietyofhardwaredevices.

Forexample,tocreatearealisticrippledpondofwaterthatreflectslightasshowninthefollowingimage,youbeginwiththefirsttechniquethatrendersthewater,addsspecularhighlights,addscaustictextures,andapplieslighttothewaterinasinglepass.Ifyourhardwarecannotrenderthistechniqueinasinglepass,asecondtechniquemightrenderthewater,addspecularhighlightsorcaustictextures,butnotapplylighttothewater.

Beforeyouuseatechnique,youcanvalidateitusingDirect3Dtoseeifitissupportedbythecurrenthardwareconfiguration.

Effectsaredefinedinaneffectfile.Aneffectfileconsistsofoneormoretechniques.Eachtechniqueconsistsofoneormorepasses.Thesefilesaretextbasedandcanbechangedwithoutrecompilingthesourceapplication.Thisenablesyoutoprogramgamesthatmakeoptimumuseofvideocardfunctionality.Effectfilesalsomakeiteasytoupgradeanexistinggametorunonnewervideocardsasadditionalfeaturesaredeveloped.

Thefollowingtopicsdiscusseffectsandhowyoucanusetheminyourapplication.

CreateanEffectMultipleTechniques

Exercises*

*FromtheDirectXMeltdown2001conference,ProgrammableShaderworkshop.

Exercise1-FixedFunctionDiffuseLightingandVertexShaderDiffuseLighting.Exercise2-VertexShaderDiffuseLighting.Lightthemodel,takingbothdiffusematerialandadiffuselightsourceintoconsideration.Exercise3-Transforms.Transformthevertexnormalintoworldspacetotakelightsourcemovementintoconsideration.Exercise4-Texturing.SetuptexturetopassontoFFPSModulatebetweenthetextureanddiffusecolorarguments.Exercise5-VertexShaderSpecularLighting.Exercise6-StandardTextureEffect.Exercise7-Multi-TexturingwithShaders.Exercise8-TexturingwithLights.Exercise9-Dot3BumpMapping,Dot3SpecularBumpMapping,andTableLookupSpecularBumpMapping.Exercise10-AnisotropicBumpMapping.Exercise11-AreaLighting,AreaandDiffuseLighting.

Formoreinformationabouteffectfiles,seeEffectFileFormat.


MathematicsofLighting

TheMicrosoft®Direct3D®LightModelcoversambient,diffuse,specular,andemissivelighting.Thisisenoughflexibilitytosolveawiderangeoflightingsituations.Yourefertothetotalamountoflightinasceneastheglobalilluminationandcomputeitusingthefollowingequation.

GlobalIllumination=AmbientLight+DiffuseLight+SpecularLight+EmissiveLight

Ambientlightingisconstantlighting.Itisconstantinalldirectionsanditcolorsallpixelsofanobjectthesame.Itisfasttocalculatebutleavesobjectslookingflatandunrealistic.ToseehowambientlightingiscalculatedbyDirect3D,seeAmbientLighting.

Diffuselightingdependsonboththelightdirectionandtheobjectsurfacenormal.Itvariesacrossthesurfaceofanobjectasaresultofthechanginglightdirectionandthechangingsurfacenumeralvector.Ittakeslongertocalculatediffuselightingbecauseitchangesforeachobjectvertex,howeverthebenefitofusingitisthatitshadesobjectsandgivesthemthree-dimensional(3-D)depth.ToseehowdiffuselightingiscalculatedinDirect3D,seeDiffuseLighting.

Specularlightingidentifiesthebrightspecularhighlightsthatoccurwhenlighthitsanobjectsurfaceandreflectsbacktowardthecamera.Itismoreintensethandiffuselightandfallsoffmorerapidlyacrosstheobjectsurface.Ittakeslongertocalculatespecularlightingthandiffuselighting,howeverthebenefitofusingitisthatitaddssignificantdetailtoasurface.ToseehowspecularlightingiscalculatedinDirect3D,seeSpecularLighting.

Emissivelightingislightthatisemittedbyanobject,forexample,aglow.ToseehowemissivelightingiscalculatedinDirect3D,seeEmissiveLighting.

Realisticlightingcanbeaccomplishedbyapplyingeachofthesetypesoflightingtoa3-Dscene.Toachieveamorerealisticlightingeffect,youaddmorelights;however,thescenetakeslongertorender.Toachievealltheeffectsadesignerwants,somegamesusemoreCPUpowerthaniscommonlyavailable.Inthiscase,itistypicaltoreducethenumberoflightingcalculationstoaminimumbyusinglightingmapsandenvironmentmapstoaddlightingtoascenewhileusingtexturemaps.

Alllightingcomputationsaremadeinmodelspacebytransformingthelightsource'spositionanddirection,alongwiththecameraposition,tomodelspaceusingtheinverseoftheworldmatrix.Asaresult,iftheworldorviewmatricesintroducenon-uniformscaling,theresultantlightingmightbeinaccurate.Toseehowlightingtransformationsarecalculated,seeCameraSpaceTransformations.

Diffuseandspecularlightvaluescanbeaffectedbyagivenlight'sattenuationandspotlightcharacteristics.Termsforbothoftheseareincludedinthediffuseandspecularequations.Formoreinformation,seeAttenuationandSpotlightTerms.


ActionMapping

Traditionally,applicationshavedonetheirownmappingofeventstoparticularbuttonsandaxes.Acar-racinggame,forexample,mightassumethatthex-axisontheuser'sjoystickormousewasthemostsuitablecontrolforsteeringthecar.Theonlywaytoaccommodateneworunusualdeviceswastoprovideconfigurationoptionssothattheusercouldspecifysomeotheraxis,suchasarotationalaxis,touseforsteering.Moreover,theapplicationhadnowayofknowingwhichinstalleddevicewasthebestfitforthegame,sotheusertypicallyhadtochooseadevicefromamenuormakesureonlythepreferreddevicewasattached.

Usingactionmapping,younolongerneedtomakeassumptionsaboutthebestuseofdevicesanddeviceobjects.Instead,yourapplicationbindsactionstovirtualcontrolswhereverpossible.Ratherthangettingdatafromthex-axisandsteeringthecartotheleftortherightaccordingly,theapplicationmightgetdatafromavirtualcontrolcalledDIAXIS_DRIVINGR_STEER.Microsoft®DirectInput®assignsthevirtualcontroltoaphysicalcontrol—thatis,adeviceobject.Itdoessobytakingintoaccounttheapplicationgenre,userpreferences,informationfromthedevicemanufacturer,andtheuser'sconfigurationofthedevice.

Actionmappingalsosimplifiestheinputloopbyreturningdataforalldevicesinaformindependentoftheparticulardevice.Asingleactioncanbemappedtomorethanonedevice,andtheinputloopcanrespondtotheactionthesamewayregardlessofwhichdeviceisbeingread.

Thefollowingtopicscontainmoreinformationonthestepsrequiredtoimplementactionmapping.

PreparingtheActionMapFindingMatchingDevicesConfiguringtheActionMapUserConfigurationoftheDeviceRetrievingActionDataMaintainingFilesDuringDevelopment


IDirectInput8ApplicationsusethemethodsoftheIDirectInput8interfacetoenumerate,create,andretrievethestatusofMicrosoft®DirectInput®devices,initializetheDirectInputobject,andinvokeaninstanceoftheMicrosoftWindows®ControlPanel.

IDirectInput8supersedestheIDirectInput,IDirectInput2,andIDirectInput7interfacesusedinearlierversionsofMicrosoftDirectX®.

IDirectInput8isaninterfacetoanewclassofobject,representedbytheclassidentifierCLSID_DirectInput8,andcannotbeobtainedbycallingQueryInterfaceonaninterfacetoobjectsofclassCLSID_DirectInput.Instead,obtaintheIDirectInput8interfacebyusingtheDirectInput8Createfunction.

ThemethodsoftheIDirectInput8interfacecanbeorganizedintothefollowinggroups.

DeviceManagement ConfigureDevices CreateDevice EnumDevices EnumDevicesBySemantics FindDevice GetDeviceStatusMiscellaneous Initialize RunControlPanel

TheIDirectInputinterface,likeallCOMinterfaces,inheritstheIUnknowninterfacemethods.TheIUnknowninterfacesupportsthefollowingthreemethods:

IUnknown AddRef QueryInterface Release

TheLPDIRECTINPUT8typeisdefinedasapointertotheIDirectInput8interface:

typedefstructIDirectInput8*LPDIRECTINPUT8;

Requirements

WindowsNT/2000/XP:RequiresWindows®2000.Windows98/Me:RequiresWindows98orlater.AvailableasaredistributableforWindows98.Header:DeclaredinDinput.h.


DirectInput8CreateCreatesaDirectInput®objectandreturnsanIDirectInput8orlaterinterface.

HRESULTWINAPIDirectInput8Create(

HINSTANCEhinst,

DWORDdwVersion,

REFIIDriidltf,

LPVOID*ppvOut,

LPUNKNOWNpunkOuter

);

Parameters

hinstInstancehandletotheapplicationorDLLthatiscreatingtheDirectInputobject.DirectInputusesthisvaluetodeterminewhethertheapplicationorDLLhasbeencertifiedandtoestablishanyspecialbehaviorsthatmightbenecessaryforbackwardcompatibility.

ItisanerrorforaDLLtopassthehandletotheparentapplication.Forexample,anActiveX®controlembeddedinaWebpagethatusesDirectInputmustpassitsowninstancehandle,andnotthehandletotheWebbrowser.ThisensuresthatDirectInputrecognizesthecontrolandcanenableanyspecialbehaviorsthatmightbenecessary.

dwVersionVersionnumberofDirectInputforwhichtheapplicationisdesigned.ThisvalueisnormallyDIRECTINPUT_VERSION.IftheapplicationdefinesDIRECTINPUT_VERSIONbeforeincludingDinput.h,thevaluemustbegreaterthan0x0700.Forearlierversions,useDirectInputCreateEx,whichisinDinput.lib.

riidltfUniqueidentifierofthedesiredinterface.ForDirectX8.0,thisvalueisIID_IDirectInput8AorIID_IDirectInput8W.PassingtheIID_IDirectInput8defineselectstheANSIorUnicodeversionoftheinterface,dependingonwhetherUNICODEisdefinedduringcompilation.

ppvOut

Addressofapointertoavariabletoreceivetheinterfacepointerifthecallsucceeds.

punkOuterPointertotheaddressofthecontrollingobject'sIUnknowninterfaceforCOMaggregation,orNULLiftheinterfaceisnotaggregated.MostcallerspassNULL.Ifaggregationisrequested,theobjectreturnedin*ppvOutisapointertoIUnknown,asrequiredbyCOMaggregation.

ReturnValues

Ifthefunctionsucceeds,thereturnvalueisDI_OK.

Ifthefunctionfails,thereturnvaluecanbeoneofthefollowingerrorvalues:

DIERR_BETADIRECTINPUTVERSIONDIERR_INVALIDPARAMDIERR_OLDDIRECTINPUTVERSIONDIERR_OUTOFMEMORY

Remarks

TheDirectInputobjectcreatedbythisfunctionisimplementedinDinput8d.dll.VersionsofinterfacesearlierthanDirectX8.0cannotbeobtainedinthisimplementation.Touseearlierversions,createtheDirectInputobjectbyusingDirectInputCreateorDirectInputCreateEx,whichareinDinput.lib.

CallingthefunctionwithpunkOuter=NULLisequivalenttocreatingtheobjectthroughCoCreateInstance(&CLSID_DirectInput8,punkOuter,CLSCTX_INPROC_SERVER,&IID_IDirectInput8W,lplpDirectInput),theninitializingitwithIDirectInput8::Initialize.

CallingthefunctionwithpunkOuter!=NULLisequivalenttocreatingtheobjectthroughCoCreateInstance(&CLSID_DirectInput8,punkOuter,CLSCTX_INPROC_SERVER,&IID_IUnknown,lplpDirectInput).Theaggregatedobjectmustbeinitializedmanually.

Requirements

WindowsNT/2000/XP:RequiresWindows®2000.Windows98/Me:RequiresWindows98orlater.AvailableasaredistributableforWindows98.Header:Declaredindinput.h.ImportLibrary:Usedinput8.lib.


DIJOYSTATEDescribesthestateofajoystickdevice.ThisstructureisusedwiththeIDirectInputDevice8::GetDeviceStatemethod.

typedefstructDIJOYSTATE{

LONGlX;

LONGlY;

LONGlZ;

LONGlRx;

LONGlRy;

LONGlRz;

LONGrglSlider[2];

DWORDrgdwPOV[4];

BYTErgbButtons[32];

}DIJOYSTATE,*LPDIJOYSTATE;

Members

lXX-axis,usuallytheleft-rightmovementofastick.

lYY-axis,usuallytheforward-backwardmovementofastick.

lZZ-axis,oftenthethrottlecontrol.Ifthejoystickdoesnothavethisaxis,thevalueis0.

lRxX-axisrotation.Ifthejoystickdoesnothavethisaxis,thevalueis0.

lRyY-axisrotation.Ifthejoystickdoesnothavethisaxis,thevalueis0.

lRzZ-axisrotation(oftencalledtherudder).Ifthejoystickdoesnothavethisaxis,thevalueis0.

rglSlider[2]Twoadditionalaxes,formerlycalledtheu-axisandv-axis,whosesemanticsdependonthejoystick.UsetheIDirectInputDevice8::GetObjectInfomethodtoobtainsemanticinformationaboutthesevalues.

rgdwPOV[4]

Directioncontrollers,suchaspoint-of-viewhats.Thepositionisindicatedinhundredthsofadegreeclockwisefromnorth(awayfromtheuser).Thecenterpositionisnormallyreportedas–1;butseeRemarks.Forindicatorsthathaveonlyfivepositions,thevalueforacontrolleris–1,0,9,000,18,000,or27,000.

rgbButtons[32]Arrayofbuttons.Thehigh-orderbitofthebyteissetifthecorrespondingbuttonisdown,andclearifthebuttonisupordoesnotexist.

Remarks

Youmustpreparethedeviceforjoystick-styleaccessbycallingtheIDirectInputDevice8::SetDataFormatmethod,passingthec_dfDIJoystickglobaldataformatvariable.

Ifanaxisisinrelativemode,theappropriatemembercontainsthechangeinposition.Ifitisinabsolutemode,themembercontainstheabsoluteaxisposition.

SomedriversreportthecenteredpositionofthePOVindicatoras65,535.Determinewhethertheindicatoriscenteredasfollows:

BOOLPOVCentered=(LOWORD(dwPOV)==0xFFFF);

NoteUnderMicrosoft®DirectX®7,slidersonsomejoystickscouldbeassignedtotheZaxis,withsubsequentcoderetrievingdatafromthatmember.UsingDirectX8,thosesamesliderswillbeassignedtotherglSliderarray.ThisshouldbetakenintoaccountwhenportingapplicationstoDirectX8.MakeanynecessaryalterationstoensurethatsliderdataisretrievedfromtherglSliderarray.

Requirements

WindowsNT/2000/XP:RequiresWindows2000.Windows98/Me:RequiresWindows98orlater.AvailableasaredistributableforWindows98.Header:DeclaredinDinput.h.

SeeAlso

DIJOYSTATE2


DIJOYSTATE2Describesthestateofajoystickdevicewithextendedcapabilities.ThisstructureisusedwiththeIDirectInputDevice8::GetDeviceStatemethod.

typedefstructDIJOYSTATE2{

LONGlX;

LONGlY;

LONGlZ;

LONGlRx;

LONGlRy;

LONGlRz;

LONGrglSlider[2];

DWORDrgdwPOV[4];

BYTErgbButtons[128];

LONGlVX;

LONGlVY;

LONGlVZ;

LONGlVRx;

LONGlVRy;

LONGlVRz;

LONGrglVSlider[2];

LONGlAX;

LONGlAY;

LONGlAZ;

LONGlARx;

LONGlARy;

LONGlARz;

LONGrglASlider[2];

LONGlFX;

LONGlFY;

LONGlFZ;

LONGlFRx;

LONGlFRy;

LONGlFRz;

LONGrglFSlider[2];

}DIJOYSTATE2,*LPDIJOYSTATE2;

Members

lXX-axis,usuallytheleft-rightmovementofastick.

lY

Y-axis,usuallytheforward-backwardmovementofastick.lZ

Z-axis,oftenthethrottlecontrol.Ifthejoystickdoesnothavethisaxis,thevalueis0.

lRxX-axisrotation.Ifthejoystickdoesnothavethisaxis,thevalueis0.

lRyY-axisrotation.Ifthejoystickdoesnothavethisaxis,thevalueis0.

lRzZ-axisrotation(oftencalledtherudder).Ifthejoystickdoesnothavethisaxis,thevalueis0.

rglSlider[2]Twoadditionalaxisvalues(formerlycalledtheu-axisandv-axis)whosesemanticsdependonthejoystick.UsetheIDirectInputDevice8::GetObjectInfomethodtoobtainsemanticinformationaboutthesevalues.

rgdwPOV[4]Directioncontrollers,suchaspoint-of-viewhats.Thepositionisindicatedinhundredthsofadegreeclockwisefromnorth(awayfromtheuser).Thecenterpositionisnormallyreportedas–1;butseeRemarks.Forindicatorsthathaveonlyfivepositions,thevalueforacontrolleris–1,0,9,000,18,000,or27,000.

rgbButtons[128]Arrayofbuttons.Thehigh-orderbitofthebyteissetifthecorrespondingbuttonisdown,andclearifthebuttonisupordoesnotexist.

lVXX-axisvelocity.

lVYY-axisvelocity.

lVZZ-axisvelocity.

lVRxX-axisangularvelocity.

lVRyY-axisangularvelocity.

lVRzZ-axisangularvelocity.

rglVSlider[2]Extraaxisvelocities.

lAXX-axisacceleration.

lAYY-axisacceleration.

lAZZ-axisacceleration.

lARxX-axisangularacceleration.

lARyY-axisangularacceleration.

lARzZ-axisangularacceleration.

rglASlider[2]Extraaxisaccelerations.

lFXX-axisforce.

lFYY-axisforce.

lFZZ-axisforce.

lFRxX-axistorque.

lFRyY-axistorque.

lFRzZ-axistorque.

rglFSlider[2]Extraaxisforces.

Remarks

YoumustpreparethedeviceforaccesstoajoystickwithextendedcapabilitiesbycallingtheIDirectInputDevice8::SetDataFormatmethod,passingthec_dfDIJoystick2globaldataformatvariable.

Ifanaxisisinrelativemode,theappropriatemembercontainsthechangeinposition.Ifitisinabsolutemode,themembercontainstheabsoluteaxisposition.

SomedriversreportthecenteredpositionofthePOVindicatoras65,535.Determinewhethertheindicatoriscenteredasfollows:

BOOLPOVCentered=(LOWORD(dwPOV)==0xFFFF);

NoteUnderMicrosoft®DirectX®7,slidersonsomejoystickscouldbeassignedtotheZaxis,withsubsequentcoderetrievingdatafromthatmember.UsingDirectX8,thosesamesliderswillbeassignedtotherglSliderarray.ThisshouldbetakenintoaccountwhenportingapplicationstoDirectX8.MakeanynecessaryalterationstoensurethatsliderdataisretrievedfromtherglSliderarray.

Requirements

WindowsNT/2000/XP:RequiresWindows2000.Windows98/Me:RequiresWindows98orlater.AvailableasaredistributableforWindows98.Header:DeclaredinDinput.h.

SeeAlso

DIJOYSTATE


ps

Providesthemethodtospecifytheversionoftheshadercode.

ps.mainVer.subVer

Registers

Argument Description ValuesmainVer mainversionnumber 1subVer subversionnumber 0,1,2,3,4

Remarks

Thisinstructionmustbethefirstinstructioninashader.

Example

//Thisexampledeclaresaversion1.0shader.

ps.1.0

//Thisexampledeclaresaversion1.4shader.

ps.1.4


defProvidesamethodtodefineconstantstobeusedwithinthepixelshader.

defdest,fVal0,fVal1,fVal2,fVal3

Registers

Argument DescriptionRegisters

Versionvn cn tn rn

dest Destinationregister x 1.0,1.1,1.2,1.3,1.4

fVal0,fVal1,fVal2,fVal3

Sourcefloatingpointvalue N/A N/A N/A N/A 1.0,1.1,1.2,

1.3,1.4

N/ANotapplicable.Thefloatvaluesdonotuseregisters.

EachofthefloatvaluesinfVal0,fVal1,fVal2,fVal3isbetween-1.0and1.0.ThisisnotnecessarilythenumberspecifiedinMAXPIXELSHADERVALUE.

Tolearnmoreaboutregisters,seeRegisters.

Remarks

definstructionsmustbeplacedaftertheversioninstructionandbeforeanyarithmeticortextureaddressinstructions.

ThedefinstructionisanalternativetosettingpixelshaderconstantsbycallingSetPixelShaderConstant.WhenSetPixelShaderiscalled,thedefinstructioniseffectivelytranslatedintoaSetPixelShaderConstantcall.ConstantregistersthatareinitializedbythedefinstructionduringSetPixelShadercanbeoverwrittenbycallingSetPixelShaderConstantmanually.

Thisinstructiondoesnotcountagainsttheinstructionlimit.Itisstrippedfromtheinstructionstreampriortobeingsenttothedriver.

FormoreinformationaboutMAXPIXELSHADERVALUE,seeD3DCAPS8.

Example

//Thisexampleoutputsaconstantcolor.

//Theshaderisshownbelow.

ps.1.0//versioninstruction

defc0,1.0f,0.0f,0.0f,1.0f//setc0register

movr0,c0//outputconstantcolor

MicrosoftDirectX8.1(pixelshaderversion1.4)

phase

Thephaseinstructionmarksthetransitionbetweenphase1andphase2.Ifnophaseinstructionispresent,theentireshaderifexecutedasifitisaphase2shader.

phase

Remarks

Thisinstructionappliestoversion1.4only.

Shaderinstructionsthatoccurbeforethephaseinstructionarephase1instructions.Allotherinstructionsarephase2instructions.Byhavingtwophasesforinstructions,themaximumnumberofinstructionspershaderisincreased.

Theunfortunateside-effectofthephasetransitionisthatthealphacomponentoftemporaryregistersareunsetoruninitializedduringthetransition.

Example

Thisexampleshowshowtogroupinstructionsasphase1orphase2instructionswithinashader.

Thephaseinstructionisalsocommonlycalledthephasemarkerbecauseitmarksthetransitionbetweenphase1and2instructions.Inaversion1.4pixelshader,ifthephasemarkerisnotpresent,theshaderisexecutedasifitisrunninginphase2.Thisisimportantbecausetherearedifferencesbetweenphase1and2instructionsandregisteravailability.Thedifferencesarenotedthroughoutthereferencesection.

ps.1.4

//Addphase1instructionshere.

phase

//Addphase2instructionshere.


addPerformsacomponent-wiseaddoftworegisters.

adddest,src0,src1

Registers


Versionvn cn tn rn

dest Destinationregisterx 1.0

x x 1.1,1.2,1.3x 1.4

src0,src1 Sourceregisterx x x x 1.0,1.1,1.2,1.3

x x 1.4phase1x x x 1.4phase2


Remarks

Thisinstructionperformsacomponent-wiseadditionoftworegistersasshownbelow.

dest.r=src0.r+src1.r

dest.g=src0.g+src1.g

dest.b=src0.b+src1.b

dest.a=src0.a+src1.a

Example

Thisexampleisforillustrationonly.TheCcodeaccompanyingtheshaderhasnotbeenoptimizedforperformance.ItcanusehelperfunctionsfromtheSampleFramework.Thesampleframeworkisthefoundationonwhichmanyofthesamplesarebuilt.

//Thisexampleaddsthevertexcolortothetexturecolor.


ps.1.0//Versioninstruction.

text0//Declaretexture.ThisexamplerequirestheDXLogotexture

//tobesetonstage0.

addr0,t0,t0//r0=t0+t0.Thisdoubleseachcolorcomponent.

//Theeffectistoincreaseimagebrightness.

//Theinputtextureisshownontheleft.Therenderedoutputfromthe

//pixelshaderisshownontheright.Inthisexample,itisbrighter

//becausethetexturecolorvalueshavebeendoubled.

//Additionalcodeloadsthetextureintexturestage0.

LPDIRECT3DDEVICE8m_pd3dDevice;//Initthisdevicepointerintheapplication.

LPDIRECT3DTEXTURE8m_pTexture0;//Usethisvariabletoholdapointertothetexture.

TCHARstrPath[512]="textureFile.jpg";

//UseahelperfunctionfromtheSDKtoloadthetexture.

D3DUtil_CreateTexture(m_pd3dDevice,strPath,&m;_pTexture0,D3DFMT_R5G6B5);

m_pd3dDevice->SetTexture(0,m_pTexture0);


bemApplyafakebumpenvironment-maptransform.

bemdest.rg,src0,src1

Registers


Versionvn cn tn rndest Destinationregister x 1.4phase1src0

Sourceregisterx x 1.4phase1

src1 x 1.4phase1


Remarks

Thisinstructionperformsthefollowingcalculation.

(Givenn==destregister#)

dest.r=src0.r+D3DTSS_BUMPENVMAT00(stagen)*src1.r

+D3DTSS_BUMPENVMAT10(stagen)*src1.g

dest.g=src0.g+D3DTSS_BUMPENVMAT01(stagen)*src1.r

+D3DTSS_BUMPENVMAT11(stagen)*src1.g

Rulesforusingbem:

1. bemmustappearinthefirstphaseofashader(thatis,beforeaphasemarker).

2. bemconsumestwoarithmeticinstructionslots.3. Onlyoneuseofthisinstructionisallowedpershader.4. Destinationwritemaskmustbe.rg/.xy.5. Thisinstructioncannotbeco-issued.

6. Asidefromtherestrictionthatdestinationwritemaskbe.rg,modifiersonsourcesrc0,src1,andinstructionmodifiersareunconstrained.

MicrosoftDirectX8.1(pixelshaderversions1.2,1.3,1.4)

cmpConditionallychoosesbetweensrc1andsrc2,basedonthecomparisonsrc0>=0.

cmpdest,src0,src1,src2

Registers


Versionvn cn tn rn

dest Destinationregisterx x 1.2,1.3x 1.4

src0,src1,src2 Sourceregisterx x x x 1.2,1.3



Remarks

Thecomparisonisdoneperchannel.

Forpixelshaderversion1.2and1.3,cmpcountsastwoarithmeticinstructions.Unfortunately,thiswasdiscoveredtoolateinthedevelopmentcycle,andthereforeisnotvalidatedproperlywhencallingCreatePixelShader.Itisincorrectlybeingcountedasconsumingonlyonearithmeticinstruction.Besuretomanuallycountthisinstructionastwoarithmeticinstructionstowardthemaximuminstructioncount.Formoreinformationaboutinstructioncounts,seeCountingInstructions.

Inaddition,forpixelshaderversion1.2and1.3,thedestinationregisterforcmpcannotbethesameasanyofthesourceregisters.Validationdoesnotcatchthis,sobesuretokeepthisinmind.

Example

Thisexampledoesafour-channelcomparison.

//Comparesallfourcomponents.

ps.1.4

defc0,-0.6,0.6,0,0.6

defc10,0,0,0

defc21,1,1,1

cmpr0,c0,c1,c2//r0isassigned1,0,0,0basedonthefollowing:

//r0.x=c2.xbecausec0.x<0

//r0.y=c1.ybecausec0.y>=0

//r0.z=c1.zbecausec0.z>=0

//r0.w=c1.wbecausec0.w>=0


cndConditionallychoosesbetweensrc1andsrc2,basedonthecomparisonsrc0>0.5.

cnddest,src0,src1,src2

Registers


Versionvn cn tn rn


x x 1.1,1.2,1.3x 1.4

src0

Sourceregister

r0.a 1.0,1.1,1.2,1.3src1,src2 x x x x 1.0,1.1,1.2,1.3

src0,src1,src2x x 1.4phase1

x x x 1.4phase2


Remarks

Forversions1.0to1.3,src0mustber0.a.Version1.4hasnosuchrestriction.

//Version1.1to1.3

if(r0.a>0.5)

dest=src1

else

dest=src2

//Version1.4compareseachchannelseparately.

foreachcomponentinsrc0

{

if(src0.component>0.5)

dest.component=src1.component

else

dest.component=src2.component

}

Example

Theseexamplesshowafour-channelcomparisondoneinaversion1.4shader,aswellasasingle-channelcomparisonpossibleinaversion1.1shader.

//Version1.4comparesallfourcomponents.

ps.1.4

defc0,-0.5,0.5,0,0.6

defc10,0,0,0

defc21,1,1,1

cndr1,c0,c1,c2//r0contains1,1,1,0because,

//r1.x=c2.xbecausec0.x≤0.5

//r1.y=c2.ybecausec0.y≤0.5

//r1.z=c2.zbecausec0.z≤0.5

//r1.w=c1.wbecausec0.w>0.5

//Version1.1to1.3comparesagainstthereplicatedalphachannel

//ofr0only.

ps.1.1

defc0,-0.5,0.5,0,0.6

defc10,0,0,0

defc21,1,1,1

movr0,c0

cndr1,r0.a,c1,c2//r1getsassigned0,0,0,0because

//r0.a>0.5,thereforer1.xyzw=c1.xyzw

//Thisexamplecomparestwovalues,AandB,toeachother.

//ThisexampleassumesAisloadedintov0andBisloadedintov1.

//BothAandBmustbeintherangeof-1to+1,andsincethe

//colorregisters(vn)aredefinedtobebetween0and1,

//therestrictionhappenstobesatisfiedinthisexample.



subr0,v0,v1_bias//r0=A-(B-0.5)

cndr0,r0.a,c0,c1//r0=(A>B?c0:c1)

//Theresultinr0isc0ifA>B.Otherwise,theresultinr0isc1.


dp3Calculatesathree-componentdotproduct.Thescalarresultisreplicatedtoallfourchannels.

dp3dest,src0,src1

Registers


Versionvn cn tn rn


x x 1.1,1.2,1.3x 1.4



dp3doesnotautomaticallyclamptheoutputresultbetweenzeroandone.Ifclampingisnecessary,usethesaturatemodifiers.

dp3canbeco-issuedaslongasdp3iswritingthecolorchannelsandtheotherinstructioniswritingthealphachannel.


Remarks

Thisinstructionexecutesinthevectorpipeline,alwayswritingouttothecolorchannels.Forversion1.4,thisinstructionstillusesthevectorpipelinebutmaywritetoanychannel.

dp3r0.rgb,t0,v0//CopyscalarresulttoRGBcomponents.

AninstructionwithadestinationregisterRGBwritemaskmaybeco-issued

withdp3asshownbelow.

dp3r0.rgb,t0,v0//Copyscalarresulttocolorcomponents.

+movr2.a,t0//Copyalphacomponentfromt0inparallel.

Thedp3instructioncanbemodifiedusingtheSignedScalinginputargumentmodifier(_bx2)appliedtoitsinputargumentsiftheyarenotalreadyexpandedtosigneddynamicrange.Foralightingshader,thesaturateinstructionmodifier(_sat)isoftenusedtoclampthenegativevaluestoblack,asshowninthefollowingexample.

dp3_satr0,t0_bx2,v0_bx2//Heret0isabumpmap,v0containsthelightdirection.

Example


Thisexampleusesadotproducttosquarethevertexdiffusecolorcomponents.



text0//Declaretexture.

dp3r0,v0,v0//Dotproductsquaresthevertexcolorvalues,

//color(v0)*color(v0).

//Brightcolorsmaxoutatwhite.

//Dimmercolorsyieldgray.

Theresultsofthisexampleareshownbelow.Theinputvertexcolorsareshownontheleft.Therenderedoutputfromthepixelshaderisshownontheright.Theleft,bottom,andrightedgesarewhitebecausetheinputcolorcomponentsreachthemaximumcolorvaluewhensquared.Thecentercolorisgraybecausethesquaredcolorvaluesarelowerwheretheinputcolorsblendtogether.

Additionalcodeloadsatextureintexturestage0

LPDIRECT3DDEVICE8m_pd3dDevice;//Initializethepointerbeforeusing.





MicrosoftDirectX8.1(pixelshaderversions1.2,1.3,1.4)

dp4Calculatesafour-componentdotproduct.Thescalarresultisreplicatedtoallchannels.

dp4dest,src0,src1

Registers


Versionvn cn tn rn

dest Destinationregisterx 1.2,1.3x 1.4

src0,src1 Sourceregisterx x x x 1.2,1.3


Thisinstructioncannotbeco-issued.

Thisinstructiondoesnotautomaticallyclamptheoutputresultbetweenzeroandone.Ifclampingisnecessary,usethesaturatemodifier.


Remarks

Thisinstructionexecutesinboththevectorandalphapipeline.

dp4r0,t0,v0//CopyscalarresulttoRGBAcomponents.

Forpixelshaderversion1.2and1.3,dp4countsastwoarithmeticinstructions.Unfortunately,thiswasdiscoveredtoolateinthedevelopmentcycleandthereforeisnotvalidatedproperlywhencallingCreatePixelShader.Itisbeingincorrectlycountedasconsumingonlyonearithmeticinstruction.Besuretomanuallycountthisinstructionastwoarithmeticinstructionstowardthe

maximuminstructioncount.Formoreinformationaboutinstructioncounts,seeCountingInstructions.

Inaddition,forpixelshaderversion1.2and1.3,thedestinationregisterfordp4cannotbethesameasanyofthesourceregisters.Validationdoesnotcatchthis,sobesuretokeepthisinmind.


lrpInterpolateslinearlybetweenthesecondandthirdsourceregistersbyaproportionspecifiedinthefirstsourceregister.

lrpdest,src0,src1,src2

Registers


Versionvn cn tn rn


x x 1.1,1.2,1.3x 1.4

src0,src1,src2 Sourceregisterx x x x 1.0,1.1,1.2,1.3



Remarks

Thisinstructionperformsthelinearinterpolationbasedonthefollowingformula.

dest=src0*src1+(1-src0)*src2

//whichisthesameas

dest=src2+src0*(src1-src2)

Example


//Thisexamplecombinesatexturecolorwithadiffusecolorvalue.




lrpr0,t0,v0,t0//Blendfromv0tot0byt0amount.

//Theinputcolorsandtheoutputcolorsareshownbelow.Thefirstimage

//(src0)determinestheamountofthesecondimage(src1)andthethirdimage

//(src2)thatareblendedtomakethefinalimage(dest).Wherethefirstimage

//iswhite,thesecondimageappearsintheoutput.Wherethefirstimageis

//black,thethirdimagesappearsintheoutput.Wherethefirstisgray,the

//finalimagecontainscolorvaluesfromthesecondandthirdimage.


LPDIRECT3DDEVICE8m_pd3dDevice;//initializethepointer

LPDIRECT3DTEXTURE8m_pTexture0;//apointertothetexture.





madMultiplyandaddinstruction.Setsthedestinationregisterto(src0*src1)+src2.

maddest,src0,src1,src2

Registers


Versionvn cn tn rn


x x 1.1,1.2,1.3x 1.4

src0,src1,src2 Sourceregisterx x x x 1.0,1.1,1.2,1.3



Remarks

Thisinstructionperformsamultiplyaccumulateoperationbasedonthefollowingformula.

dest=src0*src1+src2

Example


//Thisexampleblendsadiffusecolor,atexturecolorandaconstantcolor.




madr0,v0,t0,v0//Mixdiffusecolorandtexturecolor.

//Thefollowingfourimagesshowthecontentsofthethreesourceregisters

//andtheresultingoutputregister.Theoutputregistershowstheresultof

//thegradientinthecenterofthedestinationimage,wherethemidtones

//appear.Thisisaresultofaddingthepixelsfromthecenterofsrc2with

//thepixelcolorcreatedfromthecenteroftheproductofsrc0*src1.

//Additionalcodeloadsatextureintexturestage0.

LPDIRECT3DDEVICE8m_pd3dDevice;//initializethispointer

LPDIRECT3DTEXTURE8m_pTexture0;//apointertothetexture.





movCopiesthecontentsofthesourcetothedestination.

movdest,src

Registers


Versionvn cn tn rn


x x 1.1,1.2,1.3x 1.4

src Sourceregisterx x x x 1.0,1.1,1.2,1.3



Example


//Thisexamplecopiesthetexturecolortotheoutput.


ps.1.0//Versioninstruction


movr0,t0//Movetexturetooutput.

//Thefollowingimagesshowthecontentsofthesourceregisterand

//theresultingdestinationregister.Theimagesareidenticalbecause

//themovinstructionwasused.








mulMultipliesthecomponentsoftwosourceregisters.Theresultisdest=src0*src1.

muldest,src0,src1

Registers


Versionvn cn tn rn


x x 1.1,1.2,1.3x 1.4




Example


//Thisexamplecombinesthetexturecolorandthediffusecolor.




mulr0,v0,t0//Multiplydiffusecolorwithgradienttexture.

//Thefollowingimagesshowthecontentsofthesourceregistersthe

//resultingoutputregister.

//Wheresrc1iswhite,thedestinationpixelcoloristhesameasthe

//sourcepixelcolorsincedest=src*1.0.

//Wheresrc1isblack,thedestinationisalsoblack.

//Thepixelcolorsinthemiddleofthedestinationimageareablend

//ofsrc0andsrc1.

//Additionalcodeloadsatextureintexturestage0.







nopNooperationisperformed.

nop

Registers

None

Remarks

Thisinstructionperformsano-op,ornooperation.Thesyntaxforcallingitisasfollows:

nop


subPerformssubtraction.Subtractsthesecondsourceregisterfromthefirstsourceregister.

subdest,src0,src1

Registers


Versionvn cn tn rn


x x 1.1,1.2,1.3x 1.4




Remarks

Thisinstructionperformsthesubtractionbasedonthefollowingformula.

dest=src0-src1

Example


//Thisexamplesubtractstexturecolorfromthediffusecolor.




subr0,v0,t0//Subtracttexturecolorfromdiffusecolor.

//Thefollowingimagesshowthecontentsofthesourceregistersand

//theresultingdestinationregister.Thecolorsinthesecondimage(src1)

//aresubtractedfromthecolorinthefirstimage(src0)tomakethe

//resultingimage(dest).




TCHAR strPath[512]="textureFile.jpg";



MicrosoftDirectX8.1(pixelshaderversions1.0,1.1,1.2,1.3)

texLoadsthedestinationregisterwithcolordata(RGBA)sampledfromatexture.

Thetexturemustbeboundtoaparticulartexturestage(n)usingSetTexture.Texturesamplingiscontrolledbythetexturestagestateattributes,setwithSetTextureStageState.

texdest

Registers


Versionvn cn tn rndest Destinationregister x 1.0,1.1,1.2,1.3


Remarks

Thedestinationregisternumberspecifiesthetexturestagenumber.

Texturesamplingusestexturecoordinatestolookup,orsample,acolorvalueatthespecified(u,v,w,q)coordinateswhiletakingintoaccountthetexturestagestateattributes.

Thetexturecoordinatedataisinterpolatedfromthevertextexturecoordinatedataandisassociatedwithaspecifictexturestage.Thedefaultassociationisaone-to-onemappingbetweentexturestagenumberandtexturecoordinatedeclarationorder.Thismeansthatthefirstsetoftexturecoordinatesdefinedinthevertexformatarebydefaultassociatedwithtexturestage0.

Texturecoordinatesmaybeassociatedwithanystageusingtwotechniques.Whenusingafixedfunctionvertexshaderorthefixedfunctionpipeline,thetexturestagestateflagTSS_TEXCOORDINDEXcanbeusedinSetTextureStageStatetoassociatecoordinatestoastage.Otherwise,thetexture

coordinatesareoutputbythevertexshaderoTnregisterswhenusingaprogrammablevertexshader.

Example


//Thisexampleappliesatexturetoaquad.



text0//samplesthetextureatstage0usingtexturecoordinatesfromstage0

movr0,t0//copiesthecolorint0tooutputregisterr0

//Therenderedoutputfromthepixelshaderisshownbelow.Itis

//simplyatexturemapappliedtoaquadobject.

//Additionalcodeisrequiredtousethisshaderandanexample

//scenarioisshownbelow.

//Loadthetextureintexturestage0.

LPDIRECT3DDEVICE8m_pd3dDevice; //Initializethepointerbeforeusing

LPDIRECT3DTEXTURE8m_pTexture0; //apointerforthetexture

TCHARstrPath[512]="DX5_Logo.bmp";

//HelperfunctionfromtheSDK



//Thiscodecreatestheshaderfromafile.Thecontentsoftheshader

//filecanalsobesuppliedasatextstring.

TCHARstrPShaderPath[512];

LPD3DXBUFFERpCode;

//HelperfunctionfromtheSDK

DXUtil_FindMediaFile(strPShaderPath,_T("shaderFile.txt"));

//Assemblethevertexshaderfromthefile.

D3DXAssembleShaderFromFile(strPShaderPath,0,NULL,&pCode;,NULL);

m_pd3dDevice->CreatePixelShader((DWORD*)pCode->GetBufferPointer(),

&m;_hPixelShader);

pCode->Release();

//Definetheobjectvertexdata.

structCUSTOMVERTEX

{

FLOATx,y,z;

FLOATtu1,tv1;

};

#defineD3DFVF_CUSTOMVERTEX(D3DFVF_XYZ|D3DFVF_TEX1|TEXCOORD2(0))

staticCUSTOMVERTEXg_Vertices[]=

{

//xyzu1v1

{-1.0f,-1.0f,0.0f,0.0f,1.0f,},

{+1.0f,-1.0f,0.0f,1.0f,1.0f,},

{+1.0f,+1.0f,0.0f,1.0f,0.0f,},

{-1.0f,+1.0f,0.0f,0.0f,0.0f,},

//v1isflippedtomeetthetopdownconventioninWindows

//theupperlefttexturecoordinateis(0,0)

//thelowerrighttexturecoordinateis(1,1).

};

//Createandfillthequadvertexbuffer.

m_pd3dDevice->CreateVertexBuffer(4*sizeof(CUSTOMVERTEX),

D3DUSAGE_WRITEONLY,D3DFVF_CUSTOMVERTEX,

D3DPOOL_MANAGED,&m;_pQuadVB);

CUSTOMVERTEX*pVertices=NULL;

m_pQuadVB->Lock(0,4*sizeof(CUSTOMVERTEX),(BYTE**)&pVertices;,0);

for(DWORDi=0;i<4;i++)

pVertices[i]=g_Vertices[i];

m_pQuadVB->Unlock();

//Checktoseeifthehardwaresupportspixelshaders.

if(D3DSHADER_VERSION_MAJOR(pCaps->PixelShaderVersion)<1)

returnE_FAIL;

//Setupthetransforms.

D3DXVECTOR3from(0,0,-5.0f);

D3DXVECTOR3at(0.0f,0.0f,0.0f);

D3DXVECTOR3up(0.0f,1.0f,0.0f);

D3DXMATRIXmatWorld;

D3DXMatrixIdentity(&matWorld;);

m_pd3dDevice->SetTransform(D3DTS_WORLD,&matWorld;);

D3DXMATRIXmatView;

D3DXMatrixLookAtLH(&matView;,&from;,&at;,&up;);

m_pd3dDevice->SetTransform(D3DTS_VIEW,&matView;);

D3DXMATRIXmatProj;

D3DXMatrixPerspectiveFovLH(&matProj;,D3DX_PI/4,1.0f,0.5f,1000.0f);

m_pd3dDevice->SetTransform(D3DTS_PROJECTION,&matProj;);

//Rendertheoutput.

//Clearthebackbuffertoblack.

m_pd3dDevice->Clear(0L,NULL,D3DCLEAR_TARGET,0x00000000,1.0f,0L);

//Setdevicestate.

m_pd3dDevice->SetRenderState(D3DRS_CULLMODE,D3DCULL_NONE);

m_pd3dDevice->SetRenderState(D3DRS_CLIPPING,FALSE);

m_pd3dDevice->SetRenderState(D3DRS_LIGHTING,FALSE);

m_pd3dDevice->SetRenderState(D3DRS_ZENABLE,FALSE);


m_pd3dDevice->SetStreamSource(0,m_pQuadVB,sizeof(CUSTOMVERTEX));

m_pd3dDevice->SetVertexShader(D3DFVF_CUSTOMVERTEX);

m_pd3dDevice->SetPixelShader(m_hPixelShader);

m_pd3dDevice->DrawPrimitive(D3DPT_TRIANGLEFAN,0,2);

m_pd3dDevice->SetTexture(0,NULL);


texbemApplyafakebumpenvironment-maptransform.Thisisaccomplishedbymodifyingthetextureaddressdataofthedestinationregister,usingaddressperturbationdata(du,dv),andatwo-dimensional(2-D)bumpenvironmentmatrix.

texbemdest,src

Registers


Versionvn cn tn rndest Destinationregister x 1.0,1.1,1.2,1.3src Sourceregister x 1.0,1.1,1.2,1.3

Theredandgreencolordatainthesrcregisterisinterpretedastheperturbationdata(du,dv).


Remarks

Thisinstructiontransformsredandgreencomponentsinthesourceregisterusingthe2-Dbumpenvironment-mappingmatrix.Theresultisaddedtothetexturecoordinatesetcorrespondingtothedestinationregisternumber,andisusedtosamplethecurrenttexturestage.

Thisoperationalwaysinterpretsduanddvassignedquantities.Forversions1.0and1.1,theSignedScalinginputmodifier(_bx2)isnotpermittedontheinputargument.

Thisinstructionproducesdefinedresultswheninputtexturescontainsignedformatdata.Mixedformatdataworksonlyifthefirsttwochannelscontainsigneddata.Formoreinformationaboutsurfaceformats,seeD3DFORMAT.

Thiscanbeusedforavarietyoftechniquesbasedonaddressperturbation,includingfakeper-pixelenvironmentmappinganddiffuselighting(bumpmapping).

//Whenusingthisinstruction,textureregistersmustfollowthefollowingsequence.

//Thetextureassignedtostaget(n)containsthe(du,dv)data.

//Thetextureassignedtostaget(m)issampled.

text(n)

texbemt(m),t(n)wherem>n

//Thecalculationsdonewithintheinstructionareshownbelow.

//1.Newvaluesfortextureaddresses(u',v')arecalculated.

//2.Samplethetextureusing(u',v')

u'=TextureCoordinates(stagem)u+D3DTSS_BUMPENVMAT00(stagem)*t(n)

D3DTSS_BUMPENVMAT10(stagem)*t(n)G

v'=TextureCoordinates(stagem)v+D3DTSS_BUMPENVMAT01(stagem)*t(n)


t(m)RGBA=TextureSample(stagem)using(u',v')ascoordinates.

NoteWhenusingtexbemortexbeml,donotre-readthesourceregisterlaterintheshaderbecausethedatawithintheregistermightbecorrupted.Theshadervalidationallowsthiseventhoughtheresultwillbeundefined.

Example

//Hereisanexampleshaderwiththetexturemapsidentifiedand

//thetexturestagesidentified.

ps.1.0

text0;definet0togeta2-tupleDuDv

texbemt1,t0;compute(u',v')

;samplet1using(u',v')

movr0,t1;outputresult

//texbemrequiresthefollowingtexturesinthefollowingtexturestages.

//

//Stage0isassignedabumpmapwith(du,dv)perturbationdata.

//

//Stage1usesatexturemapwithcolordata.

//

//Thisinstructionsetsthematrixdataonthetexturestagethatissampled.

//Thisisdifferentfromthefunctionalityofthefixedfunctionpipelinewhere

//theperturbationdataandthematricesoccupythesametexturestage.


texbemlApplyafakebumpenvironment-maptransformwithluminancecorrection.Thisisaccomplishedbymodifyingthetextureaddressdataofthedestinationregister,usingaddressperturbationdata(du,dv),atwo-dimensional(2-D)bumpenvironmentmatrix,andluminance.

texbemldest,src

Registers



Theredandgreencolordatainthesrcregisterisinterpretedastheperturbationdata(du,dv).


Remarks

Thisinstructiontransformstheredandgreencomponentsinthesourceregisterusingthe2-Dbumpenvironmentmappingmatrix.Theresultisaddedtothetexturecoordinatesetcorrespondingtothedestinationregisternumber.Aluminancecorrectionisappliedusingtheluminancevalueandthebiastexturestagevalues.Theresultisusedtosamplethecurrenttexturestage.

Thiscanbeusedforavarietyoftechniquesbasedonaddressperturbationsuchasfakeper-pixelenvironmentmapping.

Thisoperationalwaysinterpretsduanddvassignedquantities.Forversions1.0and1.1,theSignedScalinginputmodifier(_bx2)isnotpermittedontheinputargument.

Thisinstructionproducesdefinedresultswheninputtexturescontainmixedformatdata.Formoreinformationaboutsurfaceformats,seeD3DFORMAT.

//Whenusingthisinstruction,textureregistersmustfollowthefollowingsequence.

//Thetextureassignedtostagetncontainsthe(du,dv)data.

//Thetextureassignedtostaget(m)issampled.

text(n)

texbemlt(m),t(n)wherem>n

//Thisexampleshowsthecalculationsdonewithintheinstruction.

//1.Newvaluesfortextureaddresses(u',v')arecalculated.

//2.Samplethetextureusing(u',v')

//3.Luminancecorrectionisapplied.

u'=TextureCoordinates(stagem)u+D3DTSS_BUMPENVMAT00(stagem)*t(n)


v'=TextureCoordinates(stagem)v+D3DTSS_BUMPENVMAT01(stagem)*t(n)


t(m)RGBA=TextureSample(stagem)using(u',v')ascoordinates.

t(m)RGBA=t(m)RGBA*[t(n)B*(D3DTSS_BUMPENVLSCALE(stagem)+D3DTSS_BUMPENVLOFFSET(stagem))]

NoteWhenusingtexbemortexbeml,donotre-readthesourceregisterlaterintheshaderbecausethedatawithintheregistermightbecorrupted.Theshadervalidationallowsthiseventhoughtheresultwillbeundefined.

Example



ps.1.0

text0;definet0togeta2-tupleDuDv

texbemlt1,t0;compute(u',v')

;applyluminancecorrection

;samplet1using(u',v')

movr0,t1;outputresult

//Thisexamplerequiresthefollowingtexturesinthefollowingtexturestages.

//

//Stage0isassignedabumpmapwith(du,dv)perturbationdata.

//

//Stage1isassignedatexturemapwithcolordata.

//

//texbemlsetsthematrixdataonthetexturestagethatissampled.

//Thisisdifferentfromthefunctionalityofthefixedfunctionpipelinewhere

//theperturbationdataandthematricesoccupythesametexturestage.


texcoordInterpretstexturecoordinatedata(UVW1)ascolordata(RGBA).

texcoorddest

Registers


Versionvn cn tn rndest Destinationregister x 1.0,1.1,1.2,1.3


Remarks

Thisinstructioninterpretsthetexturecoordinateset(UVW1)correspondingtothedestinationregisternumberascolordata(RGBA).Ifthetexturecoordinatesetcontainsfewerthanthreecomponents,themissingcomponentsaresetto0.Thefourthcomponentisalwayssetto1.Allvaluesareclampedbetween0and1.

Theadvantageoftexcoordisthatitprovidesawaytopassvertexdatainterpolatedathighprecisiondirectlyintothepixelshader.However,oncethedataiswrittenintothedestinationregister,someprecisionwillbelost,dependingonthenumberofbitsusedbythehardwareforregisters.

Notextureissampledbythisinstruction.Onlytexturecoordinatessetonthistexturestagearerelevant.

Anytexturedata(suchasposition,normal,andlightsourcedirection)canbemappedbyavertexshaderintoatexturecoordinate.ThisisdonebyassociatingatexturewithatextureregisterusingSetTextureandbyspecifyinghowthetexturesamplingisdoneusingSetTextureStageState.Ifthefixedfunctionpipelineisused,besuretosupplytheTSS_TEXCOORDINDEXflag.

//Thisinstructionisusedasfollows:

texcoordtn

//Atextureregister(tn)containsfourcolorvalues(RGBA).Thedatacanalsobe

//thoughtofasvectordata(xyzw).Texcoordwillretrieve3ofthesevalues(xyz)from

//texturecoordinatesetx,andthefourthcomponent(w)issetto1.

//Thetextureaddressiscopiedfromthetexturecoordinatesetn.

//Theresultisclampedbetween0and1.

Example


//Hereisanexampleshaderusingtexcoord.

ps.1.0;versioninstruction

texcoordt0;declaret0holdtexturecoordinates,

;whichrepresentrgbavaluesinthisexample

movr0,t0;movethecolorint0tooutputregisterr0

Therenderedoutputfromthepixelshaderisshownbelow.The(u,v,w,1)coordinatevaluesmaptothe(rgb)channels.Thealphachannelissetto1.Atthecornersoftheimage,coordinate(0,0,0,1)isinterpretedasblack,(1,0,0,1)isred,(0,1,0,1)isgreen,and(1,1,0,1)containsgreenandred,producingyellow.

//Additionalcodeisrequiredtousethisshaderandanexample

//scenarioisshownbelow.

//Thiscodecreatestheshaderfromafile.Thecontentsoftheshader

//filecanalsobesuppliedasatextstring.

TCHARstrPShaderPath[512];

LPD3DXBUFFERpCode;

DXUtil_FindMediaFile(strPShaderPath,_T("shaderFile.txt"));



m_pd3dDevice->CreatePixelShader((DWORD*)pCode->GetBufferPointer(),

&m;_hPixelShader);

pCode->Release();

//Thiscodedefinestheobjectvertexdata.

structCUSTOMVERTEX

{

FLOATx,y,z;

FLOATtu1,tv1;

};

#defineD3DFVF_CUSTOMVERTEX(D3DFVF_XYZ|D3DFVF_TEX1|TEXCOORD2(0))


{

//xyzu1v1

{-1.0f,-1.0f,0.0f,0.0f,0.0f,},

{+1.0f,-1.0f,0.0f,1.0f,0.0f,},

{+1.0f,+1.0f,0.0f,1.0f,1.0f,},

{-1.0f,+1.0f,0.0f,0.0f,1.0f,},

};


texcrdCopiestexturecoordinatedatafromthesourcetexturecoordinateiteratorregisterascolordatainthedestinationregister.

texcrddest,src

Registers


Versionvn cn tn rndest Destinationregister x 1.4

src Sourceregisterx 1.4phase1x 1.4phase2


Remarks

Thisinstructioninterpretscoordinatedataascolordata(RGBA).

Notextureissampledbythisinstruction.Onlytexturecoordinatessetonthistexturestagearerelevant.

Whenusingtexcrd,keepinmindthefollowingdetailabouthowdataiscopiedfromthesourceregistertothedestinationregister.Thesourcetexturecoordinateregister(t#)holdsdataintherange[-D3DCAPS8.MaxTextureRepeat,D3DCAPS8.MaxTextureRepeat],whilethedestinationregister(r#)canholddataonlyinthe(likelysmaller)range[-D3DCAPS8.MaxPixelShaderValue,D3DCAPS8.MaxPixelShaderValue].Notethatforpixelshaderversion1.4,D3DCAPS8.MaxPixelShaderValuemustbeaminimumofeight.Thetexcrdinstruction,intheprocessofclampingsourcedatathatisoutofrangeofthedestinationregister,islikelytobehavedifferentlyondifferenthardware.Thefirstpixelshaderversion1.4hardwareonthemarketwillperformaspecialclampforvaluesoutsideofrange.Thisclampisdesignedtoproduceanumber

thatcanfitintothedestinationregister,butalsotopreservetextureaddressingbehaviorforout-of-rangedata(seeD3DTEXTUREADDRESS)ifthedataweretobesubsequentlyusedfortexturesampling.However,newhardwarefromdifferentmanufacturersmightnotexhibitthisbehaviorandmightsimplychopdatatofitthedestinationregisterrange.Therefore,thesafestcourseofactionwhenusingpixelshaderversion1.4texcrdistosupplytexturecoordinatedataonlyintothepixelshaderthatisalreadywithintherange[-8,8]sothatyoudonotrelyonthewayhardwareclamps.

Unliketexcoord,texcrddoesnotclampvaluesbetween0and1.

Rulesforusingtexcrd:

1. Thesame.xyzor.xywmodifiermustbeappliedtoeveryreadofanindividualt(n)registerwithinatexcrdortexldinstruction.

2. Thefourthchannelresultoftexcrdisunset/undefinedinallcases.3. Thethirdchannelisunset/undefinedforthexyw_dwcase.

Example

Thecompletesetofallowedsyntaxfortexcrd,takingintoaccountallvalidsourcemodifier/selectoranddestinationwritemaskcombinations,isshownbelow.Notethatthe.rgbaand.xyzwnotationcanbeusedinterchangeably.

texcrdr(m).rgb,t(n).xyz

//Copiesfirstthreechannelsoftexturecoordinateiteratorregister,

//t(n),intor(m).Thefourthchannelof

//r(m)isuninitialized.

texcrdr(m).rgb,t(n)

//Producesthesameresultasthepreviousinstruction.

texcrdr(m).rgb,t(n).xyw

//Putsfirst,second,andfourthcomponentsoft(n)intofirstthreechannels

//ofr(m).Thefourthchannelofr(m)isuninitialized.

//Hereisaprojectivedivideexampleusingthe_dwmodifier.

texcrdr(m).rg,t(n)_dw.xyw

//Thisexamplecopiesx/wandy/wfromt(n)intothe

//firsttwochannelsofr(m).Thethirdandfourth

//channelsofr(m)areuninitialized.Anydatapreviously

//writtentothethirdchannelofr(m)willbelost.Data

//inthefourthchannelofr(m)islostduetothephase

//marker.Forversion1.4,theD3DTTFF_PROJECTEDflagisignored.


texdepthCalculatedepthvaluestobeusedinthedepthbuffercomparisontestforthispixel.

texdepthdest

Registers


Versionvn cn tn rndest Destinationregister r5 1.4phase2only


Remarks

Thisinstructionusesr5.r/r5.ginthedepthbuffercomparisontestforthispixel.Thedataintheblueandalphachannelsisignored.Ifr5.g=0,theresultofr5.r/r5.g=1.0.

Temporaryregisterr5istheonlyregisterthatthisinstructioncanuse.

Afterexecutingthisinstruction,temporaryregisterr5isunavailableforadditionaluseintheshader.

Whenmultisampling,usingthisinstructioneliminatesmostofthebenefitofthehigherresolutiondepthbuffer.Becausethepixelshaderexecutesonceperpixel,thesingledepthvalueoutputbytexm3x2depthortexdepthwillbeusedforeachofthesub-pixeldepthcomparisontests.

Example

Hereisanexampleusingtexdepth.

ps.1.4

texldr0,t0//Sampletexturefromtexturestage0(dest

//registernumber)intor0.

//Usetexturecoordinatedatafromt0.

texcrdr1.rgb,t1//Loadasecondsetoftexturecoordinatedataintor1.

addr5.rg,r0,r1//Addthetwosetsoftexturecoordinatedata.

phase//Phasemarker,requiredwhenusingtexdepthinstruction.

texdepthr5//Calculatepixeldepthasr5.r/r5.g.

//Doothercolorcalculationswithshaderoutputr0.

MicrosoftDirectX8.1(pixelshaderversions1.2and1.3)

texdp3Performsathree-componentdotproductbetweendatainthetextureregisternumberandthetexturecoordinatesetcorrespondingtothedestinationregisternumber.

texdp3dest,src

Registers


Versionvn cn tn rndest Destinationregister x 1.2,1.3src Sourceregister x 1.2,1.3

Remarks

Textureregistersmustusethefollowingsequence.

text(n)//Definetnasastandard3-vector(tnmustbe

//definedinsomewaybeforetexdp3usesit).

texdp3t(m),t(n)//wherem>n

//Performathree-componentdotproductbetweentnand

//thetexturecoordinatesetm.Thescalarresultis

//replicatedtoallcomponentsoft(m).

Hereismoredetailabouthowthedotproductisaccomplished.

//Thetexdp3instructionperformsathree-componentdotproductand

//replicatesittoallfourcolorchannels.

t(m)RGBA=TextureCoordinates(stagem)UVW•t(n)RGB


texdp3texPerformsathree-componentdotproductandusestheresulttodoa1-Dtexturelookup.

texdp3texdest,src

Registers



Remarks

Textureregistersmustusethefollowingsequence.

text(n)//Definetnasastandard3-vector(tnmustbe

//definedinsomewaybeforetexdp3texusesit).

texdp3text(m),t(n)//wherem>n.

//Performathree-componentdotproductbetweent(n)and

//thetexturecoordinatesetm.Usethescalarresultto

//doa1-Dtexturelookupattexturestagemandplace

//theresultint(m).

Hereismoredetailabouthowthedotproductandtexturelookuparedone.

//Thetexdp3texinstructionperformsathree-componentdotproduct.

u'=TextureCoordinates(stagem)UVW•t(n)RGB

//Theresultisusedtosamplethetextureattexturestagembyperforming

//a1-Dlookup.

t(m)RGBA=TextureSample(stagem)RGBAusing(u',0,0)ascoordinates.


texkilltexkillsrc

Cancelsrenderingofthecurrentpixelifanyofthefirstthreecomponents(UVW)ofthetexturecoordinatesislessthanzero.

Registers


Versionvn cn tn rn

src Sourceregisterx 1.0,1.1,1.2,1.3x x 1.4phase2only


Remarks

texkilldoesnotsampleanytexture.Itoperatesonthefirstthreecomponentsofthetexturecoordinatesgivenbythesourceregisternumber.Forps1.4,texkilloperatesonthedatainthefirstthreecomponentsofthesourceregister.

Youcanusethisinstructiontoimplementarbitraryclipplanesintherasterizer.

Whenusingvertexshaders,theapplicationisresponsibleforapplyingtheperspectivetransform.Thiscancauseproblemsforthearbitraryclippingplanesbecauseifitcontainsanisomorphicscalefactors,theclipplanesneedtobetransformedaswell.Therefore,itisbesttoprovideanunprojectedvertexpositiontouseinthearbitraryclipper,whichisthetexturecoordinatesetidentifiedbythetexkilloperator.

//Thisinstructionisusedasfollows:

texkilltn

//Thepixelmaskingisaccomplishedasfollows:

if(anyofthefirst3componentsofTextureCoordinates(stagen)UVWQ

cancelpixelrender

Forps1.0,1.1,1.2,and1.3,texkilloperatesonthetexturecoordinatesetgivenbythesourceregisternumber.Inversion1.4,however,texkilloperatesonthedatacontainedinthetexturecoordinateiteratorregister(tn)orinthetemporaryregister(rn)thathasbeenspecifiedasthesource.

Whenmultisamplingisenabled,anyantialiasingeffectachievedonpolygonedgesduetomultisamplingwillnotbeachievedalonganyedgethathasbeengeneratedbytexkill.Thepixelshaderrunsonceperpixel.

Example

Thisexampleisforillustrationonly.

//Thisexamplemasksoutpixelsthathavenegativetexturecoordinates.Thepixel

//colorsareinterpolatedfromvertexcolorsprovidedinthevertexdata.



texkillt0//Maskoutpixelusingtexturecoordinatesfromstage0.

movr0,v0//Movethediffusecolorinv0tor0.

//Therenderedoutputfromthepixelshaderisshownbelow.Itshows

//vertexcolordataappliedtoaplane.Thetexturecoordinatedata

//isdeclaredinthevertexdatadeclarationinthisexample.

structCUSTOMVERTEX

{

FLOATx,y,z;

DWORDcolor;

FLOATtu1,tv1;

};

#defineD3DFVF_CUSTOMVERTEX(D3DFVF_XYZ|D3DFVF_DIFFUSE|D3DFVF_TEX1|D3DTEXCOORD2(0))


{

//xyzcoloru1,v1

{-1.0f,-1.0f,0.0f,0xffff0000,-0.5f,1.0f,},

{1.0f,-1.0f,0.0f,0xff00ff00,0.5f,1.0f,},

{1.0f,1.0f,0.0f,0xff0000ff,0.5f,0.0f,},

{-1.0f,1.0f,0.0f,0xffffffff,-0.5f,0.0f,},

};

//Thetexturecoordinatesrangefrom-0.5to0.5inu,and0.0to1.0inv.

//Thisinstructioncausesthenegativeuvaluesgetmaskedout.

//Thefirstimageshowsthevertexcoloredappliedtothequadwithoutthe

//texkillinstructionapplied.

//Thesecondimageshowstheresultofthetexkillinstruction.Thepixelcolors

//fromthetexturecoordinatesbelow0(wherexgoesfrom-0.5to0.0)aremasked

//out.Thebackgroundcolor(white)isusedwherethepixelcolorismasked.

MicrosoftDirectx8.1(pixelshaderversion1.4)

texldLoadsthedestinationregisterwithcolordata(RGBA)sampledusingthecontentsofthesourceregisterastexturecoordinates.Thesampledtextureisthetextureassociatedwiththedestinationregisternumber.

texlddest,src

Registers


Versionvn cn tn rndest Destinationregister x 1.4

src Sourceregisterx 1.4phase1x x 1.4phase2

Whenusingr(n)asasourceregister,thefirstthreecomponents(XYZ)musthavebeeninitializedinthepreviousphaseoftheshader.


Remarks

Thisinstructionsamplesthetextureinthetexturestageassociatedwiththedestinationregisternumber.Thetextureissampledusingtexturecoordinatedatafromthesourceregister.

ThesyntaxforthetexldandtexcrdinstructionsexposesupportforaprojectivedividewithaTextureRegisterModifier.Forpixelshaderversion1.4,theD3DTTFF_PROJECTEDtexturetransformflagsisalwaysignored.

Rulesforusingtexld:

1. Thesame.xyzor.xywmodifiermustbeappliedtoeveryreadofanindividualt(n)registerwithinbothtexcrdortexldinstructions.If.xywis

beingusedont(n)registerread(s),thiscanbemixedwithotherread(s)ofthesamet(n)registerusing.xyw_dw.

2. The_dzsourcemodifierisonlyvalidontexldwithr(n)sourceregister(thusphase2only).

3. The_dzsourcemodifiermaybeusednomorethantwotimespershader.

Examples

Thetexldinstructionofferssomecontroloverwhichcomponentsofthesourcetexturecoordinatedataareused.Thecompletesetofallowedsyntaxfortexldfollows,andincludesallvalidsourceregistermodifiers,selectors,andwritemaskcombinations.

texldr(m),t(n).xyz

//Usesxyzfromt(n)tosample1-D,2-D,or3-Dtexture.

texldr(m),t(n)

//Sameasprevious.

texldr(m),t(n).xyw

//Usesxyw(skippingz)fromt(n)tosample1-D,2-Dor3-Dtexture.

texldr(m),t(n)_dw.xyw

//Samples1-Dor2-Dtextureatx/w,y/wfromt(n).Theresult

//isundefinedforacube-maplookup.

texldr(m),r(n).xyz

//Samples1-D,2-D,or3-Dtextureatxyzfromr(m).

//Thisispossibleinthesecondphaseoftheshader.

texldr(m),r(n)

//Sameasprevious.

texldr(m),r(n)_dz.xyz

//Samples1-Dor2-Dtextureatx/z,y/zfromr(m).

//Possibleonlyinsecondphase.

//Theresultisundefinedforacube-maplookup.

texldr(n),r(n)_dz

//Sameasprevious.


texm3x2depthCalculatethedepthvaluetobeusedindepthtestingforthispixel.

texm3x2depthdest,src

Registers


Versionvn cn tn rndest Destinationregister x 1.3src Sourceregister x 1.3


Remarks

Thisinstructionmustbeusedwiththetexm3x2padinstruction.

Whenusingthesetwoinstructions,textureregistersmustusethefollowingsequence.

text(n)//Definetnasastandard3-vector.(tnmustbe

//definedinsomewaybeforeitisused.

texm3x2padt(m),t(n)//Wherem>n

//Calculatezvalue.

texm3x2deptht(m+1),t(n)//Calculatewvalue;usebothzandwto

//finddepth.

Thedepthcalculationisdoneafterusingadotproductoperationtofindzandw.Hereismoredetailabouthowthedepthcalculationisaccomplished.

//Thetexm3x2padinstructioncalculatesz.

z=TextureCoordinates(stagem)UVW•t(n)RGB

//Thetexm3x2depthinstructioncalculatesw.

w=TextureCoordinates(stagem+1)UVW•t(n)RGB

//Calculatedepthandstoretheresultint(m+1).

if(w==0)

t(m+1)=1.0

else

t(m+1)=z/w

Thecalculateddepthistaggedtobeusedinthedepthtestforthepixel,replacingtheexistingdepthtestvalueforthepixel.

Besuretoclampz/wtobeintherangeof(0-1).Ifz/wisoutsidethisrange,theresultstoredinthedepthbufferwillbeundefined.

Afterexecutingtex3x2depth,registert(m+1)isnolongeravailableforuseintheshader.

Whenmultisampling,usingthisinstructioneliminatesmostofthebenefitofthehigherresolutiondepthbuffer.Becausethepixelshaderexecutesonceperpixel,thesingledepthvalueoutputbytexm3x2depth/texdepthwillbeusedforeachofthesub-pixeldepthcomparisontests.


texm3x2padPerformsthefirstrowmultiplicationofatwo-rowmatrixmultiply.Thisinstructionmustbecombinedwitheithertexm3x2texortexm3x2depth.Refertoeitheroftheseinstructionsfordetailsonusingtexm3x2pad.

texm3x2paddest,src

Registers




Remarks

Thisinstructioncannotbeusedbyitself.


texm3x2texPerformsthefinalrowofa3×2matrixmultiplyandusestheresulttodoatexturelookup.texm3x2texmustbeusedinconjunctionwiththetexm3x2padinstruction.

texm3x2texdest,src

Registers




Remarks

Theinstructionisusedasoneoftwoinstructionsrepresentinga3×2matrixmultiplyoperation.Thisinstructionmustbeusedwiththetexm3x2pad.

Whenusingthesetwoinstructions,textureregistersmustusethefollowingsequence.

text(n)//Definetnasastandard3-vector(tnmust

//bedefinedinsomewaybeforeitisused).

texm3x2padt(m),t(n)//wherem>n

//Performfirstrowofmatrixmultiply.

texm3x2text(m+1),t(n)//Performsecondrowofmatrixmultiply

//toget(u,v)tosampletexture

//associatedwithstagem+1.

Hereismoredetailabouthowthe3×2multiplyisaccomplished.

//Thetexm3x2padinstructionperformsthefirstrowofthemultiplytofindu

u'=t(n)RGB•TextureCoordinates(stagem)UVW

//Thetexm3x2texinstructionperformsthesecondrowofthemultiplytofindv

v'=t(n)RGB•TextureCoordinates(stagem+1)UVW

//Thetexm3x2texinstructionsamplesthetextureonstage(m+1)with(u

//storestheresultint(m+1).

t(m+1)RGB=TextureSample(stagem+1)RGBusing(u',v')ascoordinates.

Example

//Hereisanexampleshaderwiththetexturemapsand


ps.1.0

text0//Bindtextureinstage0toregistert0.

texm3x2padt1,t0//Firstrowofmatrixmultiply.

texm3x2text2,t0//Secondrowofmatrixmultiplytoget(u,v)

//withwhichtosampletextureinstage2.

movr0,t2//Outputresult.

//Thisexamplerequiresthefollowingtexturesinthefollowingtexturestages.

//

//Stage0takesamapwith(x,y,z)perturbationdata.

//

//Stage1holdstexturecoordinates.Notextureisrequiredinthetexturestage.

//

//Stage2holdsbothtexturecoordinatesaswellasa2-Dtexturesetat

//thattexturestage.


texm3x3Performsa3×3matrixmultiplywhenusedinconjunctionwithtwotexm3x3padinstructions.

texm3x3dest,src

Registers



Remarks

Thisinstructionisthesameasthetexm3x3texinstruction,withoutthetexturelookup.

Thisinstructionisusedasthefinalofthreeinstructionsrepresentinga3×3matrixmultiplyoperation.The3×3matrixiscomprisedofthetexturecoordinatesofthethirdtexturestage,andbythetwoprecedingtexturestages.Anytextureassignedtoanyofthethreetexturestagesisignored.

Thisinstructionmustbeusedwithtwotexm3x3padinstructions.Textureregistersmustfollowthefollowingsequence.





texm3x3padt(m+1),t(n)//Performsecondrowofmatrixmultiply.

texm3x3t(m+2),t(n)//Performthirdrowofmatrixmultiplytogeta

//3-vectorresult.


//Thefirsttexm3x3padinstructionperformsthefirstrowofthemultiply

//tofindu'.


//Thesecondtexm3x3padinstructionperformsthesecondrowofthemultiply

//tofindv'.

v'=TextureCoordinates(stagem+1)UVW•t(n)RGB

//Thetexm3x3texinstructionperformsthethirdrowofthemultiply

//tofindw'.

w'=TextureCoordinates(stagem+2)UVW•t(n)RGB

//Placetheresultofthematrixmultiplyinthedestinationregister.

t(m+2)RGBA=(u',v',w',1)


texm3x3padPerformsthefirstorsecondrowmultiplyofathree-rowmatrixmultiply.Thisinstructionmustbeusedincombinationwithtexm3x3,texm3x3spec,texm3x3vspec,ortexm3x3tex.

texm3x3paddest,src

Registers




Remarks

Thisinstructioncannotbeusedbyitself.


texm3x3texPerformsa3×3matrixmultiplyandusestheresulttodoatexturelookup.texm3x3texmustbeusedwithtwotexm3x3padinstructions.

texm3x3texdest,src




Remarks

Thisinstructionisusedasthefinalofthreeinstructionsrepresentinga3×3matrixmultiplyoperation,followedbyatexturelookup.The3×3matrixiscomprisedofthetexturecoordinatesofthethirdtexturestageandthetwoprecedingtexturestages.Theresultingthree-componentvector(u,v,w)isusedtosamplethetextureinstage3.Anytextureassignedtotheprecedingtwotexturestagesisignored.The3×3matrixmultiplyistypicallyusefulfororientinganormalvectortothecorrecttangentspaceforthesurfacebeingrendered.

Thisinstructionmustbeusedwithtwotexm3x3padinstructions.Textureregistersmustusethefollowingsequence.






texm3x3text(m+2),t(n)//Performthirdrowofmatrixmultiplytogeta

//3-vectorwithwhichtosampletexture

//associatedwithtexturestagem+2.



//tofindu'.



//tofindv'.


//Thetexm3x3specinstructionperformsthethirdrowofthemultiply

//tofindw'.


//Lastly,thetexm3x3texinstructionsamplest(m+2)with(u',v',w')

//andstorestheresultint(m+2).

t(m+2)RGBA=TextureSample(stagem+2)RGBAusing(u',v',w')ascoordinates.

Example



ps.1.0



texm3x3padt2,t0//Secondrowofmatrixmultiply.

texm3x3text3,t0//Thirdrowofmatrixmultiplytogeta

//3-vectorwithwhichtosampletextureatstage3

movr0,t3//outputresult.

//Thisexamplerequiresthefollowingtexturestagesetup.

//

//Stage0isassignedatexturemapwithnormaldata.Thisisoften

//referredtoasabumpmap.Thedatais(XYZ)normalsfor

//eachtexel.Texturecoordinateset0defineshowtosamplethis

//normalmap.

//

//Texturecoordinateset1isassignedtorow1ofthe3×3matrix.

//Anytextureassignedtostage1isignored.

//


//Anytextureassignedtostage2isignored.

//


//Avolumeorcubetextureshouldbesettostage3forlookupbythe

//transformed3-Dvector.

//


texm3x3specPerformsa3×3matrixmultiplyandusestheresulttoperformatexturelookup.Thiscanbeusedforspecularreflectionandenvironmentmapping.texm3x3specmustbeusedinconjunctionwithtwotexm3x3padinstructions.

texm3x3specdest,src0,src1,src2

Registers


Versionvn cn tn rndest Destinationregister x 1.0,1.1,1.2,1.3src0,src1

Sourceregisterx 1.0,1.1,1.2,1.3

src2 x 1.0,1.1,1.2,1.3


Remarks

Thisinstructionperformsthefinalrowofa3×3matrixmultiply,usestheresultingvectorasanormalvectortoreflectaneye-rayvector,andthenusesthereflectedvectortoperformatexturelookup.Theshaderreadstheeye-rayvectorfromaconstantregister.The3×3matrixmultiplyistypicallyusefulfororientinganormalvectortothecorrecttangentspaceforthesurfacebeingrendered.

The3×3matrixiscomprisedofthetexturecoordinatesofthethirdtexturestageandthetwoprecedingtexturestages.Theresultingpostreflectionvector(u,v,w)isusedtosamplethetextureonthefinaltexturestage.Anytextureassignedtotheprecedingtwotexturestagesisignored.

Thisinstructionmustbeusedwithtwotexm3x3padinstructions.Textureregistersmustusethefollowingsequence.






texm3x3spect(m+2),t(n),c0//Performthirdrowofmatrixmultiply.

//Thendoatexturelookuponthetexture



//tofindu'.



//tofindv'.



//tofindw'.


//Thetexm3x3specinstructionthendoesareflectioncalculation.

(u'',v'',w'')=2*[(N•E)/(N•N)]*N-E

//wherethenormalNisgivenby

//N=(u',v',w')

//andtheeye-rayvectorEisgivenbytheconstantregister

//E=c#(Anyconstantregister--c0,c1,c2,etc.--canbeused.)

//Lastly,thetexm3x3specinstructionsamplest(m+2)with(u'',v'',w


t(m+2)RGBA=TextureSample(stagem+2)RGBAusing(u'',v'',w'')ascoordinates.

Example

//Hereisanexampleshaderwiththetexturemapsand


ps.1.0

text0//Bindtextureinstage0toregistert0(tnmust




texm3x3spect3,t0,c#//Thirdrowofmatrixmultiplytogeta3-vector.

//Reflect3-vectorbytheeye-rayvectorinc#.

//Usereflectedvectortolookuptexturein

//stage3

movr0,t3//outputresult


//



//eachtexel.Texturecoordinatesatstagendefineswheretosamplethis

//normalmap.

//

//Texturecoordinatesetmisassignedtorow1ofthe3×3matrix.

//Anytextureassignedtostagemisignored.

//

//Texturecoordinatesetm+1isassignedtorow2ofthe3×3matrix.

//Anytextureassignedtostagem+1isignored.

//


//Stagem+2isassignedavolumeorcubetexturemap.Thetextureprovides

//colordata(RGBA).

//

//Theeye-rayvectorEisgivenbya

//constantregisterE=c#.


texm3x3vspecPerformsa3×3matrixmultiplyandusestheresulttoperformatexturelookup.Thiscanbeusedforspecularreflectionandenvironmentmappingwheretheeye-rayvectorisnotconstant.texm3x3vspecmustbeusedinconjunctionwithtwotexm3x3padinstructions.

Iftheeye-rayvectorisconstant,thetexm3x3specinstructionwillperformthesamematrixmultiplyandtexturelookup.

texm3x3vspecdest,src

Registers




Remarks

Thisinstructionperformsthefinalrowofa3×3matrixmultiplyoperation,interpretstheresultingvectorasanormalvectortoreflectaneye-rayvector,andthenusesthereflectedvectorasatextureaddressforatexturelookup.Itworksjustliketexm3x3spec,exceptthattheeye-rayvectoristakenfromthefourthcomponentofthetexturecoordinates.The3×3matrixmultiplyistypicallyusefulfororientinganormalvectortothecorrecttangentspaceforthesurfacebeingrendered.

The3×3matrixiscomprisedofthetexturecoordinatesofthethirdtexturestageandthetwoprecedingtexturestages.Theresultingpost-reflectionvector(UVW)isusedtosamplethetextureinstage3.Anytextureassignedtotheprecedingtwotexturestagesisignored.

Thisinstructionmustbeusedwiththetexm3x3padinstruction.Textureregistersmustusethefollowingsequence.






texm3x3vspect(m+2),t(n)//Performthirdrowofmatrixmultiply.

//Thendoatexturelookuponthetexture



//tofindu'.



//tofindv'.



//tofindw'.


//Thetexm3x3vspecinstructionalsodoesareflectioncalculation.

(u'',v'',w'')=2*[(N•E)/(N•N)]*N-E

//wherethenormalNisgivenby

//N=(u',v',w')

//andtheeye-rayvectorEisgivenby

//E=(TextureCoordinates(stagem)Q,TextureCoordinates(stagem+1)Q,TextureCoordinates(stagem+2)

//Lastly,thetexm3x3vspecinstructionsamplest(m+2)with(u'',v'',w


t(m+2)RGBA=TextureSample(stagem+2)RGBAusing(u'',v'',w'')ascoordinates.

Example



ps.1.0




texm3x3vspect3,t0//Thirdrowofmatrixmultiplytogeta3-vector.

//Reflect3-vectorbytheeye-rayvector.

//Usereflectedvectortodoatexturelookup

//atstage3.

movr0,t3//Outputresult.


//



//eachtexel.Texturecoordinatesatstagendefineshowtosamplethis

//normalmap.

//

//Texturecoordinatesetmisassignedtorow1ofthe3×3matrix.

//Anytextureassignedtostagemisignored.

//


//Anytextureassignedtostagem+1isignored.

//


//Stagem+2isassignedavolumeorcubetexturemap.Thetextureprovides

//colordata(RGBA).

//

//Theeye-rayvectorEispassedintotheinstructioninthefourth

//component(q)ofthetexturecoordinatedataatstagesm,m+1,andm+2.


texreg2arInterpretsthealphaandredcolorcomponentsofthesourceregisterastextureaddressdata(u,v)tosamplethetextureatthestagecorrespondingtothedestinationregisternumber.Theresultisstoredinthedestinationregister.

texreg2ardest,src

Registers




Remarks

Thisinstructionisusefulforcolor-spaceremappingoperations.

//Hereisanexampleofthesequencetheinstructionfollows.

text(n)

texreg2art(m),t(n)wherem>n

//Hereismoredetailabouthowtheremappingisaccomplished.

//Thefirstinstructionloadsthetexturecolor(RGBA)intoregistertn.

textn

//Thesecondinstructionremapsthecolor.

t(m)RGBA=TextureSample(stagem)RGBAusingt(n)ARascoordinates.

Forthisinstruction,thesourceregistermustuseunsigneddata.Useofsignedormixeddatainthesourceregisterwillproduceundefinedresults.Formoreinformation,seeD3DFORMAT.


texreg2gbInterpretsthegreenandbluecolorcomponentsofthesourceregisterastextureaddressdatatosamplethetextureatthestagecorrespondingtothedestinationregisternumber.

texreg2gbdest,src

Registers




Remarks

Thisinstructionisusefulforcolor-spaceremappingoperations.


text(n)

texreg2gbt(m),t(n)wherem>n

//Hereismoredetailabouthowtheremappingisaccomplished.


textn


t(m)RGBA=TextureSample(stagem)RGBAusingt(n)GBascoordinates.

Forthisinstruction,thesourceregistermustuseunsigneddata.Useofsignedormixeddatainthesourceregisterwillproduceundefinedresults.Formoreinformation,seeD3DFORMAT.


texreg2rgbInterpretsthered,green,andblue(RGB)colorcomponentsofthesourceregisterastextureaddressdatainordertosamplethetextureatthestagecorrespondingtothedestinationregisternumber.Theresultisstoredinthedestinationregister.

texreg2rgbdest,src

Registers



Remarks

Thisinstructionisusefulforcolor-spaceremappingoperations.Itsupportstwo-dimensional(2-D)andthree-dimensional(3-D)coordinates.Itcanbeusedjustlikethetexreg2arortexreg2gbtoremap2-Ddata.However,thisinstructionalsosupports3-Ddatasoitcanbeusedwithcubemapsand3-Dvolumetextures.


text(n)

texreg2rgbt(m),t(n)wherem>n

Hereismoredetailabouthowtheremappingisaccomplished.


textn


t(m)RGB=TextureSample(stagem)RGBusingt(n)RGBascoordinates.


IDirect3DDevice8::SetPixelShaderConstantSetsthevaluesinthepixelconstantarray.

HRESULTSetPixelShaderConstant(

DWORDRegister,

CONSTvoid*pConstantData,

DWORDConstantCount

);

Parameters

Register[in]Registeraddressatwhichtostartloadingdataintothepixelconstantarray.

pConstantData[in]Pointertothedatablockholdingthevaluestoloadintothepixelconstantarray.Thesizeofthedatablockis(ConstantCount*4*sizeof(float)).

ConstantCount[in]Numberofconstantstoloadintothepixelconstantarray.Eachconstantiscomprisedoffourfloating-pointvalues.

ReturnValues

Ifthemethodsucceeds,thereturnvalueisD3D_OK.

Ifthemethodfails,thereturnvaluecanbeD3DERR_INVALIDCALL.

Remarks

Thisisthemethodusedtoloadtheconstantregistersofthepixelshaderassembler.

Requirements

Header:DeclaredinD3d8.h.ImportLibrary:UseD3d8.lib.

SeeAlso

IDirect3DDevice8::GetPixelShaderConstant


IDirect3DDevice8::CreatePixelShaderCreatesapixelshader.

HRESULTCreatePixelShader(

CONSTDWORD*pFunction,

DWORD*pHandle

);

Parameters

pFunction[in]Pointertothepixelshaderfunctiontokenarray,specifyingtheblendingoperations.ThisvaluecannotbeNULL.

pHandle[out,retval]Pointertothereturnedpixelshaderhandle.

ReturnValues


Ifthemethodfails,thereturnvaluecanbeoneofthefollowingvalues.

D3DERR_INVALIDCALLD3DERR_OUTOFVIDEOMEMORYE_OUTOFMEMORY

Requirements


SeeAlso

IDirect3DDevice8::DeletePixelShader,D3DXAssembleShader,D3DXAssembleShaderFromFile


D3DXAssembleShaderAssemblesanASCIIdescriptionofashaderintobinaryform,wheretheshadersourceisinmemory.

HRESULTD3DXAssembleShader(

LPCVOIDpSrcData,

UINTSrcDataLen,

DWORDFlags,

LPD3DXBUFFER*ppConstants,

LPD3DXBUFFER*ppCompiledShader,

LPD3DXBUFFER*ppCompilationErrors

);

Parameters

pSrcData[in]Pointertothesourcecode.

SrcDataLen[in]Sizeofthesourcecode,inbytes.

Flags[in]AcombinationoftheD3DXASMflags,specifyingassemblyoptions.

ppConstants[out]ReturnsapointertoanID3DXBufferinterface,representingthereturnedconstantdeclarations.Theseconstantsarereturnedasavertexshaderdeclarationfragment.Itisuptotheapplicationtoinsertthecontentsofthisbufferintotheirdeclaration.Forpixelshadersthisparameterismeaninglessbecauseconstantdeclarationsareincludedintheassembledshader.ThisparameterisignoredifitisNULL.

ppCompiledShader[out]ReturnsapointertoanID3DXBufferinterface,representingthereturnedcompiledobjectcode.ThisparameterisignoredifitisNULL.

ppCompilationErrors[out]ReturnsapointertoanID3DXBufferinterface,representingthereturnedASCIIerrormessages.ThisparameterisignoredifitisNULL.

ReturnValues



D3DERR_INVALIDCALLD3DXERR_INVALIDDATAE_OUTOFMEMORY

Requirements

Header:DeclaredinD3dx8core.h.ImportLibrary:UseD3dx8.lib.


D3DCAPS8RepresentsthecapabilitiesofthehardwareexposedthroughtheMicrosoft®Direct3D®object.

typedefstruct_D3DCAPS8{

D3DDEVTYPEDeviceType;

UINTAdapterOrdinal;

DWORDCaps;

DWORDCaps2;

DWORDCaps3;

DWORDPresentationIntervals;

DWORDCursorCaps;

DWORDDevCaps;

DWORDPrimitiveMiscCaps;

DWORDRasterCaps;

DWORDZCmpCaps;

DWORDSrcBlendCaps;

DWORDDestBlendCaps;

DWORDAlphaCmpCaps;

DWORDShadeCaps;

DWORDTextureCaps;

DWORDTextureFilterCaps;

DWORDCubeTextureFilterCaps;

DWORDVolumeTextureFilterCaps;

DWORDTextureAddressCaps;

DWORDVolumeTextureAddressCaps;

DWORDLineCaps;

DWORDMaxTextureWidth,MaxTextureHeight;

DWORDMaxVolumeExtent;

DWORDMaxTextureRepeat;

DWORDMaxTextureAspectRatio;

DWORDMaxAnisotropy;

floatMaxVertexW;

floatGuardBandLeft;

floatGuardBandTop;

floatGuardBandRight;

floatGuardBandBottom;

floatExtentsAdjust;

DWORDStencilCaps;

DWORDFVFCaps;

DWORDTextureOpCaps;

DWORDMaxTextureBlendStages;

DWORDMaxSimultaneousTextures;

DWORDVertexProcessingCaps;

DWORDMaxActiveLights;

DWORDMaxUserClipPlanes;

DWORDMaxVertexBlendMatrices;

DWORDMaxVertexBlendMatrixIndex;

floatMaxPointSize;

DWORDMaxPrimitiveCount;

DWORDMaxVertexIndex;

DWORDMaxStreams;

DWORDMaxStreamStride;

DWORDVertexShaderVersion;

DWORDMaxVertexShaderConst;

DWORDPixelShaderVersion;

floatMaxPixelShaderValue;

}D3DCAPS8;

Members

DeviceTypeMemberoftheD3DDEVTYPEenumeratedtype,whichidentifieswhattypeofresourcesareusedforprocessingvertices.

AdapterOrdinalAdapteronwhichthisDirect3DDeviceobjectwascreated.ThisordinalisvalidonlytopasstomethodsoftheIDirect3D8interfacethatcreatedthisDirect3DDeviceobject.TheIDirect3D8interfacecanalwaysberetrievedbycallingIDirect3DDevice8::GetDirect3D.

CapsThefollowingdriver-specificcapability.D3DCAPS_READ_SCANLINE

Displayhardwareiscapableofreturningthecurrentscanline.Caps2

Thefollowingdriver-specificcapabilities.D3DCAPS2_CANCALIBRATEGAMMA

Thesystemhasacalibratorinstalledthatcanautomaticallyadjustthegammarampsothattheresultisidenticalonallsystemsthathaveacalibrator.Toinvokethecalibratorwhensettingnewgammalevels,usetheD3DSGR_CALIBRATEflagwhencallingtheIDirect3DDevice8::SetGammaRampmethod.Calibratinggammarampsincurssomeprocessingoverheadandshouldnotbeusedfrequently.

D3DCAPS2_CANRENDERWINDOWEDThedriveriscapableofrenderinginwindowedmode.

D3DCAPS2_CANMANAGERESOURCEThedriveriscapableofmanagingresources.Onsuchdrivers,D3DPOOL_MANAGEDresourceswillbemanagedbythedriver.TohaveDirect3DoverridethedriversothatDirect3Dmanagesresources,usetheD3DCREATE_DISABLE_DRIVER_MANAGEMENTflagwhencallingIDirect3D8::CreateDevice

D3DCAPS2_DYNAMICTEXTURESThedriversupportsdynamictextures.

D3DCAPS2_FULLSCREENGAMMAThedriversupportsdynamicgammarampadjustmentinfull-screenmode.

D3DCAPS2_NO2DDURING3DSCENEWhentheD3DCAPS2_NO2DDURING3DSCENEcapabilityissetbythedriver,itmeansthat2-DoperationscannotbeperformedbetweencallstoIDirect3DDevice8::BeginSceneandIDirect3DDevice8::EndScene.

Typically,thiscapabilityissetbyhardwarethatpartitionsthesceneandthenrenderseachpartitioninsequence.Thepartitioningisperformedinthedriver,andthehardwarecontainsasmallcoloranddepthbufferthatcorrespondstothesizeoftheimagepartition.Typically,onthistypeofrenderinghardware,onceeachpartoftheimageisrendered,thedatainthecolorbuffersarewrittentovideomemoryandthecontentsofthedepthbufferarediscarded.Also,notethat3-DrenderingdoesnotstartuntilEndSceneisencountered.Next,thesceneisprocessedinregions.Therefore,theprocessingordercannotbeguaranteed.Forexample,thefirstregionthatisprocessed,typicallytheupperleftcornerofthewindow,mightincludethelast

triangleintheframe.Thisdiffersfrommoretraditionalgraphicssystemsinwhicheachcommandisprocessedsequentiallyintheorderthatitwassent.The2-Doperationsareimpliedtooccuratsomefixedpointintheprocessing.InthesystemsthatsetD3DCAPS2_NO2DDURING3DSCENE,theprocessingorderisnotguaranteed.Therefore,thedisplayadaptermightdiscard2-Doperationsthatareencounteredduring3-Drendering.

Ingeneral,itisrecommendedthat2-DoperationsbeperformedoutsideofaBeginSceneandEndScenepair.If2-DoperationsaretobeperformedbetweenaBeginSceneandEndScenepair,thenitisnecessarytochecktheD3DCAPS2_NO2DDURING3DSCENEcapability.Ifitisset,theapplicationmustexpectthatany2-DoperationthatoccursbetweenBeginSceneandEndScenewillbediscarded.FormoreinformationonwritingapplicationsforsystemsthatsetD3DCAPS2_NO2DDURING3DSCENE,seeRemarks.

D3DCAPS2_RESERVEDReserved;notused.

Caps3Thefollowingdriver-specificcapabilities.D3DCAPS3_ALPHA_FULLSCREEN_FLIP_OR_DISCARD

ThedevicewillworkasexpectedwiththeD3DRS_ALPHABLENDENABLErenderstatewhenafull-screenapplicationusesD3DSWAPEFFECT_FLIPorD3DRS_SWAPEFFECT_DISCARD.D3DRS_ALPHABLENDENABLEworksasexpectedwhenusingD3DSWAPEFFECT_COPYandD3DSWAPEFFECT_COPYSYNC.

D3DCAPS3_RESERVEDReserved;notused.

PresentationIntervalsBitmaskofvaluesrepresentingwhatpresentationswapintervalsareavailable.D3DPRESENT_INTERVAL_IMMEDIATE

Thedriversupportsanimmediatepresentationswapinterval.D3DPRESENT_INTERVAL_ONE

Thedriversupportsapresentationswapintervalofeveryscreenrefresh.

D3DPRESENT_INTERVAL_TWO

Thedriversupportsapresentationswapintervalofeverysecondscreenrefresh.

D3DPRESENT_INTERVAL_THREEThedriversupportsapresentationswapintervalofeverythirdscreenrefresh.

D3DPRESENT_INTERVAL_FOURThedriversupportsapresentationswapintervalofeveryfourthscreenrefresh.

CursorCapsBitmaskindicatingwhathardwaresupportisavailableforcursors.D3DCURSORCAPS_COLOR

Afull-colorcursorissupportedinhardware.Specifically,thisflagindicatesthatthedriversupportsatleastahardwarecolorcursorinhigh-resolutionmodes(withscanlinesgreaterthanorequalto400).

D3DCURSORCAPS_LOWRESAfull-colorcursorissupportedinhardware.Specifically,thisflagindicatesthatthedriversupportsahardwarecolorcursorinbothhigh-resolutionandlow-resolutionmodes(withscanlineslessthan400).

Direct3Ddoesnotdefinealpha-blendingcursorcapabilities.

DevCapsFlagsidentifyingthecapabilitiesofthedevice.D3DDEVCAPS_CANBLTSYSTONONLOCAL

Devicesupportsblitsfromsystem-memorytexturestononlocalvideo-memorytextures.

D3DDEVCAPS_CANRENDERAFTERFLIPDevicecanqueuerenderingcommandsafterapageflip.Applicationsdonotchangetheirbehaviorifthisflagisset;thiscapabilitysimplymeansthatthedeviceisrelativelyfast.

D3DDEVCAPS_DRAWPRIMTLVERTEXDeviceexportsaDrawPrimitive-awarehardwareabstractionlayer(HAL).

D3DDEVCAPS_EXECUTESYSTEMMEMORYDevicecanuseexecutebuffersfromsystemmemory.

D3DDEVCAPS_EXECUTEVIDEOMEMORYDevicecanuseexecutebuffersfromvideomemory.

D3DDEVCAPS_HWRASTERIZATIONDevicehashardwareaccelerationforscenerasterization.

D3DDEVCAPS_HWTRANSFORMANDLIGHTDevicecansupporttransformationandlightinginhardware.

D3DDEVCAPS_NPATCHESDevicesupportsN-patches.

D3DDEVCAPS_PUREDEVICEDevicecansupportrasterization,transform,lighting,andshadinginhardware.

D3DDEVCAPS_QUINTICRTPATCHESDevicesupportsquinticBéziercurvesandB-splines.

D3DDEVCAPS_RTPATCHESDevicesupportsrectangularandtriangularpatches.

D3DDEVCAPS_RTPATCHHANDLEZEROWhenthisdevicecapabilityisset,thehardwarearchitecturedoesnotrequirecachingofanyinformation,anduncachedpatches(handlezero)willbedrawnasefficientlyascachedones.NotethatsettingD3DDEVCAPS_RTPATCHHANDLEZEROdoesnotmeanthatapatchwithhandlezerocanbedrawn.Ahandle-zeropatchcanalwaysbedrawnwhetherthiscapissetornot.

D3DDEVCAPS_SEPARATETEXTUREMEMORIESDeviceistexturingfromseparatememorypools.

D3DDEVCAPS_TEXTURENONLOCALVIDMEMDevicecanretrievetexturesfromnon-localvideomemory.

D3DDEVCAPS_TEXTURESYSTEMMEMORYDevicecanretrievetexturesfromsystemmemory.

D3DDEVCAPS_TEXTUREVIDEOMEMORYDevicecanretrievetexturesfromdevicememory.

D3DDEVCAPS_TLVERTEXSYSTEMMEMORYDevicecanusebuffersfromsystemmemoryfortransformedandlitvertices.

D3DDEVCAPS_TLVERTEXVIDEOMEMORYDevicecanusebuffersfromvideomemoryfortransformedandlitvertices.

PrimitiveMiscCapsGeneralcapabilitiesforthisprimitive.Thismembercanbeoneormoreofthefollowingflags.D3DPMISCCAPS_BLENDOP

Devicesupportsthealpha-blendingoperationsdefinedintheD3DBLENDOPenumeratedtype.

D3DPMISCCAPS_CLIPPLANESCALEDPOINTS

Devicecorrectlyclipsscaledpointsofsizegreaterthan1.0touser-definedclippingplanes.

D3DPMISCCAPS_CLIPTLVERTSDeviceclipspost-transformedvertexprimitives.

D3DPMISCCAPS_COLORWRITEENABLEDevicesupportsper-channelwritesfortherendertargetcolorbufferthroughtheD3DRS_COLORWRITEENABLEstate.

D3DPMISCCAPS_CULLCCWThedriversupportscounterclockwisecullingthroughtheD3DRS_CULLMODEstate.(Thisappliesonlytotriangleprimitives.)ThisflagcorrespondstotheD3DCULL_CCWmemberoftheD3DCULLenumeratedtype.

D3DPMISCCAPS_CULLCWThedriversupportsclockwisetrianglecullingthroughtheD3DRS_CULLMODEstate.(Thisappliesonlytotriangleprimitives.)ThisflagcorrespondstotheD3DCULL_CWmemberoftheD3DCULLenumeratedtype.

D3DPMISCCAPS_CULLNONEThedriverdoesnotperformtriangleculling.ThiscorrespondstotheD3DCULL_NONEmemberoftheD3DCULLenumeratedtype.

D3DPMISCCAPS_LINEPATTERNREPThedrivercanhandlevaluesotherthan1inthewRepeatFactormemberoftheD3DLINEPATTERNstructure.(Thisappliesonlytoline-drawingprimitives.)

D3DPMISCCAPS_MASKZDevicecanenableanddisablemodificationofthedepthbufferonpixeloperations.

D3DPMISCCAPS_TSSARGTEMPDevicesupportsD3DTA_TEMPfortemporaryregister.

RasterCapsInformationonraster-drawingcapabilities.Thismembercanbeoneormoreofthefollowingflags.D3DPRASTERCAPS_ANISOTROPY

Devicesupportsanisotropicfiltering.D3DPRASTERCAPS_ANTIALIASEDGES

Devicecanantialiaslinesformingtheconvexoutlineofobjects.Formoreinformation,seeD3DRS_EDGEANTIALIAS.

D3DPRASTERCAPS_COLORPERSPECTIVEDeviceiteratescolorsperspectivecorrect.

D3DPRASTERCAPS_DITHERDevicecandithertoimprovecolorresolution.

D3DPRASTERCAPS_FOGRANGEDevicesupportsrange-basedfog.Inrange-basedfog,thedistanceofanobjectfromtheviewerisusedtocomputefogeffects,notthedepthoftheobject(thatis,thez-coordinate)inthescene.

D3DPRASTERCAPS_FOGTABLEDevicecalculatesthefogvaluebyreferringtoalookuptablecontainingfogvaluesthatareindexedtothedepthofagivenpixel.

D3DPRASTERCAPS_FOGVERTEXDevicecalculatesthefogvalueduringthelightingoperation,andinterpolatesthefogvalueduringrasterization.

D3DPRASTERCAPS_MIPMAPLODBIASDevicesupportslevel-of-detail(LOD)biasadjustments.Thesebiasadjustmentsenableanapplicationtomakeamipmapappearcrisperorlesssharpthanitnormallywould.FormoreinformationaboutLODbiasinmipmaps,seeD3DTSS_MIPMAPLODBIAS.

D3DPRASTERCAPS_PATThedrivercanperformpatterneddrawinglinesorfillswithD3DRS_LINEPATTERNfortheprimitivebeingqueried.

D3DPRASTERCAPS_STRETCHBLTMULTISAMPLEDeviceprovideslimitedmultisamplesupportthroughastretch-bltimplementation.Whenthiscapabilityisset,D3DRS_MULTISAMPLEANTIALIAScannotbeturnedonandoffinthemiddleofascene.Multisamplemaskingcannotbeperformedifthisflagisset.

D3DPRASTERCAPS_WBUFFERDevicesupportsdepthbufferingusingw.

D3DPRASTERCAPS_WFOGDevicesupportsw-basedfog.W-basedfogisusedwhenaperspectiveprojectionmatrixisspecified,butaffineprojectionsstillusez-basedfog.Thesystemconsidersaprojectionmatrixthatcontainsanonzerovalueinthe[3][4]elementtobeaperspectiveprojectionmatrix.

D3DPRASTERCAPS_ZBIASDevicesupportsz-biasvalues.Theseareintegervaluesassignedtopolygonsthatallowphysicallycoplanarpolygonstoappearseparate.Formoreinformation,seeD3DRS_ZBIAS.

D3DPRASTERCAPS_ZBUFFERLESSHSRDevicecanperformhidden-surfaceremoval(HSR)withoutrequiring

theapplicationtosortpolygonsandwithoutrequiringtheallocationofadepthbuffer.Thisleavesmorevideomemoryfortextures.ThemethodusedtoperformHSRishardware-dependentandistransparenttotheapplication.

Z-bufferlessHSRisperformedifnodepth-buffersurfaceisassociatedwiththerendering-targetsurfaceandthedepth-buffercomparisontestisenabled(thatis,whenthestatevalueassociatedwiththeD3DRS_ZENABLEenumerationconstantissettoTRUE).

D3DPRASTERCAPS_ZFOGDevicesupportsz-basedfog.

D3DPRASTERCAPS_ZTESTDevicecanperformz-testoperations.Thiseffectivelyrendersaprimitiveandindicateswhetheranyzpixelshavebeenrendered.

ZCmpCapsZ-buffercomparisoncapabilities.Thismembercanbeoneormoreofthefollowingflags.D3DPCMPCAPS_ALWAYS

Alwayspasstheztest.D3DPCMPCAPS_EQUAL

Passtheztestifthenewzequalsthecurrentz.D3DPCMPCAPS_GREATER

Passtheztestifthenewzisgreaterthanthecurrentz.D3DPCMPCAPS_GREATEREQUAL

Passtheztestifthenewzisgreaterthanorequaltothecurrentz.D3DPCMPCAPS_LESS

Passtheztestifthenewzislessthanthecurrentz.D3DPCMPCAPS_LESSEQUAL

Passtheztestifthenewzislessthanorequaltothecurrentz.D3DPCMPCAPS_NEVER

Alwaysfailtheztest.D3DPCMPCAPS_NOTEQUAL

Passtheztestifthenewzdoesnotequalthecurrentz.SrcBlendCaps

Source-blendingcapabilities.Thismembercanbeoneormoreofthefollowingflags.(TheRGBAvaluesofthesourceanddestinationareindicatedbythesubscriptssandd.)D3DPBLENDCAPS_BOTHINVSRCALPHA

Sourceblendfactoris(1–As,1–As,1–As,1–As),anddestinationblendfactoris(As,As,As,As);thedestinationblendselectionisoverridden.

D3DPBLENDCAPS_BOTHSRCALPHAThedriversupportstheD3DBLEND_BOTHSRCALPHAblendmode.(Thisblendmodeisobsolete.Formoreinformation,seeD3DBLEND.)

D3DPBLENDCAPS_DESTALPHABlendfactoris(Ad,Ad,Ad,Ad).

D3DPBLENDCAPS_DESTCOLORBlendfactoris(Rd,Gd,Bd,Ad).

D3DPBLENDCAPS_INVDESTALPHABlendfactoris(1–Ad,1–Ad,1–Ad,1–Ad).

D3DPBLENDCAPS_INVDESTCOLORBlendfactoris(1–Rd,1–Gd,1–Bd,1–Ad).

D3DPBLENDCAPS_INVSRCALPHABlendfactoris(1–As,1–As,1–As,1–As).

D3DPBLENDCAPS_INVSRCCOLORBlendfactoris(1–Rd,1–Gd,1–Bd,1–Ad).

D3DPBLENDCAPS_ONEBlendfactoris(1,1,1,1).

D3DPBLENDCAPS_SRCALPHABlendfactoris(As,As,As,As).

D3DPBLENDCAPS_SRCALPHASATBlendfactoris(f,f,f,1);f=min(As,1-Ad).

D3DPBLENDCAPS_SRCCOLORBlendfactoris(Rs,Gs,Bs,As).

D3DPBLENDCAPS_ZEROBlendfactoris(0,0,0,0).

DestBlendCapsDestination-blendingcapabilities.ThismembercanbethesamecapabilitiesthataredefinedfortheSrcBlendCapsmember.

AlphaCmpCapsAlpha-testcomparisoncapabilities.ThismembercanincludethesamecapabilityflagsdefinedfortheZCmpCapsmember.IfthismembercontainsonlytheD3DPCMPCAPS_ALWAYScapabilityoronlytheD3DPCMPCAPS_NEVERcapability,thedriverdoesnotsupportalphatests.Otherwise,theflagsidentifytheindividualcomparisonsthatare

supportedforalphatesting.ShadeCaps

Shadingoperationscapabilities.Itisassumed,ingeneral,thatifadevicesupportsagivencommandatall,itsupportstheD3DSHADE_FLATmode(asspecifiedintheD3DSHADEMODEenumeratedtype).ThisflagspecifieswhetherthedrivercanalsosupportGouraudshadingandwhetheralphacolorcomponentsaresupported.Whenalphacomponentsarenotsupported,thealphavalueofcolorsgeneratedisimplicitly255.Thisisthemaximumpossiblealpha(thatis,thealphacomponentisatfullintensity).

Thecolor,specularhighlights,fog,andalphainterpolantsofatriangleeachhavecapabilityflagsthatanapplicationcanusetofindouthowtheyareimplementedbythedevicedriver.

Thismembercanbeoneormoreofthefollowingflags.

D3DPSHADECAPS_ALPHAGOURAUDBLENDDevicecansupportanalphacomponentforGouraud-blendedtransparency(theD3DSHADE_GOURAUDstatefortheD3DSHADEMODEenumeratedtype).Inthismode,thealphacolorcomponentofaprimitiveisprovidedatverticesandinterpolatedacrossaface,alongwiththeothercolorcomponents.

D3DPSHADECAPS_COLORGOURAUDRGBDevicesupportsGouraudshading.Inthismode,thered,green,andbluecomponentsforaprimitiveareprovidedatverticesandinterpolatedacrossaface.

D3DPSHADECAPS_FOGGOURAUDDevicesupportsGouraudshadingoffog.

D3DPSHADECAPS_SPECULARGOURAUDRGBDevicesupportsGouraudshadingofspecularhighlights.

TextureCapsMiscellaneoustexture-mappingcapabilities.Thismembercanbeoneormoreofthefollowingflags.D3DPTEXTURECAPS_ALPHA

Alphaintexturepixelsissupported.D3DPTEXTURECAPS_ALPHAPALETTE

Devicecandrawalphafromtexturepalettes.D3DPTEXTURECAPS_CUBEMAP

SupportscubetexturesD3DPTEXTURECAPS_CUBEMAP_POW2

Devicerequiresthatcubetexturemapshavedimensionsspecifiedaspowersof2.

D3DPTEXTURECAPS_MIPCUBEMAPDevicesupportsmipmappedcubetextures.

D3DPTEXTURECAPS_MIPMAPDevicesupportsmipmappedtextures.

D3DPTEXTURECAPS_MIPVOLUMEMAPDevicesupportsmipmappedvolumetextures.

D3DPTEXTURECAPS_NONPOW2CONDITIONALConditionallysupportstheuseoftextureswithdimensionsthatarenotpowersof2.Adevicethatexposesthiscapabilitycanusesuchatextureifallofthefollowingrequirementsaremet.ThetextureaddressingmodeforthetexturestageissettoD3DTADDRESS_CLAMP.Texturewrappingforthetexturestageisdisabled(D3DRS_WRAPnsetto0).Mipmappingisnotinuse(usemagnificationfilteronly).TextureformatsmustnotbeDXT1-5

Atexturethatisnotapoweroftwocannotbesetatastagethatwillbereadbasedonashadercomputation(suchasthebem,beml,ortexm3x3instructionsinpixelshadersversions1.0to1.3).Forexample,thesetexturescanbeusedtostorebumpsthatwillbefedintotexturereads,butnottheenvironmentmapsthatareusedintexbem,texbeml,ortexm3x3spec.Thismeansthatatexturewithdimensionsthatarenotpowersoftwocannotbeaddressedorsampledusingtexturecoordinatescomputedwithintheshader.Thistypeofoperationisknownasadependentreadandcannotbeperformedonthesekindsoftextures.

D3DPTEXTURECAPS_PERSPECTIVEPerspectivecorrectiontexturingissupported.

D3DPTEXTURECAPS_POW2Alltexturesmusthavewidthsandheightsspecifiedaspowersof2.Thisrequirementdoesnotapplytoeithercubetexturesorvolumetextures.

D3DPTEXTURECAPS_PROJECTEDSupportstheD3DTTFF_PROJECTEDtexturetransformationflag.

Whenapplied,thedevicedividestransformedtexturecoordinatesbythelasttexturecoordinate.Ifthiscapabilityispresent,thentheprojectivedivideoccursperpixel.Ifthiscapabilityisnotpresent,buttheprojectivedivideneedstooccuranyway,thenitisperformedonaper-vertexbasisbytheDirect3Druntime.

D3DPTEXTURECAPS_SQUAREONLYAlltexturesmustbesquare.

D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZETextureindicesarenotscaledbythetexturesizepriortointerpolation.

D3DPTEXTURECAPS_VOLUMEMAPDevicesupportsvolumetextures.

D3DPTEXTURECAPS_VOLUMEMAP_POW2Devicerequiresthatvolumetexturemapshavedimensionsspecifiedaspowersof2.

TextureFilterCapsTexture-filteringcapabilitiesforaDirect3DTextureobject.Per-stagefilteringcapabilitiesreflectwhichfilteringmodesaresupportedfortexturestageswhenperformingmultiple-textureblendingwiththeIDirect3DDevice8interface.Thismembercanbeanycombinationofthefollowingper-stagetexture-filteringflags.D3DPTFILTERCAPS_MAGFAFLATCUBIC

Devicesupportsper-stageflatcubicfilteringformagnifyingtextures.TheflatcubicmagnificationfilterisrepresentedbytheD3DTEXF_FLATCUBICmemberoftheD3DTEXTUREFILTERTYPEenumeratedtype.

D3DPTFILTERCAPS_MAGFANISOTROPICDevicesupportsper-stageanisotropicfilteringformagnifyingtextures.TheanisotropicmagnificationfilterisrepresentedbytheD3DTEXF_ANISOTROPICmemberoftheD3DTEXTUREFILTERTYPEenumeratedtype.

D3DPTFILTERCAPS_MAGFGAUSSIANCUBICDevicesupportstheper-stageGaussiancubicfilteringformagnifyingtextures.TheGaussiancubicmagnificationfilterisrepresentedbytheD3DTEXF_GAUSSIANCUBICmemberoftheD3DTEXTUREFILTERTYPEenumeratedtype.

D3DPTFILTERCAPS_MAGFLINEARDevicesupportsper-stagebilinearinterpolationfilteringformagnifyingtextures.ThebilinearinterpolationmagnificationfilterisrepresentedbytheD3DTEXF_LINEARmemberofthe

D3DTEXTUREFILTERTYPEenumeratedtype.D3DPTFILTERCAPS_MAGFPOINT

Devicesupportsper-stagepoint-samplefilteringformagnifyingtextures.Thepoint-samplemagnificationfilterisrepresentedbytheD3DTEXF_POINTmemberoftheD3DTEXTUREFILTERTYPEenumeratedtype.

D3DPTFILTERCAPS_MINFANISOTROPICDevicesupportsper-stageanisotropicfilteringforminifyingtextures.TheanisotropicminificationfilterisrepresentedbytheD3DTEXF_ANISOTROPICmemberoftheD3DTEXTUREFILTERTYPEenumeratedtype.

D3DPTFILTERCAPS_MINFLINEARDevicesupportsper-stagebilinearinterpolationfilteringforminifyingtextures.ThebilinearminificationfilterisrepresentedbytheD3DTEXF_LINEARmemberoftheD3DTEXTUREFILTERTYPEenumeratedtype.

D3DPTFILTERCAPS_MINFPOINTDevicesupportsper-stagepoint-samplefilteringforminifyingtextures.Thepoint-sampleminificationfilterisrepresentedbytheD3DTEXF_POINTmemberoftheD3DTEXTUREFILTERTYPEenumeratedtype.

D3DPTFILTERCAPS_MIPFLINEARDevicesupportsper-stagetrilinearinterpolationfilteringformipmaps.ThetrilinearinterpolationmipmappingfilterisrepresentedbytheD3DTEXF_LINEARmemberoftheD3DTEXTUREFILTERTYPEenumeratedtype.

D3DPTFILTERCAPS_MIPFPOINTDevicesupportsper-stagepoint-samplefilteringformipmaps.Thepoint-samplemipmappingfilterisrepresentedbytheD3DTEXF_POINTmemberoftheD3DTEXTUREFILTERTYPEenumeratedtype.

CubeTextureFilterCapsTexture-filteringcapabilitiesforaDirect3DCubeTextureobject.Per-stagefilteringcapabilitiesreflectwhichfilteringmodesaresupportedfortexturestageswhenperformingmultiple-textureblendingwiththeIDirect3DDevice8interface.Thismembercanbeanycombinationoftheper-stagetexture-filteringflagsdefinedfortheTextureFilterCapsmember.

VolumeTextureFilterCapsTexture-filteringcapabilitiesforaDirect3DVolumeTextureobject.Per-stage

filteringcapabilitiesreflectwhichfilteringmodesaresupportedfortexturestageswhenperformingmultiple-textureblendingwiththeIDirect3DDevice8interface.Thismembercanbeanycombinationoftheper-stagetexture-filteringflagsdefinedfortheTextureFilterCapsmember.

TextureAddressCapsTexture-addressingcapabilitiesforDirect3DTextureobjects.Thismembercanbeoneormoreofthefollowingflags.D3DPTADDRESSCAPS_BORDER

Devicesupportssettingcoordinatesoutsidetherange[0.0,1.0]tothebordercolor,asspecifiedbytheD3DTSS_BORDERCOLORtexture-stagestate.

D3DPTADDRESSCAPS_CLAMPDevicecanclamptexturestoaddresses.

D3DPTADDRESSCAPS_INDEPENDENTUVDevicecanseparatethetexture-addressingmodesoftheuandvcoordinatesofthetexture.ThisabilitycorrespondstotheD3DTSS_ADDRESSUandD3DTSS_ADDRESSVrender-statevalues.

D3DPTADDRESSCAPS_MIRRORDevicecanmirrortexturestoaddresses.

D3DPTADDRESSCAPS_MIRRORONCEDevicecantaketheabsolutevalueofthetexturecoordinate(thus,mirroringaround0),andthenclamptothemaximumvalue.

D3DPTADDRESSCAPS_WRAPDevicecanwraptexturestoaddresses.

VolumeTextureAddressCapsTexture-addressingcapabilitiesforDirect3DVolumeTextureobjects.ThismembercanbeoneormoreoftheflagsdefinedfortheTextureAddressCapsmember.

LineCapsDefinesthecapabilitiesforline-drawingprimitives.D3DLINECAPS_ALPHACMP

Supportsalpha-testcomparisons.D3DLINECAPS_BLEND

Supportssource-blending.D3DLINECAPS_FOG

Supportsfog.D3DLINECAPS_TEXTURE

Supportstexture-mapping.

D3DLINECAPS_ZTESTSupportsz-buffercomparisons.

MaxTextureWidthandMaxTextureHeightMaximumtexturewidthandheightforthisdevice.

MaxVolumeExtentMaximumvolumeextent.

MaxTextureRepeatThisnumberrepresentsthemaximumrangeoftheintegerbitsofthepost-normalizedtexturecoordinates.Atexturecoordinateisstoredasa32-bitsignedintegerusing27bitstostoretheintegerpartand5bitsforthefloatingpointfraction.Themaximumintegerindex,227,isusedtodeterminethemaximumtexturecoordinate,dependingonhowthehardwaredoestexture-coordinatescaling.

SomehardwarereportsthecapD3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE.Forthiscase,thedevicedefersscalingtexturecoordinatesbythetexturesizeuntilafterinterpolationandapplicationofthetextureaddressmode,sothenumberoftimesatexturecanbewrappedisgivenbytheintegervalueinMaxTextureRepeat.

Lessdesirably,onsomehardwareD3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZEisnotsetandthedevicescalesthetexturecoordinatesbythetexturesize(usingthehighestlevelofdetail)priortointerpolation.ThislimitsthenumberoftimesatexturecanbewrappedtoMaxTextureRepeat/textureSize.

Example:

GivenMaxTextureRepeat=32kandtexturesize=4KB:

ifthehardwaresetsD3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE

#oftimesatexturecanbewrapped=MaxTextureRepeat

//whichis32kinthisexample

else

#oftimesatexturecanbewrapped=MaxTextureRepeat/textureSize

//whichis227/4k

MaxTextureAspectRatioMaximumtextureaspectratiosupportedbythehardware,typicallyapowerof2.

MaxAnisotropyMaximumvalidvaluefortheD3DTSS_MAXANISOTROPYtexture-stagestate.

MaxVertexWMaximumW-baseddepthvaluethatthedevicesupports.

GuardBandLeft,GuardBandTop,GuardBandRight,andGuardBandBottom

Screenspacecoordinatesoftheguard-bandclippingregion.Coordinatesinsidethisrectanglebutoutsidetheviewportrectangleareautomaticallyclipped.

ExtentsAdjustNumberofpixelstoadjusttheextentsrectangleoutwardtoaccommodateantialiasingkernels.

StencilCapsFlagsspecifyingsupportedstencil-bufferoperations.Stenciloperationsareassumedtobevalidforallthreestencil-bufferoperationrenderstates(D3DRS_STENCILFAIL,D3DRS_STENCILPASS,andD3DRS_STENCILFAILZFAIL).D3DSTENCILCAPS_DECR

TheD3DSTENCILOP_DECRoperationissupported.D3DSTENCILCAPS_DECRSAT

TheD3DSTENCILOP_DECRSAToperationissupported.D3DSTENCILCAPS_INCR

TheD3DSTENCILOP_INCRoperationissupported.D3DSTENCILCAPS_INCRSAT

TheD3DSTENCILOP_INCRSAToperationissupported.D3DSTENCILCAPS_INVERT

TheD3DSTENCILOP_INVERToperationissupported.D3DSTENCILCAPS_KEEP

TheD3DSTENCILOP_KEEPoperationissupported.D3DSTENCILCAPS_REPLACE

TheD3DSTENCILOP_REPLACEoperationissupported.D3DSTENCILCAPS_ZERO

TheD3DSTENCILOP_ZEROoperationissupported.

Formoreinformation,seetheD3DSTENCILOPenumeratedtype.

FVFCapsFlexiblevertexformatcapabilities.D3DFVFCAPS_DONOTSTRIPELEMENTS

Itispreferablethatvertexelementsnotbestripped.Thatis,ifthevertexformatcontainselementsthatarenotusedwiththecurrent

renderstates,thereisnoneedtoregeneratethevertices.Ifthiscapabilityflagisnotpresent,strippingextraneouselementsfromthevertexformatprovidesbetterperformance.

D3DFVFCAPS_PSIZEPointsizeisdeterminedbyeithertherenderstateorthevertexdata.

IfD3DFVFCAPS_PSIZEisset,pointsizecancomefromD3DFVF_PSIZEdataintheFVFvertexdeclaration.Otherwise,pointsizeisdeterminedbytherenderstateD3DRS_POINTSIZE.

Iftheapplicationprovidespointsizeinboth(therenderstateandtheFVFdata),thevertexdataoverridestherender-statedata.

D3DFVFCAPS_TEXCOORDCOUNTMASKMasksthelowWORDofFVFCaps.Thesebits,casttotheWORDdatatype,describethetotalnumberoftexturecoordinatesetsthatthedevicecansimultaneouslyuseformultipletextureblending.(Youcanuseuptoeighttexturecoordinatesetsforanyvertex,butthedevicecanblendusingonlythespecifiednumberoftexturecoordinatesets.)

TextureOpCapsCombinationofflagsdescribingthetextureoperationssupportedbythisdevice.Thefollowingflagsaredefined.D3DTEXOPCAPS_ADD

TheD3DTOP_ADDtexture-blendingoperationissupported.D3DTEXOPCAPS_ADDSIGNED

TheD3DTOP_ADDSIGNEDtexture-blendingoperationissupported.

D3DTEXOPCAPS_ADDSIGNED2XTheD3DTOP_ADDSIGNED2Xtexture-blendingoperationissupported.

D3DTEXOPCAPS_ADDSMOOTHTheD3DTOP_ADDSMOOTHtexture-blendingoperationissupported.

D3DTEXOPCAPS_BLENDCURRENTALPHATheD3DTOP_BLENDCURRENTALPHAtexture-blendingoperationissupported.

D3DTEXOPCAPS_BLENDDIFFUSEALPHATheD3DTOP_BLENDDIFFUSEALPHAtexture-blendingoperationissupported.

D3DTEXOPCAPS_BLENDFACTORALPHATheD3DTOP_BLENDFACTORALPHAtexture-blendingoperationissupported.

D3DTEXOPCAPS_BLENDTEXTUREALPHATheD3DTOP_BLENDTEXTUREALPHAtexture-blendingoperationissupported.

D3DTEXOPCAPS_BLENDTEXTUREALPHAPMTheD3DTOP_BLENDTEXTUREALPHAPMtexture-blendingoperationissupported.

D3DTEXOPCAPS_BUMPENVMAPTheD3DTOP_BUMPENVMAPtexture-blendingoperationissupported.

D3DTEXOPCAPS_BUMPENVMAPLUMINANCETheD3DTOP_BUMPENVMAPLUMINANCEtexture-blendingoperationissupported.

D3DTEXOPCAPS_DISABLETheD3DTOP_DISABLEtexture-blendingoperationissupported.

D3DTEXOPCAPS_DOTPRODUCT3TheD3DTOP_DOTPRODUCT3texture-blendingoperationissupported.

D3DTEXOPCAPS_LERPTheD3DTOP_LERPtexture-blendingoperationissupported.

D3DTEXOPCAPS_MODULATETheD3DTOP_MODULATEtexture-blendingoperationissupported.

D3DTEXOPCAPS_MODULATE2XTheD3DTOP_MODULATE2Xtexture-blendingoperationissupported.

D3DTEXOPCAPS_MODULATE4XTheD3DTOP_MODULATE4Xtexture-blendingoperationissupported.

D3DTEXOPCAPS_MODULATEALPHA_ADDCOLORTheD3DTOP_MODULATEALPHA_ADDCOLORtexture-blendingoperationissupported.

D3DTEXOPCAPS_MODULATECOLOR_ADDALPHATheD3DTOP_MODULATECOLOR_ADDALPHAtexture-blendingoperationissupported.

D3DTEXOPCAPS_MODULATEINVALPHA_ADDCOLORTheD3DTOP_MODULATEINVALPHA_ADDCOLORtexture-blendingoperationissupported.

D3DTEXOPCAPS_MODULATEINVCOLOR_ADDALPHATheD3DTOP_MODULATEINVCOLOR_ADDALPHAtexture-blendingoperationissupported.

D3DTEXOPCAPS_MULTIPLYADDTheD3DTOP_MULTIPLYADDtexture-blendingoperationissupported.

D3DTEXOPCAPS_PREMODULATETheD3DTOP_PREMODULATEtexture-blendingoperationissupported.

D3DTEXOPCAPS_SELECTARG1TheD3DTOP_SELECTARG1texture-blendingoperationissupported.

D3DTEXOPCAPS_SELECTARG2TheD3DTOP_SELECTARG2texture-blendingoperationissupported.

D3DTEXOPCAPS_SUBTRACTTheD3DTOP_SUBTRACTtexture-blendingoperationissupported.

MaxTextureBlendStagesMaximumnumberoftexture-blendingstagessupported.Thisvalueisthenumberofblendersavailable.IntheDirectX8.xprogrammablepipeline,thiscorrespondstothenumberofinstructionssupportedbypixelshadersonthisparticularimplementation.

MaxSimultaneousTexturesMaximumnumberoftexturesthatcanbesimultaneouslyboundtothetextureblendingstages.Thisvalueisthenumberoftexturesthatcanbeusedinasinglepass.Ifthesametextureisusedintwoblendingstages,itcountsastwowhencomparedagainsttheMaxSimultaneousTexturesvalue.Intheprogrammablepipeline,thisindicatesthenumberoftextureregisterssupportedbypixelshadersonthisparticularpieceofhardware,andthenumberoftexturedeclarationinstructionsthatcanbepresent.

VertexProcessingCapsVertexprocessingcapabilities.Foragivenphysicaldevice,thiscapabilitymightvaryacrossDirect3DDeviceobjectsdependingontheparameterssuppliedtoIDirect3D8::CreateDevice.D3DVTXPCAPS_DIRECTIONALLIGHTS

Devicesupportsdirectionallights.D3DVTXPCAPS_LOCALVIEWER

Devicesupportslocalviewer.D3DVTXPCAPS_MATERIALSOURCE7

Devicesupportsselectablevertexcolorsources.D3DVTXPCAPS_POSITIONALLIGHTS

Devicesupportspositionallights(includingpointlightsandspotlights).

D3DVTXPCAPS_TEXGENDevicecangeneratetexturecoordinates.

D3DVTXPCAPS_TWEENINGDevicesupportsvertextweening.

D3DVTXPCAPS_NO_VSDT_UBYTE4DevicedoesnotsupporttheD3DVSDT_UBYTE4vertexdeclarationtype.

MaxActiveLightsMaximumnumberoflightsthatcanbeactivesimultaneously.Foragivenphysicaldevice,thiscapabilitymightvaryacrossDirect3DDeviceobjectsdependingontheparameterssuppliedtoIDirect3D8::CreateDevice.

MaxUserClipPlanesMaximumnumberofuser-definedclippingplanessupported.Thismembercanrangefrom0throughD3DMAXUSERCLIPPLANES.Foragivenphysicaldevice,thiscapabilitymayvaryacrossDirect3DDeviceobjectsdependingontheparameterssuppliedtoIDirect3D8::CreateDevice.

MaxVertexBlendMatricesMaximumnumberofmatricesthatthisdevicecanapplywhenperformingmultimatrixvertexblending.Foragivenphysicaldevice,thiscapabilitymayvaryacrossDirect3DDeviceobjectsdependingontheparameterssuppliedtoIDirect3D8::CreateDevice.

MaxVertexBlendMatrixIndexDWORDvaluethatspecifiesthemaximummatrixindexthatcanbeindexedintousingtheper-vertexindices.ThenumberofmatricesisMaxVertexBlendMatrixIndex+1,whichisthesizeofthematrixpalette.Ifnormalsarepresentinthevertexdatathatneedstobeblendedforlighting,thenthenumberofmatricesishalfthenumberspecifiedbythiscapabilityflag.IfMaxVertexBlendMatrixIndexissettozero,thedriverdoesnotsupportindexedvertexblending.IfthisvalueisnotzerothenthevalidrangeofindicesiszerothroughMaxVertexBlendMatrixIndex.

AzerovalueforMaxVertexBlendMatrixIndexindicatesthatthedriverdoesnotsupportindexedmatrices.

Whensoftwarevertexprocessingisused,256matricescouldbeusedfor

indexedvertexblending,withorwithoutnormalblending.

Foragivenphysicaldevice,thiscapabilitymayvaryacrossDirect3DDeviceobjectsdependingontheparameterssuppliedtoIDirect3D8::CreateDevice.

MaxPointSizeMaximumsizeofapointprimitive.Ifsetto1.0fthendevicedoesnotsupportpointsizecontrol.Therangeisgreaterthanorequalto1.0f.

MaxPrimitiveCountMaximumnumberofprimitives,orverticesforeachDrawPrimitivecall.NotethatwhenDirect3DisworkingwithaDirectX6.0orDirectX7.0driver,thisfieldissetto0xFFFF.Thismeansthatnotonlythenumberofprimitivesbutalsothenumberofverticesislimitedbythisvalue.

MaxVertexIndexMaximumsizeofindicessupportedforhardwarevertexprocessing.Itispossibletocreate32-bitindexbuffersbyspecifyingD3DFMT_INDEX32;however,youwillnotbeabletorenderwiththeindexbufferunlessthisvalueisgreaterthan0x0000FFFF.

MaxStreamsMaximumnumberofconcurrentdatastreamsforIDirect3DDevice8::SetStreamSource.Thevalidrangeis1–16.Notethatifthisvalueis0,thedriverisnotaDirectX8driver.

MaxStreamStrideMaximumstrideforIDirect3DDevice8::SetStreamSource.

VertexShaderVersionVertexshaderversion,indicatingthelevelofvertexshadersupportedbythedevice.OnlyvertexshaderswithversionnumbersequaltoorlessthanthiswillsucceedincallstoIDirect3DDevice8::CreateVertexShader.ThelevelofshaderisspecifiedtoCreateVertexShaderasthefirsttokeninthevertexshadertokenstream.

DirectX7.0functionalityis0DirectX8.xfunctionalityis01

Themainversionnumberisencodedinthesecondbyte.Thelowbytecontainsasub-versionnumber.

MaxVertexShaderConstThenumberofvertexshaderinputregistersthatarereservedforconstants.

PixelShaderVersionTwonumbersthatrepresentthepixelshadermainandsubversions.FormoreinformationabouttheversionssupportedinDirectX8.x,seethepixelshaderversioninstruction.

MaxPixelShaderValueMaximumvalueofpixelshaderarithmeticcomponent.Thisvalueindicatestheinternalrangeofvaluessupportedforpixelcolorblendingoperations.Withintherangethattheyreportto,implementationsmustallowdatatopassthroughpixelprocessingunmodified(unclamped).Normally,thevalueofthismemberisanabsolutevalue.Forexample,a1.0indicatesthattherangeis–1.0to1,andan8.0indicatesthattherangeis–8.0to8.0.Thevaluemustbe>=1.0foranyhardwarethatsupportspixelshaders.

Remarks

TheMaxTextureBlendStagesandMaxSimultaneousTexturesmembersmightseemverysimilar,buttheycontaindifferentinformation.TheMaxTextureBlendStagesmembercontainsthetotalnumberoftexture-blendingstagessupportedbythecurrentdevice,andtheMaxSimultaneousTexturesmemberdescribeshowmanyofthosestagescanhavetexturesboundtothembyusingtheIDirect3DDevice8::SetTexturemethod.

Whenthedriverfillsthisstructure,itcansetvaluesforexecute-buffercapabilities,evenwhentheinterfacebeingusedtoretrievethecapabilities(suchasIDirect3DDevice8)doesnotsupportexecutebuffers.

ForsystemsthatsettheD3DCAPS2_NO2DDURING3DSCENEcapabilityflag,performanceproblemsmayoccurifyouuseatextureandthenmodifyitduringascene.Thisistrueonallhardware,butitismoresevereonhardwarethatexposestheD3DCAPS2_NO2DDURING3DSCENEcapability.IfD3DCAPS2_NO2DDURING3DSCENEispresentonthehardware,application-basedtexturemanagementshouldensurethatnotextureusedinthecurrentBeginSceneandEndSceneblockisevictedunlessabsolutelynecessary.Inthecaseofextremelyhightextureusagewithinascene,theresultsareundefined.Thisoccurswhenyoumodifyatexturethatyouhaveusedinthesceneandthereisnosparetexturememoryavailable.Forsuchsystems,thecontentsofthezbufferbecomeinvalidatEndScene.ApplicationsshouldnotcallIDirect3DDevice8::CopyRectstoorfromthebackbufferonthistypeofhardwareinsideaBeginSceneandEndScenepair.Inaddition,applications

shouldnottrytoaccessthezbufferiftheD3DPRASTERCAPS_ZBUFFERLESSHSRcapabilityflagisset.Finally,applicationsshouldnotlockthebackbufferorthezbufferinsideaBeginSceneandEndScenepair.

ThefollowingflagsconcerningmipmappedtexturesarenotsupportedinDirectX8.x.

D3DPTFILTERCAPS_NEARESTD3DPTFILTERCAPS_LINEARD3DPTFILTERCAPS_MIPNEARESTD3DPTFILTERCAPS_MIPLINEARD3DPTFILTERCAPS_LINEARMIPNEARESTD3DPTFILTERCAPS_LINEARMIPLINEAR

Requirements

Header:DeclaredinD3d8caps.h.

SeeAlso

IDirect3D8::GetDeviceCaps,IDirect3DDevice8::GetDeviceCaps


IDirect3DDevice8::GetDeviceCapsRetrievesthecapabilitiesoftherenderingdevice.

HRESULTGetDeviceCaps(

D3DCAPS8*pCaps

);

Parameters

pCaps[out]PointertoaD3DCAPS8structure,describingthereturneddevice.

ReturnValues


Ifthemethodfails,thereturnvaluecanbeD3DERR_INVALIDCALL.

Remarks

GetDeviceCapsretrievesthesoftwarevertexpipelinecapabilitieswhenthedeviceisbeingusedinsoftwarevertexprocessingmode.SoftwarevertexprocessingmodeisselectedwhenadevicehasbeencreatedwithD3DCREATE_SOFTWAREVERTEXPROCESSING,orwhenadevicehasbeencreatedwithD3DCREATE_MIXEDVERTEXPROCESSINGandD3DRS_SOFTWAREVERTEXPROCESSINGissettoTRUE.

Requirements



InstructionModifiers

Useinstructionmodifierstochangetheoutputofaninstruction.Forinstance,usethemtomultiplyordividetheresultbyafactoroftwo,ortoclamptheresultbetweenzeroandone.Instructionmodifiersareappliedaftertheinstructionexecutesbutbeforewritingtheresulttothedestinationregister.

Alistofthemodifiersisshownbelow.

Modifier Description Syntax Version1.0 1.1 1.2 1.3 1.4

_x2 Multiplyby2 register_x2 X X X X X_x4 Multiplyby4 register_x4 X X X X X_x8 Multiplyby8 register_x8 X_d2 Divideby2 register_d2 X X X X X_d4 Divideby4 register_d4 X_d8 Divideby8 register_d8 X_sat Saturate(clampfrom0and1) register_sat X X X X X

Themultiplymodifiermultipliestheregisterdatabyapoweroftwoafteritisread.Thisisthesameasashiftleft.Thedividemodifierdividestheregisterdatabyapoweroftwoafteritisread.Thisisthesameasashiftright.Thesaturatemodifierclampstherangeofregistervaluesfromzerotoone.

Instructionmodifierscanbeusedonarithmeticinstructions.Theymaynotbeusedontextureaddressinstructions.

Examples

Multiplymodifier

Thisexampleloadsthedestinationregister(dest)withthesumofthetwocolorsinthesourceoperands(src0andsrc1)andmultipliestheresultbytwo.

add_x2dest,src0,src1

Thisexamplecombinestwoinstructionmodifiers.First,twocolorsinthesourceoperands(src0andsrc1)areadded.Theresultisthenmultipliedbytwo,andclampedbetween0.0to1.0foreachcomponent.Theresultissavedinthedestinationregister.

add_x2_satdest,src0,src1

Dividemodifier

Thisexampleloadsthedestinationregister(dest)withthesumofthetwocolorsinthesourceoperands(src0andsrc1)anddividestheresultbytwo.

add_d2dest,src0,src1

Saturatemodifier

Forarithmeticinstructions,thesaturationmodifierclampstheresultofthisinstructionintotherange0.0to1.0foreachcomponent.Thefollowingexampleshowshowtousethisinstructionmodifier.

dp3_satr0,t0_bx2,v0_bx2;t0isbump,v0islightdirection

Thisoperationoccursafteranymultiplyordivideinstructionmodifier._satismostoftenusedtoclampdotproductresults.However,italsoenablesconsistentemulationofmultipassmethodswheretheframebufferisalwaysintherange0to1,andofMicrosoft®DirectX®6.0and7.0multitexturesyntax,inwhichsaturationisdefinedtooccurateverystage.

Thisexampleloadsthedestinationregister(dest)withthesumofthetwocolorsinthesourceoperands(src0andsrc1),andclampstheresultintotherange0.0to1.0foreachcomponent.

add_satdest,src0,src1

Thisexamplecombinestwoinstructionmodifiers.First,twocolorsinthesourceoperands(src0andsrc1)areadded.Theresultismultipliedbytwoandclampedbetween0.0to1.0foreachcomponent.Theresultissavedinthedestinationregister.

add_x2_satdest,src0,src1

MicrosoftDirectx8.1(pixelshaderversions1.0,1.1,1.2,1.3,1.4)

SourceRegisterModifiersUsesourceregistermodifierstochangethevaluereadfromaregisterbeforeaninstructionexecutes.Thecontentsofasourceregisterareleftunchanged.Modifiersareusefulforadjustingtherangeofregisterdatainpreparationfortheinstruction.Asetofmodifierscalledselectorscopiesorreplicatesthedatafromasinglechannel(r,g,b,a)intotheotherchannels.

Version1.4shadershavemodifierfunctionalityspecifictoshaderinstructionstexldandtexcrd.Thesemodifiersaffectversion1.4textureregistersandaredetailedinTextureRegisterModifiers.

Sourceregistermodifiers Syntax Version1.0 1.1 1.2 1.3 1.4

Bias register_bias X X X X XInvert 1-register X X X X XNegate -register X X X X XScale×2 register_x2 XSignedScaling register_bx2 X X X X X

Sourceregistermodifierscanbeusedonlyonarithmeticinstructions.Theycannotbeusedontextureaddressinstructions.Theexceptiontothisisthesignedscalemodifier(_bx2).Forversion1.0and1.1,signedscalecanbeusedonthesourceargumentofanytexm*instruction.Forversion1.2or1.3,signedscalecanbeusedonthesourceargumentofanytextureaddressinstruction.

Somemodifierspecificrestrictions:

Negatecanbecombinedwitheitherthebias,signedscaling,orscale×2modifier.Whencombined,negateisexecutedlast.Invertcannotbecombinedwithanyothermodifier.Invert,negate,bias,signedscaling,andscale×2canbecombinedwithanyoftheselectors.Sourceregistermodifiersshouldnotbeusedonconstantregistersbecausetheywillcauseundefinedresults.Forversion1.4,modifiersonconstantsarenotallowedandwillfailvalidation.


SourceRegisterSelectorsThismodifierreplicatesasinglechannelofasource-registerargumenttoallchannels.

sourceregister.channel

Sourceregisterselectors Syntax Version1.0 1.1 1.2 1.3 1.4

Redreplicate sourceregister.r XGreenreplicate sourceregister.g XBluereplicate sourceregister.b X X X XAlphareplicate sourceregister.a X X X X X

Redreplicate.Replicatestheredchanneltoallchannels.Greenreplicate.Replicatesthegreenchanneltoallchannels.Bluereplicate.Replicatesthebluechanneltoallchannels.Alphareplicate.Replicatesthealphachanneltotoallchannels.

Register

Sourceregister.Formoreaboutregistertypes,seeRegisters.

Inversion1.1,1.2,and1.3,bluereplicateisavailableonlyonthesourceregisterofarithmeticinstruction,whichusesanalphadestinationregisterwritemask.

Remarks

Sourceregisterselectorsareappliedbeforeanysourceregistermodifiersandbeforetheinstructionexecutes.

Copyingthecontentsofachannelintooneormoreotherchannelsiscommonlyreferredtoas"swizzling."

Theseselectorsarevalidonsourceregistersforarithmeticinstructions.Thefourselectorsoperateondifferentchannels.

Analternatesyntaxforther,g,b,achannelsisx,y,z,w.

Sourceselectorsandsourcemodifiersmaybecombinedfreely.Inthisexample,registerr0usestheinvert,bias,andsignedscalingmodifier,aswellasthegreenselector.Thecontentsofthesourceregisterareunaffected;themodifiermodifiesonlythedataread.

-r0_bx2.g

Tounderstandtheorderoftheexecutionofthesemodifiersandselectors,seeOrderofOperations.

ThisoperatorcanbeusedinconjunctionwiththeInvertorNegateoperators.

AlphareplicatefunctionalityisanalogoustotheD3DTA_ALPHAREPLICATEflagintheMicrosoft®DirectX®6.0and7.0multitexturesyntax.

Example

Theexamplesbelowillustrateeachofthefourselectors.

//Replicatetheredcolorchanneltotheallchannelsbefore

//doingthemultiply.

mulr0,r0,r1.r//theresultisr1.rgba=r1.r

//Replicatethegreencolorchanneltotheallchannelsbefore

//doingthemultiply.

mulr0,r0,r1.g//theresultisr1.rgba=r1.g

//Replicatethebluecolorchanneltotheallchannelsbefore

//doingthemultiply.

mulr0,r0,r1.b//theresultisr1.rgba=r1.b

//Forps1.1,1.2,1.3,thebluereplicateexample

//wouldrequireadestinationwritemask.

mulr0.a,r0,r1.b

//alphareplicate

mulr0,r0,r1.a;Replicatethealphacolorchanneltoallchannels.


DestinationRegisterWriteMasksdestinationregister.writemask

Writemaskscontrolwhichchannels(red,green,blue,alpha)areupdatedinthedestinationregister.

Register

Destinationregister.Formoreaboutregistertypes,seeRegisters.

Remarks

Thefollowingdestinationwritemasksareavailable.

WriteMask Syntax Version1.0 1.1 1.2 1.3 1.4

red,green,blue,alpha destinationregister.rgba X X X X Xnone destinationregister X X X X Xcolor(red,green,blue) destinationregister.rgb X X X X Xalpha destinationregister.a X X X X Xred destinationregister.r Xgreen destinationregister.g Xblue destinationregister.b Xarbitrary destinationregister.rgba Seenotebelow.

NoteThearbitrarymaskallowsanysetofchannelstobecombinedtoproduceamask.Thechannelsmustbelistedintheorderr,g,b,a—forexample,register.rba,whichupdatesthered,blue,andalphachannelsofthedestination.Thearbitrarymaskisavailableonlyinversion1.4.

Ifnodestinationwritemaskisspecified,thedestinationwritemaskdefaultstothergbacase.Inotherwords,allchannelsinthedestinationregisterareupdated.

Analternatesyntaxforther,g,b,achannelsisx,y,z,w.

Forversions1.0to1.3,thedp3arithmeticinstructioncanuseonlythe.rgbor.rgbaoutputwritemasks.

Destinationregisterwritemasksaresupportedforarithmeticoperationsonly.Theycannotbeusedontextureaddressinginstructions,withtheexceptionoftheversion1.4instructions,texcrdandtexld.

Examples

default

Thedefaultistowriteallfourcolorchannels.

//Allfourcolorchannelscanbewrittenbyexplicitlylistingthem.

mulr0.rgba,t0,v0

//Or,thedefaultmaskcanbeusedtowriteallfourchannels.

mulr0,t0,v0

alphawritemask

Thealphawritemaskisusedtocontrolwritingtothealphachannel.

//Thealphawritemaskisalsoreferredtoasthescalarwritemask,

//becauseitusesthescalarpipeline.

addr0.a,t1,v1

Sothisinstructioneffectivelyputsthesumofthealphacomponentoft1andthealphacomponentofv1intor0.a.

colorwritemask

Thecolorwritemaskisusedtocontrolwritingtothecolorchannels.

//Thecolorwritemaskisalsoreferredtoasthevectorwritemask,

//becauseitusesthevectorpipeline.

mulr0.rgb,t0,v0

arbitrarywritemask

Forversion1.4,destinationwritemaskscanbeusedinanycombinationaslongasthemasksareorderedr,g,b,a.

//Thisexampleupdatesthered,blue,andalphachannels.

movr0.rba,r1

co-issuedinstructions

Aco-issuedinstructionallowstwopotentiallydifferentinstructionstobeissuedsimultaneously.ThisisaccomplishedbyexecutingtheinstructionsinthealphapipelineandtheRGBpipeline.

//Forexample,thedefaultexampleshownabove:

mulr0,t0,v0

//isalsoequivalenttothefollowingco-issuedinstruction

mulr0.rgb,t0,v0

+mulr0.a,t0,v0

Theadvantageofpairinginstructionsthiswayisthatitallowsdifferentoperationstobeperformedinthevectorandscalarpipelineinparallel.

MicrosoftDirectx8.1(pixelshaderversion1.4)

TextureRegisterModifiersfortexldandtexcrd

Twopixelshaderversion1.4textureaddressinstructions,texldandtexcrd,havecustomsyntax.Theseinstructionssupporttheirownsetofsourceregistermodifiers,sourceregisterselectors,anddestination-registerwritemasks,asshownbelow.

SourceRegisterModifiersfortexldandtexcrd

Thesemodifiersprovideprojectivedividefunctionalitybydividingthexandyvaluesbyeitherthezorwvalues.

Sourceregistermodifiers Description Syntax Version

_dzDividex,ycomponentsbyz

sourceregister_dz 1.4

_db sourceregister_db 1.4

_dwDividex,ycomponentsbyw

sourceregister_dw 1.4

_da sourceregister_da 1.4

Register


Remarks

The_dzor_dbmodifierdoesthefollowing:

x'=x/z(x'=1.0ifz==0)

y'=y/z(y'=1.0ifz==0)

z'isundefined

w'isundefined

The_dwor_damodifierdoesthefollowing:

x'=x/w(x'=1.0ifw==0)

y'=y/w(y'=1.0ifw==0)

z'isundefined

w'isundefined

NoteForpixelshaderversion1.4,theD3DTTFF_PROJECTEDflagunderD3DTSS_TEXTURETRANSFORMFLAGSisignoredbecauseaprojectivedivideisaccomplishedbythesourceregistermodifierslistedpreviously.

SourceRegisterSelectorsfortexldandtexcrd

Selectorsreplicatethecontentsofonechannelintootherchannels.Replicatingthecontentsofachanneltooneormoreotherchannelsiscommonlyreferredtoas"swizzling."

Sourceregisterselectors Description Syntax Version

xyzMapsx,y,zdatatochannelsx,y,z,z

sourceregister.xyz 1.4

rgb sourceregister.rgb 1.4

xywMapsx,y,wdatatochannelsx,y,w,w

sourceregister.xyw 1.4

rga sourceregister.rga 1.4

Register


Remarks

Thetexldandtexcrdinstructionsneverreadmorethanthefirstthreecomponents.So,theseselectorsprovidetheoptionoftakingthethirdcomponentfromeitherthethirdorthefourthcomponentofthesourceregister.

DestinationRegisterWriteMasksfortexldandtexcrd

Writemaskscontrolwhichchannels(red,green,blue,alpha)areupdatedinthedestinationregister.

Destinationregisterwritemasks Description Syntax Used

by Version

xyzw

Updatesthex,y,z,wchannels

destinationregister.xyzw

texldonly 1.4

rgba destinationregister.rgba

texldonly 1.4

none destinationregister

texldonly 1.4

xyzUpdatesthex,y,zchannels

destinationregister.xyz

texcrdonly 1.4

rgb destinationregister.rgb

texcrdonly 1.4

xyUpdatesthex,ychannels

destinationregister.xy

texcrdonly 1.4

rg destinationregister.rg

texcrdonly 1.4

Register

Destinationregister.Formoreaboutregistertypes,seeRegisters.


D3DXMESHFlagsusedtospecifycreationoptionsforamesh.

enum_D3DXMESH{

D3DXMESH_32BIT=0x001,

D3DXMESH_DONOTCLIP=0x002,

D3DXMESH_POINTS=0x004,

D3DXMESH_RTPATCHES=0x008,

D3DXMESH_NPATCHES=0x4000,

D3DXMESH_VB_SYSTEMMEM=0x010,

D3DXMESH_VB_MANAGED=0x020,

D3DXMESH_VB_WRITEONLY=0x040,

D3DXMESH_VB_DYNAMIC=0x080,

D3DXMESH_VB_SOFTWAREPROCESSING=0x8000,

D3DXMESH_IB_SYSTEMMEM=0x100,

D3DXMESH_IB_MANAGED=0x200,

D3DXMESH_IB_WRITEONLY=0x400,

D3DXMESH_IB_DYNAMIC=0x800,

D3DXMESH_IB_SOFTWAREPROCESSING=0x10000,

D3DXMESH_VB_SHARE=0x1000,

D3DXMESH_USEHWONLY=0x2000,

D3DXMESH_SYSTEMMEM=0x110,

D3DXMESH_MANAGED=0x220,

D3DXMESH_WRITEONLY=0x440,

D3DXMESH_DYNAMIC=0x880,

D3DXMESH_SOFTWAREPROCESSING=0x18000

};

Constants

D3DXMESH_32BITThemeshhas32-bitindicesinsteadof16-bitindices.A32-bitmeshcansupportupto(2^32)-1facesandvertices.

D3DXMESH_DONOTCLIPUsetheD3DUSAGE_DONOTCLIPusageflagforvertexandindexbuffers.

D3DXMESH_POINTSUsetheD3DUSAGE_POINTSusageflagforvertexandindexbuffers.

D3DXMESH_RTPATCHES

UsetheD3DUSAGE_RTPATCHESusageflagforvertexandindexbuffers.D3DXMESH_NPATCHES

SpecifyingthisflagcausesthevertexandindexbufferofthemeshtobecreatedwithD3DUSAGE_NPATCHESflag.ThisisrequiredifthemeshobjectistoberenderedusingN-patchenhancementusingMicrosoft®Direct3D®.

D3DXMESH_VB_SYSTEMMEMUsetheD3DPOOL_SYSTEMMEMmemoryclassforvertexbuffers.

D3DXMESH_VB_MANAGEDUsetheD3DPOOL_MANAGEDmemoryclassforvertexbuffers.

D3DXMESH_VB_WRITEONLYUsetheD3DUSAGE_WRITEONLYusageflagforvertexbuffers.

D3DXMESH_VB_DYNAMICUsetheD3DUSAGE_DYNAMICusageflagforvertexbuffers.

D3DXMESH_VB_SOFTWAREPROCESSINGUsetheD3DUSAGE_SOFTWAREPROCESSINGforflagforvertexbuffers.

D3DXMESH_IB_SYSTEMMEMUsetheD3DPOOL_SYSTEMMEMmemoryclassforindexbuffers.

D3DXMESH_IB_MANAGEDUsetheD3DPOOL_MANAGEDmemoryclassforindexbuffers.

D3DXMESH_IB_WRITEONLYUsetheD3DUSAGE_WRITEONLYusageflagforindexbuffers.

D3DXMESH_IB_DYNAMICUsetheD3DUSAGE_DYNAMICusageflagforindexbuffers.

D3DXMESH_IB_SOFTWAREPROCESSINGUsetheD3DUSAGE_SOFTWAREPROCESSINGusageflagforindexbuffers.

D3DXMESH_VB_SHAREForcestheclonedmeshestosharevertexbuffers.

D3DXMESH_USEHWONLYUsehardwareprocessingonly.Thisflagshouldbespecifiedonlyforahardwareprocessingdevice.Onamixed-modedevice,thisflagwillcausethesystemtoeitherusehardwareonly,orifthehardwareisnotcapable,itwillapproximateusingthesoftwarecapabilities.

D3DXMESH_SYSTEMMEMEquivalenttospecifyingbothD3DXMESH_VB_SYSTEMMEMandD3DXMESH_IB_SYSTEMMEM.

D3DXMESH_MANAGED

EquivalenttospecifyingbothD3DXMESH_VB_MANAGEDandD3DXMESH_IB_MANAGED.

D3DXMESH_WRITEONLYEquivalenttospecifyingbothD3DXMESH_VB_WRITEONLYandD3DXMESH_IB_WRITEONLY.

D3DXMESH_DYNAMICEquivalenttospecifyingbothD3DXMESH_VB_DYNAMICandD3DXMESH_IB_DYNAMIC.

D3DXMESH_SOFTWAREPROCESSINGEquivalenttospecifyingbothD3DXMESH_VB_SOFTWAREPROCESSINGandD3DXMESH_IB_SOFTWAREPROCESSING

Requirements

Header:DeclaredinD3dx8mesh.h.


ID3DXMeshApplicationsusethemethodsoftheID3DXMeshinterfacetomanipulatemeshobjects.

ToobtaintheID3DXMeshinterface,calleithertheD3DXCreateMeshorD3DXCreateMeshFVFfunction.ThemethodsoftheID3DXMeshinterfacecanbeorganizedintothefollowinggroups.

Locking LockAttributeBufferUnlockAttributeBuffer

Optimization OptimizeOptimizeInplace

Remarks

ThisinterfaceinheritsadditionalfunctionalityfromtheID3DXBaseMeshinterface.

Thisinterface,likeallCOMinterfaces,inheritsadditionalfunctionalityfromtheIUnknownInterface.

TheLPD3DXMESHtypeisdefinedasapointertotheID3DXMeshinterface,asshownbelow.

typedefstructID3DXMesh*LPD3DXMESH;

Requirements


SeeAlso

MeshFunctions


PALETTEENTRYSpecifiesthecolorandusageofanentryinalogicalpalette.

typedefstructtagPALETTEENTRY{

BYTEpeRed;

BYTEpeGreen;

BYTEpeBlue;

BYTEpeFlags;

}PALETTEENTRY;

Members

peRedTheredintensityvalueforthepaletteentry.

peGreenThegreenintensityvalueforthepaletteentry.

peBlueTheblueintensityvalueforthepaletteentry.

peFlagsThealphaintensityvalueforthepaletteentry.NotethatasofMicrosoft®DirectX®8.0,thismemberistreateddifferentlythandocumentedintheMicrosoft®PlatformSoftwareDevelopmentKit(SDK).

Requirements

Header:DeclaredinWingdi.h;includeWindows.h.


D3DX_NORMALMAPFlagsControlthegenerationofnormalmaps.

#defineD3DX_NORMALMAP_MIRROR_U(1<<16)

#defineD3DX_NORMALMAP_MIRROR_V(2<<16)

#defineD3DX_NORMALMAP_MIRROR(3<<16)

#defineD3DX_NORMALMAP_INVERTSIGN(8<<16)

#defineD3DX_NORMALMAP_COMPUTE_OCCLUSION(16<<16)

Constants

D3DX_NORMALMAP_MIRROR_UIndicatesthatpixelsofftheedgeofthetextureontheU-axisshouldbemirrored,notwrapped.

D3DX_NORMALMAP_MIRROR_VIndicatesthatpixelsofftheedgeofthetextureontheV-axisshouldbemirrored,notwrapped.

D3DX_NORMALMAP_MIRRORSameasspecifyingD3DX_NORMALMAP_MIRROR_U|D3DX_NORMALMAP_MIRROR_V.

D3DX_NORMALMAP_INVERTSIGNInvertsthedirectionofeachnormal.

D3DX_NORMALMAP_COMPUTE_OCCLUSIONComputestheper-pixelocclusiontermandencodesitintothealpha.Analphaof1meansthatthepixelisnotobscuredinanyway,andanalphaof0meansthatthepixeliscompletelyobscured.

Requirements

Header:DeclaredinD3d8tex.h.

SeeAlso

D3DXComputeNormalMap


D3DX_CHANNELFlagsThefollowingflagsareusedtospecifywhichchannelsinatexturetooperateon.

#defineD3DX_CHANNEL_RED1

#defineD3DX_CHANNEL_BLUE2

#defineD3DX_CHANNEL_GREEN4

#defineD3DX_CHANNEL_ALPHA8

#defineD3DX_CHANNEL_LUMINANCE16

Constants

D3DX_CHANNEL_REDIndicatestheredchannelshouldbeused.

D3DX_CHANNEL_BLUEIndicatesthebluechannelshouldbeused.

D3DX_CHANNEL_GREENIndicatesthegreenchannelshouldbeused.

D3DX_CHANNEL_ALPHAIndicatesthealphachannelshouldbeused.

D3DX_CHANNEL_LUMINANCEIndicatestheluminancesofthered,green,andbluechannelsshouldbeused.

Requirements

Header:DeclaredinD3d8tex.h.


IUnknownInterface

AllCOMobjectssupportaninterfacecalledIUnknown.ThisinterfaceprovidesMicrosoft®DirectX®withcontroloftheobject'slifetimeandtheabilitytoretrieveotherinterfacesimplementedbytheobject.IUnknownhasthreemethods.

AddRefincrementstheobject'sreferencecountby1whenaninterfaceoranotherapplicationbindsitselftotheobject.QueryInterfacequeriestheobjectaboutthefeaturesthatitsupportsbyrequestingpointerstoaspecificinterface.Releasedecrementstheobject'sreferencecountby1.Whenthecountreaches0,theobjectisdeallocated.

TheAddRefandReleasemethodsmaintainanobject'sreferencecount.Forexample,ifyoucreateaMicrosoftDirect3D®object,theobject'sreferencecountissetto1.Everytimeafunctionreturnsapointertoaninterfaceforthatobject,thefunctionmustcallAddRefthroughthatpointertoincrementthereferencecount.MatcheachAddRefcallwithacalltoRelease.Beforethepointercanbedestroyed,youmustcallReleasethroughthatpointer.Afteranobject'sreferencecountreaches0,theobjectisdestroyed,andallinterfacestoitbecomeinvalid.

TheQueryInterfacemethoddetermineswhetheranobjectsupportsaspecificinterface.Ifanobjectsupportsaninterface,QueryInterfacereturnsapointertothatinterface.Youthencanusethemethodsofthatinterfacetocommunicatewiththeobject.IfQueryInterfacesuccessfullyreturnsapointertoaninterface,itimplicitlycallsAddReftoincrementthereferencecount,soyourapplicationmustcallReleasetodecrementthereferencecountbeforedestroyingthepointertotheinterface.

Requirements

WindowsNT/2000/XP:RequiresWindowsNT3.1orlater.Windows98/Me:RequiresWindows98orlater.

Header:DeclaredinUnknwn.h.


D3DXIMAGE_FILEFORMATDescribesthesupportedimagefileformats.

typedefenum_D3DXIMAGE_FILEFORMAT

{

D3DXIFF_BMP=0,

D3DXIFF_JPG=1,

D3DXIFF_TGA=2,

D3DXIFF_PNG=3,

D3DXIFF_DDS=4,

D3DXIFF_PPM=5,

D3DXIFF_DIB=6,

D3DXIFF_FORCE_DWORD=0x7fffffff

}D3DXIMAGE_FILEFORMAT;

Constants

D3DXIFF_BMPMicrosoft®Windows®bitmapfileformat.

D3DXIFF_JPGJointPhotographicExpertsGroupcompressedfile.

D3DXIFF_TGATruevisionTargaimagefile.

D3DXIFF_PNGPortableNetworkGraphicsfileformat.

D3DXIFF_DDSMicrosoftDirectDraw®surfacefileformat.

D3DXIFF_PPMPortablepixmapfileformat.

D3DXIFF_DIBWindowsbitmapfileformat.

D3DXIFF_FORCE_DWORDForcesthisenumerationtocompileto32bitsinsize.Thisvalueisnotused.

Requirements

Header:DeclaredinD3dx8tex.h.


LPD3DXFILL2DFunctiontypeusedbythetexturefillfunctions.

VOID(*LPD3DXFILL2D)(

D3DXVECTOR4*pOut,

D3DXVECTOR2*pTexCoord,

D3DXVECTOR2*pTexelSize,

LPVOIDpData

);

Parameters

pOut[out]Pointertoavector,whichthefunctionusestoreturnitsresult.X,Y,Z,andWwillbemappedtoR,G,B,andArespectively.

pTexCoord[in]Pointertoavectorcontainingthecoordinatesofthetexelcurrentlybeingevaluated.Texturecoordinatecomponentsfortextureandvolumetexturesrangefrom0to1.Texturecoordinatecomponentsforcubetexturesrangefrom-1to1.

pTexelSize[in]Pointertoavectorcontainingthedimensionsofthecurrenttexel.

pData[in]Pointertouserdata.

Requirements


SeeAlso

D3DXFillTexture


LPD3DXFILL3DFunctiontypeusedbythetexturefillfunctions.

VOID(*LPD3DXFILL3D)(

D3DXVECTOR4*pOut,

D3DXVECTOR3*pTexCoord,

D3DXVECTOR3*pTexelSize,

LPVOIDpData

);

Parameters

pOut[out]Pointertoavector,whichthefunctionusestoreturnitsresult.X,Y,Z,andWwillbemappedtoR,G,B,andArespectively.

pTexCoord[in]Pointertoavectorcontainingthecoordinatesofthetexelcurrentlybeingevaluated.Texturecoordinatecomponentsfortextureandvolumetexturesrangefrom0to1.Texturecoordinatecomponentsforcubetexturesrangefrom-1to1.

pTexelSize[in]Pointertoavectorcontainingthedimensionsofthecurrenttexel.

pData[in]Pointertouserdata.

Requirements


SeeAlso

D3DXFillCubeTexture,D3DXFillVolumeTexture


SampleFramework

TheMicrosoft®DirectX®8.1andMicrosoft®Direct3D®SoftwareDevelopmentKit(SDK)graphicssampleframeworkisanevolutionfromtheDirectX7.0graphicssampleframework.TheSDKsamplesareinstalledbydefaultin\Dxsdk\Samples\Multimedia.ThefoldersofinterestareCommonandDirect3D.ThesampleframeworkiscontainedintheCommonfolderandtheDirect3DsamplesbasedonthegraphicsframeworkarecontainedintheDirect3Dfolder.

Thegraphicsframeworkconsistsoffivesourcemodules.

d3dapp.cppexposestheapplicationinterfaceusedforsamples.OfparticularinterestisclassCD3DApplication.d3dfile.cppfurnishes.xfilesupport,toenablesamplestoload.xfiles.OfparticularinterestareclassesCD3DmeshandCD3DFrame.d3dfont.cppfurnishesbasicfontoutputsupport,toenablethingslikestatisticsviews.OfparticularinterestisclassCD3DFont.d3dutil.cppprovidesgenerallyuseful3dimensionalfunctions,suchasmaterial,light,andtexturehelperfunctions.dxutil.cppprovidesgenerallyusefulDirectXfunctions,suchasmedia,registry,andtimerhelperfunctions.

CorrespondingheaderfilesarelocatedintheCommon\Includefolder.

EachsampleimplementsasubclassofCD3DApplication,whichistypicallynamedCMyD3DApplication,andsetofoverridablesthatareshownbelow.

//Overridablefunctionsforthe3dimensionalscenecreatedbytheapplication

virtualHRESULTConfirmDevice(D3DCAPS8*,DWORD,D3DFORMAT){returnS_OK;}

virtualHRESULTOneTimeSceneInit(){returnS_OK;}

virtualHRESULTInitDeviceObjects(){returnS_OK;}

virtualHRESULTRestoreDeviceObjects(){returnS_OK;}

virtualHRESULTFrameMove(){returnS_OK;}

virtualHRESULTRender(){returnS_OK;}

virtualHRESULTInvalidateDeviceObjects(){returnS_OK;}

virtualHRESULTDeleteDeviceObjects(){returnS_OK;}

virtualHRESULTFinalCleanup(){returnS_OK;}

Theprototypesforthesemethodsarecontainedind3dapp.hinthe

CD3Dapplicationclass.ThesamplescreateanewDirect3Dapplicationandoverride

thosemethodsthatareneededbytheapplication.

DerivedClassExample

Thisexampleusesasubsetoftheoverrideablemethods.TheclassCMyD3DApplicationcontainsthefollowingmethods.Eachofthesemethodsisexplainedbelow.

classCMyD3DApplication:publicCD3DApplication

{

public:

CMyD3DApplication();

protected:

HRESULTConfirmDevice(D3DCAPS8*,DWORD,D3DFORMAT);

HRESULTDeleteRestoreDeviceObjects();

HRESULTRestoreDeviceObjects();

HRESULTFrameMove();

HRESULTRender();

private:

LPDIRECT3DVERTEXBUFFER8m_pVB; //Vertexbuffertoholdvertices

};

Constructor

Theconstructorinitializesthewindowtitle,enablesdepthbufferingandinitializesthevertexbuffer.

CMyD3DApplication::CMyD3DApplication()

{

m_strWindowTitle=_T("D3DExample");//titlebarstring

m_bUseDepthBuffer=TRUE;//enabledepthbuffer

m_pVB=NULL;//initialize

}

Thewindowtitleisawidecharacterstringthatisvisibleinthetitlebarorthewindowclasswhentheapplicationisinvoked.Itisoptional.

Thebaseclasscontainsamembervariableforenablingdepthbuffering.ThedefaultvalueforthisbooleanvariableisFALSE,whichdisablesdepthbuffering.

Thewindowtitleisawidecharacterstringthatisvisibleinthetitlebarorthewindowclasswhentheapplicationisinvoked.Itisoptional.

ConfirmDeviceObjects

DeleteDeviceObjects

DeleteDeviceObjectsiscalledwhentheapplicationisexiting,orifthedeviceisbeingchanged.Youusethismethodtodeletedevicedependentobjects,suchasthevertexbuffer.

HRESULTCVShader1::DeleteDeviceObjects()

{

m_pQuadVB->Release();

m_pQuadVB=NULL;

returnS_OK;

}

RestoreDeviceObjects

Thismethodiscalledwhentheapplicationneedstorestoredevicememoryobjectsanddevicestates.ThisisrequiredafteraDirectXdeviceiscreatedorresized.Thismethoddoesmostoftheworkofcreatingobjectsandinitializingrenderstates.

HRESULTCMyD3DApplication::RestoreDeviceObjects()

{

//Createthevertexbuffer.Allocateenoughmemory(fromthedefaultpool)

//toholdthecustomvertices.Specifytheflexiblevertexformat(FVF),sothevertexbufferknowswhat

// dataitcontains.

if(FAILED(m_pd3dDevice->CreateVertexBuffer(NUM_VERTS*sizeof(CUSTOMVERTEX),

0,D3DFVF_CUSTOMVERTEX,D3DPOOL_DEFAULT,&m;_pVB)))

{

returnE_FAIL;

}

//Fillthevertexbuffer.First,lockthevertexbuffertogetaccesstothe

//vertices.Thismechanismisrequiredbecausevertexbuffersmaybeindevice

//memory.Thenusememcpytodoafastdatacopy.

VOID*pVertices;

if(FAILED(m_pVB->Lock(0,sizeof(g_Vertices),

(BYTE**)&pVertices;,0)))

returnE_FAIL;

memcpy(pVertices,g_Vertices,sizeof(g_Vertices));

m_pVB->Unlock();

//Settheprojectionmatrix.Thesizeofthebackbuffercomesfromthebase

//class

D3DXMATRIXmatProj;

FLOATfAspect=m_d3dsdBackBuffer.Width/

(FLOAT)m_d3dsdBackBuffer.Height;

D3DXMatrixPerspectiveFovLH(&matProj;,D3DX_PI/4,fAspect,

1.0f,100.0f);

m_pd3dDevice->SetTransform(D3DTS_PROJECTION,&matProj;);

//Setuptheviewmatrix.Aviewmatrixcanbedefinedfromaneye

//point,alookatpointandanupdirectionvector.Inthisexample,

//theeyepositionis(0,1,-4)thelookatpointis(0,0,0)andthe

//upvectoris(0,1,0.

D3DXMATRIXmatView;

D3DXMatrixLookAtLH(&matView;,&D3DXVECTOR3;(0.0f,1.0f,-4.0f),

&D3DXVECTOR3;(0.0f,0.0f,0.0f),

&D3DXVECTOR3;(0.0f,1.0f,0.0f));

m_pd3dDevice->SetTransform(D3DTS_VIEW,&matView;);

//Setupdefaulttexturestates

//Setuprenderstates(thisisonlyoneexamplerenderstate)

m_pd3dDevice->SetRenderState(D3DRS_CULLMODE,D3DCULL_NONE);

returnS_OK;

}

Thismethodcreatesthevertexbufferandcopiesthevertexdataintoit.Itcreatestheviewandprojectionmatrices,whichdefinethecameraorientationtotheobjectinthevertexbuffer.Texturestagestatescanbesetinthismethodalthoughnonearepresentinthisexample.Renderstatesthatarenotlikelytochangeareset.Thesedeterminehowthescenerenders.

FrameMove

Thismethodcontainsactionsthathappeneveryframesuchasanimation.Inthisexample,itaddsayaxisrotationtotheworldtransform.

HRESULTCMyD3DApplication::FrameMove()

{

//Forourworldmatrix,justrotatetheobjectaboutthey-axis.

D3DXMATRIXmatWorld;

D3DXMatrixRotationY(&matWorld;,::TimeGetTime()/150.0f);

m_pd3dDevice->SetTransform(D3DTS_WORLD,&matWorld;);

returnS_OK;

}

TheWindowsmethod::TimeGetTime()isusedtoreturnthecurrenttime.Onceitisdividedby150,thisgeneratesaincrementalangletorotatetheobject.

Render

Thismethodiscalledwhenitistimetorendertheoutput.Thisfunctionclearstheviewportandrenderthescene.Italsorendersstatechanges.

HRESULTCMyD3DApplication::Render()

{

//Cleartheviewport

m_pd3dDevice->Clear(0L,NULL,D3DCLEAR_TARGET|D3DCLEAR_ZBUFFER,

D3DCOLOR_XRGB(0,0,0),1.0f,0L);

//Beginthescene

if(SUCCEEDED(m_pd3dDevice->BeginScene()))

{

m_pd3dDevice->SetStreamSource(0,m_pVB,sizeof(CUSTOMVERTEX));


m_pd3dDevice->DrawPrimitive(D3DPT_TRIANGLEFAN,0,NUM_TRIS);

m_pd3dDevice->EndScene();

}

returnS_OK;

}

TheRendermethodfirstclearstheviewportusingClear.Then,withintheBeginScne/EndScenepairitusesSetStreamSourcetoinformtheruntimethatitusesvertexbufferm_pVBwithastrideofthesizeofthecustomvertextype.Then,itinformstheruntimethatitusesaflexiblevertexformat(FVF)shader,thesimplesttype.FinallyitinvokesDrawPrimitivetorenderthequad.

Otherfunctions

DeleteDeviceObjectsiscalledwhentheapplicationexits,orifthedevicechanges.Youusethismethodtodeletedevicedependentobjects.

ConfirmDevicechecksthedeviceforsomeminimumsetofcapabilities.Itiscalledduringthedeviceinitialization.

InvalidateDeviceObjectsiscalledwhenthedevicedependentobjectsmightbe

removed.Devicedependentobjectssuchasvertexbuffersareusuallyaddedtothismethod.

OneTimeSceneInitisprovidedforcodethatneedstorunduringtheinitialapplicationstartup.

DirectXDevforgraphics,networking,andinputathttp://DISCUSS.MICROSOFT.COM/archives/DIRECTXDEV.html.


ApplicationWizardTheMicrosoft®DirectX®AppWizardcreatesasmallC++templateapplicationthatcanintegratethecommonDirectXcomponents—MicrosoftDirect3D®,MicrosoftDirectInput®,MicrosoftDirectMusic®,MicrosoftDirectSound®,andMicrosoftDirectPlay®.Itprovidesbasic,easy-to-build-uponfunctionallyanddemonstratestheuseofeachcomponent.

Alongwiththetemplate,AppWizardincludesthesameC++classesfoundintheDirectXsoftwaredevelopmentkit(SDK)commondirectory.TheseC++classesperformminimalwrappingofDirectXtogetyouupandrunningquickly.AlltheDirectXSDKsamplesmakeuseoftheseclasses.Forexample,theDirect3DsamplesuseD3dapp.*,theDirectMusicsamplesuseDmutil.*,theDirectSoundsamplesuseDsutil.*,andtheDirectPlaysamplesuseNetconnect.*.

TheAppWizardtargetaudienceisamateurC++gamedevelopers,3-Dhobbyists,andaudiohobbyists(whodonotneed3-D).

RunningAppWizard

AppWizardislaunchedfromMicrosoftVisualStudio®6.0whenyoucreateanewproject.ItisoneoftheprojecttypesavailablewhenyouchooseFile,New,thentheProjectstab,asshowninthefollowingexample.

WhenyouenteraprojectnameandclickOK,thewizardpresentsaseriesofdialogboxestoallowyoutoconfiguretheDirectXservicesthattheapplicationwillneed.ThenumberofdialogboxesgeneratedbythewizarddependonwhichDirectXtechnologiesyouselect(Direct3D,DirectInput,andDirectPlayeachgeneratetheirowndialogboxes).ThefilesincludedintheprojectdependontheDirectXtechnologiesselected,aswellastheMicrosoftWindows®technologiesselected—MicrosoftWin32®,MicrosoftFoundationClasses(MFC),andGraphicsDeviceInterface(GDI).Youselectthesetechnologiesonthefirstpageofthewizard,whichisshowninthefollowingexample.

Thewizardhasthreesteps:Step1istheopeningpage,step2istheDirect3Dpage,andstep3istheDirectInputpage.TheDirectMusicandDirectSoundoptionsdonotgenerateadditionalpagesbuttheDirectPlayPeer-to-Peeroptionwillgenerateanadditionalpage.

Thewizardusesoneoffourbasetemplates,basedontheoptionsyouselect.

1. ForanapplicationthatisnotMFC-basedandusesDirect3D,chooseSingledocumentwindowandDirect3D.Thisisthestandardcaseandissimilartotheapplicationusedinthedolphinsample.

2. ForanapplicationthatisMFC-basedandusesDirect3D,chooseMFCdialogbasedandDirect3D.TheapplicationwillbesimilartotheMFCfogsample.

3. ForaWindowsapplicationthatusesGDIbutnotMFC,chooseSingledocumentwindow.ThisapplicationcanuseCreateWindowandbasicGameLoopduringidletime.

4. ForanapplicationthatusesGDIandisMFC-based,chooseMFCdialogbased.TheapplicationwillbesimilartotheMFCAppWizarddialogtemplate.

TheDirect3D,DirectInput,andDirectPlaycheckboxeseachaddanotherpagetothewizard.Thesepagesaredescribedinthefollowingsections.

Direct3DPage

ThefollowingDirect3DpageisshownimmediatelyafterthefirstpageifyouselectedtheDirect3Dcheckboxinstep1.

TheDirect3Dpageisstep2becausestep1wasthefirstpageofthewizard.

TheDirect3Dexclusiveoptionsare:

1. Blank.NoDirect3Dobjectiscreated.2. Triangle.Createsasimpleobjectwithtwoback-to-backtriangles.3. Teapot.CreatesacomplexobjectusingD3DXCreateTeapot.

IfDirect3Dfontsischecked,theprojectincludesD3dfont.cppandD3dfont.h.Otherwise,theprojectusesD3DXFonttodisplay3-Dfonts.

If3Dmeshesischecked,theprojectincludesD3dfile.cppandD3dfile.h.

DirectInputPage

ThefollowingDirectInputpageisshownimmediatelyaftertheDirect3DpageifyouselectedtheDirectInputcheckboxinstep1.

TheDirectInputpageisstep3.Theoptionsonthispageare:

DirectInputactionmapping.UsesActionMappingtogatherinputdata.DirectInputkeyboarddevice.Usesasimplekeyboarddevicetogatherinputdata.

IfyoucheckedDirectInputinstep1,theprojectwillincludeDiutil.cppandDiutil.cppfiles.TheDirectXSDKsample,Root\Samples\bin\Donut3D.exe,usestheseclassfiles.

TheapplicationwilluseeitherActionMapperorakeyboarddeviceobjecttorecordkeystate.Ifneitherischecked,DirectInputwilluseWM_KEYDOWNmessagestorecordkeystate.

DirectMusicandDirectSoundCheckBoxes

Thesecheckboxesappearonpage1ofthewizard.Theydonoaddpagestothewizard.

IfDirectMusicischecked,theprojectwillincludeDmutil.cppandDmutil.h.TheDirectMusicsamplesusethesefiles.

IfDirectSoundischecked,theprojectwillincludeDsutil.cppandDsutil.h.TheDirectSoundsamplesusethesefilestoloadandplaysounds.

IfbothDirectMusicandDirectSoundarechecked,DirectMusicisusedtoloadandplaythesounds,butDsutil.*isstillincludedintheproject.

IfeitherDirectMusicorDirectSoundischecked,Bounce.wavisincludedintheproject.PressingtheAkeywillplaythesound.

IfneitherDirectMusicnorDirectSoundischecked,bounce.wavisnotincludedandtheAkeyisnotrecorded,noristheHelpstringdisplayed.

DirectPlayPage

ThefollowingDirectPlaypageisshownimmediatelyaftertheDirectInputpageifyouselectedtheDirectPlayPeer-to-Peercheckboxinstep1.

TheDirectPlaypageisstep4,assumingthatstep1wasthefirstpageofthewizard,step2wastheDirect3Dpage,andstep3wastheDirectInputpage.

IfDirectVoiceischecked,theprojectwillincludeNetvoice.cppandNetvoice.h.TheDirectPlayVoicesamplesusethesefiles.

TheprojectwillintegratetheNetConnectDirectPlayconnectiondialogboxesintotheapplication.WhentheNetConnectdialogboxesfinish,anactiveDirectPlayconnectionorfailureresults.Ifsuccessful,thearrowkeystateispassedbetweenallplayersusingDirectPlay.

IfDirectInputActionMapperisused,DirectPlaysendstheaxisdataacrossthenetwork;otherwiseitsendsthestateofthefourarrowkeys.


DirectXGraphicsC/C++TutorialsThetutorialsinthissectionshowhowtouseMicrosoft®Direct3D®andDirect3DXinaC/C++applicationforcommontasks.Thetasksaredividedintorequiredsteps.Insomecases,stepsareorganizedintosubstepsforclarity.

Thefollowingtutorialsareprovided.

Tutorial1:CreatingaDeviceTutorial2:RenderingVerticesTutorial3:UsingMatricesTutorial4:CreatingandUsingLightsTutorial5:UsingTextureMapsTutorial6:UsingMeshes

NoteThesamplecodeinthesetutorialsisfromsourceprojectswhoselocationisprovidedineachtutorial.

ThesamplefilesinthesetutorialsarewritteninC++.IfyouareusingaCcompiler,youmustmaketheappropriatechangestothefilesforthemtosuccessfullycompile.Attheveryleast,youneedtoaddthevtableandthispointerstotheinterfacemethods.

SomecommentsintheincludedsamplecodemightdifferfromthesourcefilesintheMicrosoftPlatformSoftwareDevelopmentKit(SDK).Changesaremadeforbrevityonlyandarelimitedtocommentstoavoidchangingthebehaviorofthesamplecode.

SeeAlso

DirectXGraphicsC/C++Samples


Direct3DC/C++ReferenceThissectioncontainsreferenceinformationfortheAPIelementsprovidedbyMicrosoft®Direct3D®.Referencematerialisdividedintothefollowingcategories.

InterfacesFunctionsMacrosVertexShaderDeclaratorMacrosStructuresEnumeratedTypesOtherTypesTextureArgumentFlagsFlexibleVertexFormatFlagsReturnValues


Direct3DXC/C++ReferenceThissectioncontainsreferenceinformationfortheAPIelementsprovidedbytheDirect3DXutilitylibrary.Referencematerialisdividedintothefollowingcategories.

InterfacesFunctionsMacrosStructuresEnumeratedTypesandFlagsC++SpecificFeaturesReturnValues


XFileC/C++ReferenceThissectioncontainsreferenceinformationfortheapplicationprogramminginterface(API)elementsyouusetoworkwithMicrosoft®DirectX®.xfiles.

InterfacesFunctionsStructuresReturnValuesXFileFormatReference


GettingStartedwithDirect3DThissectionprovidesabriefintroductiontothethree-dimensional(3-D)graphicsfunctionalityintheMicrosoft®Direct3D®applicationprogrammerinterface(API).HereyouwillfindanoverviewofthegraphicspipelineandtutorialstohelpyougetbasicDirect3Dfunctionalityupandrunningquickly.

Direct3DArchitectureDirectXGraphicsC/C++Tutorials


UsingDirect3DThissectionexplainstheoperationoftheMicrosoft®Direct3D®fixedfunctionpipeline.Thepipelineconsistsofseveralbuildingblocks.Theseblocksaredetailedinthefollowingsections.

VertexData

Transforms

ViewportsandClipping

LightsandMaterials

Textures

Rendering

AboutDevices


ProgrammablePipelineUsingshadersandeffects,developerscannowprogramthepipeline.Thesetopicsarecoveredinthefollowingsections.

VertexShadersPixelShadersEffects


AdvancedTopics

Microsoft®Direct3D®providesapowerfulsetoftoolsthatyoucanusetoincreasetherealisticappearanceofa3-Dscene.ThissectionpresentsinformationoncommonspecialeffectsthatcanbeproducedwithDirect3D,buttherangeofpossibleeffectsisnotlimitedtothosepresentedhere.Thediscussioninthissectionisorganizedintothefollowingtopics.

AntialiasingBumpMappingEnvironmentMappingGeometryBlendingIndexedVertexBlendingMatrixStacksStencilBufferTechniquesVertexTweeningObjectGeometry


Direct3DAppendixThissectioncontainsadditionalmaterialthatcoverstopicssuchasfileformatsandtipsforperformanceimprovements.

DDSFileFormat

ThissectionexplainstheDDSfileformatindetail.

DeviceStates

Thissectionexplainsdevicestates,whichareusedtosetrenderingandtexturingattributes.

ProgrammingTips

Thesetipsarederivedfromlessonslearnedfromprogrammingtopicssuchastroubleshootingaprogram,implementingmultithreading,oroptimizingcodeforperformance.

XFiles

ThissectionexplainsXfilesindepth,includingtheirarchitecture,thefileformat,andsomesamplesoffileloadingandsaving.

MeshViewHelp

Thissectionoutlinesthefunctionalitythatisavailableinthemeshviewexecutable.Thishandyexecutablecanbeusedtoexperimentwithmeshesbyapplyingdifferentmeshutilityoperations.ThisapplicationispartoftheSDKinstall.

MicrosoftDirectX8.1(version1.0,1.1)

CreateaVertexShader

Thisexamplecreatesavertexshaderthatappliesaconstantcolortoanobject.TheexamplewillshowthecontentsoftheshaderfileaswellasthecoderequiredintheapplicationtosetuptheMicrosoft®Direct3D®pipelinefortheshaderdata.

Tocreateavertexshader

Step1:DeclarethevertexdataStep2:DesigntheshaderfunctionalityStep3:CheckforvertexshadersupportStep4:DeclaretheshaderregistersStep5:CreatetheshaderStep6:Rendertheoutputpixels

IfyoualreadyknowhowtobuildandrunDirect3Dsamples,youcancutandpastecodefromthisexampleintoyourexistingapplication.

Step1:Declarethevertexdata

Thisexampleusesaquadrilateralthatismadeupoftwotriangles.Thevertexdatawillcontain(x,y,z)positionandadiffusecolor.TheD3DFVF_CUSTOMVERTEXmacroisdefinedtomatchthevertexdata.Thevertexdataisdeclaredinaglobalarrayofvertices(g_Vertices).Thefourverticesarecenteredabouttheorigin,andeachvertexisgivenadifferentdiffusecolor.

//Declarevertexdatastructure.

structCUSTOMVERTEX

{

FLOATx,y,z;

DWORDdiffuseColor;

};

//DeclarecustomFVFmacro.

#defineD3DFVF_CUSTOMVERTEX(D3DFVF_XYZ|D3DFVF_DIFFUSE)

//Declarethevertexpositionanddiffusecolordata.

CUSTOMVERTEXg_Vertices[]=

{

//xyzdiffusecolor

{-1.0f,-1.0f,0.0f,0xffff0000},//red-bottomright

{+1.0f,-1.0f,0.0f,0xff00ff00},//green-bottomleft

{+1.0f,+1.0f,0.0f,0xff0000ff},//blue-topleft

{-1.0f,+1.0f,0.0f,0xffffff00},//redandgreen=yellow-topright

};

Step2:Designtheshaderfunctionality

Thisshaderappliesaconstantcolortoeachvertex.TheshaderfileVertexShader.vshfollows:

vs.1.0//versioninstruction

m4x4oPos,v0,c0//transformverticesbyview/projectionmatrix

movoD0,c4//loadconstantcolor

Thisfilecontainsthreeinstructions.

Thefirstinstructioninashaderfilemustbetheshaderversiondeclaration.Thisinstruction(vs)declaresthevertexshaderversion,whichis1.0inthiscase.

Thesecondinstruction(m4x4)transformstheobjectverticesusingtheview/projectionmatrix.Thematrixisloadedintofourconstantregistersc0,c1,c2,c3(asshownbelow).

Thethirdinstruction(mov)copiestheconstantcolorinregisterc4totheoutputdiffusecolorregisteroD0.Thisresultsincoloringtheoutputvertices.

Step3:Checkforvertexshadersupport

Thedevicecapabilitycanbequeriedforvertexshadersupportbeforeusingavertexshader.

D3DCAPS8caps;

m_pd3dDevice->GetDeviceCaps(∩);//initializem_pd3dDevicebeforeusingif(D3DSHADER_VERSION_MAJOR(caps.VertexShaderVersion)<1)

returnE_FAIL;

ThecapsstructurereturnsthefunctionalcapabilitiesofthehardwareafterGetDeviceCapsiscalled.UsetheD3DSHADER_VERSION_MAJORmacrototestthesupportedversionnumber.Iftheversionnumberislessthan1.0,thiscallwillfail.Theresultofthismethodshouldbeusedtocontrolwhetherornot

vertexshadersareinvokedbyanapplication.

Step4:Declaretheshaderregisters

Theshaderiscreatedbydeclaringtheshaderregistersandcompilingtheshaderfile.Oncecreated,Direct3Dreturnsashaderhandle,whichisanintegernumberthatisusedtoidentifytheshader.

//Createtheshaderdeclaration.

DWORDdwDecl[]=

{

D3DVSD_STREAM(0),

D3DVSD_REG(D3DVSDE_POSITION,D3DVSDT_FLOAT3),

D3DVSD_REG(D3DVSDE_DIFFUSE,D3DVSDT_D3DCOLOR),

D3DVSD_END()

};

Thevertexdeclarationdeclaresthemappingbetweeninputdatastreamsandvertexbuffers.Multiplestreamscanbedeclaredintheshaderdeclaration,uptothenumberspecifiedintheMaxStreamscap.VertexbuffersareassociatedwithinputstreamsusingSetStreamSourceasillustratedinstep5.

Step5:Createtheshader

Theshaderisassembledandcreatednext.

//Createthevertexshader.

TCHARstrPath[512];//locationoftheshaderfile

LPD3DXBUFFERpCode;//assembledshadercode

DXUtil_FindMediaFile(strPath,_T("VertexShader.vsh"));

D3DXAssembleShaderFromFile(strPath,0,NULL,&pCode;,NULL);//assembleshadercode

m_pd3dDevice->CreateVertexShader(dwDecl,(DWORD*)pCode->GetBufferPointer(),&m;_hVertexShader,0)))

pCode->Release();

Oncetheshaderfileislocated,D3DXAssembleShaderFromFilereadsandvalidatestheshaderinstructions.CreateVertexShadertakestheshaderdeclarationandtheassembledinstructionsandcreatestheshader.Itreturnstheshaderhandle,whichisusedtorendertheoutput.

CreateVertexShadercanbeusedtocreateprogrammableorfixedfunctionshaders.Programmableshadersaregeneratedifapointertoashaderdeclarationispassedasthesecondparameter.Otherwise,afixedfunctionvertexshaderis

generatedifNULLispassedasthesecondparameter.

Step6:Rendertheoutputpixels

Hereisanexampleofthecodethatcouldbeusedintherenderlooptorendertheobject,usingthevertexshader.Therenderloopupdatesthevertexshaderconstantsasaresultofchangesinthe3-DsceneanddrawstheoutputverticeswithacalltoDrawPrimitive.

//Turnlightingoff.Thisisincludedforclaritybutisnotrequired.


//Updatevertexshaderconstantsfromviewprojectionmatrixdata.

D3DXMATRIXmat,matView,matProj;

D3DXMatrixMultiply(&mat;,&matView;,&matProj;);

D3DXMatrixTranspose(&mat;,&mat;);

m_pd3dDevice->SetVertexShaderConstant(0,&mat;,4);

//Declareanddefinetheconstantvertexcolor.

floatcolor[4]={0,1,0,0};

m_pd3dDevice->SetVertexShaderConstant(4,&color;,1);

//Rendertheoutput.


m_pd3dDevice->SetVertexShader(m_hVertexShader);


Lightingisturnedoffjusttomakeitclearthatthevertexcolorisfromtheshaderonly.Thisstatementisoptionalinthisexample.

Theviewandprojectionmatrixescontaincamerapositionandorientationdata.Gettingupdateddataandupdatingtheshaderconstantregistersisincludedintherenderloopbecausethescenemightchangebetweenrenderedframes.

Asusual,DrawPrimitiverenderstheoutputdatausingthevertexdataprovidedfromSetStreamSource.SetVertexShaderiscalledtotellDirect3Dtousethevertexshader.Theresultofthevertexshaderisshowninthefollowingimage.Itshowstheconstantcolorontheplaneobject.

MicrosoftDirectX8.1(shaderversions1.0,1.1)

Shader2-Applyvertexcolors

Thisexampleappliesthevertexcolorfromthevertexdatatotheobject.Thevertexdatacontainspositiondataaswellasdiffusecolordata.Thisisreflectedinthevertexdeclarationandthefixedvertexfunctionmacro.Theseareshownbelow.

structCUSTOMVERTEX_POS_COLOR

{

floatx,y,z;

DWORDdiffuseColor;

};

#defineD3DFVF_CUSTOMVERTEX_POS_COLOR(D3DFVF_XYZ|D3DFVF_DIFFUSE)

//Createvertexdatawithpositionandtexturecoordinates.

CUSTOMVERTEX_POS_COLORg_Vertices[]=

{

//xyzdiffuse

{-1.0f,0.25f,0.0f,0xffff0000,}, //-bottomright-red

{0.0f,0.25f,0.0f,0xff00ff00,}, //-bottomleft-green

{0.0f,1.25f,0.0f,0xff0000ff,}, //-topleft-blue

{-1.0f,1.25f,0.0f,0xffffffff,}, //-topright-white

};

Thevertexshaderdeclarationneedstoreflectthepositionandcolordataalso.

DWORDdwDecl2[]=

{

D3DVSD_STREAM(0),

D3DVSD_REG(0,D3DVSDT_FLOAT3),//Register0willcontainthepositiondata.

D3DVSD_REG(1,D3DVSDT_D3DCOLOR),//Register1willcontainthecolordata.

D3DVSD_END()

};

Onewayfortheshadertogetthetransformationmatrixisfromaconstantregister.ThisisdonebycallingSetVertexShaderConstant.

D3DXMATRIXmat;

D3DXMatrixMultiply(&mat;,&m;_matView,&m;_matProj);


hr=m_pd3dDevice->SetVertexShaderConstant(1,&mat;,4);

if(FAILED(hr))returnhr;

Thisdeclarationdeclaresonestreamofdata,whichcontainsthepositionandthe

colordata.Thecolordataisassignedtovertexregister7.

Lastly,hereistheshaderfile.

vs.1.0;versioninstruction

m4x4oPos,v0,c0;transformverticesbyview/projectionmatrix

movoD0,v1;loadcolorfromregister7todiffusecolor

Itcontainsthreeinstructions.Thefirstisalwaystheversioninstruction.Thesecondinstructiontransformsthevertices.Thethirdinstructionmovesthecolorinthevertexregistertotheoutputdiffusecolorregister.Theresultisoutputverticesusingthevertexcolordata.

Theresultingoutputlookslikethefollowing:

//Hereisanexampleoftheclassusedtoproducethisvertexshader.

//Thisexampleisforillustrationonly.Ithasnotbeenoptimizedforperformance.

//CVShader.h

//Usevertexcolortocolortheobject.

CUSTOMVERTEX_POS_COLORg_VerticesVS[]=

{

//xyzdiffuse

{-1.0f,0.25f,0.0f,0xffff0000,}, //-bottomright-red

{0.0f,0.25f,0.0f,0xff00ff00,}, //-bottomleft-green

{0.0f,1.25f,0.0f,0xff0000ff,}, //-topleft-blue

{-1.0f,1.25f,0.0f,0xffffffff,}, //-topright-red

};

classCVShader

{

public:

CVShader();

HRESULTConfirmDevice(D3DCAPS8*pCaps,DWORDdwBehavior,D3DFORMATFormat);

HRESULTDeleteDeviceObjects();

HRESULTRender();

HRESULTRestoreDeviceObjects(LPDIRECT3DDEVICE8l_pd3dDevice);

HRESULTInitMatrices();

HRESULTUpdateVertexShaderConstants();

private:

LPDIRECT3DVERTEXBUFFER8 m_pQuadVB;

LPDIRECT3DDEVICE8 m_pd3dDevice;

DWORD m_hVertexShader;

D3DXMATRIX m_matView;

D3DXMATRIX m_matProj;

};

CVShader::CVShader()

{

m_pQuadVB =NULL;

m_pd3dDevice =NULL;

m_hVertexShader =0;

}

HRESULTCVShader::ConfirmDevice(D3DCAPS8*pCaps,DWORDdwBehavior,

D3DFORMATFormat)

{

if(D3DSHADER_VERSION_MAJOR(pCaps->VertexShaderVersion)<1)

returnE_FAIL;

returnS_OK;

}

HRESULTCVShader::DeleteDeviceObjects()

{

SAFE_RELEASE(m_pQuadVB);

HRESULThr;

if(m_hVertexShader>0)

{

hr=m_pd3dDevice->DeleteVertexShader(m_hVertexShader);

if(FAILED(hr))

{

::MessageBox(NULL,"","DeleteVertexShaderfailed",MB_OK);

returnE_FAIL;

}

m_hVertexShader=0;

}

//localtothisclass

m_pd3dDevice=NULL;

returnS_OK;

}

HRESULTCVShader::InitMatrices()

{

HRESULThr;

D3DXVECTOR3from(0.0f,0.0f,3.0f);

D3DXVECTOR3at(0.0f,0.0f,0.0f);

D3DXVECTOR3up(0.0f,1.0f,0.0f);

D3DXMATRIXmatWorld;

D3DXMatrixIdentity(&matWorld;);

hr=m_pd3dDevice->SetTransform(D3DTS_WORLD,&matWorld;);

D3DXMatrixIdentity(&m;_matView);

D3DXMatrixLookAtLH(&m;_matView,&from;,&at;,&up;);

m_pd3dDevice->SetTransform(D3DTS_VIEW,&m;_matView);

D3DXMatrixIdentity(&m;_matProj);

D3DXMatrixPerspectiveFovLH(&m;_matProj,D3DX_PI/4,1.0f,0.5f,1000.0f);

m_pd3dDevice->SetTransform(D3DTS_PROJECTION,&m;_matProj);

returnS_OK;

}

HRESULTCVShader::Render()

{

if(m_pQuadVB)

{

HRESULThr;

hr=m_pd3dDevice->SetRenderState(D3DRS_LIGHTING,FALSE);

UpdateVertexShaderConstants();

hr=m_pd3dDevice->SetStreamSource(0,m_pQuadVB,

sizeof(CUSTOMVERTEX_POS_COLOR));

hr=m_pd3dDevice->SetVertexShader(m_hVertexShader);

hr=m_pd3dDevice->DrawPrimitive(D3DPT_TRIANGLEFAN,0,2);

}

returnS_OK;

}

HRESULTCVShader::RestoreDeviceObjects(LPDIRECT3DDEVICE8l_pd3dDevice)

{

HRESULThr;

if(l_pd3dDevice==NULL)

{

::MessageBox(NULL,"","InvalidD3D8Deviceptr",MB_OK);

returnE_FAIL;

}

else

m_pd3dDevice=l_pd3dDevice;

InitMatrices();

//CreatequadVertexBuffer.

hr=m_pd3dDevice->CreateVertexBuffer(4*sizeof(CUSTOMVERTEX_POS_COLOR),

D3DUSAGE_WRITEONLY,

D3DFVF_CUSTOMVERTEX_POS_COLOR,

D3DPOOL_DEFAULT,

&m;_pQuadVB);


//FillthequadVB.

CUSTOMVERTEX_POS_COLOR1*pVertices=NULL;

hr=m_pQuadVB->Lock(0,4*sizeof(CUSTOMVERTEX_POS_COLOR),(BYTE**)&pVertices;,0);


for(DWORDi=0;i<4;i++)

pVertices[i]=g_VerticesVS2[i];

m_pQuadVB->Unlock();


TCHARstrVertexShaderPath[512];

LPD3DXBUFFERpCode;

DWORDdwDecl2[]=

{

D3DVSD_STREAM(0),

D3DVSD_REG(0,D3DVSDT_FLOAT3),

D3DVSD_REG(1,D3DVSDT_D3DCOLOR),

D3DVSD_END()

};

//Findthevertexshaderfile.

DXUtil_FindMediaFile(strVertexShaderPath,_T("VShader.vsh"));


if(FAILED(hr=D3DXAssembleShaderFromFile(strVertexShaderPath,

0,NULL,&pCode;,NULL)))

returnhr;


if(SUCCEEDED(hr=m_pd3dDevice->CreateVertexShader(dwDecl2,

(DWORD*)pCode->GetBufferPointer(),&m;_hVertexShader,0)))

pCode->Release();

returnhr;

}

HRESULTCVShader::UpdateVertexShaderConstants()

{

HRESULThr;

D3DXMATRIXmat;



hr=m_pd3dDevice->SetVertexShaderConstant(1,&mat;,4);

returnhr;

}


Shader3-Applyatexturemap

Thisexampleappliesatexturemaptotheobject.

Thevertexdatacontainsobjectpositiondataaswellastexturepositionoruvdata.Thiscauseschangestothevertexdeclarationstructureandthefixedvertexfunctionmacro.Thevertexdataisalsoshownbelow.

structCUSTOMVERTEX_POS_TEX1

{

floatx,y,z; //objectpositiondata

floattu1,tv1; //texturepositiondata

};

#defineD3DFVF_CUSTOMVERTEX_POS_TEX1(D3DFVF_XYZ|D3DFVF_TEX1)

CUSTOMVERTEX_POS_TEX1g_Vertices[]=

{

//xyzu1v1

{-0.75f,-0.5f,0.0f,0.0f,0.0f}, //-bottomright

{0.25f,-0.5f,0.0f,1.0f,0.0f}, //-bottomleft

{0.25f,0.5f,0.0f,1.0f,-1.0f}, //-topleft

{-0.75f,0.5f,0.0f,0.0f,-1.0f}, //-topright

};

D3DUtil_CreateTexture(m_pd3dDevice,_T("earth.bmp"),&m;_pTexture0,D3DFMT_R5G6B5);

Thetextureimagemustbeloaded.Inthiscase,thefile"earth.bmp"containsa2-Dtexturemapoftheearthandwillbeusedtocolortheobject.

Thevertexshaderdeclarationneedstoreflecttheobjectpositionandtexturepositiondata.

DWORDdwDecl2[]=

{

D3DVSD_STREAM(0),

D3DVSD_REG(D3DVSDE_POSITION,D3DVSDT_FLOAT3),

D3DVSD_REG(8,D3DVSDT_FLOAT2),

D3DVSD_END()

};

Thisdeclarationdeclaresonestreamofdatathatcontainstheobjectpositionandthetexturepositiondata.Thetexturepositiondataisassignedtovertexregister8.

TherenderingcodetellsMicrosoft®Direct3D®wheretofindthedatastreamandtheshader,andsetsuptexturestagesbecauseatexturemapisbeingapplied.

m_pd3dDevice->SetStreamSource(0,m_pQuadVB,sizeof(CUSTOMVERTEX_POS_TEX1));


m_pd3dDevice->SetTextureStageState(0,D3DTSS_COLOROP,D3DTOP_MODULATE);

m_pd3dDevice->SetTextureStageState(0,D3DTSS_COLORARG1,D3DTA_TEXTURE);

m_pd3dDevice->SetTextureStageState(0,D3DTSS_COLORARG2,D3DTA_DIFFUSE);




Becausethereisasingletexture,thetexturestagestatesneedtobesetfortexturestate0.ThesemethodstellDirect3Dthatthetexelvalueswillbeusedtoprovidediffusecolorfortheobjectvertices.Inotherwords,a2-Dtexturemapwillbeappliedlikeadecal.

Hereistheshaderfile.

vs.1.0 ;versioninstruction

m4x4oPos,v0,c0 ;transformverticesbyview/projectionmatrix

movoT0,v8 ;movetexturecolortooutputtextureregister

Theshaderfilecontainsthreeinstructions.Thefirstisalwaystheversioninstruction.Thesecondinstructiontransformsthevertices.Thethirdinstructionmovesthetexturecolorsfromregisterv8totheoutputdiffusecolorregister.Thatresultsinatexturemappedobject,whichisshownbelow.


Shader4-Applyatexturemapwithlighting

Thisexampleusesavertexshadertoapplyatexturemapandaddlightingtothescene.Theobjectusedisasphere.Thesamplecodeappliesatexturemapoftheearthtothesphereandappliesdiffuselightingtosimulatenightandday.

ThecodesampleaddstotheShader3examplebyaddinglightingtoatexturemappedobject.RefertoShader3forinformationaboutloadingthetexturemapandsettingupthetexturestagestates.

ThereisadetailedexplanationofthesamplecodeframeworkatSampleFramework.Youcancutandpastethesamplecodeintothesampleframeworktoquicklygetaworkingsample.

CreateVertexShader

ThevertexdatahasbeenmodifiedfromtheShader3sampletoincludevertexnormals.Forlightingtoappear,theobjectmusthavevertexnormals.Thedatastructureforthevertexdataandtheflexiblevertexformat(FVF)macrousedtodeclarethedatatypeareshownbelow.

structCUSTOMVERTEX_POS_NORM_COLOR1_TEX1

{

floatx,y,z;//position

floatnx,ny,nz;//normal

DWORDcolor1;//diffusecolor

floattu1,tv1;//texturecoordinates

};

#defineD3DFVF_CUSTOMVERTEX_POS_NORM_COLOR1_TEX1(D3DFVF_XYZ|D3DFVF_NORMAL|D3DFVF_DIFFUSE|D3DFVF_TEX1)

Ashaderdeclarationdefinestheinputvertexregistersandthedataassociatedwiththem.ThismatchestheFVFmacrousedtocreatethevertexbufferdatalater.

DWORDdwDecl[]=

{

D3DVSD_STREAM(0),

D3DVSD_REG(0,D3DVSDT_FLOAT3),//position

D3DVSD_REG(4,D3DVSDT_FLOAT3),//normal

D3DVSD_REG(7,D3DVSDT_D3DCOLOR),//diffusecolor

D3DVSD_REG(8,D3DVSDT_FLOAT2),//texturecoordinate

D3DVSD_END()

};

Thisdeclaresonestreamofdata,whichcontainsthevertexposition,normal,diffusecolor,andtexturecoordinates.Theintegerineachlineistheregisternumberthatwillcontainthedata.So,thetexturecoordinatedatawillbeinregisterv8,forinstance.

Next,createtheshaderfile.YoucancreateashaderfromanASCIItextstringorloaditfromashaderfilethatcontainsthesameinstructions.Thisexampleusesashaderfile.

//Shaderfile

//v7vertexdiffusecolorusedforthelightcolor

//v8texture

//c4viewprojectionmatrix

//c12lightdirection

vs.1.0//versioninstruction

m4x4oPos,v0,c4//transformverticesusingviewprojectiontransform

dp3r0,v4,c12//performlightingNdotLcalculationinworldspace

muloD0,r0.x,v7//calculatefinalpixelcolorfromlightintensityand

//interpolateddiffusevertexcolor

movoT0.xy,v8//copytexturecoordinatestooutput

Youalwaysentertheversioninstructionfirst.ThelastinstructionmovesthetexturedatatotheoutputregisteroT0.Afteryouwritetheshaderinstructions,youcanusethemtocreatetheshader.

//Nowthatthefileexists,useittocreateashader.

TCHARstrVertexShaderPath[512];

LPD3DXBUFFERpCode;

DXUtil_FindMediaFile(strVertexShaderPath,_T("VShader3.vsh"));

D3DXAssembleShaderFromFile(strVertexShaderPath,0,NULL,&pCode,NULL);

m_pd3dDevice->CreateVertexShader(dwDecl,(DWORD*)pCode->GetBufferPointer(),&m_hVertexShader,0);

pCode->Release();

Afterthefileislocated,Direct3Dcreatesthevertexshaderandreturnsashaderhandleandtheassembledshadercode.Thissampleusesashaderfile,whichisonemethodforcreatingashader.TheothermethodistocreateanASCIItextstringwiththeshaderinstructionsinit.Foranexample,seeProgrammableShadersforDirectX8.0.

VertexShaderConstants

http://msdn.microsoft.com/library/Welcome/dsmsdn/directx01152001.htm

Youcandefinevertexshaderconstantsoutsideoftheshaderfileasshowninthefollowingexample.Here,youuseconstantstoprovidetheshaderwithaview/projectionmatrix,adiffuselightcolor,RGBA,andthelightdirectionvector.

floatconstants[4]={0,0.5f,1.0f,2.0f};

m_pd3dDevice->SetVertexShaderConstant(0,&constants;,1);

D3DXMATRIXmat;



m_pd3dDevice->SetVertexShaderConstant(4,&mat;,4);

floatcolor[4]={1,1,1,1};

m_pd3dDevice->SetVertexShaderConstant(8,&color;,1);

floatlightDir[4]={-1,0,1,0};//fatterslice

m_pd3dDevice->SetVertexShaderConstant(12,&lightDir;,1);

Youcanalsodefineconstantsinsideashaderusingthedefinstruction

Render

Afteryouwritetheshaderinstructions,connectthevertexdatatothecorrectvertexregistersandinitializetheconstants,youshouldrendertheoutput.RenderingcodetellsDirect3DwheretofindthevertexbufferdatastreamandprovidesDirect3Dwiththeshaderhandle.Becauseyouuseatexture,youmustsettexturestagestotellDirect3Dhowtousethetexturedata.

//Identifythevertexbufferdatasource.

m_pd3dDevice->SetStreamSource(0,m_pVB,sizeof(CUSTOMVERTEX_POS_NORM_COLOR1_TEX1));

//Identifytheshader.


//Definethetexturestage(s)andsetthetexture(s)used

m_pd3dDevice->SetTextureStageState(0,D3DTSS_COLOROP,D3DTOP_MODULATE);

m_pd3dDevice->SetTextureStageState(0,D3DTSS_COLORARG1,D3DTA_TEXTURE);

m_pd3dDevice->SetTextureStageState(0,D3DTSS_COLORARG2,D3DTA_DIFFUSE);


//Drawtheobject.

DWORDdwNumSphereVerts=2*m_dwNumSphereRings*(m_dwNumSphereSegments+1);

m_pd3dDevice->DrawPrimitive(D3DPT_TRIANGLESTRIP,0,dwNumSphereVerts-2);

//SetthetexturestagetoNULLaftertherendercommands.Leavingthis

//outwillcauseamemoryleak.


Theoutputimagefollows:

Withthetexturemapapplied,thespherelooksliketheplanetEarth.Thelightingcreatesabrighttodarkgradientonthefaceoftheglobe.

AdditionalCode

Thereisadditionalcoderequiredtosupportthisexample.Shownbelowareafewoftheothermethodsforcreatingthesphereobject,loadingthetexture,andcheckingforthecorrectversionofpixelshadersupport.

//Confirmthatthehardwaresupportsversion1shaderinstructions.

if(D3DSHADER_VERSION_MAJOR(pCaps->VertexShaderVersion)<1)

returnE_FAIL;

//Loadtexturemapforthesphereobject.

LPDIRECT3DTEXTURE8m_pTexture0;

D3DUtil_CreateTexture(m_pd3dDevice,_T("earth.bmp"),&m;_pTexture0,D3DFMT_R5G6B5);

//Createthesphereobject.

DWORDdwNumSphereVerts=2*m_dwNumSphereRings*(m_dwNumSphereSegments+1);

//onceforthetop,onceforthebottomvertices

//GettheWorld-View(WV)matrixset.

D3DXMATRIXmatWorld,matView,matWorldView;

m_pd3dDevice->GetTransform(D3DTS_WORLD,&matWorld;);

m_pd3dDevice->GetTransform(D3DTS_VIEW,&matView;);

D3DXMatrixMultiply(&matWorldView;,&matWorld;,&matView;);

m_pd3dDevice->CreateVertexBuffer(

dwNumSphereVerts*sizeof(CUSTOMVERTEX_POS_NORM_COLOR1_TEX1),

D3DUSAGE_WRITEONLY,

D3DFVF_CUSTOMVERTEX_POS_NORM_COLOR1_TEX1,

D3DPOOL_DEFAULT,

&m;_pVB) );

CUSTOMVERTEX_POS_NORM_COLOR1_TEX1*pVertices;

HRESULThr;

hr=m_pVB->Lock(0,dwNumSphereVerts*sizeof(pVertices),

(BYTE**)&pVertices;,0);

if(SUCCEEDED(hr))

{

FLOATfDeltaRingAngle=(D3DX_PI/m_dwNumSphereRings);

FLOATfDeltaSegAngle=(2.0f*D3DX_PI/m_dwNumSphereSegments);

//Generatethegroupofringsforthesphere.

for(DWORDring=0;ring<m_dwNumSphereRings;ring++)

{

FLOATr0=sinf((ring+0)*fDeltaRingAngle);

FLOATr1=sinf((ring+1)*fDeltaRingAngle);

FLOATy0=cosf((ring+0)*fDeltaRingAngle);

FLOATy1=cosf((ring+1)*fDeltaRingAngle);

//Generatethegroupofsegmentsforthecurrentring.

for(DWORDseg=0;seg<(m_dwNumSphereSegments+1);seg++)

{

FLOATx0=r0*sinf(seg*fDeltaSegAngle);

FLOATz0=r0*cosf(seg*fDeltaSegAngle);

FLOATx1=r1*sinf(seg*fDeltaSegAngle);

FLOATz1=r1*cosf(seg*fDeltaSegAngle);

//Addtwoverticestothestrip,whichmakesupthesphere

//(usingthetransformednormaltogeneratetexturecoords).

pVertices->x=x0;

pVertices->y=y0;

pVertices->z=z0;

pVertices->nx=x0;

pVertices->ny=y0;

pVertices->nz=z0;

pVertices->color=HIGH_WHITE_COLOR;

pVertices->tu=-((FLOAT)seg)/m_dwNumSphereSegments;

pVertices->tv=(ring+0)/(FLOAT)m_dwNumSphereRings;

pVertices++;

pVertices->x=x1;

pVertices->y=y1;

pVertices->z=z1;

pVertices->nx=x1;

pVertices->ny=y1;

pVertices->nz=z1;

pVertices->color=HIGH_WHITE_COLOR;

pVertices->tu=-((FLOAT)seg)/m_dwNumSphereSegments;

pVertices->tv=(ring+1)/(FLOAT)m_dwNumSphereRings;

pVertices++;

}

hr=m_pVB->Unlock();

}

}


CreateaPixelShader

ThisexampleusesapixelshadertoapplyaGouraudinterpolateddiffusecolortoageometricplane.TheexamplewillshowthecontentsoftheshaderfileaswellasthecoderequiredintheapplicationtosetuptheMicrosoft®Direct3D®pipelinefortheshaderdata.

Tocreateapixelshader

1. Checkforpixelshadersupport.2. Declarethevertexdata.3. Designthepixelshader.4. Createthepixelshader.5. Rendertheoutputpixels.

IfyoualreadyknowhowtobuildandrunDirect3Dsamples,youshouldbeabletocutandpastecodefromthisexampleintoyourexistingapplication.

Step1:Checkforpixelshadersupport

Tocheckforpixelshadersupport,usethefollowingcode.Thisexamplechecksforpixelshaderversion1.1.

D3DCAPS8caps;

m_pd3dDevice->GetDeviceCaps(∩);//initm_pd3dDevicebeforeusingif(D3DPS_VERSION(1,1)!=caps.PixelShaderVersion)

returnE_FAIL;

Thecapsstructurereturnsthefunctionalcapabilitiesofthepipeline.UsetheD3DPS_VERSIONmacrototestforthesupportedshaderversionnumber.Iftheversionnumberislessthan1.1,thiscallwillfail.Ifthehardwaredoesnotsupporttheshaderversionthatistested,theapplicationwillhavetofallbacktoanotherrenderingapproach(perhapsalowershaderversionisavailable).

Step2:Declarethevertexdata

Thisexampleusesaplane,whichismadeupoftwotriangles.Thedatastructureforeachvertexwillcontainpositionanddiffusecolordata.The

D3DFVF_CUSTOMVERTEXmacrodefinesadatastructuretomatchthevertexdata.Theactualvertexdataisdeclaredinaglobalarrayofverticescalledg_Vertices[].Thefourverticesarecenteredabouttheorigin,andeachvertexisgivenadifferentdiffusecolor.

//Declarevertexdatastructure.

structCUSTOMVERTEX

{

FLOATx,y,z;

DWORDdiffuseColor;

};

//DeclarecustomFVFmacro.

#defineD3DFVF_CUSTOMVERTEX(D3DFVF_XYZ|D3DFVF_DIFFUSE)

//Declarethevertexpositionanddiffusecolordata.

CUSTOMVERTEXg_Vertices[]=

{

//xyzdiffusecolor

{-1.0f,-1.0f,0.0f,0xffff0000},//red-bottomleft

{+1.0f,-1.0f,0.0f,0xff00ff00},//green-bottomright

{+1.0f,+1.0f,0.0f,0xff0000ff},//blue-topright

{-1.0f,+1.0f,0.0f,0xffffffff},//white-topleft

};

Step3:Designthepixelshader

ThisshadermovestheGouraudinterpolateddiffusecolordatatotheoutputpixels.TheshaderfilePixelShader.txtfollows:


movr0,v0//Movethediffusevertexcolortotheoutputregister.

Thefirstinstructioninapixelshaderfiledeclaresthepixelshaderversion,whichis1.0.

Thesecondinstructionmovesthecontentsofthecolorregister(v0)intotheoutputregister(r0).Thecolorregistercontainsthevertexdiffusecolorbecausethevertexdataisdeclaredtocontaintheinterpolateddiffusecolorinstep1.Theoutputregisterdeterminesthepixelcolorusedbytherendertarget(becausethereisnoadditionalprocessing,suchasfog,inthiscase).

Step4:Createthepixelshader

Thepixelshaderiscreatedfromthepixelshaderinstructions.Inthisexample,theinstructionsarecontainedinaseparatefile.Theinstructionscouldalsobeusedinatextstring.

TCHARstrPath[512];//usedtolocatetheshaderfile

LPD3DXBUFFERpCode;//pointstotheassembledshadercode

DXUtil_FindMediaFile(strPath,_T("PixelShader.txt"));

ThisfunctionisahelperfunctionusedbytheSampleFramework.Thesampleframeworkisthefoundationonwhichmanyofthesamplesarebuilt.

D3DXAssembleShaderFromFile(strPath,0,NULL,&pCode;,NULL);//assembleshadercode

m_pd3dDevice->CreatePixelShader((DWORD*)pCode->GetBufferPointer(),&m;_hPixelShader);

Oncetheshaderiscreated,thehandlem_hPixelShaderisusedtorefertoit.

Step5:Rendertheoutputpixels

Renderingtheoutputpixelsisverysimilartousingthefixedfunctionpipelinesequenceofcallsexceptthatthepixelshaderhandleisnowusedtosettheshader.

//Turnlightingoffforthisexample.Itwillnotcontributetothefinalpixelcolor.

//Thepixelcolorwillbedeterminedsolelybyinterpolatingthevertexcolors.






ThesourceofthevertexdataissetwithSetStreamSource.Inthisexample,SetVertexShaderusesthesameFlexibleVertexFormat(FVF)macrousedduringvertexdatadeclarationtotellDirect3Dtodofixedfunctionvertexprocessing.Vertexshadersandpixelshadersmaybeusedtogetherorseparately.Thefixedfunctionpipelinecanalsobeusedinsteadofeitherpixelorvertexshaders.SetPixelShadertellsDirect3Dwhichpixelshadertouse,DrawPrimitivetellsDirect3Dhowtodrawtheplane.

Thegouraudshadedpixelsareshowninthefollowingimage.

PixelShaderExamplescontainsexamplesthatshowhowtoapplytexturemapsandblendbetweentexturesandvertexcolors.


TextureConsiderationsThepixelshadercompletelyreplacesthepixel-blendingfunctionalityspecifiedbytheMicrosoft®DirectX®6.0and7.0multi-texturingapplicationprogramminginterfaces(APIs),specificallythoseoperationsdefinedbytheD3DTSS_COLOROP,D3DTSS_COLORARG1,D3DTSS_COLORARG2,D3DTSS_ALPHAOP,D3DTSS_ALPHAARG1,andD3DTSS_ALPHAARG2texturestagestates,andassociatedargumentsandmodifiers.Whenaproceduralpixelshaderisset,thesestatesareignored.

PixelShadersandTextureStageStates

Whenpixelshadersareinoperation,thefollowingtexturestagestatesarestillobserved.

D3DTSS_ADDRESSUD3DTSS_ADDRESSVD3DTSS_ADDRESSWD3DTSS_BUMPENVMAT00D3DTSS_BUMPENVMAT01D3DTSS_BUMPENVMAT10D3DTSS_BUMPENVMAT11D3DTSS_BORDERCOLORD3DTSS_MAGFILTERD3DTSS_MINFILTERD3DTSS_MIPFILTERD3DTSS_MIPMAPLODBIASD3DTSS_MAXMIPLEVELD3DTSS_MAXANISOTROPYD3DTSS_BUMPENVLSCALED3DTSS_BUMPENVLOFFSETD3DTSS_TEXCOORDINDEXD3DTSS_TEXTURETRANSFORMFLAGS

Becausethesetexturestagestatesarenotpartofthepixelshader,theyarenotavailableatshadercompiletimesothedrivercanmakenoassumptionsaboutthem.Forexample,thedrivercannotdifferentiatebetweenbilinearandtrilinearfilteringatthattime.Theapplicationisfreetochangethesestateswithoutrequiringtheregenerationofthecurrentlyboundshader.

PixelShadersandTextureSampling

Texturesamplingandfilteringoperationsarecontrolledbythestandardtexturestagestatesforminification,magnification,mipfiltering,andthewrapaddressingmodes.Formoreinformation,seeTextureStageStates.Thisinformationisnotavailabletothedriveratshadercompiletime,soshadersmustbeabletocontinueoperationwhenthisstatechanges.Theapplicationisresponsibleforsettingtexturesofthecorrecttype(imagemap,cubemap,volumemap,etc.)neededbythepixelshader.Settingatextureoftheincorrecttypewillproduceunexpectedresults.

Post-ShaderPixelProcessing

Otherpixeloperations—suchasfogblending,stenciloperations,andrendertargetblending—occurafterexecutionoftheshader.Rendertargetblendingsyntaxisupdatedtosupportnewfeaturesasdescribedinthistopic.

PixelShaderInputs

Diffuseandspecularcolorsaresaturated(clamped)totherange0through1beforeusebytheshaderbecausethisistherangeofvalidinputstotheshader.

Colorvaluesinputtothepixelshaderareassumedtobeperspectivecorrect,butthisisnotguaranteedinallhardware.Colorsgeneratedfromtexturecoordinatesbytheaddressshaderarealwaysiteratedinaperspectivecorrectmanner.However,theyarealsoclampedtotherange0to1duringiteration.

PixelShaderOutputs

Theresultemittedbythepixelshaderisthecontentsofregisterr0.Whateveritcontainswhentheshadercompletesprocessingissenttothefogstageandrendertargetblender.


ConfirmingPixelShaderSupportYoucanquerymembersofD3DCAPS8todeterminethelevelofsupportforoperationsinvolvingpixelshaders.ThefollowingtableliststhedevicecapabilitiesrelatedtoprogrammablepixelprocessinginMicrosoft®DirectX®8.1.

Devicecapability Description

MaxPixelShaderValue

Rangeofvaluesthatmaybestoredinregistersis[-MaxPixelShaderValue,MaxPixelShaderValue].

MaxSimultaneousTextures Numberoftexturestagesthatcanbeusedintheprogrammablepixelshader.

PixelShaderVersion Levelofsupportforpixelshaders.

ThePixelShaderVersioncapabilityindicatesthelevelofpixelshadersupported.Onlypixelshaderswithversionnumbersequaltoorlessthanthisvaluewillbesuccessfullycreated.ThemajorversionnumberisencodedinthesecondbyteofPixelShaderVersion.Thelowbytecontainsaminorversionnumber.Thepixelshaderversionisindicatedbythefirsttokenineachshader.

EachimplementationsetsthePixelShaderVersionmembertoindicatethemaximumpixelshaderversionthatitcanfullysupport.ThisimpliesthatimplementationsshouldneverfailthecreationofavalidshaderoftheversionlessthanorequaltotheversionreportedbyPixelShaderVersion.

SettingPixelShaderTextureInputs

Thetexturecoordinatedataisinterpolatedfromthevertextexturecoordinatedataandisassociatedwithaspecifictexturestage.Thedefaultassociationisaone-to-onemappingbetweentexturestagenumberandtexturecoordinatedeclarationorder.Thismeansthatthefirstsetoftexturecoordinatesdefinedinthevertexformatare,bydefault,associatedwithtexturestage0.

Texturecoordinatescanbeassociatedwithanystage,usingeitherofthefollowingtwotechniques.Whenusingafixedfunctionvertexshader,thetexturestagestateflagTSS_TEXCOORDINDEXcanbeusedinIDirect3DDevice8::SetTextureStageStatetoassociatecoordinateswithastage.Otherwise,thetexturecoordinatesareoutputbythevertexshaderoTnregisterswhenusingaprogrammablevertexshader.

SettingthePixelShaderConstantRegisters

Youcanusethefollowingmethodstosetandretrievethevaluesinthepixelshaderconstantregisters.

IDirect3DDevice8::GetPixelShaderConstantIDirect3DDevice8::SetPixelShaderConstant

Inaddition,youcanusethedefinstructiontosettheconstantregistersofapixelshader,insideapixelshader.Thisinstructionmustcomebeforeallotherinstructionsexcepttheversioninstruction.

CompilingandCreatingaPixelShader

TheDirect3DXutilitylibraryprovidesasetoffunctionstocompilepixelshaders.Thefollowingfunctionsareprovided.

D3DXAssembleShaderD3DXAssembleShaderFromFile

TheIDirect3DDevice8::CreatePixelShadercreateapixelshaderinDirectX8.1fromacompiledshaderdeclaration.ThecompiledshaderdeclarationisobtainedfromD3DXAssembleShader.

AgivenshadermightfailcreationbecauseoftherestraintsoftheDirectX8.1hardwaremodel.


PixelShaderExamplesThetopicCreateaPixelShaderprovidesanexampleofhowtouseapixelshadertoapplyasinglediffusecolor.Thefollowingareexamplesofotherpixelshaderfunctions.Eachexamplebuildsonthepreviousexamplebyaddingapieceofadditionalpixelshaderfunctionality.

ApplyaTextureMapBlendaDiffuseVertexColorwithaTextureBlendTwoTexturesUsingaConstantColor

ApplyaTextureMap

Thisexampleappliesatexturemaptoaplane.Thedifferencesbetweenthisexampleandthepreviousexampleareasfollows:

ThevertexdatastructureandtheFlexibleVertexFormat(FVF)macroincludetexturecoordinates.Thevertexdataincludesu,vdata.Thevertexdatanolongerneedsdiffusecolorbecausethepixelcolorswillcomefromthetexturemap.Thetextureislinkedtotexturestage0withSetTexture.Becausethepreviousexampledidnotuseatexture,therewasnoSetTexturemethodused.Theshaderusesthet0textureregisterinsteadofthev0diffusecolorregister.

Thesamplecodefollows:

//Definevertexdatastructure.

structCUSTOMVERTEX

{

FLOATx,y,z;

FLOATu1,v1;

};

//DefinecorrespondingFVFmacro.

#defineD3DFVF_CUSTOMVERTEX(D3DFVF_XYZ|D3DFVF_TEX|D3DFVF_TEXCOORDSIZE2(0))

//Createvertexdatawithpositionandtexturecoordinates.


{

//xyzu1v1

{-1.0f,-1.0f,0.0f,0,1,},

{1.0f,-1.0f,0.0f,1,1,},

{1.0f,1.0f,0.0f,1,0,},

{-1.0f,1.0f,0.0f,0,0,},




};

//Createatexture.ThisfileisintheDirectX8.1mediafromtheSDKdownload.

TCHARstrPath[512];

DXUtil_FindMediaFile(strPath,_T("DX5_Logo.bmp"));



//Createthepixelshader.

DXUtil_FindMediaFile(strPShaderPath,_T("PixelShader2.txt"));

ThisfunctionisahelperfunctionusedbytheSampleFramework.Thesampleframeworkisthefoundationonwhichmanyofthesamplesarebuilt.



//Loadthetextureandrendertheoutputpixels.

m_pd3dDevice->SetTexture(0,m_pTexture0); //loadTSS0fromthetexture


Contentsofthefile"PixelShader2.txt"

//Appliesatexturemaptoobjectvertices.

ps.1.0//Versioninstructionmustbefirstinthefile.

text0//Declaretextureregistert0,whichwillbeloadedfromTextureStage0.

movr0,t0//Movethecontentsofthetextureregister(t0)totheoutputregister(r0).

Theresultingimageisshowninthefollowingexample.

BlendaDiffuseVertexColorwithaTexture

Thisexampleblendsormodulatesthecolorsinatexturemapwiththevertexcolors.Thedifferencesbetweenthisexampleandthepreviousexampleareasfollows:

Thevertexdatastructure,theFVFmacro,andthevertexdataincludediffusecolor.Theshaderfileusesthemultiplyinstruction(mul)toblendormodulatethetexturecolorswiththevertexdiffusecolor.

Thetexturecreateandloadcodeisthesame.Itisincludedhereforcompleteness.

structCUSTOMVERTEX

{

FLOATx,y,z;

DWORDcolor1;

FLOATtu1,tv1;

};

#defineD3DFVF_CUSTOMVERTEX(D3DFVF_XYZ|D3DFVF_DIFFUSE|D3DFVF_TEX1|D3DFVF_TEXCOORDSIZE2(0))


{

//xyzdiffuseu1v1

{-1.0f,-1.0f,0.0f,0xffff0000,0,1,},//red

{1.0f,-1.0f,0.0f,0xff00ff00,1,1,},//green

{1.0f,1.0f,0.0f,0xff0000ff,1,0,},//blue

{-1.0f,1.0f,0.0f,0xffffffff,0,0,},//white




};


TCHARstrPath[512];




//Createthepixelshader.

DXUtil_FindMediaFile(strPShaderPath,_T("PixelShader3.txt"));



//Loadthetextureandrendertheoutputpixels.

m_pd3dDevice->SetTexture(0,m_pTexture0); //loadTSS0fromthetexture




text0//declaretextureregistert0whichwillbeloadedfromTextureStage0

mulr0,v0,t0//v0*t0,thenmovetor0

Theinputstotheshaderareshowninthefollowingexample.Thefirstimageshowsthevertexcolors.Thesecondimageshowsthetexturemap.

Theresultingimageisshowninthefollowingexample.Itshowstheoutput,whichisablendofthevertexcolorandthetextureimage.

BlendTwoTexturesUsingaConstantColor

Thisexampleblendstwotexturemaps,usingthevertexcolor,todeterminehowmuchofeachtexturemapcolortouse.Thedifferencesbetweenthisexampleandthepreviousexampleareasfollows:

Thevertexdatastructure,theFVFmacro,andthevertexdataincludeasecondsetoftexturecoordinatesbecausethereisasecondtexture.SetTextureisalsocalledtwice,usingtwotexturestagestates.Theshaderfiledeclarestwotextureregistersandusesthelinearinterpolate(lrp)instructiontoblendthetwotextures.Thevaluesofthediffusecolorsdeterminetheratiooftexture0totexture1intheoutputcolor.

Hereisthesamplecode.

structCUSTOMVERTEX

{

FLOATx,y,z;

DWORDcolor;

FLOATtu1,tv1;

FLOATtu2,tv2;//asecondsetoftexturecoordinates

};

#defineD3DFVF_CUSTOMVERTEX(D3DFVF_XYZ|D3D_FVF_DIFFUSE|D3DFVF_TEX2|D3DFVF_TEXCOORDSIZE4(0))


{

//xyzcoloru1v1u2v2

{-1.0f,-1.0f,0.0f,0xff0000ff,1.0f,1.0f,1.0f,1.0f},

{+1.0f,-1.0f,0.0f,0xffff0000,0.0f,1.0f,0.0f,1.0f},

{+1.0f,+1.0f,0.0f,0xffffff00,0.0f,0.0f,0.0f,0.0f},

{-1.0f,+1.0f,0.0f,0xffffffff,1.0f,0.0f,1.0f,0.0f},

};


TCHARstrPath[512];

LPDIRECT3DTEXTURE8m_pTexture0,m_pTexture1;



DXUtil_FindMediaFile(strPath,_T("snow2.jpg"));


//Loadthetexturesstages.


m_pd3dDevice->SetTexture(1,m_pTexture1);//Useasecondtexturestage.






ps.1.0//pixelshaderversion

text0//textureregistert0isloadedfromtexturestage0

text1//textureregistert1isloadedfromtexturestage1

movr1,t1//movetextureregister1intooutputregisterr1

lrpr0,v0,t0,r1//linearlyinterpolatebetweent0andr1byaproportion

//specifiedinv0

Theresultingoutputisasfollows:


ConvertingTextureOperations

Pixelshadersextendandgeneralizethemulti-texturecapabilitiesofMicrosoft®DirectX®6.0and7.0inthefollowingways.

Asetofgeneralread/writeregistersisaddedtoenablemoreflexibleexpression.TheserialcascadeusingD3DTA_CURRENTrequiresthespecificationofaseparateresultregisterargumentforeachstage.TheD3DTOP_MODULATE2XandD3DTOP_MODULATE4Xtextureoperationsarebrokenintoseparatemodifiersapplicabletoanyinstructionorthogonally.ThiseliminatestheneedforseparateD3DTOP_MODULATEandD3DTOP_MODULATE2Xoperations.Thebiasandunbiastextureoperationmodifiersareorthogonal.Thiseliminatestheneedforseparateaddandaddbiasoperations.Anoptionalthirdargumentisaddedtomodulateadd,sotheproceduralpixelshadercandoarg1×arg2+arg0.ThiseliminatestheD3DTOP_MODULATEALPHA_ADDCOLORandD3DTOP_MODULATECOLOR_ADDALPHAtextureoperations.Anoptionalthirdargumentisaddedtotheblendoperation,sotheproceduralpixelshadercanusearg0astheblendproportionbetweenarg1andarg2.ThiseliminatestheD3DTOP_BLENDDIFFUSEALPHA,D3DTOP_BLENDTEXTUREALPHA,D3DTOP_BLENDFACTORALPHA,D3DTOP_BLENDTEXTUREALPHAPM,andD3DTOP_BLENDCURRENTALPHAtextureoperations.Textureaddressmodifyingoperations,suchasD3DTOP_BUMPENVMAP,arebrokenoutfromthecolorandalphaoperationsanddefinedasathirdoperationtype,specificallyforoperatingontextureaddresses.

Tosupportthisincreasedflexibilityefficiently,theapplicationprogramminginterface(API)syntaxischangedfromDWORDpairstoanASCIIassemblecodesyntax.Thisexposesthefunctionalityofferedbyproceduralpixelshaders.

NoteWhenyouusepixelshaders,specularaddisnotspecificallycontrolledbyarenderstate,anditisuptothepixelshadertoimplementifneeded.However,fogblendingisstillappliedbythefixedfunctionpipeline.


Debugging

MFCPixelShaderSampleApplication

YoucanusetheMFCPixelShaderSampleapplicationtolearnpixelshaderinstructionsinteractively.Programmedintothisapplicationarediffusevertexcolorsandtwotextureimages.TheapplicationhasfiveworkingpixelshadersthatyoucanselectbypushingthebuttonsintheShadersbox.Itincludesaviewwindowonthelefttoshowtherenderedresult,aninstructionwindowontherighttoallowuserstoenterinstructionsforvalidation,andathirdwindowtoviewdebugoutput.

Asanexample,runtheapplicationandtypethefollowinginstructionsintheinstructionwindow.

ps.1.0

text0

movr0,t0

ThisresultsintheMicrosoft®DirectX®5logoimageintherenderedviewwindow.

Thisshaderappliesatexturemap.NoticethatthecompilationresulttextwindowsaysSuccess,whichindicatesthatalltheinstructionsarevalid.

Next,removethesecondinstruction,whichisthetexturedeclaration.Oncethisisdeleted,thecompilationresultsays:

(Statement2)(ValidationError)Readofuninitializedcomponents(*)int0:*R/X/0*G/Y/1*B/Z/2*A/W/3

Thiserroridentifiesthestatementthatfails,Statement2,andwhyitfailsUninitializedcomponentint0.YoucanfixthisproblembyaddingStatement2again.Whenyoudothis,theshaderworksagain.

Thisisasimpleexamplebutitillustratestheusefulnessofthetool.Bytryingdifferentinstructions,registers,andinstructionsequences,youcanbetter

understandpixelshadersandvertexshaders.ThesampleapplicationalsohasanOpenbutton,whichsupportsloadingofashaderfilesothatyoucanloadanyshaderfilesyouhavealreadycreated.

ShaderDebuggers

SomegraphicschipcompaniesprovideashaderdebuggingtoolontheirWebsites.FindthesetoolsbysearchingtheWeborbyreadingthearticlelistedbelow.Youcanattachadebuggertoaprogramwhileitisrunningandusethedebuggertostepthroughashader.Bysettingbreakpoints,youcanstepthroughtheshadercodeonelineatatimeandwatchregisterstatechanges.Formoreinformationaboutvertexshadersanddebuggingtips,seeUsingVertexShaders:Part1.

TextureBlendingDebugging

Anothersampleapplicationthatispartofthesoftwaredevelopmentkit(SDK)installationisMFCTex.ThisMicrosoftFoundationClasses(MFC)applicationisagoodwaytolearnhowtoperformmulti-textureblendingoperationsinthefixedfunctionpipeline.

DiagnosticSupport

AnotheroptionforhelpwithdebuggingDirectXproblemsistousetheDirectXDiagnosticViewer(DXDiag.exe)tocreateadumpofyourmachine.ThisisdonebyrunningDxDiag.exeafteryourmachinehascrashedandsendingthedumptoMicrosoft,usingeithertheReportbuttonontheMoreHelptaborbysendingittodirectx@microsoft.com.Thedumpcanbeusedtotrackdownandreproducetheproblem.

Additionaldebuginformationcanbefoundathttp://msdn.microsoft.com/directx

http://msdn.microsoft.com/voices/directx02192001.asp

http://msdn.microsoft.com/directx.htm


CreateanEffectThisexampleusesaneffectfiletoapplyatexturemaptoanobject.Theexampleshowsthecontentsoftheeffectfile,aswellasthecoderequiredintheapplicationtoloadandrunthefile.

Tocreateaneffect:

Step1:CreatetheEffectFileStep2:LoadtheEffectFileStep3:RendertheEffect

Step1:Createtheeffectfile

/*

*Step1:Createtheeffectfile

*Thiseffectfilemapsa3-Dtexturemapontotheobject.

*ThiscodeneedstobeinafilenamedEffects.fx

*/

TextureDiffuseTexture;

TechniqueT0

{

PassP0

{

Texture[0]=NULL;

PixelShader=NULL;

VertexShader=XYZ|Normal|Diffuse|Tex1;

Lighting=False;

CullMode=None;

Texture[0]=<DiffuseTexture>;

ColorOp[0]=SelectArg1;

ColorArg1[0]=Texture;

ColorOp[1]=Disable;

}

}

Step2:LoadtheEffectFile

{

HRESULThr;

D3DXTECHNIQUE_DESCtechnique;

ID3DXEffectm_pEffect;

//Assumesthatm_pd3dDevicehasbeeninitialized

if(FAILED(hr=D3DXCreateEffectFromFile(m_pd3dDevice,"effect.fx",&m;_pEffect,NULL)))

returnhr;

if(FAILED(hr=FindNextValidTechnique(NULL,&technique;)))

returnhr;

m_pEffect->SetTechnique(technique.Index);

m_pEffect->SetTexture("DiffuseTexture",m_pTexture0);

}

Oncetheeffectfileiscreated,ID3DXEffect::FindNextValidTechniquereturnsatechniquethathasbeenvalidatedonthehardware.

Step3:RendertheEffect

{

HRESULThr;

UINTuPasses;

if(FAILED(hr=m_pd3dDevice->SetStreamSource(0,m_pVB,

sizeof(CUSTOMVERTEX_POS_NORM_COLOR1_TEX1))))

returnhr;

m_pEffect->Begin(&uPasses;,0);

//The0specifiesthatID3DXEffect::BeginandID3DXEffect::Endwill

//saveandrestoreallstatemodifiedbytheeffect.

for(UINTuPass=0;uPass<uPasses;uPass++)

{

//Setthestateforaparticularpassinatechnique

m_pEffect->Pass(uPass);

m_pd3dDevice->DrawPrimitive(D3DPT_TRIANGLESTRIP,0,dwNumSphereVerts-2);

}

m_pEffect->End();

}


MultipleTechniquesAneffectfiledefinesthetechniquesused.Thebasiclayoutofaneffectfilestartswithoneormoredeclarationsandthendefineseachtechniqueforthateffect.Thissampleshowsabasiceffectfilethatcontainstwotexturesandtwotechniques.Thiseffectfileallowsadevicethatdoesn'tsupportsingle-passrenderingfortwotexturestousemultiplepassestorenderthetextures.

//Declaretwotextures.

texturetex0;//Firsttexture

texturetex1;//Secondtexture

//Technique't0'willrenderthesceneinonepass.Thecolor

//foreachpixeliscalculatedtobetex0+tex1.Becauseituses

//twotexturesatonce,itwillworkonlyoncardsthatsupport

//multitexture.

techniquet0

{

passp0

{

Texture[0]=<tex0>;



Texture[1]=<tex1>;

ColorOp[1]=Add;


ColorArg2[1]=Current;

ColorOp[2]=Disable;

}

}

//Technique't1'rendersthesceneintwopasses.Thefirstpasssets

//eachpixeltothecoloroftex0.Thesecondpassaddsinthecolor

//oftex1.Theresultshouldlookidenticaltothefirst

//technique.However,thistechniquecanbeusedoncardsthatdonot

//supportmultitexture.

techniquet1

{

passp0

{

AlphaBlendEnable=False;

Texture[0]=<tex0>;



ColorOp[1]=Disable;

}

passp1

{

AlphaBlendEnable=True;

SrcBlend=One;

DestBlend=One;

Texture[0]=<tex1>;


ColorArg[0]=Texture;

ColorOp[1]=Disable;

}

}

Thisexampleshowsthebasicsyntaxandlayoutofatypicaleffectfile.

//

//SampleEffect

//Thiseffectaddstwotextures,usingsinglepassormultipasstechnique.

//

texturetex0;

texturetex1;

//Singlepass

techniquet0

{

passp0

{

Texture[0]=<tex0>;

Texture[1]=<tex1>;



ColorOp[1]=Add;



ColorOp[2]=Disable;

}

}

//Multipass

techniquet1

{

passp0

{

Texture[0]=<tex0>;



ColorOp[1]=Disable;

}

passp1

{


SrcBlend=One;

DestBlend=One;

Texture[0]=<tex1>;



ColorOp[1]=Disable;

}

}


Exercise1:DiffuseLighting//

//EffectFileWorkshopSolutionforExercise1

//Copyright(c)2001MicrosoftCorporation.Allrightsreserved.

//

vectorlhtR; //Directionoflight

vectormatD; //Objectdiffusematerialcolor

matrixmWld; //World

matrixmTot; //Total

//Loadmodel

stringXFile="sphere.x";

//Backgroundcolor

DWORDBCLR=0xff333333;

//Nopixelshader

pixelshaderpNIL;

//Techniquenamesfordisplayinviewerwindow

stringtec0="Exercise1a:FixedFunctionDiffuseLighting";

stringtec1="Exercise1b:VertexShaderDiffuseLighting";

/////////////////////////////////////////////////////////////////////////////

///////Exercise1a:FixedFunctionDiffuseLighting//////////

///////Changediffusematerialcolortocolorfrommodel,//////////

///////ratherthanthecurrentwhitematerialconstant.//////////

/////////////////////////////////////////////////////////////////////////////

//Given:Theapphasalreadysetthematricesbeforecallingthistechnique.

techniquetec0

{

passP0

{

//Diffuse,specular,andambientmaterialcolorsofobject

MaterialDiffuse=;//Diffusefromobjectmaterialdiffuse

MaterialDiffuse=(0.0f,0.0f,1.0f,1.0f);//Diffusefromconstantcolor

MaterialSpecular=(0.0f,0.0f,0.0f,0.0f);

MaterialAmbient=(0.0f,0.0f,0.0f,0.0f);

//LightProperties.lhtR,thelightdirection,isinputfromtheshaderapp

LightType[0]=DIRECTIONAL;

LightDiffuse[0]=(1.0f,1.0f,1.0f,1.0f);

LightSpecular[0]=(0.0f,0.0f,0.0f,0.0f);

LightAmbient[0]=(0.0f,0.0f,0.0f,0.0f);

LightDirection[0]=;

LightRange[0]=100000.0f;

//Turnlightingonanduselightzero

LightEnable[0]=TRUE;

Lighting=TRUE;

//Assigndiffusecolortobeused


ColorArg1[0]=Diffuse;

AlphaOp[0]=SelectArg1;

AlphaArg1[0]=Diffuse;

//Onlyonecolorbeingused

ColorOp[1]=Disable;

AlphaOp[1]=Disable;

//Z-bufferingtobeused

ZEnable=true;

ZWriteEnable=true;

}

}

/////////////////////////////////////////////////////////////////////////////

///////Exercise1b:VertexShaderDiffuseLighting//////////

///////Changediffusematerialcolortocolorfrommodel,//////////

///////ratherthanthecurrentwhitematerialconstant.//////////

/////////////////////////////////////////////////////////////////////////////

techniquetec1

{

passp0

{

//Loadmatrices

VertexShaderConstant[0]=;//WorldMatrix

VertexShaderConstant[4]=;//World*View*ProjMatrix

//Materialpropertiesofobject

VertexShaderConstant[9]=(1.0f,1.0f,1.0f,1.0f);//Diffusefromconstantcolor

VertexShaderConstant[9]=;//Diffusefromobjectmaterialdiffuse

VertexShaderConstant[10]=(0.0f,0.0f,0.0f,0.0f);//Specularfromconstantcolor

VertexShaderConstant[11]=(0.0f,0.0f,0.0f,0.0f);//Ambientfromconstantcolor

//LightProperties.lhtR,thelightdirection,isinputfromtheshaderapp

VertexShaderConstant[13]=(1.0f,1.0f,1.0f,1.0f);//Diffuse

VertexShaderConstant[14]=(0.0f,0.0f,0.0f,0.0f);//Specular

VertexShaderConstant[15]=(0.0f,0.0f,0.0f,0.0f);//Ambient

VertexShaderConstant[16]=;//Lightdirection







ColorOp[1]=Disable;

AlphaOp[1]=Disable;

//Definitionofthevertexshader,declarationsthenassembly

VertexShader=

decl

{

stream0;

floatv0[3];//Position

floatv3[3];//Normal

floatv7[3];//TextureCoord1

floatv8[3];//Texturecoord2

}

asm

{

vs.1.1//Versionnumber

m4x4oPos,v0,c4//Transformpointtoprojectionspace.

m3x3r0,v3,c0//TransformnormaltoworldSpace,putresultintor0.

dp3r0,r0,-c16//Dotproductagainstlight,r0nowhaslighting

//constantinx,y,andzcomponents(r,g,b).

mulr0,r0,c13//Modulateagainstdiffuselightcolor.

movoD0,r0//Putintodiffusecoloroutput.

};

}

}


Exercise2:VertexShaderDiffuseLighting//



//

vectorlhtR; //Lightdirectionfromapp


matrixmWld; //World

matrixmTot; //Total

//Loadmodel

stringXFile="f40.x";

//Backgroundcolor


//Nopixelshader

pixelshaderpNIL;


stringtec0="Solution2:VertexShaderDiffuseLighting";

/////////////////////////////////////////////////////////////////////////////

///////Exercise2:VertexShaderDiffuseLighting//////////

///////Lightthemodeltakingbothdiffusematerialand//////////

///////diffuselightsourceintoconsideration.//////////

/////////////////////////////////////////////////////////////////////////////

techniquetec0

{

passp0

{

//Loadmatrices

VertexShaderConstant[0]=; //WorldMatrix

VertexShaderConstant[4]=; //World*View*ProjMatrix





//LightProperties.lhtRisinputfromtheshaderapp




VertexShaderConstant[16]=; //Lightdirection







ColorOp[1]=Disable;

AlphaOp[1]=Disable;


VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{


m4x4oPos,v0,c4//Transformpointtoprojectionspace

dp3r0,v3,-c16//Dotproductagainstuntransformedlight

mulr0,r0,c13//Modulateagainstdiffuselightcolor

mulr0,r0,c9//Modulateagainstdiffusematerial

movoD0,r0//PutintoDiffuseColoroutput

};

}

}


Exercise3:Transforms//



//

vectorlhtR; //Lightdirectionfromapp


matrixmWld; //World

matrixmTot; //Total

//Loadmodel


//BackgroundColor


//Nopixelshader

pixelshaderpNIL;


stringtec0="Solution3:Transforms";

/////////////////////////////////////////////////////////////////////////////

///////Exercise3:Transforms//////////

///////Transformthevertexnormalintoworldspacetotake//////////

///////lightsourcemovementintoconsideration.//////////

/////////////////////////////////////////////////////////////////////////////

techniquetec0

{

passp0

{

//Loadmatrices


















ColorOp[1]=Disable;

AlphaOp[1]=Disable;


VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{


m4x4oPos,v0,c4//Transformpointtoprojectionspace.

movr0,v3//Copyuntransformednormalintor0.

m3x3r0,v3,c0//Transformnormaltoworldspace,putresult

//intor0soprecedingmovnotnecessary.

dp3r0,r0,-c16//Dotproductagainstlight,r0nowhaslightingconstant

//inx,yandzcomponents(r,g,b).

mulr0,r0,c13//Modulateagainstdiffuselightcolor.

mulr0,r0,c9//Modulateagainstdiffusematerial.

movoD0,r0//Putintodiffusecoloroutput.

};

}

}


Exercise4:Texturing//



//

vectorlhtR;//Lightdirectionfromapp

vectormatD;//Objectdiffusematerialcolor

matrixmWld;//World

matrixmTot;//Total

texturetDif;//Diffusetextureofobject

//Loadmodel

stringXFile="bust.x";

//Backgroundcolor


//Nopixelshader

pixelshaderpNIL;


stringtec0="Exercise4:Texturing";

/////////////////////////////////////////////////////////////////////////////

///////Exercise4:Texturing//////////

///////SetuptexturetopassontoFFPS//////////

///////Modulatebetweenthetextureanddiffusecolorargs.//////////

/////////////////////////////////////////////////////////////////////////////

techniquetec0

{

passp0

{

//Loadmatrices











VertexShaderConstant[16]=; //LightDirection

//Usefulconstant(s)

VertexShaderConstant[20]=(-1.0f,-1.0f,0.5f,1.0f);

//Assigndiffusetexture

Texture[0]=;

//Setuptexturewrappingmode

wrap0=U|V;

AddressU[0]=Wrap;

AddressV[0]=Wrap;

//Assigntexturecolortobeused


ColorOp[0]=Modulate;//Modulatebetweenargs

ColorArg2[0]=Diffuse;//Adddiffusecomponentasarg



//Ensureremainingstagesaredisabled

ColorOp[1]=Disable;

AlphaOp[1]=Disable;


VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{



m3x3r0,v3,c0//TransformNormaltoWorldSpace,putresultintor0

dp3r0,r0,-c16//Dotproductagainstlight,r0nowhaslighting

//constantinx,yandzcomponents(r,g,b)

mulr0,r0,c13//Modulateagainstdiffuselightcolor

mulr0,r0,c9//Modulateagainstdiffusematerial

movoD0,r0//Outputdiffusecolor

//movoT0,v7//outputtexturecoordinates

//OR

movoT0.xy,v7.xy//outputonlythexandychannelsforbetterefficiency

};

}

}


Exercise5:VertexShaderSpecularLighting//

//EffectFileWorkshopExercise5


//

vectorlhtR;//Lightdirection

matrixmWld;//World

matrixmTot;//Total

vectormatD;//Materialdiffuse

vectormatS;//Materialspecular

vectorvCPS;//Cameraposition

//Backgroundcolor

DWORDBCLR=0xFF000000;

pixelshaderpNIL;



stringtec0="Exercise5:VertexShaderSpecularLighting";

techniquetec0

{

passp0

{

//Loadmatrices




VertexShaderConstant[9]=;//Diffuse

VertexShaderConstant[10]=;//Specular


//Propertiesoflight





//BlendingConstants

VertexShaderConstant[20]=(0.7f,0.7f,0.7f,0.7f);


//CameraInformation.

VertexShaderConstant[24]=;





ColorOp[1]=Disable;

AlphaOp[1]=Disable;

VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{



m4x4r0,v0,c0//Transformpointtoworldspace

addr0,-r0,c24//Getavectortowardthecameraposition

//Thisisthenegativeofthecameradirection

//Normalize

dp3r11.x,r0.xyz,r0.xyz//Loadthesquareintor1

rsqr11.xyz,r11.x//Gettheinverseofthesquare

mulr0.xyz,r0.xyz,r11.xyz//Multiply,r0=-(cameravector)

addr2.xyz,r0.xyz,-c16//Gethalfangle

//Normalize



mulr2.xyz,r2.xyz,r11.xyz//Multiply,r2=HalfAngle

m3x3r1,v3,c0//Transformnormaltoworldspace,putinr1

//r2=halfangle,r1=normal,r3(output)=intensity

dp3r3.xyzw,r1,r2

//Nowraiseitseveraltimes

mulr3,r3,r3//2nd

mulr3,r3,r3//4th

mulr3,r3,r3//8th

mulr3,r3,r3//16th

//Computediffuseterm

dp3r4,r1,-c16

//Blenditin

mulr3,c20,r3//Kd

mulr4,r4,c21//Ks

mulr4,r4,c10//Specular

madr4,r3,c9,r4//Diffuse

movoD0,r4//PutintoDiffuseColor

};

}

}

Exercise5B//

//EffectFileWorkshopExercise5B


//

vectorlhtR; //LightDirection

matrixmWld; //World

matrixmTot; //Total


texturetEnv;//Environmenttexture

texturetDif;

vectormatD;//ObjectDiffuseMaterialColor

vectormatS;//ObjectSpecularMaterialColor

//Backgroundcolor


pixelshaderpNIL;

//stringXFile="f40.x";

stringXFile="viper.x";

stringBIMG="lobbyzneg.bmp";


stringtec0="Exercise5b:VertexShaderSpecularEnvmap";

techniquetec0

{

passp0

{

//Loadmatrices







//Propertiesoflight





//Blendingconstants

VertexShaderConstant[20]=(-2.0f,-2.0f,-2.0f,-2.0f);




//Camerainformation


ColorOp[0]=Modulate;





ColorOp[1]=Disable;

AlphaOp[1]=Disable;

Texture[0]=;

PixelShader=;


SrcBlend=One;

DestBlend=InvSrcAlpha;

VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{




addr0,r0,-c24//Getavectortowardthecameraposition

//Thisisthecameradirection

//Normalize



mulr0.xyz,r0.xyz,r11.xyz//Multiply,r0=(cameravector)


dp3r3,r0,r1//DotproductCam*Normal

mulr2,c20,r3

madoT0.xyz,r2,r1,r0//Computereflectionvector

//(1-cos)^4=approxfresnel

addr0,c23,r3 //Complementcolor

mulr1,r0,r0//Square

mulr0,r1,r1//4th

mulr0,r0,c22

//movr1,c9

//mulr1,r1,c21//Blendinscaleddiffusematerialcolor

addoD0,r0,r1 //PutintoDiffuseColor

};

}

}

techniquetec1

{

passp0

{

//Loadmatrices







//Propertiesoflight





//BlendingConstants






//CameraInformation







ColorOp[1]=Add;


ColorArg2[1]=Specular;

ColorOp[2]=Disable;

AlphaOp[2]=Disable;

Texture[0]=;

PixelShader=;

//AlphaBlendEnable=True;

//SrcBlend=One;//SrcAlpha;

//DestBlend=InvSrcAlpha;

//CullMode=None;

SpecularEnable=True;

VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{



m4x4r0,v0,c0//TransformpointtoWorldSpace

addr0,r0,-c25//Getavectortowardthecameraposition,

//thisisthecameradirection

//Normalize






mulr2,c20,r3



addr0,c23,r3//Complementcolor

mulr1,r0,r0//Square

addoD0,r1,c21

movr1,c9

muloD1,r1,c21//Blendinscaleddiffusematerialcolor

};

}

}

techniquetec2

{

passp0

{

//Loadmatrices







//Propertiesoflight





//Blendingconstants






//Camerainformation







ColorOp[1]=Add;



ColorOp[2]=Disable;

AlphaOp[2]=Disable;

Texture[0]=;

PixelShader=;

//FillMode=Wireframe;


VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{



m4x4r0,v0,c0//TransformpointtoworldSpace



//Normalize






mulr2,c20,r3




mulr1,r0,r0 //Square

//addr1,r1,c21

//muloD0,r1,c10

madoD0,r1,c10,c10

movr1,c9

muloD1,r1,c21//blendinscaleddiffusematcolor

};

}

}

techniquetec4

{

passp0

{

//Loadmatrices







//Propertiesoflight





//BlendingConstants





//CameraInformation


//FillMode=Wireframe;






ColorOp[1]=Disable;

AlphaOp[1]=Disable;

Texture[0]=;

PixelShader=;


SrcBlend=One;

DestBlend=InvSrcAlpha;

//CullMode=None;

VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{






//Normalize






mulr2,c20,r3





mulr0,r1,r1 //4th

mulr0,r0,c22

movr1,c9

//addr0,r0,c10//Addinspecular

addoD0,r0,r1//PutintoDiffuseColor

};

}

}

Exercise5C

//

//EffectFileWorkshopExercise5C


//

vectorlhtR; //Lightdirection

matrixmWld; //World

matrixmTot; //Total

vectorvCPS; //Cameraposition


texturetDif;


//Backgroundcolor


pixelshaderpNIL;

//stringXFile="sphere.x";

//stringXFile="f40.x";

stringXFile="viper.x";

stringBIMG="lobbyzneg.bmp";


stringtec0="Exercise5b:VertexShaderSpecularEnvmap";

techniquetec0

{

passp0

{

//Loadmatrices







//Propertiesoflight





//BlendingConstants






//Camerainformation







ColorOp[1]=Add;



AlphaOp[1]=Disable;

Texture[0]=;

PixelShader=;

//AlphaBlendEnable=True;

//SrcBlend=One;//SrcAlpha;

//DestBlend=InvSrcAlpha;

//CullMode=None;


VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{






//Normalize






mulr2,c20,r3





//mulr0,r1,r1 //4th

//mulr0,r1,r1

addoD0,r1,c21

mulr0,r0,c22

movr1,c9

muloD1,r1,c25//Blendinscaleddiffusematcolor

//addoD0,r0,r1//PutintoDiffuseColor

//addoD0,r0,r1//PutintoDiffuseColor

};

}

}


Exercise6:StandardTextureEffect//

//StandardTextureEffect


//

vectormatD;//Materialdiffuse

vectormatS;//Materialspecular

vectormatA;//Materialambient

DWORDlhtT;//Lighttype

vectorlhtD;//Lightdiffuse

vectorlhtS;//Lightspecular

vectorlhtA;//Lightambient


vectorlhtP;//Lightposition

vectorvOff;//Embossoffset

vectorvVwD;//Viewdirection


matrixmEnv;//Environmentmaptransform

matrixmWld;//World

matrixmTot;//Total

matrixmWl0;//Blendingmatrices

matrixmWl1;

matrixmWl2;

matrixmWl3;

matrixmWl4;

matrixmWl5;

matrixmWl6;

matrixmWl7;

matrixmIdt=

[

1.0,0.0,0.0,0.0,

0.0,1.0,0.0,0.0,

0.0,0.0,1.0,0.0,

0.0,0.0,0.0,1.0

];

DWORDBCLR=0x0000000;

texturetDif;//Diffusetexture


texturetEvC;//Circularyintegratexcubetexture

texturetEvL;

texturetDf2;//Secondtexture

texturetDf3;

texturetDf4;

texturetSt1;//Proceduralsatintexture

texturetSt2;//Proceduralstaintexture2

texturetMt1;//Brushedmetaltexture

texturetFrn;//FresnelShader

texturetGlw;//GlowShader

texturetL10;//Lightlookuptextureforspec

texturetL80;

texturetL64;

texturetL32;

texturetL16;

texturetfg1;

texturetfg2;

texturetNSE;

texturetNSN;

pixelshaderpNIL;

stringXFile="tiny.x";

stringSkinned="true";

//Skinnedversion,lotsoftransformshavetohappenhere

vertexshadersDif=

decl

{

stream0;

floatv0[3];//Blendweights

floatv1[3];//Indices

ubytev2[4];

//OR

//d3dcolorv2[1];//ifhardwaredoesn'tsupportubyte,used3dcolorinstead

floatv3[3];

floatv7[3];

floatv8[3];

}

asm

{

vs.1.1

//Theindicesareputintoancolor

//Ifubyteissupported,thistherightwaytodoit

mulr1,v2.xyzw,c41.zzzz

//OR

//Ifubyteisnotsupported,decodefroma32bitd3dcolorvalue

//mulr1,v2.zyxw,c41.wwww

//Firstcomputethelastblendingweight

movr0.xyz,v1.xyz;

dp3r0.w,v1.xyz,c40.xxx;

addr0.w,-r0.w,c40.x

//Nowdoabunchofmatrixmultiples,

//r5=Position

//r6=Normal

mova0.x,r1.x

movr5,v0

m4x3r5,v0,c[a0.x];//Worldmatricesstartat0

m3x3r6,v3,c[a0.x];

//Blendthem

mulr5,r5,r0.xxxx

mulr6,r6,r0.xxxx

//Set2

mova0.x,r1.y

m4x3r2,v0,c[a0.x];

m3x3r3,v3,c[a0.x];

//Addthemin

madr5,r2,r0.yyyy,r5;

madr6,r3,r0.yyyy,r6;

//Set3

mova0.x,r1.z

m4x3r2,v0,c[a0.x];

m3x3r3,v3,c[a0.x];

//Addthemin

madr5,r2,r0.zzzz,r5;

madr6,r3,r0.zzzz,r6;

//Set4

mova0.x,r1.w

m4x3r2,v0,c[a0.x];

m3x3r3,v3,c[a0.x];

//Addthemin

madr5,r2,r0.wwww,r5;

madr6,r3,r0.wwww,r6;

//Computeposition

movr5.w,c40.x

m4x4oPos,r5,c50;



mulr6.xyz,r6.xyz,r11.xyz//Multiply

dp3r4.xyz,r6,-c48

movoD0.xyz,r4.xyz

movoT0.xy,v7.xy

};

//SkinnedDiffuse1

stringtec0="Exercise6:SkinnedDiffuse";

techniquetec0

{

passP0

{





AlphaArg1[0]=Current;

ColorOp[1]=Disable;

AlphaOp[1]=Disable;

MinFilter[0]=Linear;

MagFilter[0]=Linear;

MipFilter[0]=Linear;

VertexShaderConstant[0]=<mWl0>;








VertexShaderConstant[32]=<mIdt>;

VertexShaderConstant[50]=<mTot>;//mTotisjustview*proj

VertexShaderConstant[48]=<lhtR>;

VertexShaderConstant[40]=(1.0f,-1.0f,0.0f,.0f);


VertexShaderConstant[43]=(0.0,0.0,1.0,0.0f);

VertexShaderConstant[44]=(0.0,0.0,0.0,0.0);

VertexShaderConstant[60]=(0.5,0.5,0.5,0.5);


VertexShaderConstant[61]=(.50f,0.43f,0.38f,1.0f);//Skycolor

VertexShaderConstant[62]=(0.18f,.10f,0.15f,1.0f);//Groundcolor

VertexShaderConstant[63]=<matD>;//Objectcolor

VerteXShaderConstant[64]=(0.0f,1.0f,0.0f,1.0f);//Skydirection

Texture[0]=<tDif>;

vertexshader=<sDif>;

wrap0=U|V;

wrap1=U|V;

AddressU[0]=Wrap;

AddressV[0]=Wrap;

AlphaBlendEnable=False;

}

}


Exercise7:Multi-TexturingwithShaders//



//


matrixmWld;//World

matrixmTot;//Total


texturetNSE;//Noisetexture

//Backgroundcolor

DWORDBCLR=0xFF0000FF;

pixelshaderpNIL;



stringtec0="Exercise7:Multi-Texturingwithshaders";

techniquetec0

{

passp0

{

//Loadmatrices

VertexShaderConstant[0]=<mWld>;//WorldMatrix

VertexShaderConstant[4]=<mTot>;//World*View*ProjMatrix





//Propertiesoflight




VertexShaderConstant[16]=<lhtR>;//Lightdirection

//Usefulconstant(s)


Texture[0]=<tDif>;

Texture[1]=<tNSE>;

wrap0=U|V;

wrap1=U|V;

AddressU[0]=wrap;

AddressV[0]=wrap;

AddressU[1]=wrap;

AddressV[1]=wrap;





VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{



m3x3r0,v3,c0//Transformnormaltoworldspace,put

//resultintor0

dp3r0,r0,-c16//Dotproductagainstlight,r0

//nowhaslightingconstantinx,yandz

//components(r,g,b)

movr0.xy,v7.xy//Copytexturecoordinatestor0

//mulr0.y,r0.y,c20//Inverttexturecoordinates

movoT0.xy,r0.xy//CopytexturecoordinatestooT0

movoT1.xy,r0.xy//CopytexturecoordinatestooT1

movoD0,r0//Copydiffusetooutput

};

PixelShader=

asm

{

ps.1.1

text0//Gettexturesamplefromstage0

text1//Gettexturesamplefromstage1

mul_x2r0,t1,t0;//Blendthemtogetherinaninterestingway

};

}

}


Exercise8:TexturingwithLights//



//


matrixmWld;//World

matrixmTot;//Total


texturetNSE;//NoiseTexture


//Backgroundcolor


pixelshaderpNIL;



stringtec0="Exercise8:Texturingwithlights";

techniquetec0

{

passp0

{

//Loadmatrices







//Propertiesoflight




VertexShaderConstant[16]=<lhtR>;//LightDirection

//Usefulconstants



//CameraInformation

VertexShaderConstant[24]=<vCPS>;

Texture[0]=<tDif>;

Texture[1]=<tNSE>;

wrap0=U|V;

wrap1=U|V;

AddressU[0]=wrap;

AddressV[0]=wrap;

AddressU[1]=wrap;

AddressV[1]=wrap;





VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{




addr0,-r0,c24//Getavectortowardthecameraposition,

//thisisthenegativeofthecameradirection

//Normalize





//Normalize





//r2=halfangle,r1=normal,r3(output)=intensity

dp3r3.xyzw,r2,r1

//Nowraiseitseveraltimes

mulr3,r3,r3//2nd

mulr3,r3,r3//4th

mulr3,r3,r3//8th

mulr3,r3,r3//16th

mulr3,r3,c20

//Computediffuseterm

dp3r4,r1,-c16

mulr4,r4,c21

movoD0,r4

movoD1,r3

movoT0.xy,v7.xy//CopytexturecoordinatestooT0

movoT1.xy,v7.xy//CopytexturecoordinatestooT1

};

PixelShader=

asm

{

ps.1.1

text0//Sampletexture0

text1//Sampletexture1

mul_x2r1,t1,t0;//Blendthemtogether

movr0,r1

mulr0,r1,v0;//Modulatediffuse

mulr1,r1,v1;//Modulatespecular

addr0,r0,v1;//Blendthemtogether

};

}

}


Exercise9:BumpMapping//



//


matrixmWld;//World

matrixmTot;//Total


texturetDf3;//Normalmapforearth

texturetL10;//Lightlookuptextureforspec

texturetL80;

texturetL64;

texturetL32;

texturetL16;

vectorvCPS;//CameraPosition

//Backgroundcolor


pixelshaderpNIL;



stringtec0="Exercise9a:Dot3BumpMapping";

stringtec1="Exercise9b:Dot3SpecularBumpMapping";

stringtec2="Exercise9c:TableLookupSpecularBumpMapping";

techniquetec0

{

passp0

{

//Loadmatrices







//Propertiesoflight





vertexShaderConstant[20]=(.5f,.5f,.5f,.5f);

//Camerainformation


Texture[0]=;

Texture[1]=;

wrap0=U|V;

wrap1=U|V;

AddressU[0]=wrap;

AddressV[0]=wrap;

AddressU[1]=wrap;

AddressV[1]=wrap;





VertexShader=

decl

{

stream0;


floatv3[3];//Normal


floatv8[3];//Tangent

}

asm

{

vs.1.1

//Transformposition

m4x4oPos,v0,c4

//Transformnormalandtangent

m3x3r7,v8,c0

m3x3r8,v3,c0

//Crossproduct

mulr0,-r7.zxyw,r8.yzxw;

madr5,-r7.yzxw,r8.zxyw,-r0;

//Transformthelightvector

dp3r6.x,r7,-c16

dp3r6.y,r5,-c16

dp3r6.z,r8,-c16

//Multiplybyahalftobias,thenaddhalf

madr6.xyz,r6.xyz,c20,c20

movoT0.xy,v7.xy

movoT1.xy,v7.xy

movoD0.xyz,r6.xyz

};

PixelShader=

asm

{

ps.1.1

text0 //Sampletexture

text1 //Samplenormal

movr0,t1

dp3r0,t1_bx2,v0_bx2;//Dot(light,normal)

mulr0,t0,r0//Modulateagainstbasecolor

};

}

}

techniquetec1

{

passp0

{

//Loadmatrices

VertexShaderConstant[0]=; //Worldmatrix

VertexShaderConstant[4]=; //World*View*Projmatrix





//Propertiesoflight





VertexShaderConstant[20]=(.5f,.5f,.5f,.5f);

//Camerainformation


Texture[0]=;

Texture[1]=;

wrap0=U|V;

wrap1=U|V;

AddressU[0]=wrap;

AddressV[0]=wrap;

AddressU[1]=wrap;

AddressV[1]=wrap;





VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{

vs.1.1

//Transformposition

m4x4oPos,v0,c4


m3x3r7,v8,c0

m3x3r8,v3,c0

//Crossproduct



//Transformposition

m4x4r2,v0,c0

//Getavectortowardthecamera

addr2,-r2,c24





//Normalize




//Transformthehalfanglevector

dp3r6.x,r7,r2

dp3r6.y,r5,r2

dp3r6.z,r8,r2

//Multiplybyahalftobias,thenaddhalf

madr6.xyz,r6.xyz,c20,c20

movoT0.xy,v7.xy

movoT1.xy,v7.xy

movoD0.xyz,r6.xyz

};

PixelShader=

asm

{

ps.1.1

text0//Samplebasemap

text1//Samplenormal

dp3r0,t1_bx2,v0_bx2;//Dot(normal,half)

mulr1,r0,r0;//Raiseitto32ndpower

mulr0,r1,r1;

mulr1,r0,r0;

mulr0,r1,r1;

mulr0,t0,r0

};

}

}

techniquetec2

{

passp0

{

//Loadmatrices







//Propertiesoflight




VertexShaderConstant[16]=;//LightDirection


//CameraInformation


Texture[0]=;

Texture[2]=;

Texture[3]=;

wrap0=U|V;

wrap1=0;

wrap2=0;

wrap3=U|V;

AddressU[0]=wrap;

AddressV[0]=wrap;

AddressU[1]=clamp;

AddressV[1]=clamp;

AddressU[2]=clamp;

AddressV[2]=clamp;





VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{

vs.1.1

//Transformposition

m4x4oPos,v0,c4


m3x3r7,v8,c0

m3x3r8,v3,c0

//Crossproduct



//Transformposition

m4x4r2,v0,c0


addr2,-r2,c24





//Normalize




//Transformthehalfanglevector

dp3r6.x,r7,r2

dp3r6.y,r5,r2

dp3r6.z,r8,r2

movoT0.xy,v7.xy//Coordinatetosampnormalfrom

movoT1.xyz,r6//Notatexcoordinate,buthalf

movoT2.xyz,r6//Angle

movoT3.xy,v7.xy

};

PixelShader=

asm

{

ps.1.1

text0 //Samplenormal

texm3x2padt1,t0_bx2//Lookitupinatable

texm3x2text2,t0_bx2

text3//Samplebasecolor

movr0,t2

mulr0,r0,t3//Blendterms

};

}

}


Exercise10:AnisotropicBumpMapping//



//


matrixmWld;//World

matrixmTot;//Total


texturetDf4;//Normalmapforearth

texturetSt2;//Anisotropiclightingtable


//Backgroundcolor


pixelshaderpNIL;

stringXFile="bust.x";


stringtec0="Exercise10:AnisotropicBumpMapping";

techniquetec0

{

passp0

{

//Loadmatrices







//Propertiesoflight






vertexShaderConstant[40]=(1.0f,1.0f,1.0f,1.0f);

//Camerainformation

VertexShaderConstant[24]=<vCPS>;

PixelShaderConstant[0]=(0.5f,0.2f,0.2f,0.2f);

Texture[0]=<tDf4>;

Texture[3]=<tSt2>;

wrap0=U|V;

wrap1=0;

wrap2=0;

wrap3=0;

AddressU[0]=wrap;

AddressV[0]=wrap;

AddressU[1]=wrap;

AddressV[1]=wrap;

AddressU[3]=wrap;

AddressV[3]=wrap;





VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{

vs.1.1

//Transformposition

m4x4oPos,v0,c4


m3x3r7,v8,c0

m3x3r8,v3,c0

//Crossproduct



//Transformposition

m4x4r2,v0,c0


addr2,-r2,c24




//Transformtheviewanglevector

dp3r6.x,r7,r2

dp3r6.y,r5,r2

dp3r6.z,r8,r2

//Transformthelightvector

dp3r2.x,r7,-c16

dp3r2.y,r5,-c16

dp3r2.z,r8,-c16

movoT0.xy,v7.xy//Coordinatestosampnormalfrom

movoT1.xyz,r2//Light

movoT2.xyz,r6//Viewangle

movoT3.xyz,c40//Garbageinthisregister

};

PixelShader=

asm

{

ps.1.1

text0

texm3x3padt1,t0_bx2//3x3transform

texm3x3padt2,t0_bx2//Thesegenerateatexcoordwhichis

texm3x3text3,t0_bx2//u=dot(light,normal)

//v=dot(view,normal)

//w=somepositivenumber

movr0,t3;

madr0,c0,t3.a,r0;//Alphahasthediffuse,soaddit

//tospecularforfinalresult

};

}

}


Exercise11:AreaLighting//



//

vectorlhtR;//LightDirection

vectormatD;//MaterialDiffuse

matrixmWld;//World

matrixmTot;//Total


//Backgroundcolor


pixelshaderpNIL;

stringXFile="skullhiv.x";


stringtec0="Exercise11a:AreaLighting";

stringtec1="Exercise11b:AreaandDiffuseLighting";

techniquetec0

{

passp0

{

//Loadmatrices




VertexShaderConstant[9]=<matD>;//Diffuse



//Propertiesoflight







VertexShaderConstant[41]=(1.00f,0.86f,0.75f,1.0f);//skycolor

VertexShaderConstant[42]=(0.25f,.25f,0.15f,1.0f);//groundcolor

VertexShaderConstant[43]=<matD>;//objectcolor

VerteXShaderConstant[44]=(0.0f,-1.0f,0.0f,1.0f);//skydirection

Texture[0]=<tDif>;

wrap0=U|V;

wrap1=0;

wrap2=0;

AddressU[0]=wrap;

AddressV[0]=wrap;










VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{

vs.1.1

m4x4oPos,v0,c4//Transformposition

m3x3r0,v3,c0//Transformnormaltoworldspace

dp3r0,r0,-c44//Dotproductagainstskyvector

//Thedotproductwasbetween-1to1.Wewant

//tore-rangethisto0to1

madr0,r0,c20,c20

//Nowlerpbetweenthetwoskycolors.

movr1,c42

subr1,c41,r1//Tosaveaclock,thisdeltashouldbe

//savedinaregister

madr0,r1,r0,c42//Nowlerp

subr1,c40,v7.zzz//Thismodulatesagainstadarkeningterm

//orocclusionterm,embeddedintheztex

//coordinate,wewant1-zthough

mulr0,r0,r1//Darkenskyterm

muloD0,r0,c9//Nowmodulateagainstobject'scolor

movoT0.xy,v7.xy

};

}

}

techniquetec1

{

passp0

{

//Loadmatrices




VertexShaderConstant[9]=<matD>;//Diffuse



//propertiesoflight

VertexShaderConstant[13]=(.6f,.6f,.6f,1.0f);//Diffuse






VertexShaderConstant[41]=(.80f,0.76f,0.65f,1.0f);//Skycolor

VertexShaderConstant[42]=(0.25f,.25f,0.15f,1.0f);//Groundcolor

VertexShaderConstant[43]=<matD>;//Objectcolor

VerteXShaderConstant[44]=(0.0f,-1.0f,0.0f,1.0f);//Skydirection

FillMode=Wireframe;

Texture[0]=<tDif>;

wrap0=U|V;

wrap1=0;

wrap2=0;

AddressU[0]=wrap;

AddressV[0]=wrap;










VertexShader=

decl

{

stream0;


floatv3[3];//Normal



}

asm

{

vs.1.1

m4x4oPos,v0,c4//Transformposition

m3x3r9,v3,c0//Transformnormaltoworldspace

dp3r0,r9,-c44//Dotproductagainstskyvector

//Thedotproductwasbetween-1to1.Wewant

//tore-rangethisto0to1

madr0,r0,c20,c20

//nowlerpbetweenthetwoskycolors

movr1,c42

subr1,c41,r1//Tosaveaclock,thisdeltashould

//besavedinaregister

madr0,r1,r0,c42//Nowlerp

subr1,c40,v7.zzz//Thismodulatesagainstadarkeningterm

//orocclusionterm,embeddedintheztex

//coordinate,wewant1-zthough

mulr2,r0,r1//Darkenskyterm

dp3r1,r9,-c16//Dotagainstlightvector

maxr1,c15,r1

//Complement,square,complement

subr1,c40,r1

mulr1,r1,r1

mulr1,r1,r1

subr1,c40,r1

madr0,r1,c13,r2//Combinewithlightdiffuse

muloD0,r0,c9//Nowmodulateagainstobject'scolor

movoT0.xy,v7.xy

};

}

}


AmbientLighting

Ambientlightingprovidesconstantlightingforascene.Itlightsallobjectverticesthesamebecauseitisnotdependentonanyotherlightingfactorssuchasvertexnormals,lightdirection,lightposition,range,orattenuation.Itisthefastesttypeoflightingbutitproducestheleastrealisticresults.Microsoft®Direct3D®containsasingleglobalambientlightpropertythatyoucanusewithoutcreatinganylight.Alternatively,youcansetanylightobjecttoprovideambientlighting.Theambientlightingforasceneisdescribedbythefollowingequation.

AmbientLighting=Mc*[Ga+sum(Lai)]

Theparametersaredefinedinthefollowingtable.

Parameter Defaultvalue Type DescriptionMc (0,0,0,0) D3DCOLORVALUE Materialambientcolor.Ga (0,0,0,0) D3DCOLORVALUE Globalambientcolor.

Lai (0,0,0,0) D3DVECTOR Lightambientcolor,oftheithlight.

sum N/A N/ASummationoftheambientlightfromthelightobjects.

ThevalueforMcisoneofthreevalues:oneofthetwopossiblevertexcolorsinavertexdeclaration,orthematerialambientcolor.Thevalueis:

vertexcolor1,ifAMBIENTMATERIALSOURCE=D3DMCS_COLOR1,andthefirstvertexcolorissuppliedinthevertexdeclaration.vertexcolor2,ifAMBIENTMATERIALSOURCE=D3DMCS_COLOR2,andthesecondvertexcolorissuppliedinvertexdeclaration.materialambientcolor

NoteIfeitherAMBIENTMATERIALSOURCEoptionisused,andthevertexcolorisnotprovided,thenthematerialambientcolorisused.

Tousethematerialambientcolor,useSetMaterialasshownintheexamplecode

below.

Gaistheglobalambientcolor.ItissetusingSetRenderState(D3DRENDERSTATE_AMBIENT).ThereisoneglobalambientcolorinaDirect3Dscene.ThisparameterisnotassociatedwithaDirect3Dlightobject.

Laiistheambientcoloroftheithlightinthescene.EachDirect3Dlighthasasetofproperties,oneofwhichistheambientcolor.Theterm,sum(Lai)isasumofalltheambientcolorsinthescene.

Example

Inthisexample,theobjectiscoloredusingthesceneambientlightandamaterialambientcolor.Thecodeisshownbelow.

#defineGRAY_COLOR 0x00bfbfbf

//creatematerial

D3DMATERIAL8mtrl;

ZeroMemory(&mtrl;,sizeof(D3DMATERIAL8));

mtrl.Ambient.r=0.75f;

mtrl.Ambient.g=0.0f;

mtrl.Ambient.b=0.0f;

mtrl.Ambient.a=0.0f;

m_pd3dDevice->SetMaterial(&mtrl;);

m_pd3dDevice->SetRenderState(D3DRS_AMBIENT,GRAY_COLOR);

Accordingtotheequation,theresultingcolorfortheobjectverticesisacombinationofthematerialcolorandthelightcolor.

Thesetwoimagesshowthematerialcolor,whichisgray,andthelightcolor,whichisbrightred.

Theresultingsceneisshownbelow.Theonlyobjectinthesceneisasphere.Ambientlightlightsallobjectverticeswiththesamecolor.Itisnotdependentonthevertexnormalorthelightdirection.Asaresult,thespherelookslikea2-Dcirclebecausethereisnodifferenceinshadingaroundthesurfaceoftheobject.

Togiveobjectsamorerealisticlook,applydiffuseorspecularlightinginadditiontoambientlighting.


DiffuseLighting

Afteradjustingthelightintensityforanyattenuationeffects,Microsoft®Direct3D®computeshowmuchoftheremaininglightreflectsfromavertex,giventheangleofthevertexnormalandthedirectionoftheincidentlight.Direct3Dskipstothisstepfordirectionallightsbecausetheydonotattenuateoverdistance.Thesystemconsiderstworeflectiontypes,diffuseandspecular,andusesadifferentformulatodeterminehowmuchlightisreflectedforeach.Aftercalculatingtheamountsoflightreflected,Direct3Dappliesthesenewvaluestothediffuseandspecularreflectancepropertiesofthecurrentmaterial.TheresultingcolorvaluesarethediffuseandspecularcomponentsthattherasterizerusestoproduceGouraudshadingandspecularhighlighting.

Diffuselightingisdescribedbythefollowingequation.

DiffuseLighting=sum[Vd*Ld*(N.Ldir)*Atten*Spot]

Theparametersaredefinedinthefollowingtable.Parameter Defaultvalue Type Description

sum N/A N/ASummationofeachlight'sdiffusecomponent.

Vd (0,0,0,0) D3DCOLORVALUE Vertexdiffusecolor.Ld (0,0,0,0) D3DCOLORVALUE Lightdiffusecolor.N N/A D3DVECTOR Vertexnormal.

Ldir (0,0,0,0) D3DCOLORVALUE Directionvectorfromobjectvertextothelight.

Atten (0,0,0,0) D3DCOLORVALUE Lightattenuation.

Spot (0,0,0,0) D3DVECTOR Characteristicsofthespotlightcone.

ThevalueforVdisoneofthreevalues:oneofthetwopossiblevertexcolorsinavertexdeclaration,orthematerialdiffusecolor.Thevalueis:

vertexcolor1,ifDIFFUSEMATERIALSOURCE=D3DMCS_COLOR1,andthefirstvertexcolorissuppliedinthevertexdeclaration.

vertexcolor2,ifDIFFUSEMATERIALSOURCE=D3DMCS_COLOR2,andthesecondvertexcolorissuppliedinthevertexdeclaration.materialdiffusecolor

Note:IfeitherDIFFUSEMATERIALSOURCEoptionisused,andthevertexcolorisnotprovided,thematerialdiffusecolorisused.

Tocalculatetheattenuation(Atten)orthespotlightcharacteristics(Spot),seeAttenuationandSpotlightTerms

Diffusecomponentsareclampedtobefrom0to255,afteralllightsareprocessedandinterpolatedseparately.Theresultingdiffuselightingvalueisacombinationoftheambient,diffuseandemissivelightvalues.

Example

Inthisexample,theobjectiscoloredusingthelightdiffusecolorandamaterialdiffusecolor.Thecodeisshownbelow.

D3DMATERIAL8mtrl;


D3DLIGHT8light;

ZeroMemory(&light;,sizeof(D3DLIGHT8));

light.Type=D3DLIGHT_DIRECTIONAL;

D3DXVECTOR3vecDir;

vecDir=D3DXVECTOR3(0.5f,0.0f,-0.5f);

D3DXVec3Normalize((D3DXVECTOR3*)&light.Direction;,&vecDir;);

//setdirectionallightdiffusecolor

light.Diffuse.r=1.0f;

light.Diffuse.g=1.0f;

light.Diffuse.b=1.0f;

light.Diffuse.a=1.0f;

m_pd3dDevice->SetLight(0,&light;);

m_pd3dDevice->LightEnable(0,TRUE);

//ifamaterialisused,SetRenderStatemustbeused

//vertexcolor=lightdiffusecolor*materialdiffusecolor

mtrl.Diffuse.r=0.75f;

mtrl.Diffuse.g=0.0f;

mtrl.Diffuse.b=0.0f;

mtrl.Diffuse.a=0.0f;


m_pd3dDevice->SetRenderState(D3DRS_DIFFUSEMATERIALSOURCE,D3DMCS_MATERIAL);


Thesetwoimagesshowthematerialcolor,whichisgray,andthelightcolor,whichisbrightred.

Theresultingsceneisshownbelow.Theonlyobjectinthesceneisasphere.Thediffuselightingcalculationtakesthematerialandlightdiffusecolorandmodifiesitbytheanglebetweenthelightdirectionandthevertexnormalusingthedotproduct.Asaresult,thebacksideofthespheregetsdarkerasthesurfaceofthespherecurvesawayfromthelight.

Combiningthediffuselightingwiththeambientlightingfromthepreviousexampleshadestheentiresurfaceoftheobject.Theambientlightshadestheentiresurfaceandthediffuselighthelpsrevealtheobject'sthree-dimensional(3-D)shape.

Diffuselightingismoreintensivetocalculatethanambientlighting.Becauseitdependsonthevertexnormalsandlightdirection,youcanseetheobjectsgeometryin3-Dspace,whichproducesamorerealisticlightingthanambientlighting.Youcanusespecularhighlightstoachieveamorerealisticlook.


SpecularLighting

Modelingspecularreflectionrequiresthatthesystemnotonlyknowthedirectionthatlightistraveling,butalsothedirectiontotheviewer'seye.ThesystemusesasimplifiedversionofthePhongspecular-reflectionmodel,whichemploysahalfwayvectortoapproximatetheintensityofspecularreflection.

Thedefaultlightingstatedoesnotcalculatespecularhighlights.Toenablespecularlighting,besuretosettheD3DRS_SPECULARENABLEtoTRUE.

SpecularLightingisdescribedbythefollowingequation.

SpecularLighting=Vs*sum[Ls*(N.H)P*Atten*Spot]

Theparametersaredefinedinthefollowingtable.

Parameter Defaultvalue Type Description

Vs (0,0,0,0) D3DCOLORVALUEVertexspecularcolor.

sum N/A N/A

Summationofeachlight'sspecularcomponent.

ThevalueforVcisoneofthreevalues:oneofthetwopossiblevertexcolorsinavertexdeclaration,orthematerialspecularcolor.Thevalueis:

vertexcolor1,ifSPECULARMATERIALSOURCE=D3DMCS_COLOR1,andthefirstvertexcolorissuppliedinthevertexdeclaration.vertexcolor2,ifSPECULARMATERIALSOURCE=D3DMCS_COLOR2,andthesecondvertexcolorissuppliedinthevertexdeclaration.materialspecularcolor

Note:IfeitherSPECULARMATERIALSOURCEoptionisused,andthevertexcolorisnotprovided,thenthematerialspecularcolorisused.

Tocalculatetheattenuation(Atten)orthespotlightcharacteristics(Spot),seeAttenuationandSpotlightTerms

Thehalfwayvector(H)existsmidwaybetweenthevectorfromanobjectvertextothelightsourceandthevectorfromanobjectvertexandthecameraposition.Microsoft®Direct3D®providestwowaystocomputethehalfwayvector.WhenD3DRS_LOCALVIEWERissettoTRUE,thesystemcalculatesthehalfwayvectorusingthepositionofthecameraandthepositionofthevertex,alongwiththelight'sdirectionvector.Thefollowingformulaillustratesthis.

H=norm(norm(Cp-Vp)+Ldir)wheretheparametersaredefinedinthefollowingtable:


Cp (0,0,0,0) D3DVECTOR Cameraposition.

Vp (0,0,0,0) D3DVECTORVertexposition.

WhenD3DRS_LOCALVIEWERissettoTRUE,Direct3Ddeterminesthehalfwayvectorbythefollowingformula.

H=norm(norm(-Vp)+Ldir)

Determiningthehalfwayvectorinthismannercanbecomputationallyintensive.Asanalternative,settingD3DRS_LOCALVIEWERtoFALSEinstructsthesystemtoactasthoughtheviewpointisinfinitelydistantonthez-axis.Thissettingislesscomputationallyintensive,butmuchlessaccurate,soitisbestusedbyapplicationsthatuseorthogonalprojection.

Specularcomponentsareclampedtobefrom0to255,afteralllightsareprocessedandinterpolatedseparately.

Example

Inthisexample,theobjectiscoloredusingthescenespecularlightcolorandamaterialspecularcolor.Thecodeisshownbelow.

D3DMATERIAL8mtrl;


D3DLIGHT8light;

ZeroMemory(&light;,sizeof(D3DLIGHT8));

light.Type=D3DLIGHT_DIRECTIONAL;

D3DXVECTOR3vecDir;

vecDir=D3DXVECTOR3(0.5f,0.0f,-0.5f);

D3DXVec3Normalize((D3DXVECTOR3*)&light.Direction;,&vecDir;);

light.Specular.r=1.0f;

light.Specular.g=1.0f;

light.Specular.b=1.0f;

light.Specular.a=1.0f;

light.Range=1000;

light.Falloff=0;

light.Attenuation0=1;



m_pd3dDevice->SetLight(0,&light;);

m_pd3dDevice->LightEnable(0,TRUE);

m_pd3dDevice->SetRenderState(D3DRS_SPECULARENABLE,TRUE);

mtrl.Specular.r=1.0f;

mtrl.Specular.g=1.0f;

mtrl.Specular.b=1.0f;

mtrl.Specular.a=1.0f;

mtrl.Power=20;


m_pd3dDevice->SetRenderState(D3DRS_SPECULARMATERIALSOURCE,D3DMCS_MATERIAL);


Thesetwoimagesshowthematerialcolor,whichisgray,andthelightcolor,whichiswhite.

Theresultingspecularhighlightisshownbelow.

Combiningthespecularhighlightwiththeambientanddiffuselightingproducesthefollowingimage.Withallthreetypesoflightingapplied,thismoreclearlyresemblesarealisticobject.

Specularlightingismoreintensivetocalculatethandiffuselighting.Itistypicallyusedtoprovidevisualcluesaboutthesurfacematerial.Thespecularhighlightvariesinsizeandcolorwiththematerialofthesurface.


EmissiveLighting

Emissivelightingisdescribedbyasingleterm.

EmissiveLighting=Me

Theparameterisdefinedinthefollowingtable.


Me (0,0,0,0) D3DCOLORVALUE Materialemissivecolor.

ThevalueforMeisoneofthreevalues:oneofthetwopossiblevertexcolorsinavertexdeclaration,orthematerialemissivecolor.Thevalueis:

vertexcolor1,ifEMISSIVEMATERIALSOURCE=D3DMCS_COLOR1,andthefirstvertexcolorissuppliedinthevertexdeclaration.vertexcolor2,ifEMISSIVEMATERIALSOURCE=D3DMCS_COLOR2,andthesecondvertexcolorissuppliedinthevertexdeclaration.materialemissivecolor

NoteIfeitherEMISSIVEMATERIALSOURCEoptionisused,andthevertexcolorisnotprovided,thematerialemissivecolorisused.

Example

Inthisexample,theobjectiscoloredusingthesceneambientlightandamaterialambientcolor.Thecodeisshownbelow.

//creatematerial

D3DMATERIAL8mtrl;


mtrl.Emissive.r=0.0f;

mtrl.Emissive.g=0.75f;

mtrl.Emissive.b=0.0f;

mtrl.Emissive.a=0.0f;


m_pd3dDevice->SetRenderState(D3DRS_EMISSIVEMATERIALSOURCE,D3DMCS_MATERIAL);

Accordingtotheequation,theresultingcolorfortheobjectverticesisthematerialcolor.

Theimagebelowshowsthematerialcolor,whichisgreen.Emissivelightlightsallobjectverticeswiththesamecolor.Itisnotdependentonthevertexnormalorthelightdirection.Asaresult,thespherelookslikea2-Dcirclebecausethereisnodifferenceinshadingaroundthesurfaceoftheobject.

Thisimageshowshowtheemissivelightblendswiththeotherthreetypesoflights,fromthepreviousexamples.Ontherightsideofthesphere,thereisablendofthegreenemissiveandtheredambientlight.Ontheleftsideofthesphere,thegreenemissivelightblendswithredambientanddiffuselightproducingaredgradient.Thespecularhighlightiswhiteinthecenterandcreatesayellowringasthespecularlightvaluefallsoffsharplyleavingtheambient,diffuseandemissivelightvalueswhichblendtogethertomakeyellow.


CameraSpaceTransformations

Verticesinthecameraspacearecomputedbytransformingtheobjectverticeswiththeworldviewmatrix.

V=V*wvMatrix

Vertexnormals,incameraspace,arecomputedbytransformingtheobjectnormalswiththeinversetransposeoftheworldviewmatrix.Theworldviewmatrixmayormaynotbesymmetrical.

N=N*(wvMatrix-1)T

Thematrixinversionandmatrixtransposeoperateona4×4matrix.Themultiplycombinesthenormalwiththe3×3portionoftheresulting4×4matrix.

Iftherenderstate,D3DRENDERSTATE_NORMALIZENORMALSissettoTRUE,vertexnormalvectorsarenormalizedaftertransformationtocameraspaceasfollows:

N=norm(N)

Lightpositionincameraspaceiscomputedbytransformingthelightsourcepositionwiththeviewmatrix.

Lp=Lp*vMatrix

Thedirectiontothelightincameraspaceforadirectionallightiscomputedbymultiplyingthelightsourcedirectionbytheviewmatrix,normalizing,andnegatingtheresult.

Ldir=-norm(Ldir*vMatrix)

FortheD3DLIGHT_POINTandD3DLIGHT_SPOTthedirectiontolightiscomputedasfollows:

Ldir=norm(Ldir),wheretheparametersaredefinedinthefollowingtable.


Ldir (0,0,0,0) D3DCOLORVALUE Directionvectorfromobjectvertextothelight

V (0,0,0,0) D3DVECTOR Vertexposition

wvMatrix Identity D3DMATRIXCompositematrixcontainingtheworldandviewtransforms

N (0,0,0,0) D3DVECTOR VertexnormalLp (0,0,0,0) D3DVECTOR Lightposition

vMatrix Identity D3DMATRIX Matrixcontainingtheviewtransform


AttenuationandSpotlightTerms

Thediffuseandspecularlightingcomponentsoftheglobalilluminationequationcontaintermsthatdescribelightattenuationandthespotlightcone.Thesetermsaredescribedbelow.

AttenuationTerm

Theattenuationofalightdependsonthetypeoflightandthedistancebetweenthelightandthevertexposition.Tocalculateattenuation,useoneofthefollowingthreeequations.

Atten=1,ifthelightisadirectionallight.Atten=0,ifthedistancebetweenthelightandthevertexexceedsthelight'srange.Atten=1/(att0i+att1i*d+att2i*di2).

Parameter Defaultvalue Type Descriptionatt0i (0,0,0,0) FLOAT Linearattenuationfactoratt1i (0,0,0,0) FLOAT Squaredattenuationfactoratt2i (0,0,0,0) FLOAT Exponentialattenuationfactor

di (0,0,0,0) FLOAT Distancefromvertexpositiontolightposition

Theatt0,att1,att2valuesarespecifiedbytheAttenuation0,Attenuation1,andAttenuation2membersoftheD3DLIGHT8structure.

Thedistancebetweenthelightandthevertexpositionisalwayspositive.

di=||Ldir||

where:


Ldir 0.0 D3DVECTORDirectionvectorfromvertexpositiontothe

lightposition

Ifdiisgreaterthanthelight'srange,thatis,theRangememberofaD3DLIGHT8structure,Direct3Dmakesnofurtherattenuationcalculationsandappliesnoeffectsfromthelighttothevertex.ThedvAttenuation0,dvAttenuation1,anddvAttenuation2valuesarethelight'sattenuationconstantsasspecifiedbythemembersofalightobject'sD3DLIGHT8structure.ThecorrespondingstructuremembersareAttenuation0,Attenuation1,andAttenuation2.

Theattenuationconstantsactascoefficientsintheformula—youcanproduceavarietyofattenuationcurvesbymakingsimpleadjustmentstothem.YoucansetAttenuation0to1.0tocreatealightthatdoesn'tattenuatebutisstilllimitedbyrange,oryoucanexperimentwithdifferentvaluestoachievevariousattenuationeffects.

Theattenuationatthemaximumrangeofthelightisnot0.0.Topreventlightsfromsuddenlyappearingwhentheyareatthelightrange,anapplicationcanincreasethelightrange.Or,theapplicationcansetupattenuationconstantssothattheattenuationfactoriscloseto0.0atthelightrange.Theattenuationvalueismultipliedbythered,green,andbluecomponentsofthelight'scolortoscalethelight'sintensityasafactorofthedistancelighttravelstoavertex.

SpotlightTerm

Parameter Defaultvalue Type Descriptionrho 0.0 N/A Angle

phi 0.0 FLOATPenumbraangleofspotlightinradians.Range:[thetaI,p)

theta 0.0 FLOAT Umbraangleofspotlightinradians.Range:[0,p)

falloff 0.0 FLOATFallofffactor.Range:(-infinity,+infinity)

where:

rho=norm(Ldcs).norm(Ldir)


Ldcs 0.0 D3DVECTORDirectionvectorfromorigintothelightpositionincameraspace

Ldir 0.0 D3DVECTORDirectionvectorfromvertexpositiontothelightposition

Aftercomputingthelightattenuation,Direct3Dalsoconsiders:spotlighteffectsifapplicable,theanglethatthelightreflectsfromasurface,andthereflectanceofthecurrentmaterialtocalculatethediffuseandspecularcomponentsforthatvertex.Formoreinformation,seeSpotlightModel.


PreparingtheActionMap

TheactionmapisaDIACTIONFORMATstructurecontaininginformationaboutapplicationactionsandtheirmappingtovirtualcontrolsordeviceobjects.ThestructureispassedbackandforthbetweentheapplicationandMicrosoft®DirectInput®toestablishthefinalmapping.Thissectionexplainshowtoinitializethemap.

1.DefineApplicationActions

ThefirststepinimplementingDirectInputactionmappingistodeterminewhatinput-drivenactionsinyourapplicationneedtobemappedtodeviceobjects.Foractionsthatcanbeperformedeitherbyanaxisorbyabutton,youmustdefineseparateactionsforbothinputtypes.Itisrecommendedthatyoudefinebuttonactionsforallimportantfunctions,incasethedevicedoesnothavetheappropriateaxes.

Thefollowingsampleenumerationofactionvaluesmightbedefinedbyacar-racinggame.Axisactionsbeginwith"eA"andbuttonactionswith"eB".

enumeGameActions

{

eA_STEER,//Steering

eB_STEER_LEFT,//Steerleft

eB_STEER_RIGHT,//Steerright

eA_ACCELERATE,//Changespeed

eB_ACCELERATE,//Speedup

eB_DECELERATE,//Slowdown

eA_BRAKE,//Brake

eB_BRAKE,//Brake

eB_UPSHIFT,//Shifttohighergear

eB_DOWNSHIFT,//Shifttolowergear

eB_CYCLEVIEW,//Cycletonextview

eB_COURSEVIEW,//Togglecourseview

eB_DRIVERVIEW,//Viewfromdriver'sseat

eB_BRAKEBIAS,//Brakebias

eA_VOLUME,//Soundvolume

eB_MUTE//Togglesound

};

#defineNUM_MY_ACTIONS16

Intheexample,actionsaredefinedasenumeratedvalues.However,theycouldbeother32-bitdatatypes,suchaspointerstofunctions.Whenyouretrievedevicedata,yougetwhateveractionvalueyouhavedefined,andyoucanhandleitinanywayyoulike.

2.DefinetheGenre

Thenextstepistodecidewhatgenreyourapplicationbelongsto.Agenredefinesasetofvirtualcontrols.Byselectingthepropergenre,youcanobtainthebestpossiblefitofvirtualcontrolstoapplicationactions.ManufacturerswhochoosetosupplydefaultmappingsfortheirdevicesmustsupportoneormoreofthegenresdefinedbyDirectInput.SeeActionMappingConstantsforalistofthesegenres.

Forthegameintheexample,theobviouschoiceistheDIVIRTUAL_DRIVING_RACEgenre,whichcontainsthefollowingvirtualcontrols.

Priority1Controls

DIAXIS_DRIVINGR_STEERDIAXIS_DRIVINGR_ACCELERATEDIAXIS_DRIVINGR_BRAKEDIBUTTON_DRIVINGR_SHIFTUPDIBUTTON_DRIVINGR_SHIFTDOWNDIBUTTON_DRIVINGR_VIEWDIBUTTON_DRIVINGR_MENU

Priority2Controls

DIAXIS_DRIVINGR_ACCEL_AND_BRAKEDIHATSWITCH_DRIVINGR_GLANCEDIBUTTON_DRIVINGR_ACCELERATE_LINKDIBUTTON_DRIVINGR_AIDSDIBUTTON_DRIVINGR_BOOSTDIBUTTON_DRIVINGR_BRAKEDIBUTTON_DRIVINGR_DASHBOARD

DIBUTTON_DRIVINGR_DEVICEDIBUTTON_DRIVINGR_GLANCE_LEFT_LINKDIBUTTON_DRIVINGR_GLANCE_RIGHT_LINKDIBUTTON_DRIVINGR_MAPDIBUTTON_DRIVINGR_PAUSEDIBUTTON_DRIVINGR_PITDIBUTTON_DRIVINGR_STEER_LEFT_LINKDIBUTTON_DRIVINGR_STEER_RIGHT_LINK

ThereisnodifferenceinfunctionalitybetweenPriority1andPriority2controls.Priority1controlsarethosemostlikelytobesupportedbydevicemanufacturersintheirdefaultmappings.However,thereisnoguaranteethatanyvirtualcontrolwillbesupportedbyadevice.

3.AssignActionstoControlsorDeviceObjects

Thenextstepincreatingtheactionmapistoassociateeachapplicationactionwithoneormoreofthevirtualcontrolsdefinedforthegenre.YoudothisbydeclaringandinitializinganarrayofDIACTIONstructures.Eachstructureinthearrayspecifiestheactionvalue,thevirtualcontroltoassociatewithit,andafriendlynamethatdescribestheaction.Leaveothermembersaszero;theywillbefilledinlaterbyDirectInput.

YoucanalsouseelementsoftheDIACTIONarraytomapactionstoparticularkeysorbuttonsonthekeyboardormouseortochannelsonaMicrosoftDirectPlay®voicedevice.Bydoingso,youcantakeadvantageofthesimplifiedinputloopforallinput,notjustthatfromvirtualcontrols.Forexample,supposeyoumaptheapplication-definedactioneB_UPSHIFTtoboththeDIBUTTON_DRIVINGR_SHIFTUPvirtualcontrolandtothePageUpkey.Whenretrievingdata,yougetbackeB_UPSHIFTwhethertheinputcamefromajoystickbuttonorthekeyboard.

Thefollowingexampledeclaresanactionmapforthecar-racinggame.

DIACTIONrgActions[]=

{

//Genre-definedvirtualaxes

{eA_STEER,DIAXIS_DRIVINGR_STEER,0,"Steer",},

{eA_ACCELERATE,DIAXIS_DRIVINGR_ACCELERATE,0,"Accelerate",},

{eA_BRAKE,DIAXIS_DRIVINGR_BRAKE,0,"Brake",},

//Genre-definedvirtualbuttons

{eB_UPSHIFT,DIBUTTON_DRIVINGR_SHIFTUP,0,"Upshift",},

{eB_DOWNSHIFT,DIBUTTON_DRIVINGR_SHIFTDOWN,0,"DownShift",},

{eB_CYCLEVIEW,DIBUTTON_DRIVINGR_VIEW,0,"ChangeView",},

//Actionsnotdefinedinthegenrethatcanbeassignedtoany

//buttonoraxis

{eA_VOLUME,DIAXIS_ANY_1,0,"Volume",},

{eB_MUTE,DIBUTTON_ANY(0),0,"ToggleSound",},

//Actionsnotdefinedinthegenrethatmustbeassignedto

//particularkeys

{eB_DRIVERVIEW,DIKEYBOARD_1,0,"DriverView",},

{eB_COURSEVIEW,DIKEYBOARD_C,0,"CourseView",},

{eB_BRAKEBIAS,DIKEYBOARD_B,0,"BrakeBias",},

//Actionsmappedtokeysaswellastovirtualcontrols

{eB_UPSHIFT,DIKEYBOARD_PRIOR,0,"Upshift",},

{eB_DOWNSHIFT,DIKEYBOARD_NEXT,0,"Downshift",},

{eB_STEER_LEFT,DIKEYBOARD_LEFT,0,"SteerLeft",},

{eB_STEER_RIGHT,DIKEYBOARD_RIGHT,0,"SteerRight",},

{eB_ACCELERATE,DIKEYBOARD_UP,0,"Accelerate",},

{eB_DECELERATE,DIKEYBOARD_DOWN,0,"Decelerate",},

{eB_BRAKE,DIKEYBOARD_END,0,"Brake",},

//Actionsmappedtobuttonsaswellastovirtualcontrolsandkeys

{eB_UPSHIFT,DIMOUSE_BUTTON0,0,"Upshift",},

{eB_DOWNSHIFT,DIMOUSE_BUTTON1,0,"Downshift",},

};

Intheexample,someactionsaremappedtoactualkeysbyusingKeyboardMappingConstants.SimilarmappingstothemousebuttonsandaxescanbemadebyusingMouseMappingConstants.

TheDIACTIONarrayiscontainedwithinaDIACTIONFORMATstructurethatalsocontainsinformationaboutthegenre,theapplication,andthedesiredscalingofaxisdata.Usethesameinstanceofthisstructurethroughouttheactionmappingprocess.Somememberswillnotbeusedimmediately,butyoucanfillintheentirestructurebeforethenextstep,FindingMatchingDevices.


FindingMatchingDevices

Afteryoudefinetheapplicationactionsandthevirtualcontrolsordeviceobjectstowhichtheseactionsaretobemapped,thenextstepistoenumeratedevicesonthesystemtofindthosethatbestsupportthedesiredvirtualcontrols.

Todoso,passtheDIACTIONFORMATstructuretoIDirectInput8::EnumDevicesBySemantics.ThismethodworksinmuchthesamewayasIDirectInput8::EnumDevicesandtakesasimilarcallbackfunction.

Devicesthathavebeenconfiguredbytheusertomatchcertaincontrolsarealwaysenumeratedfirst.Forexample,ifauserhasconfiguredawheelastheprimarysteeringdevicefordrivinggames,thenthewheelisenumeratedfirstwheneverdevicesthatsupportDIAXIS_DRIVINGR_STEERarerequested,takingprecedenceoverothercapabledevicessuchasjoysticksthathavenotbeenconfiguredbytheuser.Otherwise,theorderinwhichavailabledevicesareenumeratedisdeterminedbythedegreetowhichtheymatchtherequestedcontrols.However,theorderinwhichdevicesareenumeratedbyMicrosoft®DirectInput®isnotguaranteed.

Intheenumerationcallback,youcanretrievethedefaultactionmappingforeachdevice,changeanymappingsyoudon'tlike,givetheuseranopportunitytoreconfigurethedevice,andapplytheactionmap.ThesestepsarecoveredinConfiguringtheActionMap.FlagsreturnedintheDIEnumDevicesBySemanticsCallbackwillprovideinformationaboutwhyaparticulardevicewasenumerated.Theseflagswillindicatewhetheradevicehasbeenusedrecently,isnewlyinstalled,orwillacceptmappingsofpriority1orpriority2controls.


ConfiguringtheActionMap

Aseachdeviceisenumerated,youcanobtainapointertoit,retrievethedefaultactionmap,makechangesinthedefaultmap,andapplythefinalmappings.

1.ObtainingtheDevice

ObtaintheIDirectInputDevice8interfacepointerforeachenumerateddevicefromthelpdidparameteroftheenumerationcallback.SeeDIEnumDevicesBySemanticsCallback.Ifyouwanttosavethedeviceinterfaceforuseinyourapplication,callAddRefonthepointerandassignittoaglobalvariable.

2.ObtainingtheDefaultActionMap

Toobtainthedefaultactionmapforthedevice,callIDirectInputDevice8::BuildActionMap.Microsoft®DirectInput®takesthelistofvirtualcontrolsspecifiedinyourDIACTIONFORMATstructureandattemptstomapthesetophysicaldeviceobjects,returningtheresultsinthesamestructure.YoushouldexaminethedwHowmemberofeachDIACTIONelementtodeterminewhetherthecontrolwassuccessfullymapped.Ifitwas,youcanalsoascertainwhatcriterionwasusedinchoosingtheobject—forexample,configurationbytheuserorbythedevicemanufacturer.

3.MakingChangestotheActionMap

Younowhavetheoptionofchangingthedefaultmappings,althoughitisnotrecommendedthatyoudoso.AfterexaminingthedwSemanticmemberoftheDIACTIONstructuretodeterminewhichdeviceobjectwasmappedtoanaction,youcanchangethatvalue.Forexample,ifanactionismappedtoDIJOFS_BUTTON9,butyouwantthatactiontobemappedtothetriggerbuttoninstead,changethevaluetoDIJOFS_BUTTON0beforeapplyingtheactionmap.

4.ApplyingtheActionMap

WhenyouaresatisfiedthattheDIACTIONFORMATstructurecontainssuitablemappingsforthedevice,callIDirectInputDevice8::SetActionMap.ThevalueyouassignedtotheuAppDatamemberofeachDIACTIONstructurenowbecomesboundtothecontrolspecifiedinthedwSemanticmember,whichinturnisboundtoaparticulardeviceobject.

5.MappingMorethanOneDevice

Repeatsteps1though4foreachdeviceyouwanttouseinyourapplication.Supposeyouwanttomapactionstobothajoystickandthekeyboard.Intheracing-gameexample,theactiondefinedinthegameaseB_DRIVERVIEWwasmappedtoakeyboardkeyinthefollowingelementoftheDIACTIONarray.

{eB_DRIVERVIEW,DIKEYBOARD_1,"DriverView",},

Inthatexample,whenBuildActionMapiscalledonanydevicethatisnotakeyboard,thelHowmemberoftheDIACTIONstructureforthatelementissettoDIAH_UNMAPPED.ContinueexaminingthelHowmemberaseachdeviceinturnisenumerated,untilavalueotherthanDIAH_UNMAPPEDisreturned.Thisindicatesthatthedevicebeingcurrentlymappedisakeyboardandtheactionhasbeensuccessfullymappedtotherequestedkey.

Evenactionsthathavebeensuccessfullymappedcanbemappedtoanotherdevice.Intheexample,eB_UPSHIFTisgiventwoDIACTIONstructures,asfollows:

{eB_UPSHIFT,DIBUTTON_DRIVINGR_SHIFTUP,0,"Upshift",},

...

{eB_UPSHIFT,DIKEYBOARD_PRIOR,0,"Upshift",},

Asdevicesaresuccessivelyenumerated,theeB_UPSHIFTactionismappedtoasuitablebuttonononeormorejoysticksorothergamecontrollers,andthenagaintothekeyboard.

6.DisplayingtheConfiguration

Toshowtheuserhowactionshavebeenmappedtodevices,passthe

DICD_DEFAULTflagtoIDirectInput8::ConfigureDevices.Thepropertysheetforthedevice,containingagraphicalrepresentationofmappings,isdisplayedinview-onlymodeasinthefollowingdiagram.Formoreinformationonthemechanicsofdisplayingtheimage,refertotheUsingActionMappingtutorial.

Ifthedevicemanufacturerhasnotprovidedadeviceimage,themappingwillbepresentedintextmodeasinthefollowingdiagram.

NoteEvenifthecooperativelevelfortheapplicationisdisablingtheMicrosoft®Windows®logokeypassivelythroughanexclusivecooperativeleveloractivelythroughuseoftheDISCL_NOWINKEYflag,thatkeywillbeactivewhilethedefaultactionmappingUIisdisplayed.

Formoreinformationaboutthispropertysheet,seeUserConfigurationoftheDevice.


UserConfigurationoftheDevice

Microsoft®DirectInput®providesapropertysheetthatcanbecalledfromanapplication,enablingtheusertoconfiguredevicesfortheapplicationandviewthecurrentconfiguration.Thispropertysheetcandisplayvariousviewsofthedeviceasprovidedbythemanufacturer.

Toenableuserconfiguration,passaDICONFIGUREDEVICESPARAMSstructurecontainingapointertotheDIACTIONFORMATstructuredescribingthedesiredmapping,alongwiththeDICD_EDITflag,totheIDirectInput8::ConfigureDevicesmethod.NormallyyouwoulddothisaftercallingIDirectInputDevice8::BuildActionMaponalldevicesthatwillbeusedintheapplication.

Thefollowingillustrationshowsatypicalpropertysheetineditmode.

Ifthedevicemanufacturerhasnotprovidedadeviceimage,themappingwillbepresentedintextmodeasinthefollowingdiagram.

NoteEvenifthecooperativelevelfortheapplicationisdisablingtheMicrosoft®Windows®logokeypassivelythroughanexclusivecooperativeleveloractivelythroughuseoftheDISCL_NOWINKEYflag,thatkeywillbeactivewhilethedefaultactionmappingUIisdisplayed.

ThepropertypageforadeviceliststhefriendlynamesthatwereprovidedbyyouinthelptszActionNamememberofeachDIACTIONstructure.IfyouhavealreadycalledBuildActionMapforadevice,thepagealsoshowsthesenamesascalloutsontheimageofthedevice,withlinespointingtothedeviceobjectstowhichtheactionshavebeenmapped.

Theusernowhastheopportunitytoreassigngameactionsbyfirstchoosingacontrolthenchoosinganactionfromthemenu.Whentheuserclosesthe

propertysheet,themethodreturnsandthemodificationsarestoredintheDIACTIONFORMATstructurethatyoupassedin.YoucannowpassthesamestructuretoIDirectInputDevice8::SetActionMapinordertoimplementthenewmappingscheme.


RetrievingActionData

Youretrievebuffereddatafromaction-mappeddevicesjustasyouwouldfromunmappeddevices:bycallingIDirectInputDevice8::GetDeviceData.However,insteadofidentifyingdeviceobjectsbyexaminingthedwOfsmemberoftheDIDEVICEOBJECTDATAstructure,youobtaintheactionassociatedwiththeobjectfromtheuAppDatamember.ThisisthesamevalueyoupassedtothedeviceintheDIACTIONstructure.Itcanbeasimpleidentifierorapointertoafunctiondesignedtohandletheaction.

Rememberthatanactioncanbeassociatedwithmorethanonedevice.Youstillhavetoobtaindatafrombothdevicesindependently,butyoucanusethesameroutinetohandlethedataregardlessofwhereitcomesfrom.

Thefollowingsamplecode,whichmightbepartofthegameloopinadrivingsimulation,retrievesdatafromalldevicesintheg_lpIdiDevicesarray.Thisarraycontainsg_nDeviceselements.

for(intiDevice=0x0;iDevice<g_nDevices;iDevice++)

{

DIDEVICEOBJECTDATAdidod;

DWORDdwObjCount=1;

//Pollthedevicefordata.

g_lpDiDevices[iDevice]->Poll();

//Retrievethedata.

g_lpDiDevices[iDevice]->GetDeviceData(sizeof(didod),

&didod,

&dwObjCount,0);

//Handletheactionsregardlessofwhatdevicereturnedthem.

switch(didod.uAppData)

{

caseeA_STEER:

SteerCar(didod.dwData);

break;

caseeB_UPSHIFT

if(didod.dwData&0x80)ShiftGears(UPSHIFT);

break;

.

.

.

default:

break;

}

}

NoteAxisconstantsforspecificgenres,suchasDIAXIS_DRIVINGR_STEERorDIAXIS_SPACESIM_LATERAL,areusedforabsolutejoystickdata.Theactionmapperattemptstomapthisvirtualcontroltoadeviceobjectthatreturnsabsolutedata.Thedatareturnedfromthatdeviceshouldbeprocessedaccordinglyintheapplication.DeviceconstantssuchasDIMOUSE_XAXIS,however,areexpectedtoreturnrelativedata.

Whenretrievingdata,eachpotentialsourceofdatashouldbeprocessedseparatelytokeeponedeviceobjectfrompossiblyoverwritingthedatafromanother.Forinstance,thefollowingDIACTIONstructuresareusedinanactionmaptocontroldirection.

{INPUT_LEFTRIGHT_ABS_AXIS,DIAXIS_SPACESIM_LATERAL,0,_T("Turn"),},

{INPUT_LEFTRIGHT_REL_AXIS,DIMOUSE_XAXIS,0,_T("Turn"),},

{INPUT_TURNLEFT,DIKEYBOARD_LEFT,0,_T("Turnleft"),},

{INPUT_TURNRIGHT,DIKEYBOARD_RIGHT,0,_T("Turnright"),},

Theapplication'sinputloopprocessesdatafromtheseactionsinthefollowingcasestatement.

switch(adod[j].uAppData)

{

caseINPUT_LEFTRIGHT_ABS_AXIS:

g_dwAbsLR=adod[j].dwData

break;

caseINPUT_LEFTRIGHT_REL_AXIS:

g_dwRelLR=adod[j].dwData;

break;

caseINPUT_TURNLEFT:

g_bLeft=(adod[j].dwData!=0);

break;

caseINPUT_TURNRIGHT:

g_bRight=(adod[j].dwData!=0)

break;

}

Notethateachdatasourceisassignedtoaseparatevariableratherthanalldatasourcesbeingassignedageneric"turn"variable.Iftheyweretoshareagenericvariable,holdingdowntheLEFTARROWkeyandthenmovingthejoystickwouldcausethekeyboardinformationtobelost.Thisisbecausethejoystickdatawouldoverwritethevariable.

Inadditiontoindividualvariables,therearemanywaystoprocessthedata.Whatevermethodisused,careshouldbetakenintheprocessingofdatatoavoidunexpectedlylostinformation.


MaintainingFilesDuringDevelopment

Duringadevelopmentcycle,unusedandoutofdate.inifilesmayaccumulateduetofrequentactionmapchanges,Microsoft®DirectX®reinstallations,multipleusers,andothernormaldevelopmentsituations.Thesefilescouldpossiblycauseunexpectedmappingsorreportsof"recent"(DIEDBS_RECENTDEVICE)fordevicesthatwouldnotbeexpectedtoreturnthatvalue.Forthisreason,itisgoodpracticetooccasionallydeleteanyunused.inifiles.ThesefilescanbefoundinC:\ProgramFiles\CommonFiles\DirectX\DirectInput\UserMaps.

NoteTheproceduresuggestedaboveismeanttobeperformedonlymanuallyduringadevelopmentcycletoensurethatthedevelopmentenvironmentisinacleanerstate.Ashippingapplicationshouldneverdeleteusermapsasthiscouldresultinthelossofauser'spreferredsettings.


IDirectInput8::ConfigureDevicesDisplayspropertypagesforconnectedinputdevicesandenablestheusertomapactionstodevicecontrols.

HRESULTIDirectInput8::ConfigureDevices(

LPDICONFIGUREDEVICESCALLBACKlpdiCallback,

LPDICONFIGUREDEVICESPARAMSlpdiCDParams,

DWORDdwFlags,

LPVOIDpvRefData

);

Parameters

lpdiCallbackAddressofacallbackfunctiontobecalledeachtimethecontentsofthesurfacechange.SeeDIConfigureDevicesCallback.PassNULLiftheapplicationdoesnothandlethedisplayofthepropertysheet.Inthiscase,Microsoft®DirectInput®displaysthepropertysheetandreturnscontroltotheapplicationwhentheuserclosesthepropertysheet.Ifyousupplyacallbackpointer,youmustalsosupplyavalidsurfacepointerinthelpUnkDDSTargetmemberoftheDICONFIGUREDEVICESPARAMSstructure.

lpdiCDParamsAddressofaDICONFIGUREDEVICESPARAMSstructurethatcontainsinformationaboutusersandgenresforthegame,aswellasinformationabouthowtheuserinterfaceisdisplayed.

dwFlagsDWORDvaluethatspecifiesthemodeinwhichthecontrolpanelshouldbeinvoked.DwFlagsmustbeoneofthefollowingvalues.DICD_DEFAULT

Openthepropertysheetinview-onlymode.DICD_EDIT

Openthepropertysheetineditmode.Thismodeenablestheusertochangeaction-to-controlmappings.Afterthecallreturns,theapplicationshouldassumecurrentdevicesarenolongervalid,releasealldeviceinterfaces,andreinitializethembycalling

IDirectInput8::EnumDevicesBySemantics.pvRefData

Application-definedvaluetopasstothecallbackfunction.

ReturnValues

Ifthemethodsucceeds,thereturnvalueisDI_OK.

Ifthemethodfails,thereturnvaluecanbeoneofthefollowing.

DIERR_INVALIDPARAMDIERR_OUTOFMEMORY

Remarks

Hardwarevendorsprovidebitmapsandotherdisplayinformationfortheirdevice.

Beforecallingthemethod,anapplicationcanmodifythetextlabelsassociatedwitheachactionbychangingthevalueinthelptszActionNamememberoftheDIACTIONstructure.

Configurationisstoredforeachuserofeachdeviceforeachgame.TheinformationcanberetrievedbytheIDirectInputDevice8::BuildActionMapmethod.

Bydefault,accelerationissupportedforthesepixelformats:

A1R5G5B516-bitpixelformatwith5bitsreservedforeachcolorand1bitreservedforalpha(transparenttexel).

A8R8G8B832-bitARGBpixelformatwithalpha.

R9G8B824-bitRGBpixelformat.

X1R5G5B516-bitpixelformatwith5bitsreservedforeachcolor.

X8R8G8B8

32-bitRGBpixelformatwith8bitsreservedforeachcolor.

Otherformatswillresultincolorconversionanddramaticallyslowtheframerate.

NoteEvenifthecooperativelevelfortheapplicationisdisablingtheMicrosoftWindows®logokeypassivelythroughanexclusivecooperativeleveloractivelythroughuseoftheDISCL_NOWINKEYflag,thatkeywillbeactivewhilethedefaultactionmappingUIisdisplayed.

Requirements



IDirectInput8::CreateDeviceCreatesandinitializesaninstanceofadevicebasedonagivenGUID,andobtainsanIDirectInputDevice8interface.

HRESULTCreateDevice(

REFGUIDrguid,

LPDIRECTINPUTDEVICE*lplpDirectInputDevice,

LPUNKNOWNpUnkOuter

);

Parameters

rguidReferenceto(C++)oraddressof(C)theinstanceGUIDforthedesiredinputdevice(seeRemarks).TheGUIDisretrievedthroughtheIDirectInput8::EnumDevicesmethod,oritcanbeoneofthefollowingpredefinedGUIDs:GUID_SysKeyboard

Thedefaultsystemkeyboard.GUID_SysMouse

Thedefaultsystemmouse.

FortheprecedingGUIDvaluestobevalid,yourapplicationmustdefineINITGUIDbeforeallotherpreprocessordirectivesatthebeginningofthesourcefile,orlinktoDxguid.lib.

lplpDirectInputDeviceAddressofavariabletoreceivetheIDirectInputDevice8interfacepointerifsuccessful.

pUnkOuterAddressofthecontrollingobject'sIUnknowninterfaceforCOMaggregation,orNULLiftheinterfaceisnotaggregated.MostcallerspassNULL.

ReturnValues


Ifthemethodfails,thereturnvaluecanbeoneofthefollowing:

DIERR_DEVICENOTREGDIERR_INVALIDPARAMDIERR_NOINTERFACEDIERR_NOTINITIALIZEDDIERR_OUTOFMEMORY

Remarks

CallingthismethodwithpUnkOuter=NULLisequivalenttocreatingtheobjectbyCoCreateInstance(&CLSID_DirectInputDevice,NULL,CLSCTX_INPROC_SERVER,riid,lplpDirectInputDevice)andtheninitializingitwithInitialize.

CallingthismethodwithpUnkOuter!=NULLisequivalenttocreatingtheobjectbyCoCreateInstance(&CLSID_DirectInputDevice,punkOuter,CLSCTX_INPROC_SERVER,&IID_IUnknown,lplpDirectInputDevice).Theaggregatedobjectmustbeinitializedmanually.

Requirements



IDirectInput8::EnumDevicesEnumeratesavailabledevices.

HRESULTEnumDevices(

DWORDdwDevType,

LPDIENUMDEVICESCALLBACKlpCallback,

LPVOIDpvRef,

DWORDdwFlags

);

Parameters

dwDevTypeDevicetypefilter.

Torestricttheenumerationtoaparticulartypeofdevice,setthisparametertoaDI8DEVTYPE_*value.SeeDIDEVICEINSTANCE.

Toenumerateaclassofdevices,useoneofthefollowingvalues.

DI8DEVCLASS_ALLAlldevices.

DI8DEVCLASS_DEVICEAlldevicesthatdonotfallintoanotherclass.

DI8DEVCLASS_GAMECTRLAllgamecontrollers.

DI8DEVCLASS_KEYBOARDAllkeyboards.EquivalenttoDI8DEVTYPE_KEYBOARD.

DI8DEVCLASS_POINTERAlldevicesoftypeDI8DEVTYPE_MOUSEandDI8DEVTYPE_SCREENPOINTER.

lpCallbackAddressofacallbackfunctiontobecalledonceforeachdeviceenumerated.SeeDIEnumDevicesCallback.

pvRefApplication-defined32-bitvaluetobepassedtotheenumerationcallback

eachtimeitiscalled.dwFlags

Flagvaluethatspecifiesthescopeoftheenumeration.Thisparametercanbeoneormoreofthefollowingvalues:DIEDFL_ALLDEVICES

Allinstalleddevicesareenumerated.Thisisthedefaultbehavior.DIEDFL_ATTACHEDONLY

Onlyattachedandinstalleddevices.DIEDFL_FORCEFEEDBACK

Onlydevicesthatsupportforcefeedback.DIEDFL_INCLUDEALIASES

Includedevicesthatarealiasesforotherdevices.DIEDFL_INCLUDEHIDDEN

Includehiddendevices.Formoreinformationabouthiddendevices,seeDIDEVCAPS.

DIEDFL_INCLUDEPHANTOMSIncludephantom(placeholder)devices.

ReturnValues


Ifthemethodfails,thereturnvaluecanbeoneofthefollowingerrorvalues:

DIERR_INVALIDPARAMDIERR_NOTINITIALIZED

Remarks

Allinstalleddevicescanbeenumerated,eveniftheyarenotpresent.Forexample,aflightstickmightbeinstalledonthesystembutnotcurrentlypluggedintothecomputer.SetthedwFlagsparametertoindicatewhetheronlyattachedorallinstalleddevicesshouldbeenumerated.IftheDIEDFL_ATTACHEDONLYflagisnotpresent,allinstalleddevicesareenumerated.

ApreferreddevicetypecanbepassedasadwDevTypefiltersothatonlythedevicesofthattypeareenumerated.

NoteTheorderinwhichdevicesareenumeratedbyDirectInputisnotguaranteed.

Requirements


SeeAlso

IDirectInput8::EnumDevicesBySemantics


IDirectInput8::EnumDevicesBySemanticsEnumeratesdevicesthatmostcloselymatchtheapplication-specifiedactionmap.

HRESULTEnumDevicesBySemantics(

LPCTSTRptszUserName,

LPDIACTIONFORMATlpdiActionFormat,

LPDIENUMDEVICESBYSEMANTICSCBlpCallback,

LPVOIDpvRef,

DWORDdwFlags

);

Parameters

ptszUserNameStringidentifyingthecurrentuser,orNULLtospecifytheuserloggedontothesystem.Theusernameistakenintoaccountwhenenumeratingdevices.Adevicewithusermappingsispreferredtoadevicewithoutanyusermappings.Bydefault,devicesinusebyotherusersarenotenumeratedforthisuser.

lpdiActionFormatAddressofaDIACTIONFORMATstructurethatspecifiestheactionmapforwhichsuitabledevicesareenumerated.

lpCallbackAddressofacallbackfunctiontobecalledonceforeachdeviceenumerated.SeeDIEnumDevicesBySemanticsCallback.

pvRefApplication-defined32-bitvaluetopasstotheenumerationcallbackeachtimeitiscalled.

dwFlagsFlagvaluethatspecifiesthescopeoftheenumeration.Thisparametercanbeoneormoreofthefollowingvalues.DIEDBSFL_ATTACHEDONLY

Onlyattachedandinstalleddevicesareenumerated.DIEDBSFL_AVAILABLEDEVICES

Onlyunowned,installeddevicesareenumerated.DIEDBSFL_FORCEFEEDBACK

Onlydevicesthatsupportforcefeedbackareenumerated.DIEDBSFL_MULTIMICEKEYBOARDS

Onlysecondary(non-system)keyboardandmousedevices.DIEDBSFL_NONGAMINGDEVICES

OnlyHID-compliantdeviceswhoseprimarypurposeisnotasagamingdevice.DevicessuchasUSBspeakersandmultimediabuttonsonsomekeyboardswouldfallwithinthisvalue.

DIEDBSFL_THISUSERAllinstalleddevicesfortheuseridentifiedbyptszUserName,andallunowneddevices,areenumerated.

DIEDBSFL_VALIDisalsodefinedinDinput.h,butisnotusedbyapplications.

ReturnValues


Ifthemethodfails,thereturnvaluecanbeoneofthefollowingerrorvalues.


Remarks

Thekeyboardandmouseareenumeratedlast.

NoteTheorderinwhichdevicesareenumeratedbyDirectInputisnotguaranteed.

Requirements


SeeAlso

IDirectInput8::EnumDevices,ActionMapping.


IDirectInput8::FindDeviceRetrievestheinstanceGUIDofadevicethathasbeennewlyattachedtothesystem.ItiscalledinresponsetoaMicrosoft®Win32®devicemanagementnotification.

HRESULTFindDevice(

REFGUIDrguidClass,

LPCTSTRptszName,

LPGUIDpguidInstance

);

Parameters

rguidClassUniqueidentifierofthedeviceclassforthedevicethattheapplicationistolocate.TheapplicationobtainstheclassGUIDfromthedevicearrivalnotification.Formoreinformation,seethedocumentationontheDBT_DEVICEARRIVALeventintheMicrosoftPlatformSoftwareDevelopmentKit(SDK).

ptszNameNameofthedevice.Theapplicationobtainsthenamefromthedevicearrivalnotification.

pguidInstanceAddressofavariabletoreceivetheinstanceGUIDforthedevice,ifthedeviceisfound.ThisvaluecanbepassedtoIDirectInput8::CreateDevice.

ReturnValues


Ifthemethodfails,thereturnvaluecanbeDIERR_DEVICENOTREG.FailureresultsiftheGUIDandnamedonotcorrespondtoadeviceclassthatisregisteredwithMicrosoft®DirectInput®.Forexample,theymightrefertoastoragedevice,ratherthananinputdevice.

Requirements



IDirectInput8::GetDeviceStatusRetrievesthestatusofaspecifieddevice.

HRESULTGetDeviceStatus(

REFGUIDrguidInstance

);

Parameters

rguidInstanceReferenceto(C++)oraddressof(C)theGUIDidentifyingtheinstanceofthedevicewhosestatusisbeingchecked.

ReturnValues

Ifthemethodsucceeds,thereturnvalueisDI_OKifthedeviceisattachedtothesystem,orDI_NOTATTACHEDotherwise.


DIERR_GENERICDIERR_INVALIDPARAMDIERR_NOTINITIALIZED

Requirements



IDirectInput8::InitializeInitializesaMicrosoft®DirectInput®object.Applicationsnormallydonotneedtocallthismethod.TheDirectInput8CreatefunctionautomaticallyinitializestheDirectInputobjectaftercreatingit.

HRESULTInitialize(

HINSTANCEhinst,

DWORDdwVersion

);

Parameters

hinstInstancehandletotheapplicationordynamic-linklibrary(DLL)thatiscreatingtheDirectInputobject.DirectInputusesthisvaluetodeterminewhethertheapplicationorDLLhasbeencertifiedandtoestablishanyspecialbehaviorsthatmightbenecessaryforbackwardscompatibility.

ItisanerrorforaDLLtopassthehandleoftheparentapplication.Forexample,aMicrosoftActiveX®controlembeddedinaWebpagethatusesDirectInputmustpassitsowninstancehandle,andnotthehandleoftheWebbrowser.ThisensuresthatDirectInputrecognizesthecontrolandcanenableanyspecialbehaviorsthatmightbenecessary.

dwVersionVersionnumberofDirectInputforwhichtheapplicationisdesigned.ThisvalueisnormallyDIRECTINPUT_VERSION.PassingtheversionnumberofapreviousversioncausesDirectInputtoemulatethatversion.

ReturnValues



DIERR_BETADIRECTINPUTVERSION

DIERR_OLDDIRECTINPUTVERSION

Requirements



IDirectInput8::RunControlPanelRunsControlPaneltoenabletheusertoinstallanewinputdeviceormodifyconfigurations.

HRESULTRunControlPanel(

HWNDhwndOwner,

DWORDdwFlags

);

Parameters

hwndOwnerHandleofthewindowtobeusedastheparentwindowforthesubsequentuserinterface.IfthisparameterisNULL,noparentwindowisused.

dwFlagsCurrentlynotusedandmustbesetto0.

ReturnValues




Requirements


SeeAlso

IDirectInputDevice8::RunControlPanel


IUnknown::AddRefIncreasesthereferencecountoftheobjectby1.

ULONGAddRef();

Parameters

Therearenoparameters.

ReturnValues

Returnsthenewreferencecount.Thisvalueisfordiagnosticandtestingpurposesonly.

Remarks

Whentheobjectiscreated,itsreferencecountissetto1.EverytimeanapplicationobtainsaninterfacetotheobjectorcallstheAddRefmethod,theobject'sreferencecountisincreasedby1.UsetheReleasemethodtodecreasetheobject'sreferencecountby1.

Requirements

WindowsNT/2000/XP:RequiresWindowsNT3.1orlater.Windows98/Me:RequiresWindows98orlater.Header:DeclaredinUnknwn.h.


IUnknown::QueryInterfaceDetermineswhethertheobjectsupportsaparticularCOMinterface.Ifitdoes,thesystemincreasestheobject'sreferencecount,andtheapplicationcanusethatinterfaceimmediately.

HRESULTQueryInterface(

REFIIDriid,

LPVOID*ppvObj

);

Parameters

riidReferenceidentifieroftheinterfacebeingrequested.

ppvObjAddressofapointertofillwiththeinterfacepointerifthequerysucceeds.

ReturnValues

Ifthemethodsucceeds,thereturnvalueisS_OK.

Ifthemethodfails,thereturnvaluemaybeE_NOINTERFACEorE_POINTER.Somecomponentsalsohavetheirowndefinitionsoftheseerrorvaluesintheirheaderfiles.InMicrosoft®DirectInput®,forexample,DIERR_NOINTERFACEisequivalenttoE_NOINTERFACE.

Remarks

Iftheapplicationdoesnotneedtousetheinterfaceretrievedbyacalltothismethod,itmustcalltheReleasemethodforthatinterfacetofreeit.TheQueryInterfacemethodenablesMicrosoftandthirdpartiestoextendobjectswithoutinterferingwithexistingorevolvingfunctionality.

Requirements



IUnknown::ReleaseDecreasesthereferencecountoftheobjectby1.

ULONGRelease();

Parameters

Therearenoparameters.

ReturnValues

Returnsthenewreferencecount.Thisvalueisfordiagnosticandtestingpurposesonly.

Remarks

Theobjectdeallocatesitselfwhenitsreferencecountreaches0.UsetheAddRefmethodtoincreasetheobject'sreferencecountby1.

ApplicationsmustcallthismethodtoreleaseonlyinterfacesthatthemethodexplicitlycreatedinapreviouscalltoIUnknown::AddRef,IUnknown::QueryInterface,oracreationfunctionsuchasDirect3DCreate8.

Requirements



ReturnValues

ThelistbelowcontainstheHRESULTvaluesthatcanbereturnedbyMicrosoft®DirectInput®methodsandfunctions.Errorsarerepresentedbynegativevaluesandcannotbecombined.

Foralistoftheerrorvalueseachmethodorfunctioncanreturn,seetheindividualdescriptions.Listsoferrorcodesinthedocumentationarenecessarilyincomplete.Forexample,anyDirectInputmethodcanreturnDIERR_OUTOFMEMORYeventhoughtheerrorcodeisnotexplicitlylistedasapossiblereturnvalueinthedocumentationforthatmethod.

DI_BUFFEROVERFLOWThedevicebufferoverflowedandsomeinputwaslost.ThisvalueisequaltotheS_FALSEstandardCOMreturnvalue.

DI_DOWNLOADSKIPPEDTheparametersoftheeffectweresuccessfullyupdated,buttheeffectcouldnotbedownloadedbecausetheassociateddevicewasnotacquiredinexclusivemode.

DI_EFFECTRESTARTEDTheeffectwasstopped,theparameterswereupdated,andtheeffectwasrestarted.

DI_NOEFFECTTheoperationhadnoeffect.ThisvalueisequaltotheS_FALSEstandardCOMreturnvalue.

DI_NOTATTACHEDThedeviceexistsbutisnotcurrentlyattached.ThisvalueisequaltotheS_FALSEstandardCOMreturnvalue.

DI_OKTheoperationcompletedsuccessfully.ThisvalueisequaltotheS_OKstandardCOMreturnvalue.

DI_POLLEDDEVICEThedeviceisapolleddevice.Asaresult,devicebufferingdoesnotcollectanydataandeventnotificationsisnotsignaleduntiltheIDirectInputDevice8::Pollmethodiscalled.

DI_PROPNOEFFECTThechangeindevicepropertieshadnoeffect.ThisvalueisequaltotheS_FALSEstandardCOMreturnvalue.

DI_SETTINGSNOTSAVEDTheactionmapwasappliedtothedevice,butthesettingscouldnotbesaved.

DI_TRUNCATEDTheparametersoftheeffectweresuccessfullyupdated,butsomeofthemwerebeyondthecapabilitiesofthedeviceandweretruncatedtothenearestsupportedvalue.

DI_TRUNCATEDANDRESTARTEDEqualtoDI_EFFECTRESTARTED|DI_TRUNCATED.

DI_WRITEPROTECTASUCCESScodeindicatingthatsettingscannotbemodified.

DIERR_ACQUIREDTheoperationcannotbeperformedwhilethedeviceisacquired.

DIERR_ALREADYINITIALIZEDThisobjectisalreadyinitialized

DIERR_BADDRIVERVERTheobjectcouldnotbecreatedduetoanincompatibledriverversionormismatchedorincompletedrivercomponents.

DIERR_BETADIRECTINPUTVERSIONTheapplicationwaswrittenforanunsupportedprereleaseversionofDirectInput.

DIERR_DEVICEFULLThedeviceisfull.

DIERR_DEVICENOTREGThedeviceordeviceinstanceisnotregisteredwithDirectInput.ThisvalueisequaltotheREGDB_E_CLASSNOTREGstandardCOMreturnvalue.

DIERR_EFFECTPLAYINGTheparameterswereupdatedinmemorybutwerenotdownloadedtothedevicebecausethedevicedoesnotsupportupdatinganeffectwhileitisstillplaying.

DIERR_GENERICAnundeterminederroroccurredinsidetheDirectInputsubsystem.ThisvalueisequaltotheE_FAILstandardCOMreturnvalue.

DIERR_HANDLEEXISTSThedevicealreadyhasaneventnotificationassociatedwithit.ThisvalueisequaltotheE_ACCESSDENIEDstandardCOMreturnvalue.

DIERR_HASEFFECTSThedevicecannotbereinitializedbecauseeffectsareattachedtoit.

DIERR_INCOMPLETEEFFECTTheeffectcouldnotbedownloadedbecauseessentialinformationismissing.Forexample,noaxeshavebeenassociatedwiththeeffect,ornotype-specificinformationhasbeensupplied.

DIERR_INPUTLOSTAccesstotheinputdevicehasbeenlost.Itmustbereacquired.

DIERR_INVALIDPARAMAninvalidparameterwaspassedtothereturningfunction,ortheobjectwasnotinastatethatpermittedthefunctiontobecalled.ThisvalueisequaltotheE_INVALIDARGstandardCOMreturnvalue.

DIERR_MAPFILEFAILAnerrorhasoccurredeitherreadingthevendor-suppliedaction-mappingfileforthedeviceorreadingorwritingtheuserconfigurationmappingfileforthedevice.

DIERR_MOREDATANotalltherequestedinformationfitintothebuffer.

DIERR_NOAGGREGATIONThisobjectdoesnotsupportaggregation.

DIERR_NOINTERFACETheobjectdoesnotsupportthespecifiedinterface.ThisvalueisequaltotheE_NOINTERFACEstandardCOMreturnvalue.

DIERR_NOTACQUIREDTheoperationcannotbeperformedunlessthedeviceisacquired.

DIERR_NOTBUFFEREDThedeviceisnotbuffered.SettheDIPROP_BUFFERSIZEpropertytoenablebuffering.

DIERR_NOTDOWNLOADEDTheeffectisnotdownloaded.

DIERR_NOTEXCLUSIVEACQUIREDTheoperationcannotbeperformedunlessthedeviceisacquiredinDISCL_EXCLUSIVEmode.

DIERR_NOTFOUNDTherequestedobjectdoesnotexist.

DIERR_NOTINITIALIZEDThisobjecthasnotbeeninitialized.

DIERR_OBJECTNOTFOUNDTherequestedobjectdoesnotexist.

DIERR_OLDDIRECTINPUTVERSIONTheapplicationrequiresanewerversionofDirectInput.

DIERR_OTHERAPPHASPRIOAnotherapplicationhasahigherprioritylevel,preventingthiscallfromsucceeding.ThisvalueisequaltotheE_ACCESSDENIEDstandardCOMreturnvalue.Thiserrorcanbereturnedwhenanapplicationhasonlyforegroundaccesstoadevicebutisattemptingtoacquirethedevicewhileinthebackground.

DIERR_OUTOFMEMORYTheDirectInputsubsystemcouldnotallocatesufficientmemorytocompletethecall.ThisvalueisequaltotheE_OUTOFMEMORYstandardCOMreturnvalue.

DIERR_READONLYThespecifiedpropertycannotbechanged.ThisvalueisequaltotheE_ACCESSDENIEDstandardCOMreturnvalue.

DIERR_REPORTFULLMoreinformationwasrequestedtobesentthancanbesenttothedevice.

DIERR_UNPLUGGEDTheoperationcouldnotbecompletedbecausethedeviceisnotpluggedin.

DIERR_UNSUPPORTEDThefunctioncalledisnotsupportedatthistime.ThisvalueisequaltotheE_NOTIMPLstandardCOMreturnvalue.

E_HANDLETheHWNDparameterisnotavalidtop-levelwindowthatbelongstotheprocess.

E_PENDINGDataisnotyetavailable.

E_POINTERAninvalidpointer,usuallyNULL,waspassedasaparameter.


IDirectInputDevice8::GetDeviceStateRetrievesimmediatedatafromthedevice.

HRESULTGetDeviceState(

DWORDcbData,

LPVOIDlpvData

);

Parameters

cbDataSizeofthebufferinthelpvDataparameter,inbytes.

lpvDataAddressofastructurethatreceivesthecurrentstateofthedevice.TheformatofthedataisestablishedbyapriorcalltotheIDirectInputDevice8::SetDataFormatmethod.

ReturnValues



DIERR_INPUTLOSTDIERR_INVALIDPARAMDIERR_NOTACQUIREDDIERR_NOTINITIALIZEDE_PENDING

Remarks

Beforedevicedatacanbeobtained,setthecooperativelevelbyusingtheIDirectInputDevice8::SetCooperativeLevelmethod,thensetthedataformatbyusingIDirectInputDevice8::SetDataFormat,andacquirethedevicebyusingtheIDirectInputDevice8::Acquiremethod.

Thefivepredefineddataformatsrequirecorrespondingdevicestatestructuresaccordingtothefollowingtable:

Dataformat Statestructurec_dfDIMouse DIMOUSESTATEc_dfDIMouse2 DIMOUSESTATE2c_dfDIKeyboard arrayof256bytesc_dfDIJoystick DIJOYSTATEc_dfDIJoystick2 DIJOYSTATE2

Forexample,ifyoupassedthec_dfDIMouseformattotheIDirectInputDevice8::SetDataFormatmethod,youmustpassaDIMOUSESTATEstructuretotheIDirectInputDevice8::GetDeviceStatemethod.

Requirements


SeeAlso

IDirectInputDevice8::Poll,PollingandEventNotification,BufferedandImmediateData


IDirectInputDevice8::GetObjectInfoRetrievesinformationaboutadeviceobject,suchasabuttonoraxis.

HRESULTGetObjectInfo(

LPDIDEVICEOBJECTINSTANCEpdidoi,

DWORDdwObj,

DWORDdwHow

);

Parameters

pdidoiAddressofaDIDEVICEOBJECTINSTANCEstructuretobefilledwithinformationabouttheobject.Thestructure'sdwSizemembermustbeinitializedbeforethismethodiscalled.

dwObjValuethatidentifiestheobjectwhoseinformationistoberetrieved.ThevaluesetforthisparameterdependsonthevaluespecifiedinthedwHowparameter.

dwHowValuethatspecifieshowthedwObjparametershouldbeinterpreted.Thisvaluecanbeoneofthefollowing:Value Meaning

DIPH_BYOFFSETThedwObjparameteristheoffsetintothecurrentdataformatoftheobjectwhoseinformationisbeingaccessed.

DIPH_BYID

ThedwObjparameteristheobjecttype/instanceidentifier.ThisidentifierisreturnedinthedwTypememberoftheDIDEVICEOBJECTINSTANCEstructurereturnedfromapreviouscalltotheIDirectInputDevice8::EnumObjectsmethod.

DIPH_BYUSAGEThedwObjparametercontainstheHIDUsagePageandUsagevaluesoftheobject,combinedbytheDIMAKEUSAGEDWORDmacro.

ReturnValues



DIERR_INVALIDPARAMDIERR_NOTINITIALIZEDDIERR_OBJECTNOTFOUNDE_POINTER

Remarks

ForcompatibilitywithMicrosoft®DirectX®3,itisalsovalidtopassaDIDEVICEOBJECTINSTANCE_DX3structurewiththedwSizememberinitializedtosizeof(DIDEVICEOBJECTINSTANCE_DX3).

Requirements



IDirectInputDevice8::SetDataFormatSetsthedataformatfortheMicrosoft®DirectInput®device.

HRESULTSetDataFormat(

LPCDIDATAFORMATlpdf

);

Parameters

lpdfAddressofastructurethatdescribestheformatofthedatathattheDirectInputDeviceshouldreturn.AnapplicationcandefineitsownDIDATAFORMATstructureoruseoneofthefollowingpredefinedglobalvariables:

c_dfDIKeyboardc_dfDIMousec_dfDIMouse2c_dfDIJoystickc_dfDIJoystick2

ReturnValues



DIERR_ACQUIREDDIERR_INVALIDPARAMDIERR_NOTINITIALIZED

Remarks

ThedataformatmustbesetbeforethedevicecanbeacquiredbyusingtheIDirectInputDevice8::Acquiremethod.Itisnecessarytosetthedataformatonlyonce.Thedataformatcannotbechangedwhilethedeviceisacquired.

Iftheapplicationisusingactionmapping,thedataformatissetinsteadbythecalltoIDirectInputDevice8::SetActionMap.

Requirements


SeeAlso

IDirectInputDevice8::GetDeviceState

Documents

Microsoft DirectX 8.1 Common Framework samples in the SDK ... · You can find further explanations of the graphics and multimedia concepts and terms discussed throughout the Microsoft®