|
 |
 |
:: ::
|
|
|
TSampleDisplay3D Component
There are three ways to use this component.
TSampleDisplay3D for Delphi, an ActiveX version and Sample Display 3D Library for any developer environment that any environment that supports the stdcall calling convention.
The most you get is from the Delphi version, you can access all the underlying stuff, and the least you get is the standalone .dll version.
All of these components are refered to as TSampleDisplay3D.
A component for use in Win32 (9x/ME/2K/XP/Vista) software with BASS.
It's purpose is to provide the most powerful and efficient (yet easy to use), 3D sample functions like displaying the sample in 3D with configurable colors,
automatic support for ID3v2 SESC, making a selection, zooming, quick-playing from click, configurable selection playback repeat count, edit and
create Subsong seekpoints, etc. all on a powerfull Direct3D display.
You should also see the included example program Tutorial1's source-code for example of how to use TSampleDisplay3D in your own programs.
See the download page to download the package.
Requirements
Delphi or a developer environment that supports the stdcall calling convention
DirectX9 installed
DirectSound installed
Clootie DX9 package (included) http://clootie.narod.ru/
BASS package (included) http://www.un4seen.com/bass.html
ID3v2 Library (included) http://www.3delite.hu/Object Pascal Developer Resources/id3v2library.html
TSampleDisplay3D in shareware and commercial software?
The component is free for free software. If like it and use it for shareware and commercial software you have to buy a license.
Installation
Unpack the appropriate BASS package (bassxx.zip). bass.dll and Delphi/bass.pas is needed in the search path.
Unpack the ClootieDX9 folder, all the files inside are needed in the search path.
Unpack the appropriate ID3v2 Library unit, id3v2Library.dll is needed in the search path.
In Delphi menu: Component: Install component
Unit file name: select "SampleDisplay3D.pas"
Compile and save package.
If everything went smooth, you can access the TSampleDisplay3D component on 3delite's tab.
Supported audio file formats: MP3, MP2, MP1, OGG, WAV and music modules. Yes, it
supports music modules too! :, MO3, IT, XM, S3M, MTM, MOD, UMX
If you want your application to handle many more audio file formats, like: Flac, OptimFrog, WavPack, Monkey's Audio, Musepack, TTA, ALAC (Apple Lossless), AC3, Speex, AACH, AAC/MP4 and AC3, etc. (you can also use winamp input plugins trough a BASS plugin) check the great BASS add-ons on the BASS page.
NOTE: To run the EXEs, first you'll have to copy bass.dll and d3dx9ab.dll into the same directory as the EXEs.
The Tutorial presentation demo in action:
TSampleDisplay3D Delphi component @ Un4seen Developments Forum
Properties
.ActiveIndex: Specifies which stream is displayed on the 3D panel.
.AllowSelect: Turn on/off selection possibility.
.AllowQuickPlay: Turn on/off middle-mouse button quick play and space-bar play/pause
possibility.
.AllowWhhelZoom: Turn on/off mouse-wheel zoom in/out possibility.
.AutoReInit: If set to True Direct3D is re-initialized every time when the panel
is resized. Very slow, but gives always precise 1:1 resolution.
.BaseStreamCount: Specifies how much slots are avalable for streams. Default is 1.
If you need more slots set to a greater value.
Note: It is not recommended to increment this value in single steps (causes
memory fragmentation), set it to a given value only when you know how much
slots you'll need. You can leave it at 1 if you don't want to use the slots
feature at all, and you want to use only a single slot.
.CacheSampleInSeparateThread: Specifies whether to run the sample caching in separate
thread.
Note: Be carefull when caching a slot's sample and you want to show it at the same time!
(Experimental and probably a feature of no use.)
.D3DVertexProcessingMode: Older 3D gfx card don't have hardware vertex processing, then select sofware mode.
vpHardware: Hardware Vertex Processing
vpMixed: Mixed Vertex Processing
vpSoftware: Software Vertex Processing
neXe - THE DirectX resource - Vertex Processing
Scan Computers - Graphics >> GPU
.Panel3DColor: Specifies the background color for the 3D panel when no 3D graphic is
drawn.
.Panel3DPicture: Specifies the picture used when no 3D graphic is drawn.
.SampleAmplitude: Specifies the sample graphics amplitude on the 3D display.
.SampleAnim: If set to True the 3D sample is animated. Setting to False will speed
up the inital show, the Zoom and ShowAll functions.
.SampleDownColor: Sample's bottom color (Left and right channel respectively).
.SampleFFT: If set to True FFT graphic is drawn below the sample when the stream
channel is playing.
.SampleLines: Draw the sample graphics as lines not as triangles (slower).
.SampleResolution: Max. triangle/line count for the sample's object. Default is 300000.
You may need to lower this to 100000 or even 50000 on some graphic cards.
The bigger the resolution the slower the rendering but the sample graphics is
more detailed.
Modern graphics cards can display about half a million triangles in one go.
.SampleScroll: If set to True the 3D sample is scrolled with the playing position.
.SampleUpColor: Sample's top color (Left and right channel respectively).
.ScrollBarHeight: Specifies the scroll bar's height.
.SelectionRepeatCount: Specifies how many times to repeat playing the selection.
.SelectionRewind: Specifies weather to position playing position to selection start
or to leave where it stoped (at the selection end).
.ShowSubsongs: If set to True Subsongs are shown.
.SuppressErrors: Do not display any error dialogs.
.UpdateSelectionPlayOnMove: When playing selection and making selection in the same
time, "selection end" BASS sync position will be updated accordingly. The
playing will jump back (or stop) from the new selected position.
.WriteSESC: Save sample cache (MP3 Stream Editor format) in ID3v2 SESC frame.
Advised as it only increases file size only a few 10KBs but results nearly
instant displaying of audio files.
If set to True, after every CacheSample() if the audio file has an ID3v2 Tag
the SESC will be saved, if it doesnt have ID3v2 Tag then it won't be. If you
want to force saving the SESC, regardless if the audio file has an ID3v2 or
not use the ID3v2_SetSESC() function with the Force flag set to True.
Note: ID3v2 SESC is automatically used when opening audio files. The
OnNeedSESC event is reaised before though.
.WriteSubsongs: .cue and Helium ID3v2 Subtracks info is automatically converted and
saved as MP3 Stream Editor Subsong layout in ID3v2 frames.
You can save the Subsongs any time with the function .ID3v2_SaveSubsongs().
Events
.AfterD3DRender: is called when the sample and all the graphics had been drawn on
the surface. You can draw on the surface that will be on top of the sample
graphics.
.AfterTagSave: is called when the ID3v2 Tag is saved (eg. MP3SE Subsong layout).
.BeforeD3DRender: is called when the D3D surface is cleared and ready for drawing.
You can draw on the surface with
.Streams.Index[Index].g_pd3dDevice
that will be behind the sample graphics.
.BeforeTagSave: is called when the component is about to save the ID3v2 (eg. MP3SE
Subsong layout).
.OnD3DDestroy: is called before freeing the Direct3D object.
.OnNeedBASSChannelHandle: is called when the component needs a BASS channel handle
for playback.
Index specifies the slot needing the handle.
Flags specifies BASS_StreamCreateFile() flags needed.
If the given stream's channel handle is 0 the component tries to create a
BASS channel handle on it's own using the default BASS_StreamCreateFile()
function. If .Streams.Index[Index].Channel is not 0 then that channel
handle is used for playback.
.OnNeedBASSDecodeChannelHandle: is called when the component needs a decoding BASS
channel handle for getting the sample cache. This event will not be raised
if the .SampleCache is filled in .OnNeedSESC!
Index specifies the slot needing the handle.
A decode channel handle is needed in Channel. If Channel is 0 the component
will try to create a decoding channel on it's own using the default
BASS_StreamCreateFile() function.
.OnNeedSESC: is called when the component needs sample cache in
.Stream.Index[Index].SampleCache
You can fill it here, or if .SampleCache size is 0 on return, the component
will try to:
1.Load ID3v2 SESC cache
if not successfull:
2.Create a decode channel handle and will get the sample cache from there.
.OnSelection: is called when the user changes the selection on the sample display.
.OnSubsongChange: is called when the user is above a Subsongs seekpoint or is dragging
the Subsong seekpoint on the sample display.
Index specifies the slot where the drag occured.
SubsongNo specifies the Subsongs seekpoint that is being dragged.
Other available properties
.g_pD3D: The Direct3D Object.
.Streams.Index[Index].g_pd3dDevice: The Direct3D device for slot specified by "Index".
.FPS: Current frames per second for the Direct3D display.
.Streams[]: the slots for the audio files.
.Cancel: Set to True if you want to abort the current task (eg cache sample task).
.Progress: Current task's progress in percents.
Functions and procedures
.StreamOpen(FileName: String; Index: Cardinal): Boolean;
Open an audio file in slot "Index".
Result is True if successfull.
.StreamClose(Index: Cardinal);
Close audio file in slot specified by "Index".
.InitD3D(Index: Cardinal): Boolean;
Initialize and display stream in slot "Index".
Result is True if successfull.
.Render;
Draw the frame. The slot specified with .ActiveIndex is drawed.
This should be called about every 30th msec (or more often) if you want smooth 3D graphics.
Another good idea is to call it in OnIdle().
.Zoom;
Zoom to the selection. The slot specified with .ActiveIndex is zoomed.
Is animated if .SampleAnim is True.
.ShowAll;
Display the whole sample. The slot specified with .ActiveIndex is showed all.
Is animated if .SampleAnim is True.
.PlaySelection;
Play the selection.
BASS channel will be created if non existent, so OnNeedBASSChannelHandle()
will be called.
The playing will rewind as specified by .SelectionRepeatCount and
.SelectionRewind.
.PlayStream(Index: Cardinal; StartPos: Int64; EndPos: Int64; FadeIn: Boolean): Boolean;
Play the slot specified by Index.
Startpos: Start position in bytes on a BASS channel handle.
EndPos: End position in bytes on a BASS channel handle.
FadeIn: Fade in when starting playback in one seconds.
BASS channel will be created if non existent, so OnNeedBASSChannelHandle()
will be called.
Result is True if successfull.
.SampleDataCache(Index: Cardinal; Force: Boolean);
Refresh (load or get) sample cache for the slot. If Force is not True
TSampleDisplay3D will first try to load ID3v2 SESC. If Force is set to True,
a new decoding channel will be created and the new sample cache will be saved
into the ID3v2 Tag if .WriteSESC is set to True.
.ID3v2_SetSESC(Index: Cardinal; Force: Boolean): Boolean;
Save sample cahce in MP3 Sream Editor format into ID3v2 SESC frame.
Force: Normally SESC will be saved only into audio files which have ID3v2 Tag. If you specify Force = True
then an ID3v2 tag will be created if non existent.
Result is True if successfull.
.StreamSaveWAV(Index: Cardinal; OutFileName: String; StartPos, EndPos: Int64): Boolean;
Save WAV PCM file from slot "Index".
OutFileName specifies where to save the file.
StartPos specifies the starting position in bytes on a BASS channel handle.
EndPos specifies the ending position in bytes on a BASS channel handle.
A decoding channel will be created, so .OnNeedBASSDecodeChannelHandle will be called also.
.StreamSaveWAV32(Index: Cardinal; OutFileName: String; StartPos, EndPos: Int64): Boolean;
Save WAV PCM file in 32bits from slot "Index".
OutFileName specifies where to save the file.
StartPos specifies the starting position in bytes on a BASS_SAMPLE_FLOAT BASS channel handle.
EndPos specifies the ending position in bytes on a BASS_SAMPLE_FLOAT BASS channel handle.
A decoding channel will be created, so .OnNeedBASSDecodeChannelHandle will be called also.
.StreamLoadCUE(Index: Cardinal; var Titles, Artists, Seeks, Albums: TStrings): String;
Manually load a .cue sheet file for the slot specified by Index.
Titles, Artists, Seeks, Albums are available as
.Streams.Index[Index].Subsongs.Titles .Streams.Index[Index].Subsongs.Artists etc.
Return value is album name.
Note: Will try to open file with the same name as the audio file but with .cue extension!
.StreamLoadSubtracks(FileName: String; var Tag: Tid3v2Tag; var Subsongs: TSubsongSeeks): Boolean;
Manually load Helium ID3v2 Subtracks for the slot specified by Index.
Tag is the ID3v2 Tag for the slot:
.Streams.Index[Index].ID3v2Tag
Subsongs:
.Streams.Index[Index].Subsongs
Result is True if succesfull.
.StreamLoadSubsongs(Index: Cardinal): Boolean;
Manually load MP3 Stream Editor ID3v2 Subsongs for the slot specified by Index.
Result is True if succesfull.
.ID3v2_SaveSubsongs(Index: Cardinal; var Tag: Tid3v2Tag; Titles, Artists, Seeks, Albums: TStrings): Boolean;
Save Subsong layout in MP3 Stream Editor ID3v2 Subsong layout format.
.Streams.Index[Index].ID3v2Tag
Titles, Artists, Seeks, Albums is available with:
.Streams.Index[Index].Subsongs.Titles etc.
Result is True if succesfull.
Other helper functions available
BGR2RGB(BGRValue: Cardinal): Cardinal;
Convert BGR color value to RGB color value.
Bytes2MB(Bytes: Single): String;
Convert bytes count into a readable string.
mSec2Time(mSec: Int64): String;
Convert msec length into a readable time format.
NGetFileSize(FileName: String): Int64;
Gives file size in bytes.
DecodeUnicode(UnicodeString: String): String;
Decode unicode string to normal string.
Credits
Brandis brandis@freemail.hu for some Taging functions.
Ian Luck @ www.un4seen.com - for the great BASS audio library.
James Webb @ audioxl.com for the great ID3 units Copyright (c) 1998-2001 audioxl.com
Copyright, Disclaimer, and all that other jazz
The TSampleDisplay3D is free for free software. If like it and use it for shareware and commercial software please buy a license.
This software is provided "as is", without warranty of ANY KIND, either expressed or implied, including but not limited to the
implied warranties of merchantability and/or fitness for a particular purpose. The author shall NOT be held liable for
ANY damage to you, your computer, or to anyone or anything else, that may result from its use, or misuse. Basically, you use it
at YOUR OWN RISK.
Usage of TSampleDisplay3D indicates that you agree to the above conditions.
You may freely distribute the TSampleDisplay3D package as long as NO FEE is charged and all the files remain INTACT AND UNMODIFIED.
All trademarks and other registered names contained in the TSampleDisplay3D package are the property of their respective owners.
Bug reports, Suggestions, Comments, Enquiries, etc...
If you have any of the aforementioned please email: 3delite@3delite.hu
|
|
|
|
|
|
