PlayBASIC2DLL Tutorial - Making your first DLL (2019-05-30 )

[kevin]

 Visit 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)


Links:

    PlayBASIC2DLL V0.99 Commercial Edition released!
    PlayBASIC To DLL Development Blog  


Script:

   

Code Select Expand


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.