(http://www.underwaredesign.com/PlayBasicSig.png)
Visit www.PlayBasic.com (http://www.playbasic.com)
PlayBASIC2DLL Tutorial - Making your first DLL (2019-05-30 )
Welcome, in this video we sit down and jump into the big world of creating machine code DLL's for PlayBASIC using our free conversion tool PlayBASIC2DLL.
PlayBASIC2DLL is a partner tool to PlayBASIC retail editions. The tool is designed to convert stand-alone playbasic source code files to dll. The users source code is translated in steps, first the code is passed PB compiler resolved down byte code. Then the byte code is imported by PB2DLL to generate the assembly representation from which is then assembled to the final DLL.
Created DLL's contain logic only and are dependent upon the PlayBASIC runtimes to execute commands, so the dll's can't be used in other languages. The real benefit is PlayBASIC coders can create high performance expansions to PlayBASIC in PlayBASIC.
This tutorial we go through the basics of setting up the tool and quickly go through the process of creating project to convert to dll.
Video:
More about PlayBASIC + PlayBASIC2DLL
http://PlayBASIC.com
https://UnderwareDesign.com
MusicBy: "You're F'd" by Lars Jensen from Thesius XII (Amiga) (https://www.underwaredesign.com/?page=programs.Thesius-XII)
Links:
PlayBASIC2DLL V0.99 Commercial Edition released! (https://www.underwaredesign.com/forums/index.php?topic=4199.0)
PlayBASIC To DLL Development Blog (https://www.underwaredesign.com/forums/index.php?topic=4105.0)
Script:
hi welcome to a prompt you look at one
of it all the tools now that five basic
to deal at all
we the list is for free recently so it's
on the forum if you're logged in you can
come over the forum and read the the
release history here when you're logged
in this you follow the links to download
it those kind of things there is a quite
a long working progress gallery about it
as well that you really should read
there's no way of putting it
you should read this stuff because
that's why it's written that's why we
put this stuff on the forum it's not a
joke we expect you to read it you might
not understand it all but hopefully
you'll understand the thought process
behind making these tools so 5x2 dll is
exactly that it converts your favorite
code into a machine code deal
file in in what's called or we nursed a
nail file or a dynamic link library if
you really like the way it sounds
windows uses dll's all over the place
so the idea of these things is we we
take a bit of code we you need to be
fast or we need to reuse and other
programs and we compile this dll from
its normal source form into pv bytecode
and that PV bike cones in translated to
machine code that's a general just just
to this whole process I assume you've
already download the file I've got the
the PB to DLL archive up here and really
we just run their application now
initially we have to run it to set this
thing up
and what we need to do is we need to
tell it where play basic ears so it's
saying that there's no valid compiler
path because there's no it hasn't seen
an obvious location for the compiler so
we hit locate and what I do now is I I
locate the version of PvE they want to
use that's okay you found a version of
it thank you very much
so our preferences are set they don't
actually all we need to do a next step
is it's going to be writing we can read
the help files for some information
about the tool itself you can do this on
your own time really we should do that
do that then right so we've initialized
the tool it's right ready to use now all
you need to do is go to play basic and
write something we can convert to a DLL
that's worthy of converting to a DLL
I've picked a particular favorite kind
of thing here we do this is a
brute-force operation we're running
through all the pixels on screen
computing a color at ran not written at
random but but in creating the color and
rendering it for every dot if we just
ran it on this computer here we can see
what the result of it
go interesting looking effect and the
colors will slowly scroll through right
so I've already saved this example it's
on the desktop over here so I made a
follower and saved a little project into
here
so what if he wanted to to really make
this application run the best it
possibly could so we've decided this
section of code here would be better
suited to running in machine code now if
we try and pass this piece of code here
through the pv to dll it has no idea
what it's looking at so what we need to
do first of all is build a function and
I'll grab this code here and we'll make
our own like I won't function you know
it will click my my fill screen or
something complete that give the in
function and place the code inside what
we probably should do here is we should
actually allow the user to pass this
fill color across it will pass the fill
color into the function and well
eliminate this code and now in its place
we'll just call our call our function so
first people are not familiar with
making functions or all those kind of
things then jump in the manual read this
stuff get wrap your head around it
because I'm not gonna go into that stuff
you're either now no you don't if you
don't know it you probably thank you for
ready to go back and starting this stuff
up up front so we've built a version of
this quite simple example that does this
I'm actually I've just
just grow a version of that that was our
starting version of this program I'm
gonna be saving over it all the time so
I think we might want to keep peace okay
so let's try and run the program
so all this accomplished we've
accomplished nothing not a thing we've
taken a bit of code that was all one
giant glob jewel of code and with
modular eyes eyes eyes it is such a word
by taking the particular function or
particular crow that does the screen
feeling and may into a function but this
is not really what PV to dll needs to
make a dll out of this function we have
to do two things
first of all we have to have a fun after
have our our source file that is made up
of really just our the functions we are
going to expose to the user or you think
we're like we're making your own
commands we we need our functions that
were that the user is going to use and
at the top we need our set up data we
can't have any do loops in it this kind
of do loop in Global's go won't work so
to do that what I would normally do
actually is I would do something
something a bit different is what's
imagine that this is our main project
with we've got a huge code base if then
we decide we want to shift some of the
some of the workload from from five
a-six runtime into machine code to make
a program to perform better doing some
brute force tasks what I would do is I
would create a new project
and call this I'm gonna save it first
where we saved the other one it's on the
desktop in it sorry desktop I already
caught fill screen demo very original in
here I would make a folder for our new
project and we'll call this you know I'm
just got my DLL as its own that's our
folder go into the folder and we'll call
this project as well this is my my DLL
functions
you know something descriptive so we can
we can load this up thing listening up
later it's saved and that should be
saved inside that folder we'll just
check so now we see the fill screen
project we've got our normal files that
PVA creates this is our code files a
backup of that file this is the project
files the icon file but we also have a
new folder which has its own its own
code file and there as well this is
going to be well we're going to play 17
old functions and we're gonna export and
create our code here's what I would do
I've got my two projects open I've got
my my big project over here which we
were just messing around with filling
the screen you know I'm finally going to
want to convert these things here across
the DLL so I would grab the function
like so
cap that function across IV into a DLL
project I'll just say that go back to
here now I don't need this function in
this section of code anymore obviously
if I try and run this piece of code it's
not going to work
that's because this function we just
spent in time creating and talking about
we've just removed it and moved it to an
entirely separate project all together
this is what yeah we have to jump into
our different mindset so sorry
corrective out DLL project
oh yeah this is a deal this is going to
be our DLL this is what's going to be
converted to a DLL that we're going to
load into memory in our main project and
call the machine code version of this
function when it's created whole lot of
gobbledygook now if I run this code we
get nothing and that's because it has no
main loop in it and it shouldn't have
any main loops in it if you need to set
up data you would you would do the data
setup up here you know dim you know an
array or something like that that you
need if I could spell it hey it's late
come on you know have you these are
global so the functions inside here I
will be able to see this array but when
the DLL is created and you import this
DLL back into your program this will be
invisible the only thing that we'll be
able to see is functions that have been
exported and are visible to the end-user
and the only way to do that is using the
name prefix DLL this really comes down
to some stuff about how DLLs work
windows dance color it's a bit boring
but this these machine code blobs of
code of functions they can have a lot of
code in them but not all of it is
exposed for to be called externally so
you can think of it like like a privacy
layer really so some some functions are
exposed publicly and which is what we're
doing here really with with we're saying
we wanted to clear this function
publicly and it'll expose a function
called my fill screen with one parameter
to us hmm so if I say this try and write
again we should just go back to thing
nothing exciting happens very good
that's what we wanted we try and run the
main application at the moment we'll get
an error because this function doesn't
exist time to fire up play basic to DLL
we now our library code our example
works this is the key point we're not
doing this process all the time we're
writing our DLL functions we're making
sure they all work once we're happy once
we we're satisfied that it does what
it's meant to do then we confer this
things with DLL that's how big
applications are written you we're not
we're not constantly compiling
everything all the time no it's just
crazy
no one's got that much time in the hands
so we fired with the free version of
this got a file got a convert file now I
got to find that thing we just were
messing around with really some of the
desktop the project folder was call it
fill screen demo now if we pick main we
should get an error actually well do
that first of all we'll show you
this main file here is a it's plain
basic source code but in that source
code there are no functions with dll to
be exported so I should fail essentially
and there you go give me some compiler
it's giving us a rough approximate of
the nation of the error the array or
function name my fill screen is not
defined joints the line compiled bought
it so no dll can be created from that
that piece of code because we've chosen
the wrong piece we need to go to this
folder and then we pick main here and
that's the process
I'll just exit this now jump out of this
got a feel screen into my DLL which is
where it was stored now we have two new
files we have a thing called unnamed DLL
which is what just created and you
include check it out it's giving us a
link dll block that we can include it in
our main project that does this task
let's see if it works and tries for a
while just see if it works back to play
basic right that's the DLL project we
don't need that or needs our main
project so we need to include this
source file mmm dot PVA if we try trying
to include it from here
we are including it from our fill screen
demos location and it should should not
work so I hope you how to locate it till
I save this file inside a folder inside
that that project that folder is called
my
my deal out bit of a slash that'll do us
see how we go well saying can't find the
dll that's what saying oh geez hope it
doesn't default to doing well just check
out include by opening up here unnamed
yeah that won't work that doesn't
doesn't work I could just cut and face
there cross across to here really
couldn't we but then we wouldn't need
the include file at all we could see
what's going on so let's do that
get rid of this include before it wasn't
working or I'm assuming it wasn't
working because it was looking for a DLL
called unnamed DLL in our full screen
project follow of course is not there
because we we say this thing over here
hopefully it works there you go where we
go so with a bit of messing around would
double the frame rate of the example
before it was running about 50 frames
per second we haven't done anything
special really with it yeah most
definitely no no me what real would be
sick going wall cheese wasn't that filth
screen routine using the fast command
and yeah it does let's go to my DLL or
just will keep this version of the
function
and we'll write another version this
time what will do is will my feel fill
screen you just call it - I don't care
this time what we need to do is we'll
replace the fast start now even though
it's called fast start internally dot is
still doing there's a multiplication
therefore every pixel at least addition
every everywhere it's a lot of place and
thank you for going to calling a
function you know it's a lot of work
that goes into just doing something that
really simple what we could do forget a
screen pointer that's bit of a misnomer
here we get the image pointer of
surfaces your own which is the screen
pitch yeah just call screen future this
is the number of bytes that occur on a
row of pixels we're assuming this
function just fills the screen by the
way he doesn't always allow for you to
fill other surfaces now I'm going to
assume that the screen is set to 32-bit
we should actually here we should check
what type of screen it is and make sure
that we are drawing to a 32-bit screen
but we're not going to let's be brave
okay so we've got our row color what we
need here is our row pointer and row
pointer is this going to equal screen
pointer plus
while ooof times the so now when
we do a poke we do a poke end poke end
row pointer and wrote our the translator
will will convert this will in line this
function completely filled end up is
pretty much a loaded store in memory we
do have to have an addition with row
pointer now we could probably do it yeah
I could probably just do X loop and then
shift it to two bits as long as X lips
never native that'll work fine
so we're grabbing this value here we're
shifting it up which is effectively the
same as multiplying it by for adding it
to the row pointer and then writing this
color into that piece of memory now we
can't really test this we can compile it
now compile ok so I'm gonna save that
just to make sure in this case here what
I tend to do it when I do this kind of
stuff as I split them apart I'll get rid
of that deal with that sorry alright we
don't need that and we just just have
just call the function as a test
yeah sync YK just to make sure that we
haven't crashed it it seems ok give this
a different value and see what we get
maybe maybe not
do we get the same result as the
previous function that's the question we
don't so we've broken
piece of code quite convincingly well
then okay so what's wrong with this
thing let's have a look we locked our
buffer we've grabbed a seed point from
it we've grabbed a pointer to the the
buffer here and that looks like a fault
look at that we want to multiply the Y
by the screen pitch so we compute the
first byte on the row hmm not masking
that's not going to work let's try it
okay I think we fixed our little fold
let's resave this stuff here just give
it a quick test compile yeah we're okay
with that gonna jump out and go back to
play bastard lol normally I wouldn't
normally I'd tweak the routine first and
then build the deal I'll be very end but
you know well we can just go back to
resting files and this file here's the
one we want to compile again I'll
convert so what it's doing is it's
taking that source code it's calling
play basic to convert the text version
of it into compiled down bytecode it's
going through the bytecode you're
viewing that to assembling and passing
that through to the assembler to produce
the DLL so it's something a bunch of
stuff alright let's have a look at our
folder it's created a a new a new DLL
and our include will have a new
declaration this one here it's our
second function I'll just be lazy and
copy that across to our main project I
realize I'm probably being pretty pretty
confusing and obtuse for people
unfortunately that system we the reality
of it let's try something pretty pretty
daring text 10/10 put some frame rate on
the bottom what we'll do is that when we
hold down space key or something sorry
when this is false
run the old the old version of it then
we'll run the second version of it and
we'll see what kind of difference in
performance we're getting just from that
one little shuffle logic let's try it
okay so getting the 109 somewhere in
there yep with the original version and
we're getting double the performance
again and all we did was just shuffle
around some logic
I'll give you think that's about the
internal like things like box routines
inside PP they're actually written in
strange them straight assembly they're
not really insane and many are unrolled
loops pretty much and it's quicker than
that would be quicker than what we're
doing in our little DLL but let's face
it I mean you can write extensions to
your to your project in play basic
convert into machine code and doesn't
cost you a cent you don't have to learn
another language you just go learn the
process I know it's awkward you know
welcome to my world this is what the
bigger base products scared the more
models products can be it can be a bit
of a nightmare anyway hopefully that
gives you a giving inside of how you
might go about structuring your projects
and how you might use P better to deal
- to take the load off the pv runtime
and you know win back some some mass
needed performance if you really need
this stuff
ok thanks for watching and hope you are
successful and we'll see you next time
Download:
Attached are the initial project and the final project. You'll need
PlayBASIC V1.64P4 to run the second example.