Release Notes for Windows CE for Dreamcast SDK Version 1.0

Discussion in 'Sega Dreamcast Development and Research' started by ASSEMbler, Apr 25, 2011.

  1. ASSEMbler

    ASSEMbler Administrator Staff Member

    Joined:
    Mar 13, 2004
    Messages:
    19,394
    Likes Received:
    1,054
    Welcome to version 1.0 of Microsoft® Windows® CE with DirectX® for the Sega Dreamcast™ System. These release notes contain information on known bugs and problems and additions to the documentation.
    Dreamcast SDK Licensing

    In order to use this software to develop and ship a game title, you must sign the Microsoft Development Tools Agreement for the Microsoft Software Development Kit for Dreamcast. For more information about Dreamcast SDK licenses, please send email to:
    dclicens@microsoft.com
    Redistribution Disclaimer

    Cross Products, Ltd. (CPL) has granted Microsoft the right to redistribute the following CPL products within the Windows CE for Dreamcast Software Development Kit (SDK) provided directly to Sega:
    · The Salsa library for personal computer linked to Microsoft applications.
    · The GD Workshop utility, as supplied to Microsoft by CPL, along with associated Help and ancillary fields.
    · Updated firmware for the Debug Adapter and GD-Emulator, as supplied to Microsoft by CPL.
    · The DACheck utility for upgrading the specified firmware files.

    This redistribution is being allowed so that Microsoft can guarantee compatibility between CPL products and specific releases of the Windows CE for Dreamcast SDK. Microsoft does not market or distribute these products on behalf of CPL. Microsoft provides no warranty to Sega or other users of the Windows CE for Dreamcast SDK for the bundled CPL products, and all responsibility for development and support of the CPL products remains with CPL and Sega.



    Sega Product Development of Sega of America grants Microsoft Corporation the right to freely distribute the following audio conversion tools with the Windows CE for Dreamcast SDK:
    · WaveCon, a PCM-to-ADPCM conversion tool designed to convert uncompressed PCM WAV audio data to the Yamaha Corporation ADPCM format to run on the Sega Dreamcast hardware.
    · DLS2STB, a DLS-to-Sega tonebank converter, designed to convert data from the MMA DLS instrument bank format to the Sega Dreamcast instrument bank.

    Viewing These Documents

    The Windows CE for Dreamcast SDK contains the Windows CE for Dreamcast operating system, all the Dreamcast DirectX components, other OS extensions, sample applications, and documentation. The documentation in Japanese may not be as complete as the English documentation. This SDK is intended to be used with Dreamcast SET5.2x and production hardware.
    The main body of documentation is provided as an InfoViewer title (IVT). In addition, several important documents are built separately as Word 97 files. If you do not have Microsoft Word 97 installed on your computer, install the Word 97 viewer provided on your CD. Run the installation program from one of the following locations:
    · \Eng\Word97Viewer\Wdview97.exe
    · \Jpn\Word97Viewer\Wdview97.exe.

    The following other documents are included with this SDK:
    · Docs\Eng\Setup.doc and Docs\Jpn\Setup.doc
    Information on how to set up your Dreamcast hardware and software, how to use the SDK and set up new applications, and how to create, emulate and burn GD-ROMs.
    · Docs\Eng\Tools.doc and Docs\Jpn\Tools.doc
    Information on the tools for running and debugging applications, including the Visual Studio® integrated development environment (IDE).
    · Docs\Eng\Segafn.doc and Docs\Jpn\Segafn.doc
    Reference information on the special compiler intrinsic functions that take advantage of Dreamcast-specific SH4 instructions.
    · Docs\Eng\Sh4notes.htm and Docs\Jpn\Sh4notes.htm
    Release notes for the Microsoft Windows CE Toolkit for Visual C++® 5.0 and the SH4 IDE Enhancement Pack for the Sega Dreamcast System.

    Windows CE for Dreamcast SDK V1.0 Features

    · Windows CE operating system
    · Win32 Multi-threaded programming model
    · Optimized for Dreamcast (small, fast, flexible)
    · Support for Dreamcast hardware (GD-ROM, Visual Memory, DMA)
    · TCP/IP, RAS, PPP communications protocols; WinSock, WinInet, modem APIs
    · Memory management
    · MIDI API

    · DirectX multimedia API
    · Optimized for Dreamcast SH4, PowerVR2, ARM sound processor
    · DirectDraw: video memory manager for Direct3D
    · Direct3D Immediate Mode: interface for 3D hardware; performs transformation, lighting, rendering
    · DirectInput: input manager (game controller, keyboard, racing wheel)
    · DirectSound: plays and captures digital audio, 3D sound
    · DirectPlay: transport-independent network gaming API
    · DirectShow: Digital audio-video synchronization

    · Tools for remote Dreamcast development: Dreamcast control, profiling, monitoring, peripheral access
    · SDK installs into Visual C++ Interactive Development Environment with SH4 compiler and debugger

    New Features Since the Last Release (Beta 2)

    · Table fog
    · Bump mapping
    · Locking of dynamic surfaces
    · Vector quantization (VQ) textures and surfaces
    · Registry values for control of video memory allocation, DRIVGLOB allocation, and rendering controls
    · Graphics capabilities reported for all hardware and driver features
    · Real-time monitors to view hardware and software performance, textures in video memory, video memory buffer content and usage
    · Function profiler
    · Visual C++ debugging over SCSI
    · Secure Sockets Layer (SSL)
    · Pocket IME and Tankanji IME

    Components List

    The following is a list of all the components of the Windows CE for Dreamcast SDK:
    · DirectDraw®
    · DirectInput®
    · DirectSound®
    · DirectPlay®
    · Direct3D® Immediate Mode
    · DirectShow™
    · MIDI
    · Visual Memory LCD
    · Visual Memory Timer
    · Visual Memory Flash
    · Pocket IME and Tankanji IME
    · WinInet
    · Image decompression library
    · Windows Sockets (Winsock)
    · GD-ROM driver
    · Serial driver
    · Windows CE kernel
    · Remote Access Service (RAS)
    · TCP/UDP/IP/PPP network protocol stack
    · Modem driver

    VCCE Installation CD Key

    At the VCCE install CD key prompt, type in all ones: 111-1111111
    Known Bugs and Problems

    This section contains a list of known bugs and problems with this release of the SDK. Where possible, these will be fixed in the next version.
    DirectDraw

    · DirectDraw currently reports the same set of capabilities for the hardware emulation layer (HEL) and the hardware abstraction layer (HAL). This is actually representative of the complete capabilities of DirectDraw, including those features present in hardware, as well as those that are emulated, such as certain types of bit block transfers (blits).
    · The IDirectDrawColorControl interface and methods are not supported.
    · Triple buffering, with one primary surface and two back buffers, is not supported in this release.
    · Changing the display mode, using IDirectDraw::SetDisplayMode, must be done before any surfaces are created, including the primary surface. Changing the display mode after creating surfaces is unsupported in this version, but is expected to be supported in a later version.
    · The DCY2 FourCC code is not supported in this release.

    DirectInput

    · There is a two-position slide switch just below the START button on Saturn gamepads. The two positions are labeled + for the left position and O for the right position. Be sure the switch is always in the O position; otherwise DirectInput does not function correctly. The Dreamcast gamepads do not have this switch.
    · Because Dreamcast gamepads do not have C or Z buttons, the C and Z buttons on Saturn gamepads are not operative.
    · If the range property is set with a difference between lMax and lMin greater than 429495, the dead-zone property has no effect at any setting.
    · After an application starts, input devices that are unplugged and plugged back in can act in unexpected ways. If the game is not calling Poll on a regular basis, it might take two EnumDevices calls to see the replugged device. This should not be an issue for games that support hot plugging because they would already be calling EnumDevices on a regular basis. This behavior is due to a limitation in the Maple bus architecture and cannot be fixed.

    DirectSound

    · The Wavcon.exe program converts 16-bit pulse code modulation (PCM) .wav files to Yamaha 4-bit ADPCM files, achieving four-to-one compression with nearly 16-bit quality. It provides content compression for DirectSound playback. The Yamaha files can be played only on Dreamcast. Stereo .wav files are not supported by Wavcon.exe. The usage syntax is:
    wavcon infilename outfilename
    · There are some volume fluctuations with one sample converted by Wavcon. There is some error inherent in converting from PCM to ADPCM, and it is worse if the sample quality is low. Some sound-editing programs have normalization features that can clean up dirty, low-quality samples to make them less sensitive to this kind of problem.
    · If you play a YAMAHA ADPCM sound that loops, the volume fluctuates randomly at each loop point. This problem should be fixed in a later release.

    Direct3D

    · Direct3D Retained Mode is not supported in the Dreamcast SDK.
    · Standard D3D viewports are supported, but the viewport boundaries must be multiples of 32 pixels in x and y dimensions.
    · Video modes can now be changed at run time, rather than only on startup.
    · Four-bit palettized textures are now supported in addition to 8-bit palettized textures
    · The punch-through drawing mode is supported, using a 5551 texture with alpha-blending enabled. This means that there are now three drawing phases—opaque, punch-through, and translucent—compared with two in the previous release.
    · Vertex fog is rendered incorrectly with specular highlights. When specular highlighting is enabled, the vertex fog in a scene becomes much too dense. If the specular highlighting is turned off, the fog disappears altogether. The workaround is to use table fog, which also has better performance.
    · The aspect ratio is incorrect for scenes rendered in a 640x240x16 display mode. Objects in the scene appear elongated along the y-axis, and the top and bottom portions of the scene are cropped off by the top and bottom of the screen. The workaround is to set a fake aspect ratio that produces the desired results.
    · A background texture quad appears in front of all other polygons in a scene. Avoid using background temporarily.[FONT=&quot] [/FONT]

    DirectShow

    · To achieve full frame rate with MPEG play, encode MPEG files in a resolution of 320x240 or less, and then scale it with IBasicVideo::SetDestinationPosition to whatever size is needed. The performance of MPEG play is expected to improve in the next release.

    Windows CE

    · The RegFlushKey function always succeeds, but does nothing. This is intentional, for compatibility purposes.
    · Microsoft strongly recommends that application developers use WinInet in ASCII mode, and not in Unicode mode.

    Filesystem

    · After switching from the GD-ROM drive to the GD-ROM emulator, using GD Workshop, you must reboot Dreamcast before it can see the change in the file system.

    Limitations of Samples

    · Some DirectDraw samples, such as Ddex4, Donuts, and Foxbear, running on Windows 95 display incorrect colors with certain video cards. This seems to be a driver issue and has been noted to occur on Matrox Millennium cards.
    · The ImgTest1 sample does not build or run on Windows NT or Windows 95, but it does build and run on Windows CE for Dreamcast.
    · The Httpdump sample does not support asynchronous functionality in this release.

    Visual Studio IDE

    · Uninstalling the SH4 IDE Enhancement Pack without uninstalling the Windows CE Embedded Toolkit for Visual C++ 5.0 displays the following error dialog and prevents you from opening Visual Studio: “The dynamic-link library Devshl.dll could not be found in the specified path…†To avoid this problem, uninstall both or neither.
    · If an application is killed by the IDE because the developer hit Stop Debugging, a large fixed allocation is not freed correctly. The driver prints this message when a new application is started:
    ERROR: Failed to allocate translucent DMA buffer space. Either a previous shutdown of the display driver failed, or the DRIVGLOB section in the Config.bib is too small. The display driver requires 1048576 bytes.
    In this case, choose Boot to reboot the Dreamcast console.

    Miscellaneous

    · Do not connect the Dreamcast development system to an SCSI controller serving other SCSI devices, such as a Windows NT system disk or other hard drives. If you do, the debug adapter may lock up or crash during the development process, resulting in possible data loss.
    · SET5.2 is a 16-MB development station. This is not expected to increase.

    Hardware

    · This release has been extensively tested on Set5.2. It may work on Set5.16, but almost no testing was done, and performance is not guaranteed. There are significant differences between Set5.16 and Set5.2. Set5.16 systems should be upgraded immediately toSet5.2.
    · Accessing video memory 1 byte at a time does not work properly. This is a limitation of the graphics chip. Word and DWORD accesses are okay.
    · The command buffer kept by the video driver is not always flushed when expected. Hardware renders, including blits, are queued and not run until needed; usually, this is signaled to the driver by a flip, a surface lock, or a render or blit to a different surface from the one currently being rendered to. For blit or flip applications, this is not a problem. However, if the front buffer is the target of the render, the application writer must know to lock or unlock a surface; for example, in order to flush the render commands through.
    · Because of a limitation in the Maple hardware, plugging an expansion device into a controller makes the controller appear to be unplugged, and then plugged back in. An application must frequently enumerate DirectInput to protect against users’ plugging in expansion devices. Games must be written to take this into account. In other words, games must handle the case in which joysticks are unplugged and plugged back in. This could also happen for other expansion devices. The Sega Visual Memory has a battery and is normally powered by that battery. When it is connected to a controller, the power source is switched from battery to controller. This transition process takes about two seconds, and Visual Memory cannot respond to a command during this period. In addition, Visual Memory occupies the expansion bus of a controller, and a controller cannot respond to a command from the main body either. As a result, neither a controller nor Visual Memory can respond to the main body for about two seconds after Visual Memory is connected to a controller. This situation causes a time-out, and the controller acts as if it were unplugged. This problem is unavoidable with the current hardware.
    · There is a design limitation in the Visual Memory unit that is compounded by the preceding problem. If the Visual Memory unit is in game mode when it is plugged into a controller, the controller is unplugged as normal, but is not replugged until the Visual Memory unit is unplugged. The user must put the Visual Memory unit in watch mode before plugging it into a controller.
    · When you use the Image Decompression library, RGBA 5551 surfaces may display a pattern of light blue pixels. This is a hardware problem, not a problem in the library software.

    Documentation Issues

    This section includes corrections and additions to the current documentation.
     
    Syclopse likes this.
  2. ASSEMbler

    ASSEMbler Administrator Staff Member

    Joined:
    Mar 13, 2004
    Messages:
    19,394
    Likes Received:
    1,054
    IMG and INIT Environment Variables

    This section lists the environment variables that determine which components go into the binary image. These environment variables should be set appropriately at the command prompt, before running Makeimg to generate a new NK.BIN image. The Makeimg utility is the only tool that is affected by the state of these environment variables. To turn an environment variable on, you must set its value to 1 at the Windows CE command line as follows:
    set IMGDIRECTX=1

    To turn an environment variable off, you must set its value to nothing, which effectively deletes the environment variable, as follows:
    set IMGDIRECTX=

    To view the list of your current environment variables, simply type “set” at the command prompt. You can view the .BIB files and .REG files in your release directory to get a more accurate representation of how these environment variables work. It is recommended that you put only DLLs that are always required for your application into the BIN image. Anything that is in the BIN image will consume RAM for the duration of your application.
    The following environment variables are used in this SDK. “On” lists the files which go into the image when the variable is set to 1. “Off” lists the files which go into the image when this variable is set to nothing.
    IMGNODEBUGGER, IMGSERIALDBG

    These two environment variables determine which kind of kernel debugging capability (using the Windbg debugger) is enabled, according to the following table:
    IMGNODEBUGGER
    IMGSERIALDBG
    Description


    Off
    Off
    SCSI debugging (for Set5.2x)
    Off
    On
    Serial debugging (for Set5 or production hardware)
    On
    Off
    no kernel debugging (default setting)
    On
    On
    no kernel debugging

    Note that even when kernel debugging capabilities are not present, you can still debug at the application level by using Visual Studio 5.0.
    IMGSCIDBG

    This variable should always be off.
    IMGPIME

    Turning this on enables the Pocket IME functionality. It will also add support for all APIs listed in the imm.h and winnls.h header files.
    On
    wince.nls, imejpp.dll, imejppui.dll, msgot.ttf, imejppm.dic, imejppn.dic, imejpps.dic
    Off (default)
    nothing

    IMGTKIME

    Turning this on enables the Tankanji IME functionality. This does not make use of the IMM component (imm.h); it is a separate small library which is intended to handle very simple kana to kanji conversions.
    On
    msgot.ttf
    Off (default)
    nothing

    IMGNOCEDDK

    This variable should always be on.

    IMGNOOLE32

    This variable is used to removed OLE32 functionality from the image.
    On (default)
    nothing
    Off
    ole32.dll

    IMGNOCOMM

    This variable should always be on.
    IMGNOPCMCIA

    This variable should always be on.
    IMGDIRECTSHOW

    This variable controls whether DirectShow components are in the image.
    On
    quartz.dll, icm.dll, iccvid.dll, msacmce.dll
    Off (default):
    nothing

    IMGTM2

    This variable should always be off.
    IMGTINY

    This variable should always be off.
    IMGDIRECTDRAW

    This variable controls whether DirectDraw components are in the image.
    On
    ddraw.dll
    Off (default)
    nothing

    IMGDIRECT3DIM

    This variable controls whether Direct3D Immediate Mode components are in the image.
    On
    d3dim.dll
    Off (default)
    nothing

    IMGDDHAL

    This variable controls whether the graphics driver is in the image.
    On
    ddhal.dll
    Off (default)
    nothing

    IMGDIRECTPLAY

    This variable controls whether DirectPlay components are in the image.
    On
    dplayx.dll, dpwsockx.dll
    Off (default)
    nothing

    IMGDIRECTSOUND

    This variable controls whether DirectSound components are in the image.
    On
    dsound.dll, sndcore.dll
    Off (default)
    nothing

    IMGDIRECTINPUT

    This variable controls whether DirectInput components are in the image.
    On
    dinputx.dll
    Off (default)
    nothing

    IMGDIRECTX

    This variable controls whether all DirectX components are in the image.
    On
    ddraw.dll, d3dim.dll, ddhal.dll, dsound.dll, sndcore.dll, dinputx.dll, segamidi.dll, cemm.dll
    Off (default)
    nothing

    IMGMICROSTK

    This variable controls whether the TCP/IP stack and Winsock components are in the image.
    On (default)
    microstk.exe, mppp.dll, mwinsock.dll, schannel.dll
    Off
    nothing

    IMGKOMODO

    This variable controls whether the WinInet components are in the image.
    On
    wininet.dll
    Off (default)
    nothing

    IMGNOSHELL

    This variable eliminates the Windows CE command line shell from the image. Keep this variable off during development, so that you can use the DCtool command line shell. When you are ready to ship your application or try running it on production hardware, which does not have a SCSI connection, turn this variable on so that these components will not consume space in your image.
    On
    nothing
    Off (default)
    shell.exe, toolhelp.dll

    IMGNODRIVERS

    This variable should always be off.
    IMGDTRACE

    This variable should always be off.
    IMGNOWDM

    This variable should always be off.
    IMGNOCDROM

    This variable should always be off.
    IMGNOMAPLE

    This variable should always be off.
    INITDIRECTSHOW

    This variable causes the appropriate DirectShow registry entries to be added to the BIN image. It is required for all applications that use DirectShow.
    On (default)
    DirectShow enabled
    Off
    DirectShow disabled

    INITNOWDM

    This variable should always be off.
    INITDSOUND

    This variable should always be off. It is now obsolete.
    INITMICROSTK

    This variable causes the TCP/IP stack to get initialized at boot time.
    On (default)
    TCP/IP stack enabled
    Off
    TCP/IP stack disabled

    INITNOCOMM

    This variable should always be on.
    INITSERIAL

    This variable initializes the WDM serial driver.
    On (default)
    Enables the serial driver.
    Off
    Disables the serial driver.

    INITMODEM

    This variable initializes the modem driver.
    On (default)
    Enables the modem driver.
    Off
    Disables the modem driver.

    INITNOMAPLE

    This variable should always be off, assuming your application will need access to the Maple input devices and other peripherals.
    DirectShow Media File Formats and Codecs

    The following media file formats are supported:
    · MPEG file (.mpg, .mpeg, .mpv, .mp2, .mpa)
    · WAV file (.wav)
    · AVI file (.avi)
    · AIF file (.aif, .aiff)
    · AU file (.au)
    · SND file (.snd)

    The following codecs are supported:
    · Video Codecs:
    · MPEG1
    · Cinepak
    · Audio Codecs:
    · MPEG1
    · MS ADPCM
    · IMA ADPCM
    · G.711
    · GSM 6.10

    DirectShow Guide

    · In the multimedia streaming section under Rendering the Video Data to a DirectDraw Surface, the following code example appears, but it is missing the two lines that begin with “pMMStream,” which start and stop the stream. The code is shown correctly here.
    CHECK_ERROR(pDDStream->CreateSample(pSurface, NULL, 0, &pSample));

    pMMStream->SetState(STREAMSTATE_RUN);

    while (true) {
    if (pSample->Update(0, NULL, NULL, 0) != S_OK) {
    break;
    }
    pPrimary->Blt(&rect, pSurface, &rect, DDBLT_WAIT, NULL);
    }

    pMMStream->SetState(STREAMSTATE_STOP);

    · In the multimedia streaming section under Running the Program, the code example under the second bulleted item has an error in the line that begins with pDD. The function call to SetCooperativeLevel uses an unsupported flag. The line of code is shown correctly here.
    pDD->SetCooperativeLevel(hWnd, DDSCL_FULLSCREEN | DDSCL_EXCLUSIVE);


    DirectShow Multimedia Streaming Reference

    · IAMMultiMediaStream::Initialize
    The reference entry for this method incorrectly discusses the use of the AMMSF_NOGRAPHTHREAD flag for the dwFlags parameter. This flag is not supported by Dreamcast, and the dwFlags parameter should always be set to 0. If dwFlags is set to AMMSF_NOGRAPHTHREAD, this method fails and returns E_NOTIMPL.
    · IAMMultiMediaStream::OpenFile
    In the reference entry for this method, MS_E_INVALIDSTREAMTYPE should be added to the list of return values that indicate failure.
    · IAMMultiMediaStream::Render
    The reference entry for this method states that dwFlags must be set to AMMSF_NOCLOCK. Actually this is true only for write streams. For read streams, dwFlags may be set to AMMSF_NOCLOCK, but it is not required.
    · IAudioData::SetFormat
    In the reference entry for this method, the following remarks should be added:
     
  3. ASSEMbler

    ASSEMbler Administrator Staff Member

    Joined:
    Mar 13, 2004
    Messages:
    19,394
    Likes Received:
    1,054
    The format of IAudioData is used only when you call the CreateSample function, and it is used only to verify that the format is compatible with the current format of the stream, if there is one. Beyond that, the format of IAudioData is ignored completely. IAudioData has a very weak connection to the stream and sample using it, so any calls to its GetFormat and SetFormat methods are not propagated anywhere. As a result, it is possible to call SetFormat even while the media file is in the run state.
    · IDirectDrawMediaStream::CreateSample and SetFormat
    The following information should be added to the Remarks section of the reference entries for both of these methods:
    In YUV420 format, image height and width must both be multiples of 16, or this method fails. There is no such restriction with the UYVY format.
    The CreateSample method should also have the following paragraph added to the Remarks section, just ahead of the last paragraph:
    Some upstream codecs may request that read-only video samples be allocated. Unless the user specifies the DDSFF_PROGRESSIVERENDER flag, a second, internal sample is created and the output from the codec is copied to this extra sample at each update, in order to ensure that the read-only agreement is kept. If you use the flag, this copying is avoided whenever possible, but you must not modify the sample because it is read-only. Using the DDSFF_PROGRESSIVERENDER flag does not guarantee that copying will be avoided, as in the case where a codec wants to allocate its own samples to decode upon. If the allocator is not read-only, there is no need to specify the DDSFF_PROGRESSIVERENDER flag, because by default no copying is done. In this case, pdwFlags can be 0.
    · IMultiMediaStream::GetTime
    In the reference entry for this method, the first paragraph under Remarks has a phrase missing from the first sentence. The paragraph should read as follows:
    If the stream does not have a clock and does not support IMediaSeeking, this method sets *pCurrentTime to 0 and returns S_FALSE. If a stream has a clock, the stream sample times are relative to the stream clock.

    Direct3D Guide

    · Rendering to off-screen surfaces
    When rendering to an off-screen surface such as a texture or off-screen surface used for later blits to the primary surface or back buffer, the accumulated render to the off-screen surface needs to be flushed prior to changing the render target again. For this release, it is recommended that applications lock and unlock offscreen surfaces and textures that are used as render targets prior to setting the render target to, for example, the back buffer.
    The following pseudocode demonstrates a typical sequence:
    Frame loop
    {
    SetRenderTarget( offscreen texture ) Clear BeginScene Render to offscreen texture EndScene Lock off-screen texture // Force render to occur.
    // No need to wait for lock to succeed. Unlock off-screen texture, if lock succeeded SetRenderTarget( back buffer ) Clear BeginScene Render from texture to backbuffer EndScene Flip}

    Direct3D Reference

    · Colorkey usage for rendering in 3-D or 2-D blits works only with 8-bit surfaces and textures. Alpha blending in 3-D works only with 16-bit textures.
    · D3DTLVERTEX
    In the reference entry for this structure, there is some incorrect information in the Remarks section about how the system does z-clipping on D3DTLVERTEX vertices. The Dreamcast system does not do any z-clipping on D3DTLVERTEX vertices. The application is expected to clip meshes so that they do not intersect the front clipping plane. Culling against the back clipping plane will not be performed by the system, either. If the vertex type is D3DTLVERTEX, he D3DDDP_DONOTCLIP flag is implied even when it is not explicitly set. Meshes are still clipped by the hardware to the left, right, top, and bottom bounds of the current viewport or the screen. Back-face culling works for D3DTLVERTEX meshes as specified by the current render state settings.
    · Two of the Direct3D overload constructors have their descriptions switched. They should read:
    D3DVERTEX
    The D3D_OVERLOADS constructors for the D3DVERTEX structure offer a convenient way for C++ programmers to create vertices.
    D3DLVERTEX
    The D3D_OVERLOADS constructors for the D3DLVERTEX structure offer a convenient way for C++ programmers to create lit vertices.

    · IDirect3DDevice2
    The D3DDP_OUTOFORDER flag is erroneously documented under four methods of the IDirect3DDevice2 interface. They are Begin, BeginIndexed, DrawIndexedPrimitive, and DrawPrimitive. The D3DDP_OUTOFORDER flag is not supported by Dreamcast.
    · IDirect3DLight::GetLight and IDirect3DLight::SetLight
    The reference entries for both of these methods state that the lpLight parameter is a pointer to a D3DLIGHT2 structure. Actually, it can be a pointer to either a D3DLIGHT or a D3DLIGHT2 structure.

    DirectDraw Reference

    · IDirectDrawColorControl
    The reference entries for this interface and its methods, GetColorControls and SetColorControls, do not state that Dreamcast does not support any color controls. GetColorControls returns DDERR_UNSUPPORTED and reports no color-control capabilities in the dwFlags member of the DDCOLORCONTROL structure.
    · DDCAPS
    The reference entry for this DirectDraw structure fails to state that the dwAlphaOverlayConstBitDepths and dwAlphaOverlayPixelBitDepths members are not supported by Dreamcast.
    Capability Flags for DirectDraw and Direct3D Display Driver

    The following tables list DirectDraw and Direct3D capabilities that can be reported by capability flags, and show which are supported by Dreamcast.
    DirectDraw Capability Flags
    Capability
    Supported by Dreamcast?


    DDCAPS_3D
    Yes
    DDCAPS_BLT
    Yes
    DDCAPS_BLTQUEUE
    Yes
    DDCAPS_BLTFOURCC
    Yes
    DDCAPS_BLTSTRETCH
    Yes
    DDCAPS_GDI
    Yes
    DDCAPS_OVERLAY
    No
    DDCAPS_OVERLAYCANTCLIP
    No
    DDCAPS_OVERLAYFOURCC
    No
    DDCAPS_OVERLAYSTRETCH
    No
    DDCAPS_PALETTE
    Yes
    DDCAPS_PALETTEVSYNC
    Yes
    DDCAPS_READSCANLINE
    Yes
    DDCAPS_STEREOVIEW
    No
    DDCAPS_VBI
    Yes
    DDCAPS_ZBLTS
    No
    DDCAPS_ZOVERLAYS
    No
    DDCAPS_COLORKEY
    Yes
    DDCAPS_ALPHA
    No
    DDCAPS_COLORKEYHWASSIST
    Yes
    DDCAPS_NOHARDWARE
    No
    DDCAPS_BLTCOLORFILL
    Yes
    DDCAPS_BANKSWITCHED
    No
    DDCAPS_BLTDEPTHFILL
    Yes
    DDCAPS_CANCLIP
    No
    DDCAPS_CANCLIPSTRETCHED
    No
    DDCAPS_CANBLTSYSMEM
    Yes
    DDCAPS2_CERTIFIED
    No
    DDCAPS2_NO2DDURING3DSCENE
    Yes
    DDCAPS2_VIDEOPORT
    No
    DDCAPS2_AUTOFLIPOVERLAY
    No
    DDCAPS2_CANBOBINTERLEAVED
    No
    DDCAPS2_CANBOBNONINTERLEAVED
    No
    DDCAPS2_COLORCONTROLOVERLAY
    No
    DDCAPS2_COLORCONTROLPRIMARY
    No
    DDCAPS2_CANDROPZ16BIT
    No
    DDCAPS2_NONLOCALVIDMEM
    No
    DDCAPS2_NONLOCALVIDMEMCAPS
    No
    DDCAPS2_NOPAGELOCKREQUIRED
    No
    DDCAPS2_WIDESURFACES
    Yes
    DDCAPS2_CANFLIPODDEVEN
    No
    DDCAPS2_CANBOBHARDWARE
    No
    DDCAPS2_COPYFOURCC
    Yes

    Color Key Capability Flag
    Capability
    Supported by Dreamcast?


    DDCKEYCAPS_SRCBLT
    Yes

    Blit Effects Capability Flags
    Capability
    Supported by Dreamcast?


    DDFXCAPS_BLTMIRRORUPDOWN
    Yes
    DDFXCAPS_BLTSTRETCHY
    Yes
    DDFXCAPS_BLTSHRINKY
    Yes
    DDFXCAPS_BLTSTRETCHX
    Yes
    DDFXCAPS_BLTSHRINKX
    Yes

    Palette Capability Flags
    Capability
    Supported by Dreamcast?


    DDPCAPS_1BIT
    No
    DDPCAPS_2BIT
    No
    DDPCAPS_4BIT
    Yes
    DDPCAPS_8BITENTRIES
    No
    DDPCAPS_8BIT
    Yes
    DDPCAPS_INITIALIZE
    Yes
    DDPCAPS_PRIMARYSURFACE
    No
    DDPCAPS_PRIMARYSURFACELEFT
    No
    DDPCAPS_ALLOW256
    Yes

    Surface Capability Flags
    Capability
    Supported by Dreamcast?


    DDSCAPS_ALPHA
    No
    DDSCAPS_BACKBUFFER
    Yes
    DDSCAPS_COMPLEX
    Yes
    DDSCAPS_FLIP
    Yes
    DDSCAPS_FRONTBUFFER
    Yes
    DDSCAPS_OFFSCREENPLAIN
    Yes
    DDSCAPS_OVERLAY
    No
    DDSCAPS_PALETTE
    Yes
    DDSCAPS_PRIMARYSURFACE
    Yes
    DDSCAPS_PRIMARYSURFACELEFT
    No
    DDSCAPS_TEXTURE
    Yes
    DDSCAPS_SYSTEMMEMORY
    Yes
    DDSCAPS_VIDEOMEMORY
    Yes
    DDSCAPS_VISIBLE
    Yes
    DDSCAPS_ZBUFFER
    Yes
    DDSCAPS_EXECUTEBUFFER
    Yes
    DDSCAPS_3DDEVICE
    Yes
    DDSCAPS_WRITEONLY
    Yes
    DDSCAPS_ALLOCONLOAD
    Yes
    DDSCAPS_MIPMAP
    Yes

    Alpha Compare Function Flags
    Capability
    Supported by Dreamcast?


    D3DPCMPCAPS_NEVER
    No
    D3DPCMPCAPS_LESS
    No
    D3DPCMPCAPS_EQUAL
    No
    D3DPCMPCAPS_LESSEQUAL
    No
    D3DPCMPCAPS_GREATER
    No
    D3DPCMPCAPS_NOTEQUAL
    No
    D3DPCMPCAPS_GREATEREQUAL
    No
    D3DPCMPCAPS_ALWAYS
    No

    Cull Mode Flags
    Capability
    Supported by Dreamcast?


    D3DPMISCCAPS_CULLNONE
    Yes
    D3DPMISCCAPS_CULLCW
    Yes
    D3DPMISCCAPS_CULLCCW
    Yes

    Plane Mask Flags
    Capability
    Supported by Dreamcast?


    D3DPMISCCAPS_MASKPLANES
    No
    D3DPMISCCAPS_MASKZ
    Yes
    D3DPMISCCAPS_LINEPATTERNREP
    No

    Destination Blending Capability Flags
    Capability
    Supported by Dreamcast?


    D3DPBLENDCAPS_ZERO
    Yes
    D3DPBLENDCAPS_ONE
    Yes
    D3DPBLENDCAPS_SRCCOLOR
    Yes
    D3DPBLENDCAPS_INVSRCCOLOR
    Yes
    D3DPBLENDCAPS_SRCALPHA
    Yes
    D3DPBLENDCAPS_INVSRCALPHA
    Yes
    D3DPBLENDCAPS_DESTALPHA
    Yes
    D3DPBLENDCAPS_INVDESTALPHA
    Yes
    D3DPBLENDCAPS_DESTCOLOR
    No
    D3DPBLENDCAPS_INVDESTCOLOR
    No
    D3DPBLENDCAPS_SRCALPHASAT
    No
    D3DPBLENDCAPS_BOTHSRCALPHA
    Yes
    D3DPBLENDCAPS_BOTHINVSRCALPHA
    Yes

    Raster Capability Flags
    Capability
    Supported by Dreamcast?


    D3DPRASTERCAPS_DITHER
    Yes
    D3DPRASTERCAPS_FOGVERTEX
    Yes
    D3DPRASTERCAPS_FOGTABLE
    Yes
    D3DPRASTERCAPS_ROP2
    No
    D3DPRASTERCAPS_STIPPLE
    No
    D3DPRASTERCAPS_SUBPIXEL
    Yes
    D3DPRASTERCAPS_ZBUFFERLESSHSR
    Yes

    Shading Capability Flags
    Capability
    Supported by Dreamcast?


    D3DPSHADECAPS_COLORFLATMONO
    No
    D3DPSHADECAPS_COLORFLATRGB
    Yes
    D3DPSHADECAPS_COLORGOURAUDMONO
    No
    D3DPSHADECAPS_COLORGOURAUDRGB
    Yes
    D3DPSHADECAPS_COLORPHONGMONO
    No
    D3DPSHADECAPS_COLORPHONGRGB
    No
    D3DPSHADECAPS_SPECULARFLATMONO
    No
    D3DPSHADECAPS_SPECULARFLATRGB
    Yes
    D3DPSHADECAPS_SPECULARGOURAUDMONO
    No
    D3DPSHADECAPS_SPECULARGOURAUDRGB
    Yes
    D3DPSHADECAPS_SPECULARPHONGMONO
    No
    D3DPSHADECAPS_SPECULARPHONGRGB
    No
    D3DPSHADECAPS_ALPHAFLATBLEND
    Yes
    D3DPSHADECAPS_ALPHAFLATSTIPPLED
    No
    D3DPSHADECAPS_ALPHAGOURAUDBLEND
    Yes
    D3DPSHADECAPS_ALPHAGOURAUDSTIPPLED
    No
    D3DPSHADECAPS_ALPHAPHONGBLEND
    No
    D3DPSHADECAPS_ALPHAPHONGSTIPPLED
    No
    D3DPSHADECAPS_FOGFLAT
    Yes
    D3DPSHADECAPS_FOGGOURAUD
    Yes
    D3DPSHADECAPS_FOGPHONG
    No

    Source Blending Capability Flags
    Capability
    Supported by Dreamcast?


    D3DPBLENDCAPS_ZERO
    Yes
    D3DPBLENDCAPS_ONE
    Yes
    D3DPBLENDCAPS_SRCCOLOR
    No
    D3DPBLENDCAPS_INVSRCCOLOR
    No
    D3DPBLENDCAPS_SRCALPHA
    Yes
    D3DPBLENDCAPS_INVSRCALPHA
    Yes
    D3DPBLENDCAPS_DESTALPHA
    Yes
    D3DPBLENDCAPS_INVDESTALPHA
    Yes
    D3DPBLENDCAPS_DESTCOLOR
    Yes
    D3DPBLENDCAPS_INVDESTCOLOR
    Yes
    D3DPBLENDCAPS_SRCALPHASAT
    No
    D3DPBLENDCAPS_BOTHSRCALPHA
    Yes
    D3DPBLENDCAPS_BOTHINVSRCALPHA
    Yes

    Texture Address Capability Flags
    Capability
    Supported by Dreamcast?


    D3DPTADDRESSCAPS_WRAP
    Yes
    D3DPTADDRESSCAPS_MIRROR
    Yes
    D3DPTADDRESSCAPS_CLAMP
    Yes


    Texture Capability Flags
    Capability
    Supported by Dreamcast?


    D3DPTEXTURECAPS_PERSPECTIVE
    Yes
    D3DPTEXTURECAPS_POW2
    Yes
    D3DPTEXTURECAPS_ALPHA
    Yes
    D3DPTEXTURECAPS_TRANSPARENCY
    Yes
    D3DPTEXTURECAPS_BORDER
    No
    D3DPTEXTURECAPS_SQUAREONLY
    No

    3D Device Capability Flags
    Capability
    Supported by Dreamcast?


    D3DDEVCAPS_FLOATTLVERTEX
    Yes
    D3DDEVCAPS_SORTINCREASINGZ
    No
    D3DDEVCAPS_SORTDECREASINGZ
    No
    D3DDEVCAPS_SORTEXACT
    No
    D3DDEVCAPS_EXECUTESYSTEMMEMORY
    Yes
    D3DDEVCAPS_EXECUTEVIDEOMEMORY
    No
    D3DDEVCAPS_TLVERTEXSYSTEMMEMORY
    Yes
    D3DDEVCAPS_TLVERTEXVIDEOMEMORY
    No
    D3DDEVCAPS_TEXTURESYSTEMMEMORY
    No
    D3DDEVCAPS_TEXTUREVIDEOMEMORY
    Yes
    D3DDEVCAPS_DRAWPRIMTLVERTEX
    Yes
    D3DDEVCAPS_CANRENDERAFTERFLIP
    Yes
    D3DDEVCAPS_TEXTURENONLOCALVIDMEM
    No

    Texture Filtering Capability Flags
    Capability
    Supported by Dreamcast?


    D3DPTFILTERCAPS_NEAREST
    Yes
    D3DPTFILTERCAPS_LINEAR
    Yes
    D3DPTFILTERCAPS_MIPNEAREST
    Yes
    D3DPTFILTERCAPS_MIPLINEAR
    Yes
    D3DPTFILTERCAPS_LINEARMIPNEAREST
    Yes
    D3DPTFILTERCAPS_LINEARMIPLINEAR
    Yes

    Texture Blending Capability Flags
    Capability
    Supported by Dreamcast?


    D3DPTBLENDCAPS_DECAL
    Yes
    D3DPTBLENDCAPS_MODULATE
    Yes
    D3DPTBLENDCAPS_DECALALPHA
    Yes
    D3DPTBLENDCAPS_MODULATEALPHA
    Yes
    D3DPTBLENDCAPS_DECALMASK
    No
    D3DPTBLENDCAPS_MODULATEMASK
    No
    D3DPTBLENDCAPS_COPY
    Yes
    D3DPTBLENDCAPS_ADD
    No
     
  4. ASSEMbler

    ASSEMbler Administrator Staff Member

    Joined:
    Mar 13, 2004
    Messages:
    19,394
    Likes Received:
    1,054
    Z Compare Function Flags
    Capability
    Supported by Dreamcast?


    D3DPCMPCAPS_NEVER
    Yes
    D3DPCMPCAPS_LESS
    Yes
    D3DPCMPCAPS_EQUAL
    Yes
    D3DPCMPCAPS_LESSEQUAL
    Yes
    D3DPCMPCAPS_GREATER
    Yes
    D3DPCMPCAPS_NOTEQUAL
    Yes
    D3DPCMPCAPS_GREATEREQUAL
    Yes
    D3DPCMPCAPS_ALWAYS
    Yes

    DirectSound Reference

    · DSCAPS
    In the reference entry for this structure, the following information is missing from the list of flag values under the dwFlags member:
    DSCAPS_PRIMARY16BIT
    The device supports primary sound buffers with 16-bit samples.
    DSCAPS_PRIMARY8BIT
    The device supports primary sound buffers with 8-bit samples.
    DSCAPS_PRIMARYMONO
    The device supports monophonic primary buffers.

    · IDirectSoundBuffer::play
    Calls to this method for buffers created with the DSBCAPS_LOCHARDWARE flag cause playback to start at the beginning of the buffer, not at the position where playback was stopped. This is due to limitations of the hardware and the driver.
    · IDirectSoundBuffer::SetCurrentPosition
    This method is not supported for DSBCAPS_LOCHARDWARE buffers. Furthermore, this method resets playback to the beginning of playing buffers. This is due to limitations of the hardware and the driver.
    · IDirectSoundBuffer::Stop
    Calls to this method for buffers created with the DSBCAPS_LOCHARDWARE flag cause the play position to be reset to the beginning of the buffer so that the next playback resumes at the beginning, not at the position where playback stopped. This is due to limitations of the hardware and the driver.
    Windows CE System Services Guide

    Input Method Editors

    The following information about the Pocket Input Method Editor (pIME) and the Tankanji Input Method Editor (TKIME) is missing from the IME Japanese Keyboard section under Input Method Editors in the System Services Guide:
    · The pIME and the TKIME cannot run simultaneously, and after one has been run, both of their environment variables must be changed before the other can be run. For example, if you run the TKIME first, you must set the following environment variables before you can run the pIME. There should be nothing after the equal sign in the first line, not even a space.
    IMGTKIME=
    IMGPIME=1

    · If you want to type in double-width English, exactly one of the IMEs must be turned on. When both IMEs are off, you cannot type in double-width English.
    · When using the TKIME in Katakana mode with full-width and RKC turned on, you cannot change to half-width with the hankaku/zenkaku keys.
    · When using the TKIME with the on-screen keyboard, ke and ka do not change to small characters, and therefore can be selected only from the large characters.
    · Neither the pIME nor the TKIME allows you to display special symbols with the hardware keyboard, only with the on-screen keyboard.
    · Neither the pIME nor the TKIME allows you to use the gamepad and keyboard simultaneously for character input. You must use one or the other.
    · When using either IME, you must unplug and replug the keyboard between uses.
    · When using either IME, if you press ALT+TILDE when you have undetermined clauses, your text is erased.
    · The UP and DOWN arrow keys do not function in the on-screen keyboard for either IME. The RIGHT and LEFT arrow keys do function in the on-screen keyboard, and all four arrows function on the hardware keyboard.
    · When the pIME is on, never press the CTRL key and type at the same time. This inserts text and your undetermined clauses are moved.
    · Neither IME supports half-width Hiragana.
    · In the pIME, you cannot select full-width Katakana from the candidate list when the output window is full.
    · The Kanji for people’s names (Jinmei) is supported.
    · You cannot input characters past the right edge of the edit box.

    The following section is also missing from the Windows CE System Services Guide:
    Speeding Up Code by Reducing Calls to EnumDevices

    Calls to the MapleEnumDevices function and the DirectInput::EnumDevices function take too long to be made every frame. These calls should be made only when a new device is attached to the system. To facilitate this, Dreamcast offers a special solution, but this solution does not work on Windows 95 or Windows NT.
    On Windows CE for Dreamcast, a named event with the name MAPLE_NEW_DEVICE is created by the input driver before the game loads. Every time a new device is attached to the system, that event is signaled. The game can call the WaitForSingleObject function with a time-out of 0 to determine whether a new device has been attached. If a new device has been attached, that function returns immediately with WAIT_OBJECT_0. If no new devices have been attached, it returns immediately with WAIT_TIMEOUT. The enumeration functions need to be called only if a new device has been attached. The Dimapletst sample shows how to use this functionality.
    It is recommended that the application enumerate devices once at initialization, regardless of the state of MAPLE_NEW_DEVICE. This ensures that no other application has cleared the MAPLE_NEW_DEVICE event. The event is cleared whenever the WaitForSingleObject function is called.
    The following code example enumerates devices only when new devices are attached.
    #ifdef UNDER_CE
    HANDLE hNewDeviceEvent =
    CreateEvent(NULL, FALSE, FALSE, TEXT("MAPLE_NEW_DEVICE"));
    if (hNewDeviceEvent == NULL)
    {
    DbgPrintf(TEXT("Error creating new device event. Closing.\n"));
    return(0);
    }
    #endif

    // Enumerate DirectInput and MapleDevice once before the game starts.

    while (PLAYING_GAME)
    {
    // Do game processes here.

    #ifdef UNDER_CE
    if (WaitForSingleObject(hNewDeviceEvent, 0) != WAIT_TIMEOUT)
    {
    #endif
    // Enumerate DirectInput.
    // Enumerate MapleDevices.
    #ifdef UNDER_CE
    }
    #endif
    }
    Processing Character Messages

    The article titled Processing Character Messages, in the Keyboard Input section of the System Services Guide states that the following keys generate WM_CHAR messages: BACKSPACE, ENTER, ESC, SHIFT+ENTER, and TAB. That functionality is not present in this release of Windows CE for Dreamcast. Printable-character keys generate WM_CHAR messages, but these five do not.
    Windows CE System Services Reference

    · Seven macros are missing from the Japanese System Services Reference. Please refer to the English System Services Reference under Macros for documentation of the following:
    FD_CLR
    FD_ISSET
    FD_SET
    FD_ZERO
    timerclear
    timercmp
    timerisset
    · CreateEvent
    In the reference entry for this function the paragraph under Remarks that begins with “Two or more processes can call...” ends with an erroneous sentence about using the bInitialOwner flag. That sentence should be deleted; the bInitialOwner flag is not used with CreateEvent.
    · FirmwareGetSerialNumber
    In the reference entry for this function, the description of the lpdwReturned parameter correctly states what the parameter contains when the function returns. However, it fails to mention that before calling this function, the caller must set this parameter to the size, in bytes, of the buffer being passed in by the pBuffer parameter.
    · HttpOpenRequest
    The reference entry for this function erroneously lists the INTERNET_FLAG_SECURE flag as a possible value for the dwFlags parameter. INTERNET_FLAG_SECURE works with the InternetConnect and InternetOpenUrl functions, but not with HttpOpenRequest.
    · ILcd Interface
    The following remarks should be added to the reference entry for this interface:
    To use the ILcd interface, you must include the Mapledev.h and Lcd.h header files and link the Mapledev.lib and Dxguid.lib libraries.
    If this interface represents an LCD device that has been removed, any method invoked on the interface fails and returns an appropriate error value. Even if the device is then reinserted, the application must close all interfaces on the device and recreate them to regain access to the device.
    · ITmr Interface
    The following remarks should be added to the reference entry for this interface:
    To use the ITmr interface, you must include the Mapledev.h and Maptimer.h header files and link the Mapledev.lib and Dxguid.lib libraries.
    If this interface represents a timer device that has been removed, any method invoked on the interface fails and returns an appropriate error value. Even if the device is then reinserted, the application must close all interfaces on the device and recreate them to regain access to the device.
    · MapleEnumerateDevices
    The following information should be added to the Remarks section of the reference entry for this function:
    If you make a call to this function while the mapledevtype parameter is set to MDT_ALLDEVICES and a keyboard is plugged in, the keyboard will be enumerated and will show a device type of 0x40. The keyboard cannot be used through the MapleDevice API, so this should be ignored. To use a keyboard, you should use either Windows messages (WM_CHAR and WM_KEYDOWN) or DirectInput.
    · MEMORYSTATUS
    The reference entry for this structure says that you do not need to set the dwLength member. That is not true. The description of dwLength should read:
    dwLength
    Specifies the size, in bytes, of this structure. You must set this member before you call the GlobalMemoryStatus function.
    · midiStreamOut
    The reference entry for this function says that the MIDI buffer must be smaller than 64 KB when this function is being used. There is no such restriction.
    · ReadFile
    In the reference entry for this function, under the parameter lpNumberOfBytesRead, the last two of three paragraphs contain inaccurate information about when this parameter can be NULL. These two paragraphs should be replaced with the following:
    This parameter cannot be NULL.
    · GetKeyboardLayout
    The following entry is missing from the reference:
    GetKeyboardLayout

    This function retrieves the active keyboard layout for the current thread.
    Syntax

    HKL GetKeyboardLayout ( DWORD idThread );
    Parameters

    idThread
    Must be zero for Dreamcast, specifying a query of the current thread.
    Return Values

    Returns the keyboard layout handle for the thread.
    See Also

    CreateThread

    · GetVideoOutputFormat
    The following entry is missing from the reference:
    GetVideoOutputFormat

    This function gets the current video output format.
    Syntax

    BYTE GetVideoOutputFormat ( VOID );
    Parameters

    None.
    Return Values

    One of the following values is returned, indicating the video output format currently in use:
    VIDFMT_NTSC
    VIDFMT_PAL
    VIDFMT_PAL_M
    VIDFMT_PAL_N
    VIDFMT_VGA

    Remarks

    To use this function, the application must include the Platutil.h header file and link with Platutil.lib.

    Appendix of Sample Applications

    · DirectShow Samples
    To build DirectShow applications, such as the sample applications Playit and iPlayit, you must link the Ddraw.lib, Strmiids.lib, and Ole32.lib libraries.
    Sega Passport

    Sega Passport information is registry data for network communications. It is stored in the internal flash memory. When Windows CE for Dreamcast boots up, it checks the Sega Passport information in the flash memory. If valid Sega Passport information is found, it is loaded into the system registry HKEY_LOCAL_MACHINE\Comm\NetworkInfo, the built-in modem is configured accordingly, and a remote access server (RAS) entry named ISP0 is created. All applications should access the Sega Passport information through the registry. The registry value NetworkInfo is of type REG_BINARY and contains a binary dump of a NetworkInfo type, which is defined in the Netinfo.h header file.
    Any changes made to the Sega Passport information in the internal flash memory are not reflected in the registry until the system reboots or the FlashLoadNetworkInfo function is called.
    FlashLoadNetworkInfo

    This function loads Sega Passport information into the system registry and configures the built-in modem accordingly. It also creates a RAS entry named ISP0 (ISP-zero) with dial-up information from the Sega Passport.
    Syntax

    BOOL FlashLoadNetworkInfo ( CONST NetworkInfo *pInfo OPTIONAL, DWORD nLength, LPDWORD lpnStatus OPTIONAL );
    Parameters

    pInfo
    [in] Reserved. Must be NULL.
    nLength
    [in] Specifies the size of NetworkInfo type.
    lpnStatus
    [out] Reserved. Must be NULL.
    Return Values

    If the function succeeds, the return value is nonzero. If the function fails, the return value is 0, and a specific error code can be retrieved by calling GetLastError.
    Remarks

    The identifier OPTIONAL in the syntax after *pInfo and lpnStatus is defined with an empty definition in a header file. It is removed by the preprocessor, so the compiler never sees it. OPTIONAL amounts to a comment to let you know that a NULL pointer is permitted here, and in this function NULL pointers are required.
    The function overwrites the ISP0 RAS entry only when a valid NetworkAccessInfo is found. The caller should delete the ISP0 entry by calling RasDeleteEntry if no valid NetworkAccessInfo is found.
    This function is declared in the Platutil.h header file and defined in Platutil.lib.
    Additional Tools Information

    · Debugging
    The Tools.doc incorrectly states that RAS is required for debugging. Debugging should now be done over SCSI. RAS was required for beta users but not for this release. The RAS setup is still needed for certain sample applications, such as Httpdump.
    · Pvrconv.exe
    The following information is missing from the Tools Overview section of Tools.doc:
    Pvrconv is a Sega tool to help you create Vector Quantization (VQ) compressed textures by converting textures from various formats (.pic, .bmp, .tga, .pix) into PowerVR texture .pvr files. Pvrconv.exe is in the <WCEDreamcast>\Tools directory along with Pvrconv.doc and Pvrconvj.doc, the English and Japanese versions of the document explaining how to use this tool. For additional information on creating and manipulating VQ surfaces in Dreamcast, see the Surfaces section under DirectDraw in the DirectX documentation. This can be viewed using the IDE InfoViewer.
    · SynthAuthor Sound Tool
    The following information is missing from the Tools Overview section of Tools.doc:
    In the Eng\Synthauth and Jpn\Synthauth directories on the CD you will find a sound authoring tool. Use SynthAuthor to create collections of instruments for the Dreamcast synthesizer or for any synthesizer designed to support the Downloadable Sample Architecture (DLS) specification. Please see the SynthAuthor.doc in these directories for information on how to use this tool.
    There are 2 MB of audio memory on the Dreamcast game console. Those 2 MB must be shared among all audio components, including tonebanks, MIDI sequences, and PCM streams (wave files). In addition, a very small amount of memory is taken up by the ARM7 driver. The maximum size of a tonebank is defined by how much other data is used. If a large, high-quality tonebank is loaded into sound memory, there is not much space left to load the actual MIDI sequences that might use that tonebank.
    You can use the SynthAuthor sound tool whether or not your sound card is DLS-enabled. SynthAuthor is used to create DLS files from WAV input or WAV files, and these may be played and tested with the software synthesizer or by using DLS download software provided with the sound card if your sound card supports DLS intrinsically.
    To convert your MMA/DLS Level 1 instrument collection to the Sega Tonebank format, use the DLS2TB.EXE program in the <WCEDreamcast>\tools directory. See the DLS2TB.TXT file on how to use this command-line DOS utility.
    · Allocating Continuous Physical Memory
    The following information is missing from Allocating Continuous Physical Memory in Tools.doc. It is an addition to the end of step 3.
    The OS uses 64-KB or 1-MB pages only when both physical and virtual addresses are aligned to pages of the appropriate size. You can manually align a physical address, but you have no control over the virtual address allocated by MmMapIoSpace. So there is no way to guarantee a certain page size is used. For example, if you pass in a 1-MB-aligned physical address to MmMapIoSpace and ask it to map 1 MB starting from that address, the optimal solution is to use one page of 1 MB. However, because MmMapIoSpace does not guarantee that the virtual address it is mapped to is 1-MB-aligned, the result may use a page size of 64 KB or even 4 KB. A workaround is to use VirtualAlloc directly and do the alignment yourself.

    Setting Up the Remote Debug Monitor

    The remote debug monitor is a small program on the Windows 95 target computer that communicates with the debugger and controls the execution of the program you are debugging. To install the remote debug monitor:
    1. Install Dreamcast on your host computer.
    2. On a Windows 95 computer, the remote debug monitor consists of the following files:
    · Msvcmon.exe
    · Msvcrt.dll
    · Tlnot.dll
    · Dm.dll
    · Msvcp5o.dll
    · Msdis109.dll

    Copy these files to the remote computer. These files are found in \Program files\Devstudio\Sharedide\Bin.
    3. These files must be the same on your host computer and target computer. Do not use previous versions of these files from previous Visual C++ installations.
    4. Follow the normal instructions for remote debugging as provided in the Visual C++ online Help

    Hitachi SH4 Processor

    This section contains information about various SH4 processor issues, including bugs fixed and bugs not fixed since the last release, and some tips for writing faster code for the SH4.
    Compiler Bugs Fixed

    · An internal compiler error (assertion failure) previously occurred in some cases when generating code for an empty switch statement.
    · Incorrect code was previously generated when dereferencing pointers of 16-bit unsigned integers, using the /Zi option.
    · Within an expression, when performing a signed compare using the result of an unsigned compare, the compiler previously generated both compares as unsigned. This error only occurred when the unsigned compare was = = or !=.
    · The compiler formerly issued an assertion when the bra 0 instruction was invoked.
    · The SinCosA and fmac intrinsic functions are now working properly
    · Inline assembly now works correctly when string pooling is used with aggressive inlining (/Ob2).

    Compiler Bugs Not Fixed

    · A call to an sprintf pointer that is cast to varargs fails on SH4. This will be fixed in a future release.
    · This new release adds support for the /Oa and /Ow compiler options, which you may use to specify that a program follows a specific set of rules with respect to the use of pointers and aliases. The use of these options enables optimizations in the compiler that might otherwise be impossible.
    There is one case of pointer usage that is so common that, although it is technically a violation of the /Oa rules, it should be recognized and accounted for by the compiler, even when /Oa is used. This is the use of scalar reference arguments and pointer-to-scalar arguments. In these cases, the intent is almost always that the value of the scalar indicated by the pointer or reference be updated by the call.
    The current implementation of /Oa for SH4 does not recognize this intent, which is a technical violation of the /Oa rules, and assumes that the aliased scalar’s value is not adjusted by the call. In the next release, the use of /Oa in these cases will be safe.
    However, the current implementation of /Ow for SH4, which assumes updates of aliased values across function calls, is safe to use in these circumstances and provides most of the advantages provided by the /Oa option.
    The following code example shows a case that fails when /Ox and /Oa are used together.
    void f(double& a) { a += 3.14; }

    int main()
    {
    double d = 0;
    f(d);
    if (d != 3.14)
    {
    printf("Reference argument failed to modify its object.\n");
    return(-1);
    }
    return 0;
    }


    Compiler Issues and Problems

    The following problems and issues were encountered in the preparation of this release.
    Inline Assembly and SH4 Mode Bits

    The semantics of several instructions of the SH4 are subject to the control of mode bits in the FPSCR control register. These bits include FR, PR, and SZ. These bits dictate which floating-point register bank is currently active and the size of floating-point register operands: 32 or 64 bits.
    The SH4 calling standard dictates specific rules about the state of these mode bits upon entry to and exit from function calls. Inline assembly code that modifies the values of these bits must avoid the violation of these rules and should follow these rules as if they were, in fact, separate function calls.
    Specifically, before control leaves the scope of an inline assembly sequence, the mode bits must be returned to the values that they had upon entry to the scope. Failure to maintain consistency in these mode bits may result in undefined and unanticipated program failures.
    The sqrt Intrinsic Workaround for OS Builds

    The operating system contains a definition of the sqrt function that generates a warning when built with a compiler that recognizes sqrt as an intrinsic function, and all warnings are treated as fatal errors. This prevents the compiler from treating the sqrt function as an intrinsic function.
    A future release of the compiler will identify and override calls to the sqrt function with an inline version that uses the FSQRT instruction. This implementation will bypass the standard intrinsic function mechanics.
    Varargs Calls through Pointers

    The SH4 calling standard provides for several methods to pass arguments on the SH4 to allow the most efficient use of the floating-point register file, when appropriate. But in the case of variable argument lists (Varargs), little flexibility is available, due to the lack of information about argument types available at compile time.
    In this release, some cases have been noted where calls are made using pointers to Varargs that have not been correctly identified as having variable argument lists. In these cases, floating-point arguments may not be correctly passed. Care should be taken in these cases to ensure that correct behavior is occurring. Avoid calling Varargs through pointers.
    Partial Redundancy Elimination

    This optimization improves run-time efficiency by moving calculations from flow traces where they are unused. This is sometimes achieved by duplicating code sequences and, in many cases, increases code size.
    Recently, performance measurements have shown paradoxical results. While manual examination of the generated code showed that it had improved, the run-time results showed a net loss in test-case performance.
    Further analysis indicates that the increase in code size can damage cache efficiency on many of the currently available SH4 environments and so may account for this speed loss. Use the /Qpartial option only after experimentation has indicated that it is helpful in improving performance.
    See Compile-Time Speed Improvements in the next section.
    Compiler Documentation Issues

    In the compiler Help files (Sh4docs.ivt) there are errors in the documentation of the _Xform3dV function. The Description section should read as follows:
    Multiply a three-dimensional vector by a 3x3 matrix.
    | a11 a12 a13 | | v0 | | (a11 * v0) + (a12 * v1) + (a13 * v2) |
    | a21 a22 a23 | | v1 | | (a21 * v0) + (a22 * v1) + (a23 * v2) |
    | a31 a32 a33 | | v2 | | (a31 * v0) + (a32 * v1) + (a33 * v2) |

    This intrinsic will load the following floating-point registers with a constant zero:
    fr12
    fr13
    fr14
    fr3 fr7 fr11 fr15

    This is because the hardware instruction supports both three-element and four-element matrix multiplication. This intrinsic function implements the three-element version.
    The main function in the example should look like this:
    void main()
    {
    int i;
    float dest[3];
    float src[3]; = {1.0, 2.0, 3.0};

    float matrix[9]={1.0, 2.0, 3.0,
    4.0, 5.0, 6.0,
    7.0, 8.0, 9.0};

    _Xform3dV(dest, src, matrix); // [matrix]x[src] à dest
    print_matrix(matrix, src, dest);
    }
    The output listed is correct.
    Compiler Features

    This release contains the following features and improvements.
    SH4 Intrinsic Functions Include Files

    The Include file containing the declarations for the SH4 intrinsic functions has been broken into three parts:
    Shintr.h
    Intrinsic functions available to all SH4 users
    Shsgintr.h
    Intrinsic functions available to users of the Sega version of the SH4
    Shosintr.h
    Intrinsic functions for operating system developers

    Other Inline Function Improvements

    Support has been added to perform the following conversions inline, using the appropriate SH4 instructions when the /Qfast option is selected:
    · Float to unsigned integer
    · Unsigned integer to float
    · Double to integer
    · Integer to double
    · Unsigned integer to double
    · Double to unsigned integer

    Compile-Time Speed Improvement

    Compile-time speed and memory efficiency have been improved in several components of the compiler, most notably the following:
    · Global value propagation (/Qgvp)
    · Late-stage local optimizations (IMLOPT)

    Fine-Grain Loop Invariant Code Motion

    The loop-invariant code motion stage of the IL optimizer has been enhanced so that it now operates on sub-expressions within statement trees. The previous implementation identified larger invariant components and raised them out of loops. This enhancement identifies small invariant sub-expressions for hoisting and works with the expression normalizer to increase the number of expressions that can be recognized as invariant within a loop.
    Address Normalization

    This new component works with loop-invariant code motion and other IL optimizer stages. It reorders IL sub-expressions within individual IL trees to improve ability to recognize common subtrees. For example, loop-invariant sub-expressions are moved to lower positions in an IL tree to make it possible for loop-invariant code motion to harvest them out of trees, when otherwise such harvesting would be blocked by interfering loop-variant components in lower tree positions. CSE benefits similarly from a canonical ordering of components.
    Perfect subtree reordering consumes too much processing time to be worthwhile, but heuristics have been applied which yield good results in most cases.
    Brigg’s Optimism in Register Allocation

    Preston Brigg’s technique improves on the traditional graph-coloring algorithm. It provides a second chance to map a physical register to a virtual register when there are too many other interfering register lifetimes. The approach is to wait until coloring time to spill a register from the candidates list, rather than spilling it as soon as the number of interfering neighbors becomes too great. While the improvement in spill rate is not dramatic, it is noticeable.
    Late-Stage Tail Merging

    A late tail-merging stage has been added to the IMLOPT component. It was found that significant opportunities for tail merging appear after other lowering and optimization stages have been applied. The technique produced a noticeable reduction in code size on sample operating-system builds.
    DAG Peep-Hole Optimizer

    Enhancements to the DAG Peep-hole Optimizer include the introduction of a more detailed dependency graph that identifies and re-uses dead registers leading into function calls and the addition of four new floating-point peep-hole patterns.
    Alignment Analysis

    Support for the analysis of address expression trees to deduce alignment when the tree is marked unaligned has been added to the IL expression-evaluation stage. It can correct the over-conservative alignment marking applied to IL trees by the front end in some cases, but is generally defeated when the address expression includes a pointer dereference.
    Improved Alias Analysis

    An alias is a name that refers to a memory location that is already referred to by a different name.
    To improve the accuracy of alias information, a new feature called AliasTrackinghas been implemented. The Alias Tracker analyzes the program to keep track of uses and definitions of aliases. It records this alias information at relevant points for use by the IL Optimizer. Three levels of alias tracking are provided: Levels 1, 2, and 3. Level 3 provides the most accurate alias information. The alias levels can be controlled by the following command-line options.
    Level
    Description


    /Qalias0
    No Alias Tracking is performed. This feature is disabled completely.
    /Qalias1
    Alias Tracking is performed within basic blocks. Within a basic block, the recorded alias information is not flow-sensitive.
    /Qalias2
    Alias Tracking is performed within basic blocks. Within a basic block, the recorded alias information is flow-sensitive. This is the default level.
    /Qalias3
    Alias Tracking is performed across basic blocks. Accurate alias information is recorded using global data flow analysis.

    Support for /Oa and /Ow

    Command-line options /Oa and /Ow are supported. The /Oa and /Ow options do not have any effect when Alias Tracking is turned off (/Qalias0).
    The Assume No Aliasing (/Oa) option tells the compiler that the program does not use aliasing.
    The Assume Aliasing Across Function Calls (/Ow) option tells the compiler that no aliasing occurs within function bodies, but that it might occur across function calls. After each function call, pointer variables must be reloaded from memory.
    The following rules must be followed for any variable not declared as volatile:
    · No pointer references a variable that is used directly.
    · No variable is used directly if a pointer to the variable is being used.
    · No variable is used directly if the variable’s address is taken within a function.
    · No pointer is used to access a memory location if another pointer is used to modify the same memory location.

    See the Help on /Oa and /Ow in the Visual Studio online documentation for more information.
    Direct3D Performance Hints

    Peak polygon rates are achieved using large non-indexed strips, calling the DrawPrimitive function. Texturing imposes a small overhead, and a single directional light imposes a very small overhead. Indexed strips using DrawIndexedPrimitive have a noticeably lower performance, and lists, indexed or non-indexed, are substantially slower than strips.
    The following table shows example rates achieved using the D3dstrip.exe supplied with the samples.
    Type of Polygon
    Rate


    Non-textured, one light, strips, DrawPrimitive
    3.1 M poly/sec
    Textured, one light, strips, DrawPrimitive
    2.9 M poly/sec
    Textured, one light, strips, DrawIndexedPrimitive
    2.2 M poly/sec
    Non-textured, no lights, strips, DrawIndexedPrimitive
    2.4 M poly/sec
    Lists
    ~ 1 M poly/sec

    C Render Loop
    Under various circumstances, the inner render loop is performed in C, as opposed to one of the various custom assembly-language loops, which are much faster. It is better to avoid this where possible. The current catch-all C routine is implemented in assembly.
    · Front-clipped meshes
    Meshes that intersect the front clipping plane are processed in C. Where possible, the DO_NOT_CLIP flag should be set for meshes that are known to be totally within the viewing frustum. If this flag is not set, a fairly quick routine establishes whether any or all of the vertices are in front of the front clipping plane. Meshes that are established to be completely beyond the front clipping plane are handled in assembly. Meshes that are partially clipped by the front clipping plane are processed in C. Meshes that are totally clipped by any clipping plane are discarded.
    · Wrapped texturing
    Where the WRAP_U and/or WRAP_V render states are used, the mesh is handled totally in C. Avoid this now by allocating extra vertices at the seams for any mesh with which texture wrapping is required.
    · Fog
    If vertex fog is enabled, the current implementation uses the generic C routine. In short, vertex fog is currently slow, and the newly included table fog should be used instead.

    Strips versus Lists
    Strips are much faster than lists in general, although they may be difficult to use in some cases. For large meshes with many common vertices for which DrawIndexedPrimitive is used, the next release will attempt to concatenate triangles where possible to form strips. This is not feasible for non-indexed meshes.
    Indexed versus Non-indexed
    In general, non-indexed meshes are rendered a little faster than indexed meshes, except where indexed meshes can convert lists into strips, as described above. The current extreme difference between 2.2 million polygons per second and 2.9 million polygons per second will be reduced somewhat in the next release, as the inner loops are optimized.
    Vertex Alignment
    Vertices should optimally be aligned on 32-byte boundaries, or at least on 8-byte boundaries. If vertices are not aligned on 8-byte boundaries they are copied to a separate buffer with memcpy before processing, since they are read using double-precision floating point reads and writes for speed.
    Render-State Changes
    Changing between two similar textures, such as two mipmaps, is a low overhead render-state change. Other render-state changes cause a re-analysis of the entire render state when rendering the next mesh, which takes a few microseconds.
    Improvements Since the Last Release
    · VQ support
    · Improved automatic list-to-strip code
    · High-speed “table” fog
    · Performance and graphics memory monitors
    · Reduced per-mesh costs.
    · Driver hints to allow for less memory overhead
     

Share This Page